This text codec was previously implemented only for Option<String>, this
extends it to all types implementing those two traits, such as numbers
or JIDs.
These more closely mirror how enums work currently with the macros.
Non-exhaustive enums may be useful though and kind of were the natural
thing to implement.
We can do this because we know that `x < y` cannot create a
`TextCodec<T>` for any `T`. This is because `<` is guaranteed to return
a boolean value, and we simply don't implement `TextCodec<T>` on bool.
This allows stateful or configurable codecs without having to express
all configuration in the type name itself. For example, we could have a
Base64 type with configurable Base64 engines without having to duplicate
the Base64 type itself.
(Note that the different engines in the Base64 crate are values, not
types.)
In 1265f4b, we introduced a change which may cause a conflict of type
names when deriving the traits on two different types. While a
workaround existed (use `mod`s to isolate the implementation), that is
ugly.
This commit allows overriding the choice of type names.
This introduces support for `Cow<'_, [u8]>` (which is not needed
currently, but still good to have) and generalizes the `Option<T>`
implementation so that it doesn't have to be copied for every other type
supported to be Base64'd (we may add support for `bytes::Bytes` at some
point, for instance).
Now it's not limited to a single feature gate per type (or even just
feature gates: it should now also be possible to add constraints
based on OS, for example) anymore.
This codec converts from a colon-separated case-insensitive hexadecimal
string into a Vec of bytes, and back to a lowercase colon-separated
hexadecimal string. Each byte must be separated by exactly one colon.
Analogous to the already existing `IntoXml` implementation helpers
based on an `Into<Element>` implementation on a type, this provides
the utilities for `AsXml`.
This is of course exceptionally inefficient, but it is only needed
transitionally until we have everything migrated to derive macros or
otherwise rewritten in terms of AsXml/FromXml.
This will soon replace the IntoXml trait. The idea here is that we
don't generally need to take ownership of values which are going to
be transformed into XML: most of the time, the XML text is created
by building a string from some more specific type, such as an
integer or an enum. Requiring to clone an entire structure for this
purpose is wasteful.
In other cases, we actually could reference data right from the structs
we are converting to XML. In those cases, assuming that an iterator
always generates owned data would be incorrect, too.
Hence, we introduce a new `Item` type which closely mirrors the
`rxml::Item` type, but where the constituents are `Cow`. In the upcoming
changes, we are going to work toward replacing all uses of `IntoXml`
with `AsXml`, as well as modifying the macros accordingly.
Text codecs allow to customize the conversion of data from/to XML,
in particular in two scenarios:
1. When the type for which the behaviour is to be defined comes from a
foreign crate, preventing the implementation of
FromXmlText/IntoXmlText.
2. When there is not one obvious, or more than one sensible, way to
convert a value to XML text and back.
Previously, we only enforced the existence of at most one `#[xml(text)]`
field only at code generation time for `FromXml`. This change enforces
it at parsing time, which is more consistent and allows for a clearer
error message.
