Uuid v0.1.0

UUID representation, parsing, formatting and generation

Installation

Add Uuid to the [Dependencies] table of your package's Rux.toml:

[Dependencies]
Uuid = { Namespace = "Rux", Version = "0.1.0" }

Standard packages are declared by hand: the registry does not serve them, so rux add Rux/Uuid cannot add them.

Dependencies

Core 0.1.0
Entropy 0.1.0
Text 0.1.0
Time 0.1.0

Guide

What it provides

A 128-bit Copy value — stored as the sixteen bytes RFC 9562 orders them in, with borrowed &Uuid inspection and the version and variant readable from it without copying or exposing an address.
Text — the canonical hyphenated form and the urn:uuid: form, written in lower case because RFC 9562 says output should be, and read in either case because input arrives as it arrives. Uuid implements Display and Debug, so {} writes the canonical form and {:urn} the URN one; upper case is not a style, because a canonical form that varies by case is not canonical, and FormatUpper remains for a format that demands it.
Writers that refuse rather than truncate — Format, FormatUpper and FormatUrn return ! FormatError and report InsufficientCapacity for a destination shorter than the form needs, leaving it exactly as it was. A truncated UUID is not a shorter UUID; it is a different string, and one a strict parser refuses and a lenient one might not.
Refusals that say where — Parse returns Uuid ! UuidParseError, and every failure carries the zero-based byte offset into the text it was given: the character that is not a hexadecimal digit, the hyphen that is missing or misplaced, the misspelling in a urn:uuid: prefix, or the end of a text that stops short. Inside a URN the offsets are into the whole string, so a caller underlining the character does not have to know which form it was handed.
Version 4 — random, from Rux/Entropy, with the version and variant bits forced whatever the source bytes said.
Version 7 — time-ordered, so byte order is time order and a database index built on one does not fragment; with a caller-owned MonotonicUuid() generator for identifiers minted in the same millisecond.
Windows GUIDs — an explicit, self-inverse byte-order conversion, because the two layouts disagree about the first three fields and a silent reinterpretation produces a valid-looking UUID with the wrong timestamp.

Formatting and comparison borrow UUID values directly. Generation returns Uuid ! EntropyError, failing rather than producing a predictable identifier when the system has no entropy, and entropy retains raw byte buffers that transfer no ownership.

Index

Types

Name	Summary
`UuidParseError`	Why text could not be read as a UUID.
`MonotonicUuid`	A generator of version 7 UUIDs that are strictly increasing, even within one millisecond.
`Uuid`	A universally unique identifier: sixteen bytes in the standard's own order.
`UuidVariant`	What layout a UUID's bytes follow.

Functions

Name	Summary
`Random`	A version 4 UUID drawn from the operating system's entropy.
`RandomFromBytes`	A version 4 UUID built from sixteen bytes the caller supplies.
`SwapGuidOrder`	The same identifier with its first three fields byte-swapped, which is how Windows stores a GUID.
`Parse`	Reads a UUID from its canonical or URN text form.
`Format`	Writes the canonical text form into `into`, in lower case.
`FormatUpper`	Writes the canonical text form into `into`, in upper case.
`FormatUrn`	Writes the URN form into `into`: the canonical form after `urn:uuid:`.
`TimeOrdered`	A version 7 UUID: the current time in its leading bits, entropy in the rest.
`TimeOrderedAt`	A version 7 UUID for a given millisecond, with entropy in the rest.
`MillisecondOf`	The millisecond a version 7 UUID carries.

Constants

Name	Summary
`UuidTextLength`	How long the canonical text form is: thirty-two digits and four hyphens.
`UuidUrnLength`	How long the URN form is: the canonical form after `urn:uuid:`.

TomlWriteDocument

Writes table as a TOML document.

MonotonicUuid

A generator of version 7 UUIDs that are strictly increasing, even within one millisecond.

Edit this page on GitHub