serde_hashkey/
key.rs

Help
1//! In-memory value representation for values.
2use crate::float::{FloatPolicy, FloatRepr, RejectFloatPolicy};
3use serde::{de, ser};
4use std::fmt;
5use std::hash::Hash;
6use std::marker;
7use std::mem;
8
9/// An opaque integer.
10#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
11pub enum Integer {
12    /// Variant representing a `i8` integer.
13    I8(i8),
14    /// Variant representing a `i16` integer.
15    I16(i16),
16    /// Variant representing a `i32` integer.
17    I32(i32),
18    /// Variant representing a `i64` integer.
19    I64(i64),
20    /// Variant representing a `i128` integer.
21    I128(i128),
22    /// Variant representing a `u8` integer.
23    U8(u8),
24    /// Variant representing a `u16` integer.
25    U16(u16),
26    /// Variant representing a `u32` integer.
27    U32(u32),
28    /// Variant representing a `u64` integer.
29    U64(u64),
30    /// Variant representing a `u128` integer.
31    U128(u128),
32}
33
34/// An opaque float derived from a given policy.
35#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
36pub enum Float<F>
37where
38    F: FloatPolicy,
39{
40    /// Variant representing a `f32` float.
41    F32(F::F32),
42    /// Variant representing a `f64` float.
43    F64(F::F64),
44}
45
46/// The central key type, which is an in-memory representation of all supported
47/// serde-serialized values.
48///
49/// This can be serialized to a type implementing [serde::Deserialize] using
50/// [from_key], and deserialized from a type implementing [serde::Serialize]
51/// using [to_key]. See the corresponding function for documentation.
52///
53/// The type parameter `F` corresponds to the [FloatPolicy] in used. It defaults
54/// to [RejectFloatPolicy] which will cause floats to be rejected.
55///
56/// [from_key]: crate::from_key
57/// [to_key]: crate::to_key
58///
59/// # Examples
60///
61/// ```
62/// use serde_derive::{Deserialize, Serialize};
63/// use serde_hashkey::{to_key, to_key_with_ordered_float};
64///
65/// #[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
66/// struct Author {
67///     name: String,
68///     age: u32,
69/// }
70///
71/// # fn main() -> Result<(), serde_hashkey::Error> {
72/// let key = to_key(&Author {
73///     name: String::from("Jane Doe"),
74///     age: 42,
75/// })?;
76///
77/// // Note: serializing floats will fail under the default policy, but succeed
78/// // under one supporting floats.
79/// assert!(to_key(&42.0f32).is_err());
80/// assert!(to_key_with_ordered_float(&42.0f32).is_ok());
81/// # Ok(()) }
82/// ```
83#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
84pub enum Key<F = RejectFloatPolicy>
85where
86    F: FloatPolicy,
87{
88    /// A unit value.
89    Unit,
90    /// A boolean value.
91    Bool(bool),
92    /// An integer.
93    Integer(Integer),
94    /// A 32-bit floating-point number.
95    Float(Float<F>),
96    /// A byte array.
97    Bytes(Box<[u8]>),
98    /// A string.
99    String(Box<str>),
100    /// A vector.
101    Seq(Box<[Key<F>]>),
102    /// A map.
103    Map(Box<[(Key<F>, Key<F>)]>),
104}
105
106impl Default for Key {
107    fn default() -> Self {
108        Self::Unit
109    }
110}
111
112impl<F> Key<F> 
113where F: FloatPolicy + Ord
114{
115    /// Normalize the key, making sure that all contained maps are sorted.
116    pub fn normalize(self) -> Self {
117        match self {
118            Key::<F>::Seq(mut vec) => {
119                for value in vec.iter_mut() {
120                    *value = mem::replace(value, Key::<F>::Unit).normalize();
121                }
122
123                Key::<F>::Seq(vec)
124            }
125            Key::<F>::Map(mut map) => {
126                for (key, value) in map.iter_mut() {
127                    *key = mem::replace(key, Key::<F>::Unit).normalize();
128                    *value = mem::replace(value, Key::<F>::Unit).normalize();
129                }
130
131                map.sort_by(|a, b| a.0.cmp(&b.0));
132                Key::<F>::Map(map)
133            }
134            other => other,
135        }
136    }
137}
138
139macro_rules! impl_integer_from {
140    ($variant:ident, $for_type:ty) => {
141        impl<F> From<$for_type> for Key<F>
142        where
143            F: FloatPolicy,
144        {
145            fn from(v: $for_type) -> Key<F> {
146                Key::Integer(Integer::$variant(v))
147            }
148        }
149    };
150}
151
152macro_rules! impl_from {
153    ($variant:path, $for_type:ty) => {
154        impl<F> From<$for_type> for Key<F>
155        where
156            F: FloatPolicy,
157        {
158            fn from(v: $for_type) -> Key<F> {
159                $variant(v.into())
160            }
161        }
162    };
163}
164
165impl_integer_from!(I8, i8);
166impl_integer_from!(I16, i16);
167impl_integer_from!(I32, i32);
168impl_integer_from!(I64, i64);
169impl_integer_from!(I128, i128);
170impl_integer_from!(U8, u8);
171impl_integer_from!(U16, u16);
172impl_integer_from!(U32, u32);
173impl_integer_from!(U64, u64);
174impl_integer_from!(U128, u128);
175
176impl_from!(Key::Bool, bool);
177impl_from!(Key::Bytes, Vec<u8>);
178impl_from!(Key::String, String);
179impl_from!(Key::Seq, Vec<Key<F>>);
180impl_from!(Key::Map, Vec<(Key<F>, Key<F>)>);
181
182/// Serialize implementation for a [Key].
183///
184/// This allows keys to be serialized immediately.
185///
186/// # Examples
187///
188/// ```
189/// use serde_derive::Serialize;
190/// use serde_hashkey::{Key, OrderedFloatPolicy, OrderedFloat, Float};
191///
192/// #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
193/// struct Foo {
194///     key: Key<OrderedFloatPolicy>,
195/// }
196///
197/// # fn main() -> Result<(), serde_json::Error> {
198/// let foo: String = serde_json::to_string(&Foo { key: Key::Float(Float::F64(OrderedFloat(42.42f64))) })?;
199///
200/// assert_eq!(foo, "{\"key\":42.42}");
201/// Ok(())
202/// # }
203/// ```
204impl<F> ser::Serialize for Key<F>
205where
206    F: FloatPolicy,
207{
208    #[inline]
209    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
210    where
211        S: ser::Serializer,
212    {
213        match self {
214            Key::Unit => serializer.serialize_unit(),
215            Key::Integer(Integer::U8(v)) => serializer.serialize_u8(*v),
216            Key::Integer(Integer::U16(v)) => serializer.serialize_u16(*v),
217            Key::Integer(Integer::U32(v)) => serializer.serialize_u32(*v),
218            Key::Integer(Integer::U64(v)) => serializer.serialize_u64(*v),
219            Key::Integer(Integer::U128(v)) => serializer.serialize_u128(*v),
220            Key::Integer(Integer::I8(v)) => serializer.serialize_i8(*v),
221            Key::Integer(Integer::I16(v)) => serializer.serialize_i16(*v),
222            Key::Integer(Integer::I32(v)) => serializer.serialize_i32(*v),
223            Key::Integer(Integer::I64(v)) => serializer.serialize_i64(*v),
224            Key::Integer(Integer::I128(v)) => serializer.serialize_i128(*v),
225            Key::Float(Float::F32(float)) => float.serialize(serializer),
226            Key::Float(Float::F64(float)) => float.serialize(serializer),
227            Key::Bytes(v) => serializer.serialize_bytes(v),
228            Key::String(v) => serializer.serialize_str(v),
229            Key::Seq(v) => v.serialize(serializer),
230            Key::Map(m) => {
231                use self::ser::SerializeMap as _;
232
233                let mut map = serializer.serialize_map(Some(m.len()))?;
234
235                for (k, v) in m.iter() {
236                    map.serialize_key(k)?;
237                    map.serialize_value(v)?;
238                }
239
240                map.end()
241            }
242            Key::Bool(v) => serializer.serialize_bool(*v),
243        }
244    }
245}
246
247/// Deserialize implementation for a [Key].
248///
249/// This allows keys to be serialized immediately.
250///
251/// # Examples
252///
253/// ```
254/// use serde_derive::Deserialize;
255/// use serde_hashkey::{Key, OrderedFloatPolicy};
256///
257/// #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Deserialize)]
258/// struct Foo {
259///     key: Key<OrderedFloatPolicy>,
260/// }
261///
262/// # fn main() -> Result<(), serde_json::Error> {
263/// let foo: Foo = serde_json::from_str("{\"key\": 42.42}")?;
264///
265/// assert!(matches!(foo.key, Key::Float(..)));
266/// Ok(())
267/// # }
268/// ```
269impl<'de, F> de::Deserialize<'de> for Key<F>
270where
271    F: FloatPolicy,
272{
273    #[inline]
274    fn deserialize<D>(deserializer: D) -> Result<Key<F>, D::Error>
275    where
276        D: de::Deserializer<'de>,
277    {
278        struct ValueVisitor<F>(marker::PhantomData<F>)
279        where
280            F: FloatPolicy;
281
282        impl<'de, F> de::Visitor<'de> for ValueVisitor<F>
283        where
284            F: FloatPolicy,
285        {
286            type Value = Key<F>;
287
288            fn expecting(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
289                fmt.write_str("any valid key")
290            }
291
292            #[inline]
293            fn visit_str<E>(self, s: &str) -> Result<Self::Value, E>
294            where
295                E: de::Error,
296            {
297                Ok(Key::String(s.into()))
298            }
299
300            #[inline]
301            fn visit_string<E>(self, s: String) -> Result<Self::Value, E>
302            where
303                E: de::Error,
304            {
305                Ok(Key::String(s.into()))
306            }
307
308            #[inline]
309            fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>
310            where
311                E: de::Error,
312            {
313                self.visit_byte_buf(v.to_owned())
314            }
315
316            #[inline]
317            fn visit_byte_buf<E>(self, v: Vec<u8>) -> Result<Self::Value, E>
318            where
319                E: de::Error,
320            {
321                Ok(Key::Bytes(v.into()))
322            }
323
324            #[inline]
325            fn visit_i8<E>(self, v: i8) -> Result<Self::Value, E>
326            where
327                E: de::Error,
328            {
329                Ok(v.into())
330            }
331
332            #[inline]
333            fn visit_i16<E>(self, v: i16) -> Result<Self::Value, E>
334            where
335                E: de::Error,
336            {
337                Ok(v.into())
338            }
339
340            #[inline]
341            fn visit_i32<E>(self, v: i32) -> Result<Self::Value, E>
342            where
343                E: de::Error,
344            {
345                Ok(v.into())
346            }
347
348            #[inline]
349            fn visit_i64<E>(self, v: i64) -> Result<Self::Value, E>
350            where
351                E: de::Error,
352            {
353                Ok(v.into())
354            }
355
356            #[inline]
357            fn visit_i128<E>(self, v: i128) -> Result<Self::Value, E>
358            where
359                E: de::Error,
360            {
361                Ok(v.into())
362            }
363
364            #[inline]
365            fn visit_u8<E>(self, v: u8) -> Result<Self::Value, E>
366            where
367                E: de::Error,
368            {
369                Ok(v.into())
370            }
371
372            #[inline]
373            fn visit_u16<E>(self, v: u16) -> Result<Self::Value, E>
374            where
375                E: de::Error,
376            {
377                Ok(v.into())
378            }
379
380            #[inline]
381            fn visit_u32<E>(self, v: u32) -> Result<Self::Value, E>
382            where
383                E: de::Error,
384            {
385                Ok(v.into())
386            }
387
388            #[inline]
389            fn visit_u64<E>(self, v: u64) -> Result<Self::Value, E>
390            where
391                E: de::Error,
392            {
393                Ok(v.into())
394            }
395
396            #[inline]
397            fn visit_u128<E>(self, v: u128) -> Result<Self::Value, E>
398            where
399                E: de::Error,
400            {
401                Ok(v.into())
402            }
403
404            #[inline]
405            fn visit_f32<E>(self, v: f32) -> Result<Self::Value, E>
406            where
407                E: de::Error,
408            {
409                Ok(Key::Float(Float::F32(
410                    <F::F32 as FloatRepr<f32>>::serialize(v).map_err(E::custom)?,
411                )))
412            }
413
414            #[inline]
415            fn visit_f64<E>(self, v: f64) -> Result<Self::Value, E>
416            where
417                E: de::Error,
418            {
419                Ok(Key::Float(Float::F64(
420                    <F::F64 as FloatRepr<f64>>::serialize(v).map_err(E::custom)?,
421                )))
422            }
423
424            #[inline]
425            fn visit_bool<E>(self, v: bool) -> Result<Self::Value, E>
426            where
427                E: de::Error,
428            {
429                Ok(Key::Bool(v))
430            }
431
432            #[inline]
433            fn visit_none<E>(self) -> Result<Self::Value, E>
434            where
435                E: de::Error,
436            {
437                self.visit_unit()
438            }
439
440            #[inline]
441            fn visit_unit<E>(self) -> Result<Self::Value, E>
442            where
443                E: de::Error,
444            {
445                Ok(Key::Unit)
446            }
447
448            #[inline]
449            fn visit_seq<V>(self, mut visitor: V) -> Result<Self::Value, V::Error>
450            where
451                V: de::SeqAccess<'de>,
452            {
453                let mut vec = visitor
454                    .size_hint()
455                    .map(Vec::with_capacity)
456                    .unwrap_or_default();
457
458                while let Some(elem) = visitor.next_element()? {
459                    vec.push(elem);
460                }
461
462                Ok(Key::Seq(vec.into()))
463            }
464
465            #[inline]
466            fn visit_map<V>(self, mut visitor: V) -> Result<Self::Value, V::Error>
467            where
468                V: de::MapAccess<'de>,
469            {
470                let mut map = visitor
471                    .size_hint()
472                    .map(Vec::with_capacity)
473                    .unwrap_or_default();
474
475                while let Some((key, value)) = visitor.next_entry()? {
476                    map.push((key, value));
477                }
478
479                Ok(Key::Map(map.into()))
480            }
481        }
482
483        deserializer.deserialize_any(ValueVisitor::<F>(marker::PhantomData))
484    }
485}
486
487#[cfg(test)]
488mod tests {
489    use crate::RejectFloatPolicy;
490
491    use super::Key;
492
493    #[test]
494    fn assert_default() {
495        assert_eq!(Key::Unit, Key::default());
496    }
497
498    #[test]
499    fn assert_impls() {
500        assert_eq::<Key<RejectFloatPolicy>>();
501        assert_hash::<Key<RejectFloatPolicy>>();
502        assert_ord::<Key<RejectFloatPolicy>>();
503
504        #[cfg(feature = "ordered-float")]
505        {
506            use crate::OrderedFloatPolicy;
507
508            assert_eq::<Key<OrderedFloatPolicy>>();
509            assert_hash::<Key<OrderedFloatPolicy>>();
510            assert_ord::<Key<OrderedFloatPolicy>>();
511        }
512
513        fn assert_eq<T: std::cmp::Eq>() {}
514        fn assert_hash<T: std::hash::Hash>() {}
515        fn assert_ord<T: std::cmp::Ord>() {}
516    }
517}
serde_hashkey/key.rs

serde_hashkey/
key.rs
