uuid

README

uuid

Universally Unique IDentifier (UUID) provision, per RFC 4122.

Code translated in part from examples in RFC 4122 and tested against Python's generation for interop.

Documentation

Overview

Package uuid provides functionality for generating universally unique identifiers. (see http://en.wikipedia.org/wiki/Universally_unique_identifier)

Example

Documents a simple use case for a generating and comparing UUIDs.

package main

import (
	"fmt"

	"github.com/apcera/util/uuid"
)

func main() {
	u1 := uuid.Variant1()
	u2 := uuid.Variant4()
	fmt.Println("Text representation of a uuid: ", u1.String())
	if u1.Equal(u2) {
		fmt.Println("UUIDs shouldn't ever be equal so this is not reached.")
	}
}

Index

• Constants
• type BadUUIDStringError
  • func (e *BadUUIDStringError) Error() string
• type NotAUUIDError
  • func (e *NotAUUIDError) Error() string
• type UUID
  • func FromBytes(raw []byte) (u UUID, e error)
  • func FromString(s string) (u UUID, e error)
  • func Generate() UUID
  • func NameSpaceDNS() UUID
  • func NameSpaceOID() UUID
  • func NameSpaceURL() UUID
  • func NameSpaceX500() UUID
  • func Variant1() (u UUID)
  • func Variant3(namespace UUID, name string) (u UUID)
  • func Variant4() (u UUID)
  • func Variant5(namespace UUID, name string) (u UUID)
  • func (u UUID) Bytes() []byte
  • func (u UUID) Compare(o UUID) int
  • func (u UUID) Equal(o UUID) bool
  • func (u UUID) MarshalJSON() ([]byte, error)
  • func (u UUID) String() string
• type UUIDSlice
  • func (u UUIDSlice) Len() int
  • func (u UUIDSlice) Less(i, j int) bool
  • func (u UUIDSlice) Swap(i, j int)

Examples

• Package

Constants

const UUIDByteLen = 16

The length of the byte array for a UUID in memory.

const UUIDHardwareByteLen = 6

The length of the hardware component of a Variant1 UUID.

const UUIDStringLen = 36

The length of a string representation of a UUID.

const Variant1EpochOffset = 12219292800000

The number of nano seconds between the switch to the Gregorian Calendar and Unix Epoch, divided by 100. This is used in Variant1() calculations.

Types

type BadUUIDStringError

type BadUUIDStringError struct {
	// contains filtered or unexported fields
}

Error thrown when a UUID can not be parsed from a string.

func (*BadUUIDStringError) Error

func (e *BadUUIDStringError) Error() string

type NotAUUIDError

type NotAUUIDError struct {
	WantedLength int
	// contains filtered or unexported fields
}

Error thrown when a UUID can not be parsed from a string.

func (*NotAUUIDError) Error

func (e *NotAUUIDError) Error() string

type UUID

type UUID []byte

func FromBytes

func FromBytes(raw []byte) (u UUID, e error)

Constructs a UUID from a raw bytes object

func FromString

func FromString(s string) (u UUID, e error)

Converts a string representation of a UUID into a UUID object.

func Generate

func Generate() UUID

Generates a Variant 1 UUID. This may change in the future so the semantics should be assumed that this returns a vaguely unique 128bit blob.

func NameSpaceDNS

func NameSpaceDNS() UUID

RFC4122 defined DNS name space UUID for Variant 3 and 5 UUIDs.

func NameSpaceOID

func NameSpaceOID() UUID

RFC4122 defined OID name space UUID for Variant 3 and 5 UUIDs.

func NameSpaceURL

func NameSpaceURL() UUID

RFC4122 defined URL name space UUID for Variant 3 and 5 UUIDs.

func NameSpaceX500

func NameSpaceX500() UUID

RFC4122 defined X500 name space UUID for Variant 3 and 5 UUIDs.

func Variant1

func Variant1() (u UUID)

Generates a "Variant 1" style UUID. This uses the machines MAC address, and the time since 15 October 1582 in nanoseconds, divided by 100.

This form of UUID is useful when you do not care if you leak MAC info, can be sure that MAC addresses are not duplicated on your network, and can be sure that no more than 9,999 UUIDs will be generated every 100ns.

func Variant3

func Variant3(namespace UUID, name string) (u UUID)

Generate a "Variant 3" style UUID. These UUIDs are not time based, instead using a namespace and a string to generate a hashed number. Variant 3 is MD5 based and should only be used for legacy reasons. Use Variant 5 for all new projects.

func Variant4

func Variant4() (u UUID)

Generates a "Variant 4" style UUID. These are nothing more than random data with the proper reserved bits set.

A random UUID has not assurance that it is in fact unique. These are only usable if you can survive duplication, or have a central source to verify uniqueness.

func Variant5

func Variant5(namespace UUID, name string) (u UUID)

Generate a "Variant 5" style UUID. These are functionally the same as Variant 3, using sha1 rather than md5. Variant 5 UUIDs are recommended for all new designs where Variant 3 would have normally been used. It takes a given UUID as a name space and a string identifier, given the same name space and string this will produce the same UUID.

func (UUID) Bytes

func (u UUID) Bytes() []byte

Returns the UUID as a series of bytes in an array.

func (UUID) Compare

func (u UUID) Compare(o UUID) int

Compares two UUID objects.

func (UUID) Equal

func (u UUID) Equal(o UUID) bool

Checks to see if two UUID objects are equal.

func (UUID) MarshalJSON

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

Returns the string representation, quoted, as bytes, for JSON encoding

func (UUID) String

func (u UUID) String() string

Returns a string representation of the given UUID data.

type UUIDSlice

type UUIDSlice []byte

func (UUIDSlice) Len

func (u UUIDSlice) Len() int

Returns the length of this data, should always be 16.

func (UUIDSlice) Less

func (u UUIDSlice) Less(i, j int) bool

Compares two the other UUID and returns true if this object is "less than" the other object.

func (UUIDSlice) Swap

func (u UUIDSlice) Swap(i, j int)

Swaps the elements at index i and j in the given Slice.