UUID versions.
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) [peabody draft]
V7 // Version 7 (k-sortable timestamp and random data) [peabody draft]
)
UUID layout variants.
const (
VariantNCS byte = iota
VariantRFC4122
VariantMicrosoft
VariantFuture
)
UUID DCE domains.
const (
DomainPerson = iota
DomainGroup
DomainOrg
)
Size of a UUID in bytes.
const Size = 16
Predefined namespace UUIDs.
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"))
)
Nil is the nil UUID, as specified in RFC-4122, that has all 128 bits set to zero.
var Nil = UUID{}
Gen is a reference UUID generator based on the specifications laid out in RFC-4122 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.
type Gen struct {
// contains filtered or unexported fields
}
func NewGen() *Gen
NewGen returns a new instance of Gen with some default values set. Most people should use this.
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 (g *Gen) NewV1() (UUID, error)
NewV1 returns a UUID based on the current timestamp and MAC address.
func (g *Gen) NewV3(ns UUID, name string) UUID
NewV3 returns a UUID based on the MD5 hash of the namespace UUID and name.
func (g *Gen) NewV4() (UUID, error)
NewV4 returns a randomly generated UUID.
func (g *Gen) NewV5(ns UUID, name string) UUID
NewV5 returns a UUID based on SHA-1 hash of the namespace UUID and name.
func (g *Gen) NewV6() (UUID, error)
NewV6 returns a k-sortable UUID based on a 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.
This is implemented based on revision 03 of the Peabody UUID draft, and may be subject to change pending further revisions. Until the final specification revision is finished, changes required to implement updates to the spec will not be considered a breaking change. They will happen as a minor version releases until the spec is final.
func (g *Gen) NewV7() (UUID, error)
NewV7 returns a k-sortable UUID based on the current millisecond precision UNIX epoch and 74 bits of pseudorandom data.
This is implemented based on revision 03 of the Peabody UUID draft, and may be subject to change pending further revisions. Until the final specification revision is finished, changes required to implement updates to the spec will not be considered a breaking change. They will happen as a minor version releases until the spec is final.
Generator provides an interface for generating UUIDs.
type Generator interface {
NewV1() (UUID, error)
NewV3(ns UUID, name string) UUID
NewV4() (UUID, error)
NewV5(ns UUID, name string) UUID
NewV6() (UUID, error)
NewV7() (UUID, error)
}
DefaultGenerator is the default UUID Generator used by this package.
var DefaultGenerator Generator = NewGen()
HWAddrFunc is the function type used to provide hardware (MAC) addresses.
type HWAddrFunc func() (net.HardwareAddr, error)
NullUUID can be used with the standard sql package to represent a UUID value that can be NULL in the database.
type NullUUID struct {
UUID UUID
Valid bool
}
func (u NullUUID) MarshalJSON() ([]byte, error)
MarshalJSON marshals the NullUUID as null or the nested UUID
func (u *NullUUID) Scan(src interface{}) error
Scan implements the sql.Scanner interface.
func (u *NullUUID) UnmarshalJSON(b []byte) error
UnmarshalJSON unmarshals a NullUUID
func (u NullUUID) Value() (driver.Value, error)
Value implements the driver.Valuer interface.
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.
type Timestamp uint64
func TimestampFromV1(u UUID) (Timestamp, error)
TimestampFromV1 returns the Timestamp embedded within a V1 UUID. Returns an error if the UUID is any version other than 1.
func TimestampFromV6(u UUID) (Timestamp, error)
TimestampFromV6 returns the Timestamp embedded within a V6 UUID. This function returns an error if the UUID is any version other than 6.
This is implemented based on revision 03 of the Peabody UUID draft, and may be subject to change pending further revisions. Until the final specification revision is finished, changes required to implement updates to the spec will not be considered a breaking change. They will happen as a minor version releases until the spec is final.
func (t Timestamp) Time() (time.Time, error)
Time returns the UTC time.Time representation of a Timestamp
UUID is an array type to represent the value of a UUID, as defined in RFC-4122.
type UUID [Size]byte
func FromBytes(input []byte) (UUID, error)
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(input []byte) UUID
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(input string) (UUID, error)
FromString returns a UUID parsed from the input string. Input is expected in a form accepted by UnmarshalText.
func FromStringOrNil(input string) UUID
FromStringOrNil returns a UUID parsed from the input string. Same behavior as FromString(), but returns uuid.Nil instead of an error.
func Must(u UUID, err error) UUID
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 NewV1() (UUID, error)
NewV1 returns a UUID based on the current timestamp and MAC address.
func NewV3(ns UUID, name string) UUID
NewV3 returns a UUID based on the MD5 hash of the namespace UUID and name.
func NewV4() (UUID, error)
NewV4 returns a randomly generated UUID.
func NewV5(ns UUID, name string) UUID
NewV5 returns a UUID based on SHA-1 hash of the namespace UUID and name.
func NewV6() (UUID, error)
NewV6 returns a k-sortable UUID based on a 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.
This is implemented based on revision 03 of the Peabody UUID draft, and may be subject to change pending further revisions. Until the final specification revision is finished, changes required to implement updates to the spec will not be considered a breaking change. They will happen as a minor version releases until the spec is final.
func NewV7() (UUID, error)
NewV7 returns a k-sortable UUID based on the current millisecond precision UNIX epoch and 74 bits of pseudorandom data.
This is implemented based on revision 03 of the Peabody UUID draft, and may be subject to change pending further revisions. Until the final specification revision is finished, changes required to implement updates to the spec will not be considered a breaking change. They will happen as a minor version releases until the spec is final.
func (u UUID) Bytes() []byte
Bytes returns a byte slice representation of the UUID.
func (u UUID) Format(f fmt.State, c rune)
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-4122 string representation. The 'S' verb returns the RFC-4122 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 (u UUID) IsNil() bool
IsNil returns if the UUID is equal to the nil UUID
func (u UUID) MarshalBinary() ([]byte, error)
MarshalBinary implements the encoding.BinaryMarshaler interface.
func (u UUID) MarshalText() ([]byte, error)
MarshalText implements the encoding.TextMarshaler interface. The encoding is the same as returned by the String() method.
func (u *UUID) Scan(src interface{}) error
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 (u *UUID) SetVariant(v byte)
SetVariant sets the variant bits.
func (u *UUID) SetVersion(v byte)
SetVersion sets the version bits.
func (u UUID) String() string
String returns a canonical RFC-4122 string representation of the UUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
func (u *UUID) UnmarshalBinary(data []byte) error
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface. It will return an error if the slice isn't 16 bytes long.
func (u *UUID) UnmarshalText(text []byte) error
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
func (u UUID) Value() (driver.Value, error)
Value implements the driver.Valuer interface.
func (u UUID) Variant() byte
Variant returns the UUID layout variant.
func (u UUID) Version() byte
Version returns the algorithm version used to generate the UUID.