uuid

A RFC 4122 Universally Unique Identifier

The number of 100-nanosecond intervals between 1582-10-15 and 1970-01-01.

Name string is a fully-qualified domain name.

Name string is an ISO OID.

Name string is a URL.

Name string is an X.500 DN (in DER or a text output format).

Get the clock sequence of a version 1 or version 6 UUID.

Inputs:

• id: The identifier.

Returns:

• clock_seq: The 14-bit clock sequence field.

Get the 12-bit counter value of a version 7 UUID.

The UUID must have been generated with a counter, otherwise this procedure will return random bits.

Inputs:

• id: The identifier.

Returns:

• counter: The 12-bit counter value.

Generate a version 1 UUID.

Inputs:

• clock_seq: The clock sequence, a number which must be initialized to a random number once in the lifetime of a system.
• node: An optional 48-bit spatially unique identifier, specified to be the IEEE 802 address of the system.

If one is not provided or available, 48 bits of random state will take its place.

• timestamp: A timestamp from the core:time package, or nil to use the current time.

Returns:

• result: The generated UUID.

Generate a version 4 UUID.

This UUID will be pseudorandom, save for 6 pre-determined version and variant bits.

Returns:

• result: The generated UUID.

Generate a version 6 UUID.

Inputs:

• clock_seq: The clock sequence from version 1, now made optional.

If unspecified, it will be replaced with random bits.

• node: An optional 48-bit spatially unique identifier, specified to be the IEEE 802 address of the system.

If one is not provided or available, 48 bits of random state will take its place.

• timestamp: A timestamp from the core:time package, or nil to use the current time.

Returns:

• result: The generated UUID.

Generate a version 7 UUID.

This UUID will be pseudorandom, save for 6 pre-determined version and variant bits and a 48-bit timestamp.

It is designed with time-based sorting in mind, such as for database usage, as the highest bits are allocated from the timestamp of when it is created.

Inputs:

• timestamp: A timestamp from the core:time package, or nil to use the current time.

Returns:

• result: The generated UUID.

Generate a version 7 UUID that has an incremented counter.

This UUID will be pseudorandom, save for 6 pre-determined version and variant bits, a 48-bit timestamp, and 12 bits of counter state.

It is designed with time-based sorting in mind, such as for database usage, as the highest bits are allocated from the timestamp of when it is created.

This procedure is preferable if you are generating hundreds or thousands of UUIDs as a batch within the span of a millisecond. Do note that the counter only has 12 bits of state, thus counter cannot exceed the number 4,095.

Example:

import "core:uuid"

// Create a batch of UUIDs all at once.
batch: [dynamic]uuid.Identifier

for i: u16 = 0; i < 1000; i += 1 {
	my_uuid := uuid.generate_v7_counter(i)
	append(&batch, my_uuid)
}

Inputs:

• counter: A 12-bit value which should be incremented each time a UUID is generated in a batch.
• timestamp: A timestamp from the core:time package, or nil to use the current time.

Returns:

• result: The generated UUID.

Generate a version 8 UUID using a specific hashing algorithm.

This UUID is generated by hashing a name with a namespace.

Note that all version 8 UUIDs are for experimental or vendor-specific use cases, per the specification. This use case in particular is for offering a non-legacy alternative to UUID versions 3 and 5.

Inputs:

• namespace: An Identifier that is used to represent the underlying namespace.

This can be any one of the Namespace_* values provided in this package.

• name: The byte slice which will be hashed with the namespace.
• algorithm: A hashing algorithm from core:crypto/hash.

Returns:

• result: The generated UUID.

Example:

import "core:crypto/hash"
import "core:encoding/uuid"
import "core:fmt"

generate_v8_hash_bytes_example :: proc() {
	my_uuid := uuid.generate_v8_hash(uuid.Namespace_DNS, "www.odin-lang.org", .SHA256)
	my_uuid_string := uuid.to_string(my_uuid, context.temp_allocator)
	fmt.println(my_uuid_string)
}

Output:

3730f688-4bff-8dce-9cbf-74a3960c5703

Generate a version 8 UUID using a specific hashing algorithm.

This UUID is generated by hashing a name with a namespace.

Note that all version 8 UUIDs are for experimental or vendor-specific use cases, per the specification. This use case in particular is for offering a non-legacy alternative to UUID versions 3 and 5.

Inputs:

• namespace: An Identifier that is used to represent the underlying namespace.

This can be any one of the Namespace_* values provided in this package.

