package uuid
Import Path
github.com/gofrs/uuid (on go.dev)
Dependency Relation
imports 14 packages, and imported by one package
Involved Source Files
codec.go
generator.go
sql.go
Package uuid provides implementations of the Universally Unique Identifier
(UUID), as specified in RFC-4122 and the Peabody RFC Draft (revision 03).
RFC-4122[1] provides the specification for versions 1, 3, 4, and 5. The
Peabody UUID RFC Draft[2] provides the specification for the new k-sortable
UUIDs, versions 6 and 7.
DCE 1.1[3] 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 4122, 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/rfc4122
[2] https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-03
[3] http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01
Package-Level Type Names (total 8)
EpochFunc is the function type used to provide the current time.
func WithEpochFunc(epochf EpochFunc) GenOption
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.
NewV1 returns a UUID based on the current timestamp and MAC address.
NewV3 returns a UUID based on the MD5 hash of the namespace UUID and name.
NewV4 returns a randomly generated UUID.
NewV5 returns a UUID based on SHA-1 hash of the namespace UUID and name.
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.
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 04 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.
*Gen : Generator
func NewGen() *Gen
func NewGenWithHWAF(hwaf HWAddrFunc) *Gen
func NewGenWithOptions(opts ...GenOption) *Gen
Generator provides an interface for generating UUIDs.
( Generator) NewV1() (UUID, error)
( Generator) NewV3(ns UUID, name string) UUID
( Generator) NewV4() (UUID, error)
( Generator) NewV5(ns UUID, name string) UUID
( Generator) NewV6() (UUID, error)
( Generator) NewV7() (UUID, error)
*Gen
var DefaultGenerator
GenOption is a function type that can be used to configure a Gen generator.
func WithEpochFunc(epochf EpochFunc) GenOption
func WithHWAddrFunc(hwaf HWAddrFunc) GenOption
func WithRandomReader(reader io.Reader) GenOption
func NewGenWithOptions(opts ...GenOption) *Gen
HWAddrFunc is the function type used to provide hardware (MAC) addresses.
func NewGenWithHWAF(hwaf HWAddrFunc) *Gen
func WithHWAddrFunc(hwaf HWAddrFunc) GenOption
NullUUID can be used with the standard sql package to represent a
UUID value that can be NULL in the database.
UUID UUID
Valid bool
MarshalJSON marshals the NullUUID as null or the nested UUID
Scan implements the sql.Scanner interface.
UnmarshalJSON unmarshals a NullUUID
Value implements the driver.Valuer interface.
*NullUUID : database/sql.Scanner
NullUUID : database/sql/driver.Valuer
NullUUID : encoding/json.Marshaler
*NullUUID : encoding/json.Unmarshaler
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.
Time returns the UTC time.Time representation of a Timestamp
func TimestampFromV1(u UUID) (Timestamp, error)
func TimestampFromV6(u UUID) (Timestamp, error)
UUID is an array type to represent the value of a UUID, as defined in RFC-4122.
Bytes returns a byte slice representation of the UUID.
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.
IsNil returns if the UUID is equal to the nil UUID
MarshalBinary implements the encoding.BinaryMarshaler interface.
MarshalText implements the encoding.TextMarshaler interface.
The encoding is the same as returned by the String() method.
Parse parses the UUID stored in the string text. Parsing and supported
formats are the same as UnmarshalText.
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.
SetVariant sets the variant bits.
SetVersion sets the version bits.
String returns a canonical RFC-4122 string representation of the UUID:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
It will return an error if the slice isn't 16 bytes long.
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
Value implements the driver.Valuer interface.
Variant returns the UUID layout variant.
Version returns the algorithm version used to generate the UUID.
UUID : github.com/ChrisTrenkamp/goxpath/tree.Result
*UUID : database/sql.Scanner
UUID : database/sql/driver.Valuer
UUID : encoding.BinaryMarshaler
*UUID : encoding.BinaryUnmarshaler
UUID : encoding.TextMarshaler
*UUID : encoding.TextUnmarshaler
UUID : fmt.Formatter
UUID : fmt.Stringer
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 NewV3(ns UUID, name string) UUID
func NewV4() (UUID, error)
func NewV5(ns UUID, name string) UUID
func NewV6() (UUID, error)
func NewV7() (UUID, error)
func (*Gen).NewV1() (UUID, error)
func (*Gen).NewV3(ns UUID, name string) UUID
func (*Gen).NewV4() (UUID, error)
func (*Gen).NewV5(ns UUID, name string) UUID
func (*Gen).NewV6() (UUID, error)
func (*Gen).NewV7() (UUID, error)
func Generator.NewV1() (UUID, error)
func Generator.NewV3(ns UUID, name string) UUID
func Generator.NewV4() (UUID, error)
func Generator.NewV5(ns UUID, name string) UUID
func Generator.NewV6() (UUID, error)
func Generator.NewV7() (UUID, error)
func Must(u UUID, err error) UUID
func NewV3(ns UUID, name string) UUID
func NewV5(ns UUID, name string) UUID
func TimestampFromV1(u UUID) (Timestamp, error)
func TimestampFromV6(u UUID) (Timestamp, error)
func (*Gen).NewV3(ns UUID, name string) UUID
func (*Gen).NewV5(ns UUID, name string) UUID
func Generator.NewV3(ns UUID, name string) UUID
func Generator.NewV5(ns UUID, name string) UUID
var NamespaceDNS
var NamespaceOID
var NamespaceURL
var NamespaceX500
var Nil
Package-Level Functions (total 19)
FromBytes returns a UUID generated from the raw byte slice input.
It will return an error if the slice isn't 16 bytes long.
FromBytesOrNil returns a UUID generated from the raw byte slice input.
Same behavior as FromBytes(), but returns uuid.Nil instead of an error.
FromString returns a UUID parsed from the input string.
Input is expected in a form accepted by UnmarshalText.
FromStringOrNil returns a UUID parsed from the input string.
Same behavior as FromString(), but returns uuid.Nil instead of an error.
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"))
NewGen returns a new instance of Gen with some default values set. Most
people should use this.
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.
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()
NewV1 returns a UUID based on the current timestamp and MAC address.
NewV3 returns a UUID based on the MD5 hash of the namespace UUID and name.
NewV4 returns a randomly generated UUID.
NewV5 returns a UUID based on SHA-1 hash of the namespace UUID and name.
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.
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.
This is implemented based on revision 04 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.
TimestampFromV1 returns the Timestamp embedded within a V1 UUID.
Returns an error if the UUID is any version other than 1.
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.
WithEpochFunc is a GenOption that allows you to provide your own EpochFunc
function.
When this option is nil, time.Now is used.
WithHWAddrFunc is a GenOption that allows you to provide your own HWAddrFunc
function.
When this option is nil, the defaultHWAddrFunc is used.
WithRandomReader is a GenOption that allows you to provide your own random
reader.
When this option is nil, the default rand.Reader is used.
Package-Level Variables (total 6)
DefaultGenerator is the default UUID Generator used by this package.
Predefined namespace UUIDs.
Predefined namespace UUIDs.
Predefined namespace UUIDs.
Predefined namespace UUIDs.
Nil is the nil UUID, as specified in RFC-4122, that has all 128 bits set to
zero.
Package-Level Constants (total 14)
UUID DCE domains.
UUID DCE domains.
UUID DCE domains.
Size of a UUID in bytes.
UUID versions.
UUID versions.
UUID versions.
UUID versions.
UUID versions.
UUID versions.
UUID layout variants.
UUID layout variants.
UUID layout variants.
UUID layout variants.
 |
The pages are generated with Golds v0.6.7. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds. |