uuid

package
v0.23.2 Latest Latest
Warning

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

 Go to latest Published: Feb 12, 2024 License: Apache-2.0 Imports: 20 Imported by: 6

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

UUID versions.

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

UUID layout variants.

View Source 
const RFC4122StrSize = 36

RFC4122StrSize of a size of the RFC-4122 string representation of UUID.

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 Max = FromUint128(uint128.FromInts(math.MaxUint64, math.MaxUint64))

Max is the maximum possible UUID, which has all 128 bits set to 1.

View Source 
var Nil = UUID{}

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

Functions

func RandomHardwareAddrFunc 

func RandomHardwareAddrFunc() (net.HardwareAddr, error)

RandomHardwareAddrFunc returns a random hardware address, with the multicast and local-admin bits set as per the IEEE802 spec.

Types

type Bytes 

type Bytes []byte

Bytes represents a byte slice which is intended to be interpreted as a binary encoding of a UUID.

func (Bytes) GetUUID 

func (b Bytes) GetUUID() UUID

GetUUID constructs a UUID from the bytes. If the data is not valid, a zero value will be returned.

func (Bytes) String 

func (b Bytes) String() string

String returns the string representation of the underlying UUID.

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. NewGen by default uses crypto/rand.Reader as its source of randomness.

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 NewGenWithReader 

func NewGenWithReader(r io.Reader) *Gen

NewGenWithReader returns a new instance of gen which uses r as its source of randomness.

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.

type Generator 

type Generator interface {
	NewV1() (UUID, error)
	// NewV2(domain byte) (UUID, error) // CRL: Removed support for V2.
	NewV3(ns UUID, name string) UUID
	NewV4() (UUID, error)
	NewV5(ns UUID, name string) UUID
}

Generator provides an interface for generating UUIDs. 

var DefaultGenerator Generator = NewGen()

DefaultGenerator is the default UUID Generator used by this package. It uses crypto/rand as the source of entropy.

type HWAddrFunc 

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

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

type NullUUID 

type NullUUID struct {
	UUID  UUID
	Valid bool
}

NullUUID can be used with the standard sql package to represent a UUID value that can be NULL in the database.

func (NullUUID) MarshalJSON 

func (u NullUUID) MarshalJSON() ([]byte, error)

MarshalJSON marshals the NullUUID as null or the nested UUID

func (*NullUUID) Scan 

func (u *NullUUID) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (*NullUUID) UnmarshalJSON 

func (u *NullUUID) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a NullUUID

func (NullUUID) Value 

func (u NullUUID) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type ShortStringer 

type ShortStringer UUID

ShortStringer implements fmt.Stringer to output Short() on String().

func (ShortStringer) String 

func (s ShortStringer) String() string

String is part of fmt.Stringer.

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 V2-V5 UUIDs 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 (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 FastMakeV4 

func FastMakeV4() UUID

FastMakeV4 generates a UUID using a fast but not cryptographically secure source of randomness.

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(input 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 FromUint128 

func FromUint128(input uint128.Uint128) UUID

FromUint128 delegates to FromBytes and wraps the result in a UUID.

func MakeV4 

func MakeV4() UUID

MakeV4 calls Must(NewV4)

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 NewPopulatedUUID 

func NewPopulatedUUID(r interface {
	Uint32() uint32
}) *UUID

NewPopulatedUUID returns a populated UUID.

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

func (u *UUID) DeterministicV4(i, n uint64)

DeterministicV4 overwrites this UUID with one computed deterministically to evenly fill the space of possible V4 UUIDs. `n` represents how many UUIDs will fill the space and `i` is an index into these `n` (and thus must be in the range `[0,n)`). The resulting UUIDs will be unique, evenly-spaced, and sorted.

func (UUID) Equal 

func (u UUID) Equal(t UUID) bool

Equal returns true iff the receiver equals the argument.

This method exists only to conform to the API expected by gogoproto's generated Equal implementations.

func (UUID) GetBytes 

func (u UUID) GetBytes() []byte

GetBytes returns the UUID as a byte slice. It incurs an allocation if the return value escapes.

func (*UUID) GetBytesMut 

func (u *UUID) GetBytesMut() []byte

GetBytesMut returns the UUID as a mutable byte slice. Unlike GetBytes, it does not necessarily incur an allocation if the return value escapes. Instead, the return value escaping will cause the method's receiver (and any struct that it is a part of) to escape. Use only if GetBytes is causing an allocation and the UUID is already on the heap.

func (UUID) MarshalBinary 

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

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (UUID) MarshalJSON 

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

MarshalJSON returns the JSON encoding of u.

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

func (u UUID) MarshalTo(data []byte) (int, error)

MarshalTo marshals u to data.

func (*UUID) Scan 

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 (*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) Short 

func (u UUID) Short() string

Short returns the first eight characters of the output of String().

func (UUID) Size 

func (u UUID) Size() int

Size returns the marshaled size of u, in bytes.

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

func (u UUID) StringBytes(buf []byte)

StringBytes writes the result of String directly into a buffer, which must have a length of at least 36.

func (UUID) ToUint128 

func (u UUID) ToUint128() uint128.Uint128

ToUint128 returns the UUID as a Uint128.

func (*UUID) Unmarshal 

func (u *UUID) Unmarshal(data []byte) error

Unmarshal unmarshals data to u.

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

func (u *UUID) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the JSON encoded data into u.

func (*UUID) UnmarshalText 

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}",
  "{6ba7b810-9dad-11d1-80b4-00c04fd430c8}",
  "urn:uuid:6ba7b8109dad11d180b400c04fd430c8",
  "urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8",
	 "6ba7-b810-9dad-11d1-80b4-00c0-4fd4-30c8"

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
hyphenated := hyphen after any group of 4 hexdig
Ex.6ba7-b810-9dad-11d1-80b4-00c0-4fd4-30c8
Ex.6ba7-b810-9dad11d1-80b400c0-4fd4-30c8

uuid := hyphenated | hashlike | braced | urn

braced := '{' hyphenated '}' | '{' hashlike  '}'
urn := URN ':' UUID-NID ':' hyphenated

func (UUID) Value 

func (u UUID) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

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.