uuid

package module
v1.2.1 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2022 License: MIT Imports: 16 Imported by: 0

README

UUID package for Go language

Build Status Coverage Status GoDoc

This package provides pure Go implementation of Universally Unique Identifier (UUID). Supported both creation and parsing of UUIDs.

With 100% test coverage and benchmarks out of box.

Supported versions:

  • Version 1, based on timestamp and MAC address (RFC 4122)
  • Version 2, based on timestamp, MAC address and POSIX UID/GID (DCE 1.1)
  • Version 3, based on MD5 hashing (RFC 4122)
  • Version 4, based on random numbers (RFC 4122)
  • Version 5, based on SHA-1 hashing (RFC 4122)

Installation

Use the go command:

$ go get github.com/satori/go.uuid

Requirements

UUID package tested against Go >= 1.6.

Example

package main

import (
	"fmt"
	"github.com/satori/go.uuid"
)

func main() {
	// Creating UUID Version 4
	// panic on error
	u1 := uuid.Must(uuid.NewV4())
	fmt.Printf("UUIDv4: %s\n", u1)

	// or error handling
	u2, err := uuid.NewV4()
	if err != nil {
		fmt.Printf("Something went wrong: %s", err)
		return
	}
	fmt.Printf("UUIDv4: %s\n", u2)

	// Parsing UUID from string input
	u2, err := uuid.FromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
	if err != nil {
		fmt.Printf("Something went wrong: %s", err)
		return
	}
	fmt.Printf("Successfully parsed: %s", u2)
}

Documentation

Documentation is hosted at GoDoc project.

Copyright (C) 2013-2018 by Maxim Bublis b@codemonkey.ru.

UUID package released under MIT License. See LICENSE for details.

Documentation

Overview

Package uuid provides implementations of the Universally Unique Identifier (UUID), as specified in RFC-4122 and the Peabody RFC Draft (revision 02).

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-02 [3] http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01

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) [peabody draft]
	V7 // Version 7 (k-sortable timestamp, with configurable precision, 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

This section is empty.

Types

type Generator added in v1.2.0 

type Generator interface {
	NewV1() (UUID, error)
	NewV2(domain byte) (UUID, error)
	NewV3(ns UUID, name string) UUID
	NewV4() (UUID, error)
	NewV5(ns UUID, name string) UUID
}

Generator provides interface for generating UUIDs.

type NullUUID added in v1.1.0 

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 added in v1.2.1 

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

MarshalJSON marshals the NullUUID as null or the nested UUID

func (*NullUUID) Scan added in v1.1.0 

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

Scan implements the sql.Scanner interface.

func (*NullUUID) UnmarshalJSON added in v1.2.1 

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

UnmarshalJSON unmarshals a NullUUID

func (NullUUID) Value added in v1.1.0 

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

Value implements the driver.Valuer interface.

type Timestamp added in v1.2.1 

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 added in v1.2.1 

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 added in v1.2.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 01 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 added in v1.2.1 

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) (u UUID, err error)

FromBytes returns UUID converted from raw byte slice input. It will return error if the slice isn't 16 bytes long.

func FromBytesOrNil 

func FromBytesOrNil(input []byte) UUID

FromBytesOrNil returns UUID converted from raw byte slice input. Same behavior as FromBytes, but returns a Nil UUID on error.

func FromString 

func FromString(input string) (u UUID, err error)

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

func FromStringOrNil 

func FromStringOrNil(input string) UUID

FromStringOrNil returns UUID parsed from string input. Same behavior as FromString, but returns a Nil UUID on error.

func Must added in v1.2.0 

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 UUID based on current timestamp and MAC address.

func NewV2 

func NewV2(domain byte) (UUID, error)

NewV2 returns DCE Security UUID based on POSIX UID/GID.

func NewV3 

func NewV3(ns UUID, name string) UUID

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

func NewV4 

func NewV4() (UUID, error)

NewV4 returns random generated UUID.

func NewV5 

func NewV5(ns UUID, name string) UUID

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

func (UUID) Bytes 

func (u UUID) Bytes() []byte

Bytes returns a byte slice representation of the UUID.

func (UUID) Format added in v1.2.1 

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 added in v1.2.1 

func (u UUID) IsNil() bool

IsNil returns if the UUID is equal to the nil UUID

func (UUID) MarshalBinary 

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

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (UUID) MarshalText 

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

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

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) 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) (err error)

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface. It will return error if the slice isn't 16 bytes long.

func (*UUID) UnmarshalText 

func (u *UUID) UnmarshalText(text []byte) (err 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"

ABNF for supported UUID text representation follows: 

uuid := canonical | hashlike | braced | urn
plain := canonical | hashlike
canonical := 4hexoct '-' 2hexoct '-' 2hexoct '-' 6hexoct
hashlike := 12hexoct
braced := '{' plain '}'
urn := URN ':' UUID-NID ':' plain
URN := 'urn'
UUID-NID := 'uuid'
12hexoct := 6hexoct 6hexoct
6hexoct := 4hexoct 2hexoct
4hexoct := 2hexoct 2hexoct
2hexoct := hexoct hexoct
hexoct := hexdig hexdig
hexdig := '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' |
          'a' | 'b' | 'c' | 'd' | 'e' | 'f' |
          'A' | 'B' | 'C' | 'D' | 'E' | 'F'

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.