Documentation ¶
Overview ¶
Package uuid provides implementations of the Universally Unique Identifier (UUID), as specified in RFC-9562 (formerly RFC-4122).
RFC-9562[1] provides the specification for versions 1, 3, 4, 5, 6 and 7.
DCE 1.1[2] provides the specification for version 2, but version 2 support was removed from this package in v4 due to some concerns with the specification itself. Reading the spec, it seems that it would result in generating UUIDs that aren't very unique. In having read the spec it seemed that our implementation did not meet the spec. It also seems to be at-odds with RFC 9562, meaning we would need quite a bit of special code to support it. Lastly, there were no Version 2 implementations that we could find to ensure we were understanding the specification correctly.
[1] https://tools.ietf.org/html/rfc9562 [2] http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01
Index ¶
- Constants
- Variables
- type EpochFunc
- type Error
- type Gen
- func (g *Gen) NewV1() (UUID, error)
- func (g *Gen) NewV1AtTime(atTime time.Time) (UUID, error)
- func (g *Gen) NewV3(ns UUID, name string) UUID
- func (g *Gen) NewV4() (UUID, error)
- func (g *Gen) NewV5(ns UUID, name string) UUID
- func (g *Gen) NewV6() (UUID, error)
- func (g *Gen) NewV6AtTime(atTime time.Time) (UUID, error)
- func (g *Gen) NewV7() (UUID, error)
- func (g *Gen) NewV7AtTime(atTime time.Time) (UUID, error)
- type GenOption
- type Generator
- type HWAddrFunc
- type NullUUID
- type Timestamp
- type UUID
- func FromBytes(input []byte) (UUID, error)
- func FromBytesOrNil(input []byte) UUID
- func FromString(text string) (UUID, error)
- func FromStringOrNil(input string) UUID
- func Must(u UUID, err error) UUID
- func NewV1() (UUID, error)
- func NewV1AtTime(atTime time.Time) (UUID, error)
- func NewV3(ns UUID, name string) UUID
- func NewV4() (UUID, error)
- func NewV5(ns UUID, name string) UUID
- func NewV6() (UUID, error)
- func NewV6AtTime(atTime time.Time) (UUID, error)
- func NewV7() (UUID, error)
- func NewV7AtTime(atTime time.Time) (UUID, error)
- func (u UUID) Bytes() []byte
- func (u UUID) Format(f fmt.State, c rune)
- func (u UUID) IsNil() bool
- func (u UUID) MarshalBinary() ([]byte, error)
- func (u UUID) MarshalText() ([]byte, error)
- func (u *UUID) Parse(s string) error
- func (u *UUID) Scan(src interface{}) error
- func (u *UUID) SetVariant(v byte)
- func (u *UUID) SetVersion(v byte)
- func (u UUID) String() string
- func (u *UUID) UnmarshalBinary(data []byte) error
- func (u *UUID) UnmarshalText(b []byte) error
- func (u UUID) Value() (driver.Value, error)
- func (u UUID) Variant() byte
- func (u UUID) Version() byte
Constants ¶
const ( // ErrInvalidFormat is returned when the UUID string representation does not // match the expected format. See also ErrIncorrectFormatInString. ErrInvalidFormat = Error("uuid: invalid UUID format") // ErrIncorrectFormatInString can be returned instead of ErrInvalidFormat. // A separate error type is used because of how errors used to be formatted // before custom error types were introduced. ErrIncorrectFormatInString = Error("uuid: incorrect UUID format in string") // ErrIncorrectLength is returned when the UUID does not have the // appropriate string length for parsing the UUID. ErrIncorrectLength = Error("uuid: incorrect UUID length") // ErrIncorrectByteLength indicates the UUID byte slice length is invalid. ErrIncorrectByteLength = Error("uuid: UUID must be exactly 16 bytes long") // ErrNoHwAddressFound is returned when a hardware (MAC) address cannot be // found for UUID generation. ErrNoHwAddressFound = Error("uuid: no HW address found") // ErrTypeConvertError is returned for type conversion operation fails. ErrTypeConvertError = Error("uuid: cannot convert") // ErrInvalidVersion indicates an unsupported or invalid UUID version. ErrInvalidVersion = Error("uuid:") )
The strings defined in the errors is matching the previous behavior before the custom error type was implemented. The reason is that some people might be relying on the exact string representation to handle errors in their code.
const ( V1 byte // Version 1 (date-time and MAC address) V3 // Version 3 (namespace name-based) V4 // Version 4 (random) V5 // Version 5 (namespace name-based) V6 // Version 6 (k-sortable timestamp and random data, field-compatible with v1) V7 // Version 7 (k-sortable timestamp and random data) )
UUID versions.
const ( VariantNCS byte = iota VariantRFC9562 VariantMicrosoft VariantFuture )
UUID layout variants.
const ( DomainPerson = iota DomainGroup DomainOrg )
UUID DCE domains.
const Size = 16
Size of a UUID in bytes.
const VariantRFC4122 = VariantRFC9562
Backward-compatible variant for RFC 4122
Variables ¶
var ( NamespaceDNS = Must(FromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8")) NamespaceURL = Must(FromString("6ba7b811-9dad-11d1-80b4-00c04fd430c8")) NamespaceOID = Must(FromString("6ba7b812-9dad-11d1-80b4-00c04fd430c8")) NamespaceX500 = Must(FromString("6ba7b814-9dad-11d1-80b4-00c04fd430c8")) )
Predefined namespace UUIDs.
var Max = UUID{
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
0xFF,
}
Max is the maximum UUID, as specified in RFC-9562, that has all 128 bits set to one.
var Nil = UUID{}
Nil is the nil UUID, as specified in RFC-9562, that has all 128 bits set to zero.
Functions ¶
This section is empty.
Types ¶
type Gen ¶
type Gen struct {
// contains filtered or unexported fields
}
Gen is a reference UUID generator based on the specifications laid out in RFC-9562 and DCE 1.1: Authentication and Security Services. This type satisfies the Generator interface as defined in this package.
For consumers who are generating V1 UUIDs, but don't want to expose the MAC address of the node generating the UUIDs, the NewGenWithHWAF() function has been provided as a convenience. See the function's documentation for more info.
The authors of this package do not feel that the majority of users will need to obfuscate their MAC address, and so we recommend using NewGen() to create a new generator.
func NewGen ¶
func NewGen() *Gen
NewGen returns a new instance of Gen with some default values set. Most people should use this.
func NewGenWithHWAF ¶
func NewGenWithHWAF(hwaf HWAddrFunc) *Gen
NewGenWithHWAF builds a new UUID generator with the HWAddrFunc provided. Most consumers should use NewGen() instead.
This is used so that consumers can generate their own MAC addresses, for use in the generated UUIDs, if there is some concern about exposing the physical address of the machine generating the UUID.
The Gen generator will only invoke the HWAddrFunc once, and cache that MAC address for all the future UUIDs generated by it. If you'd like to switch the MAC address being used, you'll need to create a new generator using this function.
func NewGenWithOptions ¶
NewGenWithOptions returns a new instance of Gen with the options provided. Most people should use NewGen() or NewGenWithHWAF() instead.
To customize the generator, you can pass in one or more GenOption functions. For example:
gen := NewGenWithOptions( WithHWAddrFunc(myHWAddrFunc), WithEpochFunc(myEpochFunc), WithRandomReader(myRandomReader), )
NewGenWithOptions(WithHWAddrFunc(myHWAddrFunc)) is equivalent to calling NewGenWithHWAF(myHWAddrFunc) NewGenWithOptions() is equivalent to calling NewGen()
func (*Gen) NewV1AtTime ¶
NewV1AtTime returns a UUID based on the provided timestamp and current MAC address.
func (*Gen) NewV6 ¶
NewV6 returns a k-sortable UUID based on the current timestamp and 48 bits of pseudorandom data. The timestamp in a V6 UUID is the same as V1, with the bit order being adjusted to allow the UUID to be k-sortable.
func (*Gen) NewV6AtTime ¶
NewV6 returns a k-sortable UUID based on the provided timestamp and 48 bits of pseudorandom data. The timestamp in a V6 UUID is the same as V1, with the bit order being adjusted to allow the UUID to be k-sortable.
type GenOption ¶
type GenOption func(*Gen)
GenOption is a function type that can be used to configure a Gen generator.
func WithEpochFunc ¶
WithEpochFunc is a GenOption that allows you to provide your own EpochFunc function. When this option is nil, time.Now is used.
func WithHWAddrFunc ¶
func WithHWAddrFunc(hwaf HWAddrFunc) GenOption
WithHWAddrFunc is a GenOption that allows you to provide your own HWAddrFunc function. When this option is nil, the defaultHWAddrFunc is used.
func WithRandomReader ¶
WithRandomReader is a GenOption that allows you to provide your own random reader. When this option is nil, the default rand.Reader is used.
type Generator ¶
type Generator interface { NewV1() (UUID, error) NewV1AtTime(time.Time) (UUID, error) NewV3(ns UUID, name string) UUID NewV4() (UUID, error) NewV5(ns UUID, name string) UUID NewV6() (UUID, error) NewV6AtTime(time.Time) (UUID, error) NewV7() (UUID, error) NewV7AtTime(time.Time) (UUID, error) }
Generator provides an interface for generating UUIDs.
type HWAddrFunc ¶
type HWAddrFunc func() (net.HardwareAddr, error)
HWAddrFunc is the function type used to provide hardware (MAC) addresses.
type NullUUID ¶
NullUUID can be used with the standard sql package to represent a UUID value that can be NULL in the database.
func (NullUUID) MarshalJSON ¶
MarshalJSON marshals the NullUUID as null or the nested UUID
func (*NullUUID) UnmarshalJSON ¶
UnmarshalJSON unmarshals a NullUUID
type Timestamp ¶
type Timestamp uint64
Timestamp is the count of 100-nanosecond intervals since 00:00:00.00, 15 October 1582 within a V1 UUID. This type has no meaning for other UUID versions since they don't have an embedded timestamp.
func TimestampFromV1 ¶
TimestampFromV1 returns the Timestamp embedded within a V1 UUID. Returns an error if the UUID is any version other than 1.
func TimestampFromV6 ¶
TimestampFromV6 returns the Timestamp embedded within a V6 UUID. This function returns an error if the UUID is any version other than 6.
func TimestampFromV7 ¶
TimestampFromV7 returns the Timestamp embedded within a V7 UUID. This function returns an error if the UUID is any version other than 7.
type UUID ¶
UUID is an array type to represent the value of a UUID, as defined in RFC-9562.
func FromBytes ¶
FromBytes returns a UUID generated from the raw byte slice input. It will return an error if the slice isn't 16 bytes long.
func FromBytesOrNil ¶
FromBytesOrNil returns a UUID generated from the raw byte slice input. Same behavior as FromBytes(), but returns uuid.Nil instead of an error.
func FromString ¶
FromString returns a UUID parsed from the input string. Input is expected in a form accepted by UnmarshalText.
func FromStringOrNil ¶
FromStringOrNil returns a UUID parsed from the input string. Same behavior as FromString(), but returns uuid.Nil instead of an error.
func Must ¶
Must is a helper that wraps a call to a function returning (UUID, error) and panics if the error is non-nil. It is intended for use in variable initializations such as
var packageUUID = uuid.Must(uuid.FromString("123e4567-e89b-12d3-a456-426655440000"))
func NewV1AtTime ¶
NewV1 returns a UUID based on the provided timestamp and MAC address.
func NewV6 ¶
NewV6 returns a k-sortable UUID based on the current timestamp and 48 bits of pseudorandom data. The timestamp in a V6 UUID is the same as V1, with the bit order being adjusted to allow the UUID to be k-sortable.
func NewV6AtTime ¶
NewV6 returns a k-sortable UUID based on the provided timestamp and 48 bits of pseudorandom data. The timestamp in a V6 UUID is the same as V1, with the bit order being adjusted to allow the UUID to be k-sortable.
func NewV7 ¶
NewV7 returns a k-sortable UUID based on the current millisecond-precision UNIX epoch and 74 bits of pseudorandom data. It supports single-node batch generation (multiple UUIDs in the same timestamp) with a Monotonic Random counter.
func NewV7AtTime ¶
NewV7 returns a k-sortable UUID based on the provided millisecond-precision UNIX epoch and 74 bits of pseudorandom data. It supports single-node batch generation (multiple UUIDs in the same timestamp) with a Monotonic Random counter.
func (UUID) Format ¶
Format implements fmt.Formatter for UUID values.
The behavior is as follows: The 'x' and 'X' verbs output only the hex digits of the UUID, using a-f for 'x' and A-F for 'X'. The 'v', '+v', 's' and 'q' verbs return the canonical RFC-9562 string representation. The 'S' verb returns the RFC-9562 format, but with capital hex digits. The '#v' verb returns the "Go syntax" representation, which is a 16 byte array initializer. All other verbs not handled directly by the fmt package (like '%p') are unsupported and will return "%!verb(uuid.UUID=value)" as recommended by the fmt package.
func (UUID) MarshalBinary ¶
MarshalBinary implements the encoding.BinaryMarshaler interface.
func (UUID) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface. The encoding is the same as returned by the String() method.
func (*UUID) Parse ¶
Parse parses the UUID stored in the string text. Parsing and supported formats are the same as UnmarshalText.
func (*UUID) Scan ¶
Scan implements the sql.Scanner interface. A 16-byte slice will be handled by UnmarshalBinary, while a longer byte slice or a string will be handled by UnmarshalText.
func (UUID) String ¶
String returns a canonical RFC-9562 string representation of the UUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
func (*UUID) UnmarshalBinary ¶
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface. It will return an error if the slice isn't 16 bytes long.
func (*UUID) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface. Following formats are supported:
"6ba7b810-9dad-11d1-80b4-00c04fd430c8", "{6ba7b810-9dad-11d1-80b4-00c04fd430c8}", "urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8" "6ba7b8109dad11d180b400c04fd430c8" "{6ba7b8109dad11d180b400c04fd430c8}", "urn:uuid:6ba7b8109dad11d180b400c04fd430c8"
ABNF for supported UUID text representation follows:
URN := 'urn' UUID-NID := 'uuid' hexdig := '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' hexoct := hexdig hexdig 2hexoct := hexoct hexoct 4hexoct := 2hexoct 2hexoct 6hexoct := 4hexoct 2hexoct 12hexoct := 6hexoct 6hexoct hashlike := 12hexoct canonical := 4hexoct '-' 2hexoct '-' 2hexoct '-' 6hexoct plain := canonical | hashlike uuid := canonical | hashlike | braced | urn braced := '{' plain '}' | '{' hashlike '}' urn := URN ':' UUID-NID ':' plain