caretta_id/lib.rs
1//! > **This crate has been renamed to [`grain-id`](https://crates.io/crates/grain-id).**
2//! > Please migrate to `grain-id` — it is a drop-in replacement with the same functionality.
3//! > `caretta-id` will no longer receive updates.
4//!
5//! A human-friendly 7 characters identifier format (e.g. `123abcd`).
6//!
7//! For a language agnostic specification of the caretta-id format, see [SPECS.md](https://github.com/fluo10/caretta-id/blob/main/SPECS.md)
8//!
9//! # Quick Start
10//! ```rust
11//! use caretta_id::CarettaId;
12//!
13//! let id = CarettaId::random();
14//! println!("{}", id); // e.g. "123abcd"
15//! ```
16//!
17//! # Why caretta-id?
18//!
19//! Traditional identifier systems face challenges in distributed environments:
20//!
21//! - **Sequential numbers** (like GitHub issue numbers) cause collisions in distributed systems
22//! - **UUIDs** are too long and not human-friendly
23//! - **Short hashes** (like Git commit hashes) lack standardization
24//!
25//! caretta-id bridges the gap between human readability and technical requirements.
26//!
27//! # Installation
28//!
29//! Add this to your `Cargo.toml`:
30//! ```toml
31//! [dependencies]
32//! caretta-id = "0.12.0"
33//!
34//! # With optional features
35//! caretta-id = { version = "0.11.0", features = ["arbitrary", "serde", "rusqlite", "sea-orm", "prost", "redb", "schemars"] }
36//! ```
37//!
38//! ## For no_std Environments
39//!
40//! This crate support `no_std`.
41//! For `no_std` environment, you'll need to disable default features.
42//! ```toml
43//! [dependencies]
44//! caretta-id = { version = "0.12.0", default-features = false }
45//! ```
46//!
47//! # Features
48//!
49//! - **Human-friendly**: Easy to read, type, and communicate
50//! - **Collision-resistant**: Sufficient entropy for personal distributed systems
51//! - **Compact**: Shorter than UUIDs while maintaining uniqueness
52//! - **Type-safe**: Rust implementation with strong typing
53//! - **Multiple integrations**: Support for serde, rusqlite, sea-orm, and protobuf
54//!
55//! ## Optional Feature Flags
56//!
57//! - `arbitrary`: `arbitrary::Arbitrary` support for fuzzing tests.
58//! - `serde`: Serialization/deserialization support
59//! - `rusqlite`: SQLite database integration
60//! - `sea-orm`: SeaORM ORM integration
61//! - `prost`: Protocol Buffers support
62//! - `redb`: `redb` integration
63//! - `schemars`: JSON Schema support
64//!
65//! # Examples
66//! ```rust
67//! use caretta_id::CarettaId;
68//! # fn main() -> Result<(), caretta_id::Error> {
69//! // Generate random caretta-id
70//! let caretta_id = CarettaId::random();
71//!
72//! // e.g. `123abcd`
73//! println!("'{}'", caretta_id);
74//!
75//! // Parse from string
76//! let valid_id: CarettaId = "012atvw".parse()?;
77//!
78//! // When decoding from BASE32, ambiguous characters (1/l/I, 0/o, v/u) are treated as 1, 0 and v respectively, so they do not cause errors.
79//! let also_valid_id: CarettaId = "ol2atuw".parse()?;
80//! assert_eq!(valid_id, also_valid_id);
81//!
82//! // Convert to/from integer
83//! let num: u64 = valid_id.into();
84//! let id_from_int: CarettaId = num.try_into()?;
85//! assert_eq!(valid_id, id_from_int);
86//!
87//! // Lossy conversion from oversized int is allowed.
88//! let id_from_overflowed_int = CarettaId::from_u64_lossy(CarettaId::CAPACITY + num);
89//! assert_eq!(valid_id, id_from_overflowed_int);
90//!
91//! # Ok(())
92//! # }
93//! ```
94#![cfg_attr(not(feature = "std"), no_std)]
95#![cfg_attr(docsrs, feature(doc_cfg))]
96
97#[cfg(all(not(feature = "std"), not(test)))]
98#[macro_use]
99extern crate core as std;
100
101/// Provides constants and private functions about encoding/decoding alphabet.
102///
103/// This module implements encoding and decoding character based on [Crockford's Base32](https://www.crockford.com/base32.html) with following exceptions:
104///
105/// - The letter `u` (`U`) is decoded to 27, same as `v`.
106/// - Characters are separated by hyphens every three characters (triplet) during encoding.
107/// During decoding, hyphens may be omitted or replaced with underscores.
108pub mod alphabet;
109mod caretta_id;
110mod error;
111mod macros;
112
113#[cfg(feature = "std")]
114mod std;
115
116#[cfg(feature = "arbitrary")]
117mod arbitrary;
118
119#[cfg(feature = "schemars")]
120mod schemars;
121
122#[cfg(feature = "rand")]
123mod rand;
124
125#[cfg(feature = "serde")]
126mod serde;
127
128#[cfg(feature = "prost")]
129mod prost;
130
131#[cfg(feature = "redb")]
132mod redb;
133
134#[cfg(feature = "rusqlite")]
135mod rusqlite;
136
137#[cfg(feature = "sea-orm")]
138mod sea_orm;
139
140pub use caretta_id::CarettaId;
141pub use error::Error;
142/// Provides message types generated by prost-build.
143#[cfg(feature = "prost")]
144pub mod proto;
145
146/// Alias of [`proto::CarettaId`]
147#[cfg(feature = "prost")]
148pub type CarettaIdProto = proto::CarettaId;