the_key/
lib.rs

1//! This library provides easy api for key management for key-value storages
2//!
3//! # Example
4//! ```
5//! use the_key::*;
6//! // Define key parts
7//! define_key_part!(Users, &[11, 11]);
8//! define_key_part!(Profiles, &[22, 22]);
9//! define_key_part!(Photos, &[33, 33]);
10//!
11//! // Define keys sequences
12//! define_key_seq!(UsersProfiles, [Users, Profiles]);
13//! define_key_seq!(UsersPhotos, [Users, Photos]);
14//!
15//! fn main() {
16//!   let user_id = &[81, 81];
17//!   let profiles = UsersProfiles::new();
18//!   let photos = UsersPhotos::new().extend("UserId", user_id);
19//!
20//!   let user_profile_key = profiles.create_key(user_id);
21//!
22//!   // Debug example
23//!   assert_eq!(
24//!     format!("{:?}", user_profile_key),
25//!     "Users[11, 11] -> Profiles[22, 22] -> Key=[81, 81]",
26//!   );
27//!
28//!   // Pretty debug example
29//!   println!("{:#?}", user_profile_key);
30//!   // Users[11, 11]
31//!   // └ Profiles[22, 22]
32//!   //   └ Key=[81, 81]
33//!
34//!   assert_eq!(
35//!     format!("{:?}", photos),
36//!     "Users[11, 11] -> Photos[33, 33] -> UserId[81, 81]",
37//!   );
38//!
39//!   // User
40//!   assert_eq!(
41//!     user_profile_key.to_vec(),
42//!     vec![11, 11, 22, 22, 81, 81],
43//!   );
44//!
45//!   // User's one photo
46//!   assert_eq!(
47//!     photos.create_key(&[99, 99]).to_vec(),
48//!     vec![11, 11, 33, 33, 81, 81, 99, 99],
49//!   );
50//! }
51//! ```
52
53#![feature(test)]
54extern crate test;
55
56mod formatting;
57
58use formatting::format_struct;
59use std::marker::PhantomData;
60
61pub type KeyPartItem = (&'static str, &'static [u8]);
62pub type KeyExtensionsItem = (&'static str, Vec<u8>);
63
64pub trait KeyPart {
65  fn new() -> Self;
66
67  /// Returns key part name
68  fn get_name(&self) -> &'static str;
69
70  /// Returns key part bytes
71  fn get_bytes(&self) -> &'static [u8];
72}
73
74pub trait KeyPartsSequence: Clone {
75  #[doc(hidden)]
76  fn get_struct() -> Vec<KeyPartItem>;
77  #[doc(hidden)]
78  fn get_extensions(&self) -> Option<&[KeyExtensionsItem]>;
79
80  fn new() -> Self;
81
82  /// Extends key sequence with a new part
83  ///
84  /// # Example
85  /// ```
86  /// use the_key::*;
87  /// define_key_part!(Part1, &[10, 20]);
88  /// define_key_part!(Part2, &[30, 40]);
89  /// define_key_seq!(MyKeySeq, [Part1, Part2]);
90  ///
91  /// fn main() {
92  ///   let key_seq = MyKeySeq::new().extend("Part3", &[50, 60]);
93  ///
94  ///   assert_eq!(
95  ///     key_seq.to_vec(),
96  ///     vec![10, 20, 30, 40, 50, 60]
97  ///   )
98  /// }
99  /// ```
100  fn extend<B: AsRef<[u8]>>(self, key_part_name: &'static str, bytes: B) -> Self;
101
102  /// Creates new [`the_key::Key`][Key] object
103  ///
104  /// # Example
105  /// ```
106  /// use the_key::*;
107  /// define_key_part!(Part1, &[10, 20]);
108  /// define_key_part!(Part2, &[30, 40]);
109  /// define_key_seq!(MyKeySeq, [Part1, Part2]);
110  ///
111  /// fn main() {
112  ///   let key_seq = MyKeySeq::new();
113  ///   let key = key_seq.create_key(&[50, 60]);
114  ///
115  ///   assert_eq!(
116  ///     key.to_vec(),
117  ///     vec![10, 20, 30, 40, 50, 60],
118  ///   );
119  /// }
120  /// ```
121  fn create_key<T: AsRef<[u8]>>(&self, key: T) -> Key<Self>;
122
123  #[doc(hidden)]
124  fn fmt_debug(
125    &self,
126    parts: &[KeyPartItem],
127    extensions: Option<&[KeyExtensionsItem]>,
128    f: &mut std::fmt::Formatter<'_>,
129  ) -> std::fmt::Result {
130    format_struct(parts, extensions, None, f)
131  }
132}
133
134#[derive(Clone)]
135pub struct Key<'a, T: KeyPartsSequence> {
136  bytes: Vec<u8>,
137  key_len: usize,
138  extensions: Option<&'a [KeyExtensionsItem]>,
139  phantom: PhantomData<T>,
140}
141
142impl<'a, T: KeyPartsSequence> Key<'a, T> {
143  pub fn new(bytes: Vec<u8>, key_len: usize, extensions: Option<&'a [KeyExtensionsItem]>) -> Self {
144    Self {
145      bytes,
146      key_len,
147      extensions,
148      phantom: PhantomData,
149    }
150  }
151
152  /// Returns key bytes
153  pub fn get_key(&self) -> &[u8] {
154    &self.bytes[self.bytes.len() - self.key_len..]
155  }
156
157  /// Returns prefix bytes
158  pub fn get_prefix(&self) -> &[u8] {
159    &self.bytes[..self.bytes.len() - self.key_len]
160  }
161
162  /// Moves out key bytes
163  pub fn to_vec(self) -> Vec<u8> {
164    self.bytes
165  }
166}
167
168impl<'a, T: KeyPartsSequence> Into<Vec<u8>> for Key<'a, T> {
169  fn into(self) -> Vec<u8> {
170    self.to_vec()
171  }
172}
173
174impl<'a, T: KeyPartsSequence> std::fmt::Debug for Key<'a, T> {
175  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
176    format_struct(
177      T::get_struct().as_slice(),
178      self.extensions,
179      Some((self.bytes.as_slice(), self.bytes.len())),
180      f,
181    )
182  }
183}
184
185impl<'a, T: KeyPartsSequence> AsRef<[u8]> for Key<'a, T> {
186  fn as_ref(&self) -> &[u8] {
187    self.bytes.as_slice()
188  }
189}
190
191#[doc(hidden)]
192#[macro_export]
193macro_rules! count {
194  ($($name:ident),*) => {
195    {
196      let mut count = 0usize;
197      $(
198        let _ = stringify!($name);
199        count += 1;
200      )*
201      count
202    }
203  }
204}
205
206/// Defines a key part. Each key part is a uniq struct whose implement trait [`the_key::KeyPart`][KeyPart]
207///
208/// # Example
209/// ```
210/// use the_key::*;
211///
212/// define_key_part!(KeyPartName, "key_part_bytes".as_bytes());
213/// ```
214#[macro_export]
215macro_rules! define_key_part {
216  ($name:ident, $bytes:expr) => {
217    #[derive(Debug)]
218    pub struct $name {
219      key_part_name: &'static str,
220      bytes: &'static [u8],
221    }
222
223    impl KeyPart for $name {
224      fn new() -> Self {
225        $name::new()
226      }
227
228      fn get_name(&self) -> &'static str {
229        self.key_part_name
230      }
231
232      fn get_bytes(&self) -> &'static [u8] {
233        self.bytes
234      }
235    }
236
237    impl $name {
238      pub const fn new() -> Self {
239        const KEY_PART: &'static [u8] = $bytes;
240        const KEY_PART_NAME: &'static str = &stringify!($name);
241
242        Self {
243          key_part_name: &KEY_PART_NAME,
244          bytes: &KEY_PART,
245        }
246      }
247    }
248  };
249}
250
251/// Defines a key sequence. Each key part is a uniq struct whose implement trait [`the_key::KeyPartsSequence`][KeyPartsSequence]
252///
253/// # Example
254/// ```
255/// use the_key::*;
256///
257/// define_key_part!(KeyPart1, "key_part_1".as_bytes());
258/// define_key_part!(KeyPart2, "key_part_2".as_bytes());
259/// define_key_seq!(KeyPartsSeq, [KeyPart1, KeyPart2]);
260/// ```
261#[macro_export]
262macro_rules! define_key_seq {
263  ($name:ident, [$($key_part:ident),*]) => {
264    #[derive(Clone)]
265    pub struct $name {
266      parts: [KeyPartItem; $crate::count!($($key_part),*)],
267      extensions: Option<Vec<KeyExtensionsItem>>,
268      len: usize,
269    }
270
271    impl $name {
272      pub fn new() -> Self {
273        let mut len = 0;
274        let parts: [KeyPartItem; $crate::count!($($key_part),*)] = [
275          $({
276            let key_part = $key_part::new();
277            let bytes = key_part.get_bytes();
278
279            len += bytes.len();
280
281            (key_part.get_name(), bytes)
282          },)*
283        ];
284
285        Self {
286          len,
287          parts,
288          extensions: None,
289        }
290      }
291
292      // This just a public api
293      #[allow(dead_code)]
294      pub fn to_vec(&self) -> Vec<u8> {
295        self.create_key(&[]).to_vec()
296      }
297    }
298
299    impl KeyPartsSequence for $name {
300      fn new() -> Self {
301        $name::new()
302      }
303
304      fn get_struct() -> Vec<KeyPartItem> {
305        let mut parts = Vec::new();
306
307        $({
308          let key = $key_part::new();
309          parts.push((key.get_name(), key.get_bytes()));
310        })*
311
312        parts
313      }
314
315      fn get_extensions(&self) -> Option<&[KeyExtensionsItem]> {
316        self.extensions.as_ref().map(|v| v.as_slice())
317      }
318
319      fn extend<B: AsRef<[u8]>>(mut self, key_part_name: &'static str, bytes: B) -> Self {
320        let key_bytes = bytes.as_ref().to_vec();
321        self.len += key_bytes.len();
322
323        self.extensions = match self.extensions {
324          Some(mut extensions) => {
325            extensions.push((key_part_name, key_bytes));
326
327            Some(extensions)
328          },
329          None => Some(vec![(key_part_name, key_bytes)]),
330        };
331
332        self
333      }
334
335      fn create_key<T: AsRef<[u8]>>(&self, key: T) -> Key<Self> {
336        let key = key.as_ref();
337        let mut result_key: Vec<u8> = Vec::with_capacity(self.len + key.len());
338
339        self.parts.iter().for_each(|(_, bytes)| {
340          result_key.extend_from_slice(bytes);
341        });
342
343        if let Some(extensions) = &self.extensions {
344          extensions.iter().for_each(|(_, bytes)| {
345            result_key.extend_from_slice(bytes);
346          });
347        }
348
349        result_key.extend_from_slice(key);
350
351        Key::new(
352          result_key,
353          key.len(),
354          self.extensions.as_ref().map(|v| v.as_slice())
355        )
356      }
357    }
358
359    impl std::fmt::Debug for $name {
360      fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
361        self.fmt_debug(
362          &self.parts,
363          self.extensions.as_ref().map(|v| v.as_slice()),
364          f
365        )
366      }
367    }
368  };
369}
370
371#[cfg(test)]
372mod tests {
373  use super::*;
374  use test::Bencher;
375
376  #[test]
377  fn key_part_test() {
378    define_key_part!(KeyPart1, "my_key_part_1".as_bytes());
379
380    let kp = KeyPart1::new();
381
382    assert_eq!(
383      kp.get_name(),
384      "KeyPart1",
385    );
386
387    assert_eq!(
388      kp.get_bytes(),
389      b"my_key_part_1",
390    );
391  }
392
393  #[test]
394  fn key_from_seq_test() {
395    define_key_part!(KeyPart1, &[10, 20]);
396    define_key_part!(KeyPart2, &[30, 40]);
397    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
398
399    assert_eq!(
400      MyPrefixSeq::new().create_key(&[50, 60]).to_vec(),
401      vec![10, 20, 30, 40, 50, 60],
402    )
403  }
404
405  #[test]
406  fn key_get_key_test() {
407    define_key_part!(KeyPart1, &[10, 20]);
408    define_key_part!(KeyPart2, &[30, 40]);
409    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
410
411    let key_seq = MyPrefixSeq::new();
412    let key = key_seq.create_key(&[70, 80]);
413
414    let expected: &[u8] = &[70, 80];
415    assert_eq!(key.get_key(), expected);
416  }
417
418  #[test]
419  fn key_get_prefix_test() {
420    define_key_part!(KeyPart1, &[10, 20]);
421    define_key_part!(KeyPart2, &[30, 40]);
422    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
423
424    let key_seq = MyPrefixSeq::new();
425    let key = key_seq.create_key(&[70, 80]);
426
427    assert_eq!(key.get_prefix(), &[10, 20, 30, 40])
428  }
429
430  #[test]
431  fn key_seq_debug() {
432    define_key_part!(KeyPart1, &[10, 20]);
433    define_key_part!(KeyPart2, &[30, 40]);
434    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
435
436    assert_eq!(
437      format!("{:?}", MyPrefixSeq::new()),
438      "KeyPart1[10, 20] -> KeyPart2[30, 40]".to_string(),
439    );
440  }
441
442  #[test]
443  fn key_seq_pretty_debug() {
444    define_key_part!(KeyPart1, &[10, 20]);
445    define_key_part!(KeyPart2, &[30, 40]);
446    define_key_part!(KeyPart3, &[50, 60]);
447    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2, KeyPart3]);
448
449    assert_eq!(
450      format!("{:#?}", MyPrefixSeq::new()),
451      "KeyPart1[10, 20]\n  └ KeyPart2[30, 40]\n    └ KeyPart3[50, 60]",
452    );
453  }
454
455  #[test]
456  fn key_seq_extend() {
457    define_key_part!(KeyPart1, &[10, 20]);
458    define_key_part!(KeyPart2, &[30, 40]);
459    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
460
461    let key_seq = MyPrefixSeq::new()
462      .extend("ExtensionPart1", &[50, 60])
463      .extend("ExtensionPart2", &[70, 80]);
464
465    assert_eq!(
466      format!("{:#?}", key_seq),
467      "KeyPart1[10, 20]\n  └ KeyPart2[30, 40]\n    └ ExtensionPart1[50, 60]\n      └ ExtensionPart2[70, 80]",
468    );
469
470    let key = key_seq.create_key(&[90, 100]);
471
472    assert_eq!(key.as_ref(), &[10, 20, 30, 40, 50, 60, 70, 80, 90, 100],);
473
474    assert_eq!(
475      format!("{:?}", key),
476      "KeyPart1[10, 20] -> KeyPart2[30, 40] -> ExtensionPart1[50, 60] -> ExtensionPart2[70, 80] -> Key=[90, 100]",
477    );
478  }
479
480  // Benches
481
482  #[bench]
483  fn bench_key_parts_spawning(b: &mut Bencher) {
484    define_key_part!(KeyPart1, "key_part_1".as_bytes());
485    define_key_part!(KeyPart2, "key_part_2".as_bytes());
486    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
487
488    b.iter(|| {
489      MyPrefixSeq::new();
490    })
491  }
492
493  #[bench]
494  fn bench_key_parts_extending(b: &mut Bencher) {
495    define_key_part!(KeyPart1, "key_part_1".as_bytes());
496    define_key_part!(KeyPart2, "key_part_2".as_bytes());
497    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
498
499    b.iter(|| {
500      MyPrefixSeq::new().extend("KeyPart3", "key_part_3".as_bytes())
501    })
502  }
503
504  #[bench]
505  fn bench_create_key(b: &mut Bencher) {
506    define_key_part!(KeyPart1, "key_part_1".as_bytes());
507    define_key_part!(KeyPart2, "key_part_2".as_bytes());
508    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
509
510    let seq = &MyPrefixSeq::new();
511
512    b.iter(|| {
513      seq.create_key("some_key".as_bytes());
514    })
515  }
516
517  #[bench]
518  fn bench_create_key_with_extending(b: &mut Bencher) {
519    define_key_part!(KeyPart1, "key_part_1".as_bytes());
520    define_key_part!(KeyPart2, "key_part_2".as_bytes());
521    define_key_seq!(MyPrefixSeq, [KeyPart1, KeyPart2]);
522
523    b.iter(|| {
524      let seq = MyPrefixSeq::new().extend("KeyPart3", "key_part_3");
525      seq.create_key("some_key".as_bytes());
526    })
527  }
528}
the_key/lib.rs

the_key/
lib.rs
