uuid

package module
v2.0.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2018 License: MIT Imports: 14 Imported by: 0

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 2, based on timestamp, MAC address and POSIX UID/GID (DCE 1.1)
  • 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.

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

Documentation

Overview

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

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

DCE 1.1[2] provides the specification for version 2.

[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)
	V2      // Version 2 (date-time and MAC address, DCE security version)
	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 DefaultGenerator = newRFC4122Generator()

DefaultGenerator is the default Generator used.

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 Equal 

func Equal(u1 UUID, u2 UUID) bool

Equal returns true if u1 and u2 equals, otherwise returns false.

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 an 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) Scan added in v1.1.0 

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

Scan implements the sql.Scanner interface.

func (NullUUID) Value added in v1.1.0 

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

Value implements the driver.Valuer interface.

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

func NewV2 

func NewV2(domain byte) (UUID, error)

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

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

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.