guid

README

Guid

Globally unique identifiers offer a quick means of generating non-colliding values across a distributed system. For this implemenation, RFC 4122 governs the desired behavior.

What's in a name?

You have likely already noticed that RFC and some implementations refer to these structures as UUIDs (Universally Unique Identifiers), where as this project is annotated as GUIDs (Globally Unique Identifiers). The name Guid was selected to make clear this project's ties to the .NET struct Guid. The most obvious relationship is the desire to have the same format specifiers available in this library's Format and Parse methods as .NET would have in its ToString and Parse methods.

Versioning

This library will adhere to the Semantic Versioning 2.0.0 specification. It may be worth noting this should allow for tools like glide to pull in this library with ease.

The Release Notes portion of this file will be updated to reflect the most recent major/minor updates, with the option to tag particular bug-fixes as well. Updates to the Release Notes for patches should be addative, where as minor/major updates should replace the previous version. If one desires to see the release notes for an older version, checkout that version of code and open this file.

Release Notes 0.2.*

0.2.4

Updating Stringf(Format) to have a single return value. Error conditions are now satisified by returning an empty string.

0.2.3

Updating String* functions to not be pointer functions. Also, adding a Stringf example.

0.2.2

• Randomly generated bits now use the crypto/rand library to ensure safer randomly generated GUIDs.
• For version 1 GUIDs, when a MAC is unfound, a random hardware address is used. The random MAC conforms to the MAC spec, which sets a bit when the address is unknown.
• Bug fixes.

0.2.1

Added an implementation of RFC4122 version1 UUID generation. It is now a supported CreationStrategy.

0.2.0

A few name changes were made, as well as setting up some mechanisms to more easily add GUID generators in the future.

• The method GUID.Format() has been renamed to GUID.Stringf().
• const block was added to define available formatting strings for Stringf and Parse
• New constructor NewGUIDs(CreationStrategy) was added to allow requests for different generation tactics.

Documentation

Index

• type CreationStrategy
• type Format
• type GUID
  • func Empty() GUID
  • func NewGUID() GUID
  • func NewGUIDs(strategy CreationStrategy) (GUID, error)
  • func Parse(value string) (GUID, error)
  • func (guid GUID) String() string
  • func (guid GUID) Stringf(format Format) string
  • func (guid *GUID) Version() uint

Examples

• GUID.String
• GUID.Stringf

Types

type CreationStrategy

type CreationStrategy string

CreationStrategy enumerates the values that are supported for populating the bits of a new Guid.

const (
	CreationStrategyVersion1 CreationStrategy = "version1"
	CreationStrategyVersion2 CreationStrategy = "version2"
	CreationStrategyVersion3 CreationStrategy = "version3"
	CreationStrategyVersion4 CreationStrategy = "version4"
	CreationStrategyVersion5 CreationStrategy = "version5"
)

These constants define the possible creation strategies available via this implementation of Guid.

type Format

type Format string

Format enumerates the values that are supported by Parse and Format

const (
	FormatB       Format = "B" // {00000000-0000-0000-0000-000000000000}
	FormatD       Format = "D" // 00000000-0000-0000-0000-000000000000
	FormatN       Format = "N" // 00000000000000000000000000000000
	FormatP       Format = "P" // (00000000-0000-0000-0000-000000000000)
	FormatX       Format = "X" // {0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}
	FormatDefault Format = FormatD
)

These constants define the possible string formats available via this implementation of Guid.

type GUID

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

GUID is a unique identifier designed to virtually guarantee non-conflict between values generated across a distributed system.

func Empty

func Empty() GUID

Empty returns a copy of the default and empty GUID.

func NewGUID

func NewGUID() GUID

NewGUID generates and returns a new globally unique identifier

func NewGUIDs

func NewGUIDs(strategy CreationStrategy) (GUID, error)

NewGUIDs generates and returns a new globally unique identifier that conforms to the given strategy.

func Parse

func Parse(value string) (GUID, error)

Parse instantiates a GUID from a text representation of the same GUID. This is the inverse of function family String()

func (GUID) String

func (guid GUID) String() string

String returns a text representation of a GUID in the default format.

Example

fmt.Printf(Empty().String())

Output:
00000000-0000-0000-0000-000000000000

func (GUID) Stringf

func (guid GUID) Stringf(format Format) string

Stringf returns a text representation of a GUID that conforms to the specified format. If an unrecognized format is provided, the empty string is returned.

Example

fmt.Printf(Empty().Stringf(FormatB))

Output:
{00000000-0000-0000-0000-000000000000}

func (*GUID) Version

func (guid *GUID) Version() uint

Version reads a GUID to parse which mechanism of generating GUIDS was employed. Values returned here are documented in rfc4122.txt.