ulys 31.0.1

a Universally Unique Lexicographically Sortable Identifier implementation, with a checksum
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

//! Serialization and deserialization.
//!
//! By default, serialization and deserialization go through ULYSes 26-character
//! canonical string representation as set by the ULID standard.
//!
//! ULYSes can optionally be serialized as u128 integers using the `ulys_as_u128`
//! module. See the module's documentation for examples.

use crate::Ulys;
use base32::Alphabet;
use serde::{Deserialize, Deserializer, Serialize, Serializer};

/// Serializes a ULYS as a base32 string.
///
/// # Errors
///
/// This function will return an error if the ULYS cannot be serialized as a base32 string.
impl Serialize for Ulys {
	fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
	where
		S: Serializer,
	{
		base32::encode(Alphabet::Crockford, &self.0.to_be_bytes())
			.to_lowercase()
			.serialize(serializer)
	}
}

/// Deserializes a ULYS from a base32 string.
///
/// # Errors
///
/// This function will return an error if the ULYS is not a valid base32 string.
impl<'de> Deserialize<'de> for Ulys {
	fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
	where
		D: Deserializer<'de>,
	{
		let deserialized_str = String::deserialize(deserializer)?;
		Self::from_string(&deserialized_str).map_err(serde::de::Error::custom)
	}
}

/// Serialization and deserialization of ULYSes through their inner u128 type.
///
/// To use it, annotate a field with
/// `#[serde(with = "ulys_as_u128")]`,
/// `#[serde(serialize_with = "ulys_as_u128")]`, or
/// `#[serde(deserialize_with = "ulys_as_u128")]`.
///
/// # Examples
/// ```
/// # use ulys::Ulys;
/// # use ulys::serde::ulys_as_u128;
/// # use serde_derive::{Serialize, Deserialize};
/// #[derive(Serialize, Deserialize)]
/// struct U128Example {
///     #[serde(with = "ulys_as_u128")]
///     identifier: Ulys
/// }
/// ```
pub mod ulys_as_u128 {
	use crate::Ulys;
	use serde::{Deserialize, Deserializer, Serialize, Serializer};

	/// Serializes a ULYS as a u128 type.
	///
	/// # Errors
	///
	/// This function will return an error if the ULYS cannot be serialized as a u128 value.
	pub fn serialize<S>(value: &Ulys, serializer: S) -> Result<S::Ok, S::Error>
	where
		S: Serializer,
	{
		value.0.serialize(serializer)
	}

	/// Deserializes a ULYS from a u128 type.
	///
	/// # Errors
	///
	/// This function will return an error if the ULYS is not a valid u128 value.
	pub fn deserialize<'de, D>(deserializer: D) -> Result<Ulys, D::Error>
	where
		D: Deserializer<'de>,
	{
		let deserialized_u128 = u128::deserialize(deserializer)?;
		Ok(Ulys(deserialized_u128))
	}
}

/// Serialization and deserialization of ULYSes through UUID strings.
///
/// To use this module, annotate a field with
/// `#[serde(with = "ulys_as_uuid")]`,
/// `#[serde(serialize_with = "ulys_as_uuid")]`, or
/// `#[serde(deserialize_with = "ulys_as_uuid")]`.
///
/// # Examples
/// ```
/// # use ulys::Ulys;
/// # use ulys::serde::ulys_as_uuid;
/// # use serde_derive::{Serialize, Deserialize};
/// #[derive(Serialize, Deserialize)]
/// struct UuidExample {
///     #[serde(with = "ulys_as_uuid")]
///     identifier: Ulys
/// }
/// ```
pub mod ulys_as_uuid {
	use crate::Ulys;
	use serde::{Deserialize, Deserializer, Serialize, Serializer};
	use uuid::Uuid;

	/// Converts the ULYS to a UUID and serializes it as a string.
	///
	/// # Errors
	///
	/// This function will return an error if the ULYS cannot be serialized as a UUID string.
	pub fn serialize<S>(value: &Ulys, serializer: S) -> Result<S::Ok, S::Error>
	where
		S: Serializer,
	{
		let uuid: Uuid = (*value).into();
		uuid.to_string().serialize(serializer)
	}

	/// Deserializes a ULYS from a string containing a UUID.
	///
	/// # Errors
	///
	/// This function will return an error if the ULYS is not a valid UUID string.
	pub fn deserialize<'de, D>(deserializer: D) -> Result<Ulys, D::Error>
	where
		D: Deserializer<'de>,
	{
		let de_string = String::deserialize(deserializer)?;
		let de_uuid = Uuid::parse_str(&de_string).map_err(serde::de::Error::custom)?;
		Ok(Ulys::from(de_uuid))
	}
}