uuid

README

Fast UUID implementation for Go

This package provides a fast implementation for representing UUIDs, parsing and generating them. It also includes methods for marshalling and unmarshalling JSON as well as reading and storing them in a SQL database.

Installation

go get github.com/m4rw3r/uuid

Documentation

See http://godoc.org/github.com/m4rw3r/uuid or the embedded godoc in the source.

Documentation

Overview

Package uuid implements a fast representation of UUIDs (Universally Unique Identifiers) and integrates with JSON and SQL drivers.

This package supports reading of multiple formats of UUIDs, including but not limited to:

a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11
{a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11}
a0eebc999c0b4ef8bb6d6bb9bd380a11
a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
{a0eebc99-9c0b4ef8-bb6d6bb9-bd380a11}

The parsing-speed of UUIDs in this package is achieved in several ways:

A lookup table converts hexadecimal digits to bytes.

Scanning and parsing is done in place without allocating anything.

Resulting bytes are written to the UUID as it is parsed. On parse errors this will leave the UUID only partially populated with data from the input string, leaving the rest of the UUID unmodified.

This package just ignores non-hexadecimal digits when scanning. This can cause some odd representations of hexadecimal data to be parsed as valid UUIDs, and longer strings like these will parse successfully:

a0eebc99,9c0b,4ef8,bb6d,6bb9bd380a11
a0eebc99This9cIs0b4eOKf8bb6d6bb9bdLOL380a11
a0-ee-bc-99-9c-0b-4e-f8-bb-6d-6b-b9-bd-38-0a-11

However, the hexadecimal digits MUST come in pairs, and the total number of bytes represented by them MUST equal 16, or it will generate a parse error. For example, invalid UUIDs like these will not parse:

a0eebc999-c0b-4ef8-bb6d-6bb9bd380a11
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a111
a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a1111

All string-creating functions will generate UUIDs in the canonical format of:

a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11

Index

• type ErrInvalidType
  • func (e ErrInvalidType) Error() string
• type ErrTooLong
  • func (e ErrTooLong) Error() string
• type ErrTooShort
  • func (e ErrTooShort) Error() string
• type ErrUneven
  • func (e ErrUneven) Error() string
• type NullUUID
  • func (n NullUUID) MarshalJSON() ([]byte, error)
  • func (n NullUUID) MarshalText() ([]byte, error)
  • func (nu *NullUUID) Scan(val interface{}) error
  • func (n *NullUUID) UnmarshalJSON(data []byte) error
  • func (n *NullUUID) UnmarshalText(data []byte) error
  • func (nu NullUUID) Value() (driver.Value, error)
• type ScanError
• type UUID
  • func FromString(str string) (UUID, error)
  • func MaybeFromString(str string) UUID
  • func MustFromString(str string) UUID
  • func V4() (UUID, error)
  • func (u UUID) IsZero() bool
  • func (u UUID) MarshalJSON() ([]byte, error)
  • func (u UUID) MarshalText() ([]byte, error)
  • func (u *UUID) ReadBytes(str []byte) error
  • func (u *UUID) Scan(val interface{}) error
  • func (u *UUID) SetString(str string) error
  • func (u *UUID) SetZero()
  • func (u UUID) String() string
  • func (u *UUID) UnmarshalJSON(data []byte) error
  • func (u *UUID) UnmarshalText(data []byte) error
  • func (u UUID) Value() (driver.Value, error)
  • func (u UUID) Version() int

Types

type ErrInvalidType

type ErrInvalidType struct {
	Type reflect.Type
}

ErrInvalidType occurs when *UUID.Scan() does not receive a string.

func (ErrInvalidType) Error

func (e ErrInvalidType) Error() string

type ErrTooLong

type ErrTooLong ScanError

ErrTooLong occurs when the supplied string contains more than the required number of hexadecimal characters to represent a UUID.

func (ErrTooLong) Error

func (e ErrTooLong) Error() string

type ErrTooShort

type ErrTooShort ScanError

ErrTooShort occurs when the supplied string does not contain enough hexadecimal characters to represent a UUID.

func (ErrTooShort) Error

func (e ErrTooShort) Error() string

type ErrUneven

type ErrUneven ScanError

ErrUneven occurs when a hexadecimal digit is not part of a pair, making it impossible to decode it to a byte.

func (ErrUneven) Error

