Skip to main content

Crate caretta_id

Crate caretta_id 

Source
Expand description

This crate has been renamed to grain-id. Please migrate to grain-id — it is a drop-in replacement with the same functionality. caretta-id will no longer receive updates.

A human-friendly 7 characters identifier format (e.g. 123abcd).

For a language agnostic specification of the caretta-id format, see SPECS.md

§Quick Start

use caretta_id::CarettaId;

let id = CarettaId::random();
println!("{}", id); // e.g. "123abcd"

§Why caretta-id?

Traditional identifier systems face challenges in distributed environments:

  • Sequential numbers (like GitHub issue numbers) cause collisions in distributed systems
  • UUIDs are too long and not human-friendly
  • Short hashes (like Git commit hashes) lack standardization

caretta-id bridges the gap between human readability and technical requirements.

§Installation

Add this to your Cargo.toml:

[dependencies]
caretta-id = "0.12.0"

# With optional features
caretta-id = { version = "0.11.0", features = ["arbitrary", "serde", "rusqlite", "sea-orm", "prost", "redb", "schemars"] }

§For no_std Environments

This crate support no_std. For no_std environment, you’ll need to disable default features.

[dependencies]
caretta-id = { version = "0.12.0", default-features = false }

§Features

  • Human-friendly: Easy to read, type, and communicate
  • Collision-resistant: Sufficient entropy for personal distributed systems
  • Compact: Shorter than UUIDs while maintaining uniqueness
  • Type-safe: Rust implementation with strong typing
  • Multiple integrations: Support for serde, rusqlite, sea-orm, and protobuf

§Optional Feature Flags

  • arbitrary: arbitrary::Arbitrary support for fuzzing tests.
  • serde: Serialization/deserialization support
  • rusqlite: SQLite database integration
  • sea-orm: SeaORM ORM integration
  • prost: Protocol Buffers support
  • redb: redb integration
  • schemars: JSON Schema support

§Examples

use caretta_id::CarettaId;
// Generate random caretta-id
let caretta_id = CarettaId::random();

// e.g. `123abcd`
println!("'{}'", caretta_id);

// Parse from string
let valid_id: CarettaId = "012atvw".parse()?;

// 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.
let also_valid_id: CarettaId = "ol2atuw".parse()?;
assert_eq!(valid_id, also_valid_id);

// Convert to/from integer
let num: u64 = valid_id.into();
let id_from_int: CarettaId = num.try_into()?;
assert_eq!(valid_id, id_from_int);

// Lossy conversion from oversized int is allowed.
let id_from_overflowed_int = CarettaId::from_u64_lossy(CarettaId::CAPACITY + num);
assert_eq!(valid_id, id_from_overflowed_int);

Modules§

alphabet
Provides constants and private functions about encoding/decoding alphabet.
protoprost
Provides message types generated by prost-build. Provides protobuf messages.

Structs§

CarettaId
Caretta id struct

Enums§

Error
A general error that can occur when working with caretta-ids.

Type Aliases§

CarettaIdProtoprost
Alias of proto::CarettaId