1 unstable release
0.1.0 | Dec 9, 2023 |
---|
#165 in #identifier
Used in stringid
15KB
278 lines
stringid
The stringid
crate is a set of helpers (macros, structs, traits) to manage identifiers
both as human readable string and unique number efficiently. It can be useful for using
immutable strings that exist until the end of the application.
The unique identifier allows for light storage + fast comparison and copy operations. While the human readable string allows convenience use in UI, serialization, debug, etc.
Why use StringId
?
You can use StringId
where you would like use an immutable String
(or [str
]) as an identifier.
And particularly if this identifier is used in several place in the data.
Two advantages of StringId
are that :
- it does not duplicate the string data.
- it does not use string for comparison, assignation, copy of Id.
⚠ Warning
The use of StringId
with a StaticStrStore
can (safely) leak memory.
The memory allocated for the str
will not be released until the end of the program, like a 'static
variable.
So you probably should avoid to use StringId
with not immutable String
,
if the identifiers (String
/str
) are likely to change regularly. Or do it knowingly.
Typical uses can be :
- tags.
- inter-resources referencing, especially if you have to serialize/deserialize the data.
Technical design
The StringId
variables only store the identifier (a unique number).
While [str
] are stored separately, only one time in memory for all copy of one Id
and are accessible through a dedicated type.
The crate stringid
components are designed to be used with new-type pattern.
So some macros are accessible trough the module macros
to help define custom types.
To store correspondence between a StringId
and the corresponding [str
] use an implementation of StrLookup
.
StrLookupHashMap
implement StrLookup
with an std::collections::HashMap
and a StaticStrStore
.
For more details, look at respective documentations.
Quick start
use std::{mem::size_of, str::FromStr};
use stringid::macros::{strlookup_hashmap, StringIdImpl};
use stringid::{create_hash_map, BufferStrStore, StringId};
// Create a struct type `CustomIdLookup`
// as a `str` lookup with `BufferStrStore` as StrStore.
#[strlookup_hashmap(key = u32, store = BufferStrStore)]
struct CustomIdLookup;
// Create a `StringId` type who use the type `CustomIdLookup`
// as `StrLookup`.
#[derive(Debug, Clone, Copy, StringIdImpl)]
struct CustomId(StringId<u32, CustomIdLookup>);
// Create instances of CustomId from str
let id_1 = CustomId::from_str("Id1").unwrap();
let id_2 = CustomId::from_str("Id2").unwrap();
let id_1_bis = id_1;
let id_1_ter = CustomId::from_str("Id1").unwrap();
// CustomId size is the size of the Id (u32 here)
assert_eq!(size_of::<u32>(), size_of::<CustomId>());
// The Id1 and Id2 are not equal
assert_ne!(id_1,id_2);
// But the id_1 and id_1_bis are
assert_eq!(id_1,id_1_bis);
// as well as id_1 and id_1_ter
assert_eq!(id_1,id_1_ter);
License: LGPL-3.0-only
Dependencies
~255–700KB
~17K SLoC