Text form v0.1.0

Reading and writing a UUID in its canonical and URN text forms.

`UuidTextLength`

pub const UuidTextLength: uint = 36;

How long the canonical text form is: thirty-two digits and four hyphens.

Source

`UuidUrnLength`

pub const UuidUrnLength: uint = 45;

How long the URN form is: the canonical form after urn:uuid:.

Source

`UuidParseError`

pub variant UuidParseError {
    WrongLength(uint),
    Misplaced(uint),
    NotHexadecimal(uint),
    BadPrefix(uint)
}

Why text could not be read as a UUID. Failure-only: every case is a failure, and each carries the zero-based UTF-8 byte offset into the text where it was found. Success is the other channel of Uuid ! UuidParseError, so there is no case here meaning nothing went wrong. Copy, carrying one offset and owning nothing.

Source

Cases

Name	Description
`WrongLength(uint)`	The text is neither thirty-six characters nor forty-five with the URN prefix. The offset is the text's length when it is too short, which is where the missing character would have gone, and the first character the canonical form has no room for when it is too long.
`Misplaced(uint)`	A hyphen is missing where the form puts one, or one appears where a digit belongs. The offset is that character.
`NotHexadecimal(uint)`	A character that is not a hexadecimal digit. The offset is that character.
`BadPrefix(uint)`	The text has the length of the URN form but its `urn:uuid:` prefix is misspelled. The offset is the first character that does not match.

Implements ParseFailure

UuidParseError conforms to ParseFailure.

`Offset`

pub func Offset(self: &UuidParseError) -> uint

Where in the input the failure was found. Borrows the error and leaves it untouched. Cannot fail; runs in constant time and allocates nothing.

Returns: the zero-based UTF-8 byte offset, which is the text's length at end of input

Source

`Parse`

pub func Parse(text: char8[..]) -> Uuid ! UuidParseError
pub func Parse(text: StringView) -> Uuid ! UuidParseError

Reads a UUID from its canonical or URN text form. Both cases of the digits are accepted, because the standard says the two mean the same thing; nothing else is. The URN prefix is compared case-insensitively, which is RFC 8141's rule for a scheme name and a different rule from the digits — both are the standard's. Reports WrongLength for text that is neither form's length, BadPrefix for a misspelled urn:uuid:, Misplaced for a hyphen that is missing or one that stands where a digit belongs, and NotHexadecimal for any other character that is not a digit. Each carries the byte offset into text where it was found. A refused parse produces no value at all rather than a half-filled one.

Overload	Summary
`pub func Parse(text: char8[..]) -> Uuid ! UuidParseError`	Reads a UUID from its canonical or URN text form.
`pub func Parse(text: StringView) -> Uuid ! UuidParseError`	Reads a UUID from the text a `StringView` borrows.

Source

Parameters

Name	Type	Description
`text`	`char8[..]` / `StringView`	the text to read

Returns: the identifier, or why the text is not one

`Format`

pub func Format(
    value: &Uuid,
    into: var char8[..]
) -> ! FormatError

Writes the canonical text form into into, in lower case. Lower case because RFC 9562 says so, and because a canonical form that varies by case is not canonical — two systems comparing text would disagree about equal UUIDs. Reports InsufficientCapacity when into is shorter than UuidTextLength, leaving it exactly as it was. A short destination is refused rather than filled with what fits, because a truncated UUID is a different string rather than a shorter one. Room past the thirty-six characters is not touched.

Source

Parameters

Name	Type	Description
`value`	`&Uuid`	the identifier to write
`into`	`var char8[..]`	the destination, at least `UuidTextLength` bytes

Returns: success when the whole form was written

`FormatUpper`

pub func FormatUpper(
    value: &Uuid,
    into: var char8[..]
) -> ! FormatError

Writes the canonical text form into into, in upper case. Offered because some formats demand it; Format is what a program should write when it has the choice. The failure Format reports, for the same reason and with the same guarantee.

Source

Parameters

Name	Type	Description
`value`	`&Uuid`	the identifier to write
`into`	`var char8[..]`	the destination, at least `UuidTextLength` bytes

Returns: success when the whole form was written

`FormatUrn`

pub func FormatUrn(
    value: &Uuid,
    into: var char8[..]
) -> ! FormatError

Writes the URN form into into: the canonical form after urn:uuid:. Reports InsufficientCapacity when into is shorter than UuidUrnLength, leaving it exactly as it was. The form is refused whole, so a destination never receives a prefix with nothing after it.

Source

Parameters

Name	Type	Description
`value`	`&Uuid`	the identifier to write
`into`	`var char8[..]`	the destination, at least `UuidUrnLength` bytes

Returns: success when the whole form was written

Random

A version 4 UUID drawn from the operating system's entropy.

TimeOrdered

A version 7 UUID: the current time in its leading bits, entropy in the rest.

Edit this page on GitHub