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 requires Go >= 1.2.

Example

package main

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

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

	// Parsing UUID from string input
	u2, err := uuid.FromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
	if err != nil {
		fmt.Printf("Something gone wrong: %s", err)
	}
	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.

Expand ▾ Collapse ▴

Documentation

Overview

    Package uuid provides implementation of Universally Unique Identifier (UUID). Supported versions are 1, 3, 4 and 5 (as specified in RFC 4122) and version 2 (as specified in DCE 1.1).

    Index

    Constants

    View Source
    const (
    	V1 byte
    	V2
    	V3
    	V4
    	V5
    )

      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 special form of UUID that is specified to have 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

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

                    Generator provides interface for generating UUIDs.

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

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

                        Scan implements the sql.Scanner interface.

                        func (NullUUID) Value

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

                          Value implements the driver.Valuer interface.

                          type UUID

                          type UUID [Size]byte

                            UUID representation compliant with specification described 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

                                    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

                                        NewV1 returns UUID based on current timestamp and MAC address.

                                        func NewV2

                                        func NewV2(domain byte) UUID

                                          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

                                              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 bytes slice representation of 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 is handled by UnmarshalBinary, while a longer byte slice or a string is handled by UnmarshalText.

                                                        func (*UUID) SetVariant

                                                        func (u *UUID) SetVariant(v byte)

                                                          SetVariant sets variant bits.

                                                          func (*UUID) SetVersion

                                                          func (u *UUID) SetVersion(v byte)

                                                            SetVersion sets version bits.

                                                            func (UUID) String

                                                            func (u UUID) String() string

                                                              Returns canonical string representation of 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 UUID layout variant.

                                                                      func (UUID) Version

                                                                      func (u UUID) Version() byte

                                                                        Version returns algorithm version used to generate UUID.