uuid

README

UUID

UUID provides functions for generating and formatting UUIDs according to RFC 4122.

Sample Usage

Version 3

Use v5, if possible (unless for legacy reasons).

Version 4

To generate a new v4 UUID:

package main

import (
	"fmt"

	"github.com/ryanfowler/uuid"
)

func main() {
	u := uuid.Must(uuid.NewV4())
	fmt.Println(u.String())
}

will output something like: 9e754ef6-8dd9-4903-af43-7aea99bfb1fe.

NewV4 will only return an error when it is unable to read random bytes from the OS. Otherwise, the returned UUID will be made up of random bytes with the appropriate variant and version bits set.

Version 5

To generate a new v5 UUID:

package main

import (
	"fmt"

	"github.com/ryanfowler/uuid"
)

func main() {
	namespace := "9e754ef6-8dd9-5903-af43-7aea99bfb1fe"
	u := uuid.NewV5(namespace, []byte("unique bytes"))
	fmt.Println(u.String())
}

will output something like: e83915a5-a2c6-573b-a5f7-8cf2badd0af5.

UUIDs generated from NewV5 with the same namespace & name will be equal every time NewV5 is called. In other words, same input -> same output.

Version 7

To generate a new v7 UUID:

package main

import (
	"fmt"

	"github.com/ryanfowler/uuid"
)

func main() {
	u := uuid.Must(uuid.NewV7(time.Now()))
	fmt.Println(u.String())
}

To get the timestamp out of a v7 UUID, you can use the following method:

u := uuid.Must(uuid.NewV7(time.Now()))
timestamp, ok := u.Time()
if ok {
	fmt.Println(timestamp)
}

Formatting

A UUID represents a 16 byte array (128 bits). In order to use the UUID in a human-readable form, either Format, Bytes, or String should be used.

Format will return the UUID bytes as 36 byte array in the format:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

where x's are hexadecimal characters.

To format the UUID into a 36 byte slice, use Bytes.

To format the UUID as a string, use String.

Parsing

A UUID can be parsed from the following formats:

• A 16-byte raw UUID.
• A 32-byte hexadecimal UUID without dashes e.g. 9e754ef68dd94903af437aea99bfb1fe
• A 36-byte hexadecimal UUID with dashes e.g. 9e754ef6-8dd9-4903-af43-7aea99bfb1fe

Example:

raw := "9e754ef6-8dd9-4903-af43-7aea99bfb1fe"
u := uuid.Must(uuid.ParseString(raw))
fmt.Println(u.String())

will ouput: 9e754ef6-8dd9-4903-af43-7aea99bfb1fe.

License

The MIT License.

See the LICENSE file for more information.

Documentation

Overview

Package uuid provides functions for generating and formatting UUIDs as specified in RFC 4122.

Index

• Variables
• type UUID
  • func Must(u UUID, err error) UUID
  • func NewV3(namespace UUID, name []byte) UUID
  • func NewV4() (UUID, error)
  • func NewV4FromRand(r io.Reader) (UUID, error)
  • func NewV5(namespace UUID, name []byte) UUID
  • func NewV7(now time.Time) (UUID, error)
  • func NewV7FromRand(now time.Time, r io.Reader) (UUID, error)
  • func Parse(b []byte) (UUID, error)
  • func ParseString(s string) (UUID, error)
  • func (u UUID) Bytes() []byte
  • func (u UUID) Format() [36]byte
  • func (u UUID) IsZero() bool
  • func (u UUID) MarshalBinary() ([]byte, error)
  • func (u UUID) MarshalJSON() ([]byte, error)
  • func (u UUID) MarshalText() ([]byte, error)
  • func (u *UUID) Scan(src interface{}) error
  • func (u UUID) String() string
  • func (u UUID) Time() (time.Time, bool)
  • func (u *UUID) UnmarshalBinary(data []byte) error
  • func (u *UUID) UnmarshalJSON(b []byte) error
  • func (u *UUID) UnmarshalText(text []byte) error
  • func (u UUID) Value() (driver.Value, error)
  • func (u UUID) Version() int

Variables

var ErrInvalidUUID = errors.New("uuid: invalid uuid provided")

ErrInvalidUUID represents the error returned during parsing when the provided bytes do not represent a valid UUID.

Types