func (e ErrUneven) Error() string

type NullUUID

type NullUUID struct {
	// Valid is true if UUID is not NULL
	Valid bool
	UUID  UUID
}

NullUUID represents a UUID that may be null. NullUUID implements the Scanner interface so it can be used as a scan destination.

func (NullUUID) MarshalJSON

func (n NullUUID) MarshalJSON() ([]byte, error)

MarshalJSON marshals a potentially null UUID into either a string- representation of the UUID or the null-constant depending on the Valid property.

func (NullUUID) MarshalText

func (n NullUUID) MarshalText() ([]byte, error)

MarshalText marshals a potentially null UUID into either a string- representation of the UUID or the null-constant depending on the Valid property.

func (*NullUUID) Scan

func (nu *NullUUID) Scan(val interface{}) error

Scan scans a uuid or null from the given value. If the supplied value is nil, Valid will be set to false and the UUID will be zeroed.

func (*NullUUID) UnmarshalJSON

func (n *NullUUID) UnmarshalJSON(data []byte) error

UnmarshalJSON parses a potentially null UUID into a NullUUI instance. If the source is the null-constant ("null"), Valid is set to false, otherwise it will attempt to parse the given string into the UUID property of the NullUUID instance, setting Valid to true if no error is encountered. If an error is encountered, Valid is set to false.

func (*NullUUID) UnmarshalText

func (n *NullUUID) UnmarshalText(data []byte) error

UnmarshalText parses a potentially null UUID into a NullUUI instance. If the source is the null-constant ("null"), Valid is set to false, otherwise it will attempt to parse the given string into the UUID property of the NullUUID instance, setting Valid to true if no error is encountered. If an error is encountered, Valid is set to false.

func (NullUUID) Value

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

Value gives the database driver representation of the UUID or NULL.

type ScanError

type ScanError struct {
	// Scanned is the number of bytes of the source string which has been
	// considered.
	Scanned int
	// Written is the number of decoded hexadecimal bytes which has
	// been written to the UUID instance.
	Written int
	// Length is the length of the source string.
	Length int
}

ScanError contains the scanner-state for when the error occurred.

type UUID

type UUID [16]byte

UUID represents a Universally-Unique-Identifier.

func FromString

func FromString(str string) (UUID, error)

FromString reads a UUID into a new UUID instance.

func MaybeFromString

func MaybeFromString(str string) UUID

MaybeFromString reads a UUID into a new UUID instance, setting the instance to zero if it fails.

func MustFromString

func MustFromString(str string) UUID

MustFromString reads a UUID into a new UUID instance, panicing on failure.

func V4

func V4() (UUID, error)

V4 creates a new random UUID with data from crypto/rand.Read().

func (UUID) IsZero

func (u UUID) IsZero() bool

IsZero returns true if the UUID is zero.

func (UUID) MarshalJSON

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

MarshalJSON returns the string-representation of the UUID as a JSON-string.

func (UUID) MarshalText

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

MarshalText returns the string-representation of the UUID as a byte-array.

func (*UUID) ReadBytes

func (u *UUID) ReadBytes(str []byte) error

ReadBytes reads the supplied byte array of hexadecimal characters representing a UUID into the instance. On invalid UUID an error is returned and the UUID state will be undetermined. This function will ignore all non-hexadecimal digits.

func (*UUID) Scan

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

Scan scans a uuid from the given interface instance. If scanning fails the state of the UUID is undetermined.

func (*UUID) SetString

func (u *UUID) SetString(str string) error

SetString reads the supplied string-representation of the UUID into the instance. On invalid UUID an error is returned and the UUID state will be undetermined. This function will ignore all non-hexadecimal digits.

func (*UUID) SetZero

func (u *UUID) SetZero()

SetZero sets the UUID to zero.

func (UUID) String

func (u UUID) String() string

String returns the string representation of the UUID. This method returns the canonical representation of “xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx“.

func (*UUID) UnmarshalJSON

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

UnmarshalJSON reads an UUID from a JSON-string into the UUID instance. If this fails the state of the UUID is undetermined.

func (*UUID) UnmarshalText

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

UnmarshalText reads an UUID from a string into the UUID instance. If this fails the state of the UUID is undetermined.

func (UUID) Value

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

Value gives the database driver representation of the UUID.

func (UUID) Version

func (u UUID) Version() int

Version returns the UUID version.