diff --git a/README.md b/README.md index 098dadc4f..c41079849 100644 --- a/README.md +++ b/README.md @@ -205,7 +205,9 @@ types. `self` determines if the format is self-descriptive. Allowing the structure of the data to be fully reconstructed from its serialized state. These formats do not require models to decode and can be converted to and from -dynamic containers such as [`musli-value`] for introspection. +dynamic containers such as [`musli-value`] for introspection. Such formats +also allows for type-coercions to be performed, so that a signed number can +be correctly read as an unsigned number if it fits in the destination type. For every feature you drop, the format becomes more compact and efficient. [`musli-storage`] using `#[musli(packed)]` for example is roughly as compact diff --git a/crates/musli-descriptive/README.md b/crates/musli-descriptive/README.md index ddd8c15a9..caa2ba217 100644 --- a/crates/musli-descriptive/README.md +++ b/crates/musli-descriptive/README.md @@ -12,14 +12,15 @@ Descriptive encoding is fully upgrade stable: * ✔ Can tolerate missing fields if they are annotated with `#[musli(default)]`. * ✔ Can skip over unknown fields. - -Furthermore, it can be fully converted back and from to the [Value] type. - -This means that it's suitable as a wire and general interchange format, -since the data model can evolve independently among clients. Once some -clients are upgraded they will start sending unknown fields which -non-upgraded clients will be forced to skip over for the duration of the -upgrade. +* ✔ Can be fully converted back and forth between dynamic containers such as + the [Value] type. +* ✔ Can handle coercion from different types of primitive types, such as + signed to unsigned integers. So primitive field types can be assuming they + only inhabit compatible values. + +This means that it's suitable as a wire and general interchange format. It's +also suitable for dynamically translating to and from different wire formats +such as JSON without having access to the data model. ```rust use musli::{Encode, Decode}; diff --git a/crates/musli-descriptive/src/lib.rs b/crates/musli-descriptive/src/lib.rs index 6e72fb808..83154e33b 100644 --- a/crates/musli-descriptive/src/lib.rs +++ b/crates/musli-descriptive/src/lib.rs @@ -9,14 +9,15 @@ //! * ✔ Can tolerate missing fields if they are annotated with //! `#[musli(default)]`. //! * ✔ Can skip over unknown fields. -//! -//! Furthermore, it can be fully converted back and from to the [Value] type. -//! -//! This means that it's suitable as a wire and general interchange format, -//! since the data model can evolve independently among clients. Once some -//! clients are upgraded they will start sending unknown fields which -//! non-upgraded clients will be forced to skip over for the duration of the -//! upgrade. +//! * ✔ Can be fully converted back and forth between dynamic containers such as +//! the [Value] type. +//! * ✔ Can handle coercion from different types of primitive types, such as +//! signed to unsigned integers. So primitive field types can be assuming they +//! only inhabit compatible values. +//! +//! This means that it's suitable as a wire and general interchange format. It's +//! also suitable for dynamically translating to and from different wire formats +//! such as JSON without having access to the data model. //! //! ```rust //! use musli::{Encode, Decode}; diff --git a/crates/musli/README.md b/crates/musli/README.md index 098dadc4f..c41079849 100644 --- a/crates/musli/README.md +++ b/crates/musli/README.md @@ -205,7 +205,9 @@ types. `self` determines if the format is self-descriptive. Allowing the structure of the data to be fully reconstructed from its serialized state. These formats do not require models to decode and can be converted to and from -dynamic containers such as [`musli-value`] for introspection. +dynamic containers such as [`musli-value`] for introspection. Such formats +also allows for type-coercions to be performed, so that a signed number can +be correctly read as an unsigned number if it fits in the destination type. For every feature you drop, the format becomes more compact and efficient. [`musli-storage`] using `#[musli(packed)]` for example is roughly as compact diff --git a/crates/musli/src/lib.rs b/crates/musli/src/lib.rs index 327f38abc..fa96743ee 100644 --- a/crates/musli/src/lib.rs +++ b/crates/musli/src/lib.rs @@ -207,7 +207,9 @@ //! `self` determines if the format is self-descriptive. Allowing the structure //! of the data to be fully reconstructed from its serialized state. These //! formats do not require models to decode and can be converted to and from -//! dynamic containers such as [`musli-value`] for introspection. +//! dynamic containers such as [`musli-value`] for introspection. Such formats +//! also allows for type-coercions to be performed, so that a signed number can +//! be correctly read as an unsigned number if it fits in the destination type. //! //! For every feature you drop, the format becomes more compact and efficient. //! [`musli-storage`] using `#[musli(packed)]` for example is roughly as compact