type UUID

type UUID [16]byte

UUID represents a universally unique identifier made up of 128 bits.

For more information see: https://en.wikipedia.org/wiki/Universally_unique_identifier

func Must

func Must(u UUID, err error) UUID

Must returns the provided UUID if err is nil, otherwise it panics.

func NewV3

func NewV3(namespace UUID, name []byte) UUID

NewV3 uses the provided namespace and name to generate and return a new v3 UUID using MD5 hashing, as per RFC 4122.

func NewV4

func NewV4() (UUID, error)

NewV4 generates and returns a new v4 UUID using random bytes, as per RFC 4122. If an error occurs while reading from "crypto/rand", it is returned.

func NewV4FromRand

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

NewV4FromRand generates and returns a new v4 UUID using the random bytes returned from the provided io.Reader.

func NewV5

func NewV5(namespace UUID, name []byte) UUID

NewV5 uses the provided namespace and name to generate and return a new v5 UUID using SHA1 hashing, as per RFC 4122.

func NewV7

func NewV7(now time.Time) (UUID, error)

NewV7 uses the provided timestamp to generate and return a new V7 UUID, as per RFC 4122. If an error occurs while reading from "crypto/rand", it is returned.

func NewV7FromRand

func NewV7FromRand(now time.Time, r io.Reader) (UUID, error)

NewV7FromRand uses the provided timestamp and random io.Reader to return a new V7 UUID, as per RFC 4122.

func Parse

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

Parse parses the provided UUID bytes, returning the UUID or any error encountered. The following formats are provided:

16 byte raw, binary UUID
32 byte hexadecimal formatted UUID without dashes e.g. 9e754ef68dd94903af437aea99bfb1fe
36 byte hexadecimal formatted UUID e.g "9e754ef6-8dd9-4903-af43-7aea99bfb1fe"

func ParseString

func ParseString(s string) (UUID, error)

ParseString parses the provided UUID string using the same rules as Parse.

func (UUID) Bytes

func (u UUID) Bytes() []byte

Bytes returns the hexadecimal format of the UUID as a slice of 36 bytes.

Example: 9e754ef6-8dd9-5903-af43-7aea99bfb1fe

func (UUID) Format

func (u UUID) Format() [36]byte

Format returns the hexadecimal format of the UUID as an array of 36 bytes.

Example: 9e754ef6-8dd9-5903-af43-7aea99bfb1fe

func (UUID) IsZero

func (u UUID) IsZero() bool

IsZero returns true if the UUID cotains all zeros (the default value).

func (UUID) MarshalBinary

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

MarshalBinary implements the BinaryMarshaler interface. It returns a byte slice representing the 16 byte binary representation of the UUID.

func (UUID) MarshalJSON

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

MarshalJSON implements the json Marshaler interface. It returns a byte slice representing the JSON string of a 36 byte hexadecimal representation of the UUID.

func (UUID) MarshalText

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

MarshalText implements the TextMarshaler interface. It returns a byte slice representing the 36 byte hexadecimal representation of the UUID.

func (*UUID) Scan

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

Scan implements the sql Scanner interface. It reads the UUID from src into u.

func (UUID) String

func (u UUID) String() string

String returns the human-readable, hexadecimal format of the UUID as a string with a length of 36 bytes.

Example: 9e754ef6-8dd9-5903-af43-7aea99bfb1fe

func (UUID) Time

func (u UUID) Time() (time.Time, bool)

Time returns the embedded timestamp of the UUID, and a boolean indicating if a timestamp was successfully parsed.

The provided UUID MUST be version 7.

func (*UUID) UnmarshalBinary

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

UnmarshalBinary implements the BinaryUnmarshaler interface. It reads the binary UUID from data into u.

func (*UUID) UnmarshalJSON

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

UnmarshalJSON implements the json Unmarshaler interface. It reads the json UUID b into u.

func (*UUID) UnmarshalText

func (u *UUID) UnmarshalText(text []byte) error

UnmarshalText implements the TextUnmarshaler interface. It reads the text UUID from text into u.

func (UUID) Value

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

Value implements the sql driver Valuer interface. It returns a formatted byte slice representation of the UUID.

func (UUID) Version

func (u UUID) Version() int

Version returns the version number of the UUID, as specified in RFC 4122.