Module serde_tagged::ser::internal

Serialization of internally tagged values.

Tagging values internally will embed the tag in the value. As the tag is being embedded in the value, not all types can be supported by this format (see section below).

This format is similar to the internally-tagged enum format provided by serde, however allows for various tag types (not only str and u32).

Warning

Deserialization of internally tagged values requires a self-describing data format.

Furthermore, neither serialize nor the Serializer check for collision of the tag-key with field-names or map-keys of the value with the tag-key. It is up to the caller to make sure that such collisions do not occur.

Supported types

Only the following types (of Serde’s data model) are supported by this tagging format:

• seq
  • Dynamically sized sequences.
  • The tag will be the first element of the sequence.
• tuple
  • Statically sized sequences.
  • The tag will be the first element of the tuple.
• map
  • Dynamically sized mappings.
  • The tag-key and tag pair will be added as (first) entry of the mapping:
• struct
  • Any normal struct (e.g. struct Name { ... }).
  • The tag will be added as first field under the specified name.
• unit struct
  • A struct without content (e.g. struct Unit;).
  • The struct will be serialized as normal struct and the tag will be added as first (and only) field under the specified name.
• newtype struct only if it contains a value that can be serialized with this format
  • A tuple struct contianing only a single value (e.g. struct Newtype(i32)).
  • The struct will be serialized as tuple struct and the tag will be added as first element of the tuple.
• tuple struct
  • A struct contianing multiple unnamed members (e.g. struct Tuple(i32, i32)).
  • The tag will be added as first element of the tuple.
• internally tagged enum: any variant
  • An enum with the #[serde(tag="<tag-key>")] attribute.
  • The tag will be added as first field under the specified name.
• adjacently tagged enum: any variant
  • An enum with the #[serde(tag="<tag-key>", content="<content-key>")] attribute.
  • The tag will be added as entry with the specified name as key to the generated mapping.
• untagged enum: tuple, non-primitive newtype, and struct variants only
  • An enum with the #[serde(untagged)] attribute.
  • The tag will be embedded using the previously elaborated rules corresponding to the respective variant type.

Primitive types and externally tagged enums are not supported.

Examples serializing to JSON

A Simple struct

Serializing a value foo with

#[derive(Serialize)]
struct Foo {
    bar: &'static str,
}

let foo = Foo { bar: "baz" };

let mut serializer = serde_json::Serializer::new(std::io::stdout());
serde_tagged::ser::internal::serialize(&mut serializer, "tag-key", "my-tag", &foo).unwrap();

with a tag-value of "my-tag" and a tag-field-name of "tag-key" will produce the following JSON output:

{
    "tag-key": "my-tag",
    "bar": "baz"
}

Structs

• Serializer
  A serializer that embeds a tag into to the provided value and then serializes it.

Functions

• serialize
  Embeds a tag into the specified value and then serializes it using the provided serializer.