# serde-ordered-collections
A serialization function, intended for use with serde_derive's `serialize_with`
annotation, which sorts the entries in a map- or list-like structure during
serialization according to the key's `Ord` implementation.
This library supports anything implementing `IntoIterator<Item = (K, V)>` for
`K: Ord`, or `IntoIterator<Item = V>` for `V: Ord`. Examples include `std::collections::HashMap`
and `std::collections::HashSet`, respectively.
In addition to producing a sorted list, which may be convenient for human
consumption, this also ensures that the serialized output is deterministic.
`HashMap`/`HashSet`, by default, will be ordered non-deterministically due to
its implicit random seeding; this makes it inappropriate when consistent output
matters.
## Usage
Add the following annotation to your `HashMap` (or other map-like) field:
```rust ignore
#[serde(serialize_with = "serde_ordered_collections::map::sorted_serialize")]
```
Or the equivalent for a `HashSet` (or list-like):
```rust ignore
#[serde(serialize_with = "serde_ordered_collections::flat::sorted_serialize")]
```
If you were previously serializing a plain `HashMap` rather than a custom type,
the easiest way to use this helper is to wrap your `HashMap` in a new
single-field struct and then apply `flatten` as follows:
```rust ignore
#[serde(flatten, serialize_with = "serde_ordered_collections::map::sorted_serialize")]
```
### Complete example using `HashMap`
```rust
use std::collections::HashMap;
use serde_derive::{Deserialize, Serialize};
#[derive(Debug, Serialize)]
struct SampleData {
#[serde(serialize_with = "serde_ordered_collections::map::sorted_serialize")]
values: HashMap<String, String>,
}
let sample_instance = SampleData {
values: {
let mut map = HashMap::new();
map.insert("c".into(), "ghi".into());
map.insert("a".into(), "abc".into());
map.insert("b".into(), "def".into());
map
},
};
let serialized_string = serde_yaml::to_string(&sample_instance).unwrap();
assert_eq!(&serialized_string, "\
---
values:
a: abc
b: def
c: ghi
");
```