README

UUID

License Build Status GoDoc Coverage Status Go Report Card

Package uuid provides a pure Go implementation of Universally Unique Identifiers (UUID) variant as defined in RFC-4122. This package supports both the creation and parsing of UUIDs in different formats.

This package supports the following UUID versions:

  • Version 1, based on timestamp and MAC address (RFC-4122)
  • Version 3, based on MD5 hashing of a named value (RFC-4122)
  • Version 4, based on random numbers (RFC-4122)
  • Version 5, based on SHA-1 hashing of a named value (RFC-4122)

Project History

This project was originally forked from the github.com/satori/go.uuid repository after it appeared to be no longer maintained, while exhibiting critical flaws. We have decided to take over this project to ensure it receives regular maintenance for the benefit of the larger Go community.

We'd like to thank Maxim Bublis for his hard work on the original iteration of the package.

License

This source code of this package is released under the MIT License. Please see the LICENSE for the full content of the license.

We recommend using v2.0.0+ of this package, as versions prior to 2.0.0 were created before our fork of the original package and have some known deficiencies.

Installation

It is recommended to use a package manager like dep that understands tagged releases of a package, as well as semantic versioning.

If you are unable to make use of a dependency manager with your project, you can use the go get command to download it directly:

$ go get github.com/gofrs/uuid

Requirements

Due to subtests not being supported in older versions of Go, this package is only regularly tested against Go 1.7+. This package may work perfectly fine with Go 1.2+, but support for these older versions is not actively maintained.

Go 1.11 Modules

As of v3.2.0, this repository no longer adopts Go modules, and v3.2.0 no longer has a go.mod file. As a result, v3.2.0 also drops support for the github.com/gofrs/uuid/v3 import path. Only module-based consumers are impacted. With the v3.2.0 release, all gofrs/uuid consumers should use the github.com/gofrs/uuid import path.

An existing module-based consumer will continue to be able to build using the github.com/gofrs/uuid/v3 import path using any valid consumer go.mod that worked prior to the publishing of v3.2.0, but any module-based consumer should start using the github.com/gofrs/uuid import path when possible and must use the github.com/gofrs/uuid import path prior to upgrading to v3.2.0.

Please refer to Issue #61 and Issue #66 for more details.

Usage

Here is a quick overview of how to use this package. For more detailed documentation, please see the GoDoc Page.

package main

import (
	"log"

	"github.com/gofrs/uuid"
)

// Create a Version 4 UUID, panicking on error.
// Use this form to initialize package-level variables.
var u1 = uuid.Must(uuid.NewV4())

func main() {
	// Create a Version 4 UUID.
	u2, err := uuid.NewV4()
	if err != nil {
		log.Fatalf("failed to generate UUID: %v", err)
	}
	log.Printf("generated Version 4 UUID %v", u2)

	// Parse a UUID from a string.
	s := "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
	u3, err := uuid.FromString(s)
	if err != nil {
		log.Fatalf("failed to parse UUID %q: %v", s, err)
	}
	log.Printf("successfully parsed UUID %v", u3)
}

References

Expand ▾ Collapse ▴

Documentation

Overview

    Package uuid provides implementations of the Universally Unique Identifier (UUID), as specified in RFC-4122,

    RFC-4122[1] provides the specification for versions 1, 3, 4, and 5.

    DCE 1.1[2] 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] 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)
    )

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

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