Module ambient_api::global::serde::ser

source ·
Expand description

Generic data structure serialization framework.

The two most important traits in this module are Serialize and Serializer.

  • A type that implements Serialize is a data structure that can be serialized to any data format supported by Serde, and conversely
  • A type that implements Serializer is a data format that can serialize any data structure supported by Serde.

The Serialize trait

Serde provides Serialize implementations for many Rust primitive and standard library types. The complete list is below. All of these can be serialized using Serde out of the box.

Additionally, Serde provides a procedural macro called serde_derive to automatically generate Serialize implementations for structs and enums in your program. See the derive section of the manual for how to use this.

In rare cases it may be necessary to implement Serialize manually for some type in your program. See the Implementing Serialize section of the manual for more about this.

Third-party crates may provide Serialize implementations for types that they expose. For example the linked-hash-map crate provides a LinkedHashMap<K, V> type that is serializable by Serde because the crate provides an implementation of Serialize for it.

The Serializer trait

Serializer implementations are provided by third-party crates, for example serde_json, serde_yaml and postcard.

A partial list of well-maintained formats is given on the Serde website.

Implementations of Serialize provided by Serde

  • Primitive types:
    • bool
    • i8, i16, i32, i64, i128, isize
    • u8, u16, u32, u64, u128, usize
    • f32, f64
    • char
    • str
    • &T and &mut T
  • Compound types:
    • [T]
    • [T; 0] through [T; 32]
    • tuples up to size 16
  • Common standard library types:
    • String
    • Option<T>
    • Result<T, E>
    • PhantomData<T>
  • Wrapper types:
    • Box<T>
    • Cow<’a, T>
    • Cell<T>
    • RefCell<T>
    • Mutex<T>
    • RwLock<T>
    • Rc<T> (if features = [“rc”] is enabled)
    • Arc<T> (if features = [“rc”] is enabled)
  • Collection types:
    • BTreeMap<K, V>
    • BTreeSet<T>
    • BinaryHeap<T>
    • HashMap<K, V, H>
    • HashSet<T, H>
    • LinkedList<T>
    • VecDeque<T>
    • Vec<T>
  • FFI types:
    • CStr
    • CString
    • OsStr
    • OsString
  • Miscellaneous standard library types:
    • Duration
    • SystemTime
    • Path
    • PathBuf
    • Range<T>
    • RangeInclusive<T>
    • Bound<T>
    • num::NonZero*
    • ! (unstable)
  • Net types:
    • IpAddr
    • Ipv4Addr
    • Ipv6Addr
    • SocketAddr
    • SocketAddrV4
    • SocketAddrV6

Structs

  • Impossible
    Helper type for implementing a Serializer that does not support serializing one of the compound types.

Traits

  • Error
    Trait used by Serialize implementations to generically construct errors belonging to the Serializer against which they are currently running.
  • Serialize
    A data structure that can be serialized into any data format supported by Serde.
  • SerializeMap
    Returned from Serializer::serialize_map.
  • SerializeSeq
    Returned from Serializer::serialize_seq.
  • SerializeStruct
    Returned from Serializer::serialize_struct.
  • SerializeStructVariant
    Returned from Serializer::serialize_struct_variant.
  • SerializeTuple
    Returned from Serializer::serialize_tuple.
  • SerializeTupleStruct
    Returned from Serializer::serialize_tuple_struct.
  • SerializeTupleVariant
    Returned from Serializer::serialize_tuple_variant.
  • Serializer
    A data format that can serialize any data structure supported by Serde.
  • StdError
    Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<T, E>.