uuid

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 9, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
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 versions.

View Source 
const (
	VariantNCS byte = iota
	VariantRFC4122
	VariantMicrosoft
	VariantFuture
)

UUID layout variants.

View Source 
const (
	DomainPerson = iota
	DomainGroup
	DomainOrg
)

UUID DCE domains.

View Source 
const Size = 16

Size of a UUID in bytes.

Variables

View Source 
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.

View Source 
var Nil = UUID{}

Nil is the nil UUID, as specified in RFC-4122, that has all 128 bits set to zero.

Functions

func NewV1Str added in v0.1.7 

func NewV1Str() (string, error)

NewV1Str returns a UUID based on the current timestamp and MAC address.

func NewV1StrNs added in v0.1.7 

func NewV1StrNs() (string, error)

NewV1StrNs returns a UUID based on the current timestamp and MAC address.

func NewV3Str added in v0.1.7 

func NewV3Str(ns UUID, name string) string

NewV3Str returns a UUID based on the MD5 hash of the namespace UUID and name.

func NewV3StrNs added in v0.1.7 

func NewV3StrNs(ns UUID, name string) string

NewV3StrNs returns a UUID based on the MD5 hash of the namespace UUID and name.

func NewV4Str added in v0.1.7 

func NewV4Str() (string, error)

NewV4Str returns a randomly generated UUID.

func NewV4StrNs added in v0.1.7 

func NewV4StrNs() (string, error)

NewV4StrNs returns a randomly generated UUID.

func NewV5Str added in v0.1.7 

func NewV5Str(ns UUID, name string) string

NewV5Str returns a UUID based on SHA-1 hash of the namespace UUID and name.

func NewV5StrNs added in v0.1.7 

func NewV5StrNs(ns UUID, name string) string

NewV5StrNs returns a UUID based on SHA-1 hash of the namespace UUID and name.

func NewV6Str added in v0.1.7 

func NewV6Str() (string, error)

NewV6Str 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 NewV6StrNs added in v0.1.7 

func NewV6StrNs() (string, error)

NewV6StrNs 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 NewV7Str added in v0.1.7 

func NewV7Str() (string, error)

NewV7Str 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.

func NewV7StrNs added in v0.1.7 

func NewV7StrNs() (string, error)

NewV7StrNs 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.

Types

type EpochFunc 

type EpochFunc func() time.Time

EpochFunc is the function type used to provide the current time.

type Gen 

type Gen struct {
	// contains filtered or unexported fields
}

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.

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 

func NewGenWithOptions(opts ...GenOption) *Gen

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) NewV1 

func (g *Gen) NewV1() (UUID, error)

NewV1 returns a UUID based on the current timestamp and MAC address.

func (*Gen) NewV3 

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 (*Gen) NewV4 

func (g *Gen) NewV4() (UUID, error)

NewV4 returns a randomly generated UUID.

func (*Gen) NewV5 

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 (*Gen) NewV6 

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 (*Gen) NewV7 

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 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.

type GenOption 

type GenOption func(*Gen)

GenOption is a function type that can be used to configure a Gen generator.

func WithEpochFunc 

func WithEpochFunc(epochf EpochFunc) GenOption

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 

func WithRandomReader(reader io.Reader) GenOption

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)
	NewV3(ns UUID, name string) UUID
	NewV4() (UUID, error)
	NewV5(ns UUID, name string) UUID
	NewV6() (UUID, error)
	NewV7() (UUID, error)
}

Generator provides an interface for generating UUIDs. 

var DefaultGenerator Generator = NewGen()

DefaultGenerator is the default UUID Generator used by this package.

type HWAddrFunc 

type HWAddrFunc func() (net.HardwareAddr, error)

HWAddrFunc is the function type used to provide hardware (MAC) addresses.

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 

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 

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 (Timestamp) Time 

func (t Timestamp) Time() (time.Time, error)

Time returns the UTC time.Time representation of a Timestamp

type UUID 

type UUID [Size]byte

UUID is an array type to represent the value of a UUID, as defined in RFC-4122.

func FromBytes 

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 

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 

func FromString(text string) (UUID, error)

FromString returns a UUID parsed from the input string. Input is expected in a form accepted by UnmarshalText.

func FromStringOrNil 

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 

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 

func NewV1() (UUID, error)

NewV1 returns a UUID based on the current timestamp and MAC address.

func NewV3 

func NewV3(ns UUID, name string) UUID

NewV3 returns a UUID based on the MD5 hash of the namespace UUID and name.

func NewV4 

func NewV4() (UUID, error)

NewV4 returns a randomly generated UUID.

func NewV5 

func NewV5(ns UUID, name string) UUID

NewV5 returns a UUID based on SHA-1 hash of the namespace UUID and name.

func NewV6 

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 

func NewV7() (UUID, error)

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.

func (UUID) Bytes 

func (u UUID) Bytes() []byte

Bytes returns a byte slice representation of the UUID.

func (UUID) Format 

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 (UUID) IsNil 

func (u UUID) IsNil() bool

IsNil returns if the UUID is equal to the nil UUID

func (UUID) MarshalBinary 

func (u UUID) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (UUID) MarshalText 

func (u UUID) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface. The encoding is the same as returned by the String() method.

func (*UUID) Parse 

func (u *UUID) Parse(s string) error

Parse parses the UUID stored in the string text. Parsing and supported formats are the same as UnmarshalText.

func (*UUID) SetVariant 

func (u *UUID) SetVariant(v byte)

SetVariant sets the variant bits.

func (*UUID) SetVersion 

func (u *UUID) SetVersion(v byte)

SetVersion sets the version bits.

func (UUID) String 

func (u UUID) String() string

String returns a canonical RFC-4122 string representation of the UUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

func (*UUID) UnmarshalBinary 

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 (*UUID) UnmarshalText 

func (u *UUID) UnmarshalText(b []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 (UUID) Variant 

func (u UUID) Variant() byte

Variant returns the UUID layout variant.

func (UUID) Version 

func (u UUID) Version() byte

Version returns the algorithm version used to generate the UUID.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.