• name: The string which will be hashed with the namespace.
• algorithm: A hashing algorithm from core:crypto/hash.

Returns:

• result: The generated UUID.

Example:

import "core:crypto/hash"
import "core:encoding/uuid"
import "core:fmt"

generate_v8_hash_string_example :: proc() {
	my_uuid := uuid.generate_v8_hash(uuid.Namespace_DNS, "www.odin-lang.org", .SHA256)
	my_uuid_string := uuid.to_string(my_uuid, context.temp_allocator)
	fmt.println(my_uuid_string)
}

Output:

3730f688-4bff-8dce-9cbf-74a3960c5703

Get the node of a version 1 or version 6 UUID.

Inputs:

• id: The identifier.

Returns:

• node: The 48-bit spatially unique identifier.

Get the raw timestamp of a version 1 UUID.

Inputs:

• id: The identifier.

Returns:

• timestamp: The timestamp, in 100-nanosecond intervals since 1582-10-15.

Get the raw timestamp of a version 6 UUID.

Inputs:

• id: The identifier.

Returns:

• timestamp: The timestamp, in 100-nanosecond intervals since 1582-10-15.

Get the raw timestamp of a version 7 UUID.

Inputs:

• id: The identifier.

Returns:

• timestamp: The timestamp, in milliseconds since the UNIX epoch.

Convert a string to a UUID.

Inputs:

• str: A string in the 8-4-4-4-12 format.

Returns:

• id: The converted identifier, or nil if there is an error.
• error: A description of the error, or nil if successful.

Stamp an array of 16 bytes as being a valid version 8 UUID.

Per the specification, all version 8 UUIDs are either for experimental or vendor-specific purposes. This procedure allows for converting arbitrary data into custom UUIDs.

Inputs:

• array: An array of 16 bytes.

Returns:

• result: A valid version 8 UUID.

Stamp a 128-bit integer as being a valid version 8 UUID.

Per the specification, all version 8 UUIDs are either for experimental or vendor-specific purposes. This procedure allows for converting arbitrary data into custom UUIDs.

Inputs:

• integer: Any integer type.

Returns:

• result: A valid version 8 UUID.

Stamp a slice of bytes as being a valid version 8 UUID.

If the slice is less than 16 bytes long, the data available will be used. If it is longer than 16 bytes, only the first 16 will be used.

This procedure does not modify the underlying slice.

Per the specification, all version 8 UUIDs are either for experimental or vendor-specific purposes. This procedure allows for converting arbitrary data into custom UUIDs.

Inputs:

• slice: A slice of bytes.

Returns:

• result: A valid version 8 UUID.

Get the timestamp of a version 1 UUID.

Inputs:

• id: The identifier.

Returns:

• timestamp: The timestamp of the UUID.

Get the timestamp of a version 6 UUID.

Inputs:

• id: The identifier.

Returns:

• timestamp: The timestamp, in 100-nanosecond intervals since 1582-10-15.

Get the timestamp of a version 7 UUID.

Inputs:

• id: The identifier.

Returns:

• timestamp: The timestamp, in milliseconds since the UNIX epoch.

Convert a UUID to a string in the 8-4-4-4-12 format.

Allocates Using Provided Allocator

Inputs:

• id: The identifier to convert.
• allocator: (default: context.allocator)
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

• str: The allocated and converted string.
• error: An optional allocator error if one occured, nil otherwise.

Convert a UUID to a string in the 8-4-4-4-12 format.

Inputs:

• id: The identifier to convert.
• buffer: A byte buffer to store the result. Must be at least 36 bytes large.
• loc: The caller location for debugging purposes (default: #caller_location)

Returns:

• str: The converted string which will be stored in buffer.

Write a UUID in the 8-4-4-4-12 format.

This procedure performs no error checking on the underlying stream.

Inputs:

• w: A writable stream.
• id: The identifier to convert.

Get the variant of a UUID.

Inputs:

• id: The identifier.

Returns:

• variant: The variant type.

Get the version of a UUID.

Inputs:

• id: The identifier.

Returns:

• number: The version number.

Write a UUID in the 8-4-4-4-12 format.

This procedure performs error checking with every byte written.

If you can guarantee beforehand that your stream has enough space to hold the UUID (36 bytes), then it is better to use unsafe_write instead as that will be faster.

Inputs:

• w: A writable stream.
• id: The identifier to convert.

Returns:

• error: An io error, if one occurred, otherwise nil.