README

uuid build status

The uuid package generates and inspects UUIDs based on RFC 4122 and DCE 1.1: Authentication and Security Services.

This package is based on the github.com/pborman/uuid package (previously named code.google.com/p/go-uuid). It differs from these earlier packages in that a UUID is a 16 byte array rather than a byte slice. One loss due to this change is the ability to represent an invalid UUID (vs a NIL UUID).

Install

go get github.com/google/uuid

Documentation

GoDoc

Full go doc style documentation for the package can be viewed online without installing this package by using the GoDoc site here: http://pkg.go.dev/github.com/google/uuid

Expand ▾ Collapse ▴

Documentation

Overview

    Package uuid generates and inspects UUIDs.

    UUIDs are based on RFC 4122 and DCE 1.1: Authentication and Security Services.

    A UUID is a 16 byte (128 bit) array. UUIDs may be used as keys to maps or compared directly.

    Index

    Constants

    View Source
    const (
    	Person = Domain(0)
    	Group  = Domain(1)
    	Org    = Domain(2)
    )

      Domain constants for DCE Security (Version 2) UUIDs.

      View Source
      const (
      	Invalid   = Variant(iota) // Invalid UUID
      	RFC4122                   // The variant specified in RFC4122
      	Reserved                  // Reserved, NCS backward compatibility.
      	Microsoft                 // Reserved, Microsoft Corporation backward compatibility.
      	Future                    // Reserved for future definition.
      )

        Constants returned by Variant.

        Variables

        View Source
        var (
        	NameSpaceDNS  = Must(Parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8"))
        	NameSpaceURL  = Must(Parse("6ba7b811-9dad-11d1-80b4-00c04fd430c8"))
        	NameSpaceOID  = Must(Parse("6ba7b812-9dad-11d1-80b4-00c04fd430c8"))
        	NameSpaceX500 = Must(Parse("6ba7b814-9dad-11d1-80b4-00c04fd430c8"))
        	Nil           UUID // empty UUID, all zeros
        )

          Well known namespace IDs and UUIDs

          Functions

          func ClockSequence

          func ClockSequence() int

            ClockSequence returns the current clock sequence, generating one if not already set. The clock sequence is only used for Version 1 UUIDs.

            The uuid package does not use global static storage for the clock sequence or the last time a UUID was generated. Unless SetClockSequence is used, a new random clock sequence is generated the first time a clock sequence is requested by ClockSequence, GetTime, or NewUUID. (section 4.2.1.1)

            func NewString

            func NewString() string

              NewString creates a new random UUID and returns it as a string or panics. NewString is equivalent to the expression

              uuid.New().String()
              

              func NodeID

              func NodeID() []byte

                NodeID returns a slice of a copy of the current Node ID, setting the Node ID if not already set.

                func NodeInterface

                func NodeInterface() string

                  NodeInterface returns the name of the interface from which the NodeID was derived. The interface "user" is returned if the NodeID was set by SetNodeID.

                  func SetClockSequence

                  func SetClockSequence(seq int)

                    SetClockSequence sets the clock sequence to the lower 14 bits of seq. Setting to -1 causes a new sequence to be generated.

                    func SetNodeID

                    func SetNodeID(id []byte) bool

                      SetNodeID sets the Node ID to be used for Version 1 UUIDs. The first 6 bytes of id are used. If id is less than 6 bytes then false is returned and the Node ID is not set.

                      func SetNodeInterface

                      func SetNodeInterface(name string) bool

                        SetNodeInterface selects the hardware address to be used for Version 1 UUIDs. If name is "" then the first usable interface found will be used or a random Node ID will be generated. If a named interface cannot be found then false is returned.

                        SetNodeInterface never fails when name is "".

                        func SetRand

                        func SetRand(r io.Reader)

                          SetRand sets the random number generator to r, which implements io.Reader. If r.Read returns an error when the package requests random data then a panic will be issued.

                          Calling SetRand with nil sets the random number generator to the default generator.

                          Types

                          type Domain

                          type Domain byte

                            A Domain represents a Version 2 domain

                            func (Domain) String

                            func (d Domain) String() string

                            type Time

                            type Time int64

                              A Time represents a time as the number of 100's of nanoseconds since 15 Oct 1582.

                              func GetTime

                              func GetTime() (Time, uint16, error)

                                GetTime returns the current Time (100s of nanoseconds since 15 Oct 1582) and clock sequence as well as adjusting the clock sequence as needed. An error is returned if the current time cannot be determined.

                                func (Time) UnixTime

                                func (t Time) UnixTime() (sec, nsec int64)

                                  UnixTime converts t the number of seconds and nanoseconds using the Unix epoch of 1 Jan 1970.

                                  type UUID

                                  type UUID [16]byte

                                    A UUID is a 128 bit (16 byte) Universal Unique IDentifier as defined in RFC 4122.

                                    func FromBytes

                                    func FromBytes(b []byte) (uuid UUID, err error)

                                      FromBytes creates a new UUID from a byte slice. Returns an error if the slice does not have a length of 16. The bytes are copied from the slice.

                                      func Must

                                      func Must(uuid UUID, err error) UUID

                                        Must returns uuid if err is nil and panics otherwise.

                                        func MustParse

                                        func MustParse(s string) UUID

                                          MustParse is like Parse but panics if the string cannot be parsed. It simplifies safe initialization of global variables holding compiled UUIDs.

                                          func New

                                          func New() UUID

                                            New creates a new random UUID or panics. New is equivalent to the expression

                                            uuid.Must(uuid.NewRandom())
                                            

                                            func NewDCEGroup

                                            func NewDCEGroup() (UUID, error)

                                              NewDCEGroup returns a DCE Security (Version 2) UUID in the group domain with the id returned by os.Getgid.

                                              NewDCESecurity(Group, uint32(os.Getgid()))
                                              

                                              func NewDCEPerson

                                              func NewDCEPerson() (UUID, error)

                                                NewDCEPerson returns a DCE Security (Version 2) UUID in the person domain with the id returned by os.Getuid.

                                                NewDCESecurity(Person, uint32(os.Getuid()))
                                                

                                                func NewDCESecurity

                                                func NewDCESecurity(domain Domain, id uint32) (UUID, error)

                                                  NewDCESecurity returns a DCE Security (Version 2) UUID.

                                                  The domain should be one of Person, Group or Org. On a POSIX system the id should be the users UID for the Person domain and the users GID for the Group. The meaning of id for the domain Org or on non-POSIX systems is site defined.

                                                  For a given domain/id pair the same token may be returned for up to 7 minutes and 10 seconds.

                                                  func NewHash

                                                  func NewHash(h hash.Hash, space UUID, data []byte, version int) UUID

                                                    NewHash returns a new UUID derived from the hash of space concatenated with data generated by h. The hash should be at least 16 byte in length. The first 16 bytes of the hash are used to form the UUID. The version of the UUID will be the lower 4 bits of version. NewHash is used to implement NewMD5 and NewSHA1.

                                                    func NewMD5

                                                    func NewMD5(space UUID, data []byte) UUID

                                                      NewMD5 returns a new MD5 (Version 3) UUID based on the supplied name space and data. It is the same as calling:

                                                      NewHash(md5.New(), space, data, 3)
                                                      

                                                      func NewRandom

                                                      func NewRandom() (UUID, error)

                                                        NewRandom returns a Random (Version 4) UUID.

                                                        The strength of the UUIDs is based on the strength of the crypto/rand package.

                                                        A note about uniqueness derived from the UUID Wikipedia entry:

                                                        Randomly generated UUIDs have 122 random bits.  One's annual risk of being
                                                        hit by a meteorite is estimated to be one chance in 17 billion, that
                                                        means the probability is about 0.00000000006 (6 × 10−11),
                                                        equivalent to the odds of creating a few tens of trillions of UUIDs in a
                                                        year and having one duplicate.
                                                        

                                                        func NewRandomFromReader

                                                        func NewRandomFromReader(r io.Reader) (UUID, error)

                                                          NewRandomFromReader returns a UUID based on bytes read from a given io.Reader.

                                                          func NewSHA1

                                                          func NewSHA1(space UUID, data []byte) UUID

                                                            NewSHA1 returns a new SHA1 (Version 5) UUID based on the supplied name space and data. It is the same as calling:

                                                            NewHash(sha1.New(), space, data, 5)
                                                            

                                                            func NewUUID

                                                            func NewUUID() (UUID, error)

                                                              NewUUID returns a Version 1 UUID based on the current NodeID and clock sequence, and the current time. If the NodeID has not been set by SetNodeID or SetNodeInterface then it will be set automatically. If the NodeID cannot be set NewUUID returns nil. If clock sequence has not been set by SetClockSequence then it will be set automatically. If GetTime fails to return the current NewUUID returns nil and an error.

                                                              In most cases, New should be used.

                                                              func Parse

                                                              func Parse(s string) (UUID, error)

                                                                Parse decodes s into a UUID or returns an error. Both the standard UUID forms of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx are decoded as well as the Microsoft encoding {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} and the raw hex encoding: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

                                                                func ParseBytes

                                                                func ParseBytes(b []byte) (UUID, error)

                                                                  ParseBytes is like Parse, except it parses a byte slice instead of a string.

                                                                  func (UUID) ClockSequence

                                                                  func (uuid UUID) ClockSequence() int

                                                                    ClockSequence returns the clock sequence encoded in uuid. The clock sequence is only well defined for version 1 and 2 UUIDs.

                                                                    func (UUID) Domain

                                                                    func (uuid UUID) Domain() Domain

                                                                      Domain returns the domain for a Version 2 UUID. Domains are only defined for Version 2 UUIDs.

                                                                      func (UUID) ID

                                                                      func (uuid UUID) ID() uint32

                                                                        ID returns the id for a Version 2 UUID. IDs are only defined for Version 2 UUIDs.

                                                                        func (UUID) MarshalBinary

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

                                                                          MarshalBinary implements encoding.BinaryMarshaler.

                                                                          func (UUID) MarshalText

                                                                          func (uuid UUID) MarshalText() ([]byte, error)

                                                                            MarshalText implements encoding.TextMarshaler.

                                                                            func (UUID) NodeID

                                                                            func (uuid UUID) NodeID() []byte

                                                                              NodeID returns the 6 byte node id encoded in uuid. It returns nil if uuid is not valid. The NodeID is only well defined for version 1 and 2 UUIDs.

                                                                              func (*UUID) Scan

                                                                              func (uuid *UUID) Scan(src interface{}) error

                                                                                Scan implements sql.Scanner so UUIDs can be read from databases transparently. Currently, database types that map to string and []byte are supported. Please consult database-specific driver documentation for matching types.

                                                                                func (UUID) String

                                                                                func (uuid UUID) String() string

                                                                                  String returns the string form of uuid, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx , or "" if uuid is invalid.

                                                                                  func (UUID) Time

                                                                                  func (uuid UUID) Time() Time

                                                                                    Time returns the time in 100s of nanoseconds since 15 Oct 1582 encoded in uuid. The time is only defined for version 1 and 2 UUIDs.

                                                                                    func (UUID) URN

                                                                                    func (uuid UUID) URN() string

                                                                                      URN returns the RFC 2141 URN form of uuid, urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, or "" if uuid is invalid.

                                                                                      func (*UUID) UnmarshalBinary

                                                                                      func (uuid *UUID) UnmarshalBinary(data []byte) error

                                                                                        UnmarshalBinary implements encoding.BinaryUnmarshaler.

                                                                                        func (*UUID) UnmarshalText

                                                                                        func (uuid *UUID) UnmarshalText(data []byte) error

                                                                                          UnmarshalText implements encoding.TextUnmarshaler.

                                                                                          func (UUID) Value

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

                                                                                            Value implements sql.Valuer so that UUIDs can be written to databases transparently. Currently, UUIDs map to strings. Please consult database-specific driver documentation for matching types.

                                                                                            func (UUID) Variant

                                                                                            func (uuid UUID) Variant() Variant

                                                                                              Variant returns the variant encoded in uuid.

                                                                                              func (UUID) Version

                                                                                              func (uuid UUID) Version() Version

                                                                                                Version returns the version of uuid.

                                                                                                type Variant

                                                                                                type Variant byte

                                                                                                  A Variant represents a UUID's variant.

                                                                                                  func (Variant) String

                                                                                                  func (v Variant) String() string

                                                                                                  type Version

                                                                                                  type Version byte

                                                                                                    A Version represents a UUID's version.

                                                                                                    func (Version) String

                                                                                                    func (v Version) String() string