Struct DynamicTnid 

pub struct DynamicTnid(/* private fields */);

A TNID with runtime-determined name.

Unlike Tnid<Name>, which enforces name correctness at compile time, DynamicTnid accepts any valid TNID name and validates it at runtime. This makes it suitable for parsing TNIDs from external sources or working with mixed TNID types.

Conversions

• Convert from Tnid<Name> using From
• Convert to Tnid<Name> using TryFrom (validates name matches)
• Convert from UuidLike using TryFrom (validates TNID structure)
• Convert to UuidLike using From

Examples

use tnid::{DynamicTnid, NameStr};

// Create a new TNID
let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_v0(name);

// Parse from string
let parsed = DynamicTnid::parse_tnid_string("user.Br2flcNDfF6LYICnT").unwrap();

// Get the name
println!("Name: {}", parsed.name());

Implementations

impl DynamicTnid

pub fn new_v0(name: NameStr<'_>) -> Self

Available on crate features time and rand only.

Generates a new v0 TNID with the given name.

This variant is time-ordered with millisecond precision, similar to UUIDv7. TNIDs created earlier will sort before those created later in all representations (u128, UUID hex, and TNID string). The remaining bits are filled with random data.

Use this when you need time-based sorting and want IDs to be roughly chronological, similar to choosing UUIDv7 over UUIDv4.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_v0(name);

pub fn new_time_ordered(name: NameStr<'_>) -> Self

Available on crate features time and rand only.

Generates a new time-ordered TNID (alias for Self::new_v0).

This variant is sortable by creation time, similar to UUIDv7. TNIDs created earlier will sort before those created later in all representations (u128, UUID hex, TNID string).

Use this when you need time-based sorting, similar to choosing UUIDv7 over UUIDv4.

pub fn new_v0_with_time(name: NameStr<'_>, time: OffsetDateTime) -> Self

Available on crate features time and rand only.

Generates a new v0 TNID with a specific timestamp.

This allows you to control the timestamp portion of the TNID, useful for testing or when you want IDs to reflect a specific point in time. The remaining bits are filled with random data.

Timestamp Range

The timestamp field uses 43 bits to store milliseconds since the Unix epoch. Times outside the representable range (1970-01-01 to ~2248) will wrap around:

• Pre-epoch times (before 1970-01-01): Wrap to appear as far-future timestamps.
• Post-2248 times: Wrap to appear as past timestamps.

See Tnid::new_v0_with_time for more details.

Examples

use tnid::{DynamicTnid, NameStr};
use time::{OffsetDateTime, Duration};

let name = NameStr::new("user").unwrap();
let now = OffsetDateTime::now_utc();
let id = DynamicTnid::new_v0_with_time(name, now);

pub fn new_v0_with_parts( name: NameStr<'_>, epoch_millis: u64, random: u64, ) -> Self

Generates a new v0 TNID with explicit timestamp and random components.

This is the lowest-level constructor for v0 TNIDs, giving you full control over both the timestamp and random portions. Useful when you need reproducible IDs (e.g., for testing) or when integrating with external randomness sources.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let timestamp_ms = 1750118400000;
let random_bits = 42;

let id = DynamicTnid::new_v0_with_parts(name, timestamp_ms, random_bits);

pub fn new_v1(name: NameStr<'_>) -> Self

Available on crate feature rand only.

Generates a new v1 TNID with the given name.

This variant maximizes entropy with 100 bits of random data, similar to UUIDv4. This is almost certainly sufficient for most use cases.

Use this when you don’t need time-based sorting and want maximum randomness, similar to choosing UUIDv4 over UUIDv7.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_v1(name);

pub fn new_high_entropy(name: NameStr<'_>) -> Self

Available on crate feature rand only.

Generates a new TNID with maximum randomness (alias for Self::new_v1).

This variant provides the highest entropy, similar to UUIDv4. Use this when you don’t need time-based sorting.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_high_entropy(name);

pub fn new_v1_with_random(name: NameStr<'_>, random_bits: u128) -> Self

Generates a new v1 TNID with explicit random bits.

This allows you to provide your own source of randomness, useful for testing or when integrating with specific random number generators.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let random_bits = 0x0123456789ABCDEF0123456789ABCDEF;

let id = DynamicTnid::new_v1_with_random(name, random_bits);

pub fn from_u128(id: u128) -> Result<Self, ParseTnidError>

Creates a TNID from a raw 128-bit value.

This is the inverse of Self::as_u128 and is useful for loading TNIDs from databases that store UUIDs as u128/binary, interoperating with UUID-based systems, or deserializing.

Returns Err if the value is not a valid TNID. Validation includes:

• Correct UUIDv8 version and variant bits
• Valid name encoding (1-4 characters, properly encoded)

Endianness

When loading from bytes, you’ll almost certainly want to parse a [u8; 16] to a u128 using big-endian byte order with u128::from_be_bytes(), as per the UUID specification.

Examples

use tnid::DynamicTnid;

let id = DynamicTnid::from_u128(0xCAB1952A_F09D_86D9_928E_96EA03DC6AF3).unwrap();
assert_eq!(id.name(), "test");

pub fn parse_tnid_string(s: &str) -> Result<Self, ParseTnidError>

Parses a TNID from its string representation.

This is the inverse of Self::to_tnid_string.

Returns Err if the string is invalid. Validation includes:

• Correct format (<name>.<encoded-data>)
• Valid name (1-4 characters, from allowed character set)
• Valid TNID Data Encoding
• Correct UUIDv8 version and variant bits

Examples

use tnid::DynamicTnid;

// Successful parsing
let parsed = DynamicTnid::parse_tnid_string("user.Br2flcNDfF6LYICnT").unwrap();
assert_eq!(parsed.name(), "user");

// Failed parsing - invalid format
assert!(DynamicTnid::parse_tnid_string("not-a-tnid").is_err());

pub fn parse_uuid_string(s: &str) -> Result<Self, ParseTnidError>

Parses a TNID from UUID hex string format.

This is the inverse of Self::to_uuid_string.

The parser accepts both uppercase and lowercase hex digits (A-F or a-f).

Returns Err if:

• The string is not a valid UUID format
• The UUID is not a valid TNID (wrong version/variant bits or invalid name encoding)

Examples

use tnid::{DynamicTnid, NameStr};

// Create a TNID and convert to UUID string
let name = NameStr::new("user").unwrap();
let original = DynamicTnid::new_v1(name);
use tnid::Case;

let uuid_string = original.to_uuid_string(Case::Lower);

// Parse it back
let parsed = DynamicTnid::parse_uuid_string(&uuid_string).unwrap();
assert_eq!(parsed.as_u128(), original.as_u128());

// Also accepts uppercase
let uuid_upper = original.to_uuid_string(Case::Upper);
let parsed_upper = DynamicTnid::parse_uuid_string(&uuid_upper).unwrap();

// Invalid: not a valid UUID format
assert!(DynamicTnid::parse_uuid_string("not-a-uuid").is_err());

pub fn name(&self) -> String

Returns the TNID’s name as a string.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_v0(name);
assert_eq!(id.name(), "user");

pub fn name_hex(&self) -> String

Returns the name encoded as a 5-character hex string.

This is useful for debugging or when you need a compact representation of the name.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("test").unwrap();
let id = DynamicTnid::new_v1(name);
assert_eq!(id.name_hex(), "cab19");

pub fn as_u128(&self) -> u128

Returns the raw 128-bit UUIDv8-compatible representation of this TNID.

This returns the complete bit representation including the name, UUID version/variant bits, and all data. This is the inverse of Self::from_u128.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_v0(name);
let as_u128 = id.as_u128();

// Convert to big-endian bytes for storage/transmission
let bytes = as_u128.to_be_bytes();

pub fn variant(&self) -> TnidVariant

Returns the TNID variant.

Examples

use tnid::{DynamicTnid, NameStr, TnidVariant};

let id_v0 = DynamicTnid::new_v0(NameStr::new("user").unwrap());
assert_eq!(id_v0.variant(), TnidVariant::V0);

let id_v1 = DynamicTnid::new_v1(NameStr::new("user").unwrap());
assert_eq!(id_v1.variant(), TnidVariant::V1);

pub fn to_tnid_string(&self) -> String

Converts the TNID to its string representation.

This is the human-readable, sortable format: <name>.<encoded-data>. This is the inverse of Self::parse_tnid_string.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_v0(name);
let tnid_string = id.to_tnid_string();

// Format: <name>.<encoded-data>
// Example: "user.Br2flcNDfF6LYICnT"
assert!(tnid_string.starts_with("user."));

pub fn to_uuid_string(&self, case: Case) -> String

Converts the TNID to UUID hex string format.

This is useful for UUID compatibility and interoperability with systems that expect UUID hex strings. This is the inverse of Self::parse_uuid_string.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_v1(name);

use tnid::Case;

let uuid_lower = id.to_uuid_string(Case::Lower);
// "cab1952a-f09d-86d9-928e-96ea03dc6af3"

let uuid_upper = id.to_uuid_string(Case::Upper);
// "CAB1952A-F09D-86D9-928E-96EA03DC6AF3"

pub fn to_bytes(&self) -> [u8; 16]

Converts the TNID to its 16-byte big-endian representation.

This is useful for storing TNIDs in binary format or transmitting over the wire. This is the inverse of Self::from_bytes.

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let id = DynamicTnid::new_v1(name);
let bytes = id.to_bytes();
assert_eq!(bytes.len(), 16);

pub fn from_bytes(bytes: [u8; 16]) -> Result<Self, ParseTnidError>

Creates a TNID from its 16-byte big-endian representation.

This is the inverse of Self::to_bytes and validates that the bytes represent a valid TNID.

Returns Err if the bytes don’t represent a valid TNID (invalid UUID version/variant bits or invalid name encoding).

Examples

use tnid::{DynamicTnid, NameStr};

let name = NameStr::new("user").unwrap();
let original = DynamicTnid::new_v1(name);
let bytes = original.to_bytes();

let parsed = DynamicTnid::from_bytes(bytes).unwrap();
assert_eq!(parsed.as_u128(), original.as_u128());

pub fn encrypt_v0_to_v1( &self, key: impl Into<EncryptionKey>, ) -> Result<Self, EncryptionError>

Available on crate feature encryption only.

Encrypts a V0 TNID to a V1 TNID, hiding timestamp information.

See crate::Tnid::encrypt_v0_to_v1 for details on behavior and invariants.

pub fn decrypt_v1_to_v0( &self, key: impl Into<EncryptionKey>, ) -> Result<Self, EncryptionError>

Available on crate feature encryption only.

Decrypts a V1 TNID back to a V0 TNID, recovering timestamp information.

See crate::Tnid::decrypt_v1_to_v0 for details on behavior and invariants.

Trait Implementations

impl Clone for DynamicTnid

fn clone(&self) -> DynamicTnid

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DynamicTnid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'r> Decode<'r, MySql> for DynamicTnid

Available on crate feature sqlx-mysql and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn decode(value: MySqlValueRef<'r>) -> Result<Self, BoxDynError>

Decode a new value of this type using a raw value from the database.

impl<'r> Decode<'r, Postgres> for DynamicTnid

Available on crate feature sqlx-postgres and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn decode(value: PgValueRef<'r>) -> Result<Self, BoxDynError>

Decode a new value of this type using a raw value from the database.

impl<'r> Decode<'r, Sqlite> for DynamicTnid

Available on crate feature sqlx-sqlite and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn decode(value: SqliteValueRef<'r>) -> Result<Self, BoxDynError>

Decode a new value of this type using a raw value from the database.

impl<'de> Deserialize<'de> for DynamicTnid

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for DynamicTnid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'q> Encode<'q, MySql> for DynamicTnid

Available on crate feature sqlx-mysql and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn encode_by_ref(&self, buf: &mut Vec<u8>) -> Result<IsNull, BoxDynError>

Writes the value of self into buf without moving self.

fn encode( self, buf: &mut <DB as Database>::ArgumentBuffer<'q>, ) -> Result<IsNull, Box<dyn Error + Send + Sync>>

where Self: Sized,

Writes the value of self into buf in the expected format for the database.

fn produces(&self) -> Option<<DB as Database>::TypeInfo>

fn size_hint(&self) -> usize

impl<'q> Encode<'q, Postgres> for DynamicTnid

Available on crate feature sqlx-postgres and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn encode_by_ref( &self, buf: &mut PgArgumentBuffer, ) -> Result<IsNull, BoxDynError>

Writes the value of self into buf without moving self.

fn encode( self, buf: &mut <DB as Database>::ArgumentBuffer<'q>, ) -> Result<IsNull, Box<dyn Error + Send + Sync>>

where Self: Sized,

Writes the value of self into buf in the expected format for the database.

fn produces(&self) -> Option<<DB as Database>::TypeInfo>

fn size_hint(&self) -> usize

impl<'q> Encode<'q, Sqlite> for DynamicTnid

Available on crate feature sqlx-sqlite and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn encode_by_ref( &self, args: &mut Vec<SqliteArgumentValue<'q>>, ) -> Result<IsNull, BoxDynError>

Writes the value of self into buf without moving self.

fn encode( self, buf: &mut <DB as Database>::ArgumentBuffer<'q>, ) -> Result<IsNull, Box<dyn Error + Send + Sync>>

where Self: Sized,

Writes the value of self into buf in the expected format for the database.

fn produces(&self) -> Option<<DB as Database>::TypeInfo>

fn size_hint(&self) -> usize

impl From<DynamicTnid> for UuidLike

fn from(dynamic: DynamicTnid) -> Self

Converts to this type from the input type.

impl<Name: TnidName> From<Tnid<Name>> for DynamicTnid

fn from(tnid: Tnid<Name>) -> Self

Converts to this type from the input type.

impl Hash for DynamicTnid

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for DynamicTnid

fn cmp(&self, other: &DynamicTnid) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for DynamicTnid

fn eq(&self, other: &DynamicTnid) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for DynamicTnid

fn partial_cmp(&self, other: &DynamicTnid) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PgHasArrayType for DynamicTnid

Available on crate feature sqlx-postgres and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn array_type_info() -> PgTypeInfo

fn array_compatible(ty: &PgTypeInfo) -> bool

impl Serialize for DynamicTnid

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<Name: TnidName> TryFrom<DynamicTnid> for Tnid<Name>

type Error = ParseTnidError

The type returned in the event of a conversion error.

fn try_from(dynamic: DynamicTnid) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<UuidLike> for DynamicTnid

type Error = ParseTnidError

The type returned in the event of a conversion error.

fn try_from(uuid: UuidLike) -> Result<Self, Self::Error>

Performs the conversion.

impl Type<MySql> for DynamicTnid

Available on crate feature sqlx-mysql and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn type_info() -> MySqlTypeInfo

Returns the canonical SQL type for this Rust type.

fn compatible(ty: &MySqlTypeInfo) -> bool

Determines if this Rust type is compatible with the given SQL type.

impl Type<Postgres> for DynamicTnid

Available on crate feature sqlx-postgres and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn type_info() -> PgTypeInfo

Returns the canonical SQL type for this Rust type.

fn compatible(ty: &<DB as Database>::TypeInfo) -> bool

Determines if this Rust type is compatible with the given SQL type.

impl Type<Sqlite> for DynamicTnid

Available on crate feature sqlx-sqlite and (crate features sqlx-postgres or sqlx-mysql or sqlx-sqlite) only.

fn type_info() -> SqliteTypeInfo

Returns the canonical SQL type for this Rust type.

fn compatible(ty: &SqliteTypeInfo) -> bool

Determines if this Rust type is compatible with the given SQL type.

impl Copy for DynamicTnid

impl Eq for DynamicTnid

impl StructuralPartialEq for DynamicTnid