uuid

package module
v0.0.0-...-4d77244 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 8, 2014 License: MIT Imports: 18 Imported by: 0

README

Go UUID implementation

Build Status GoDoc

This package provides RFC 4122 compliant UUIDs. It will generate the following:

  • Version 1: based on timestamp and MAC address
  • Version 3: based on MD5 hash
  • Version 4: based on crytographically secure random numbers
  • Version 5: based on SHA-1 hash

Functions NewV1, NewV3, NewV4, NewV5, New, NewHex and ParseUUID() for generating versions 3, 4 and 5 UUIDs are as specified in RFC 4122.

Requirements

Go 1.2 and tip supported.

Recent Changes to original work by nu7hatch

  • Varient type bits are now set correctly
  • Varient type can now be retrieved more efficiently
  • New tests for variant setting to confirm correctness
  • New tests added to confirm proper version setting
  • Type UUID change to UUIDArray for V3-5 UUIDS and UUIDStruct added for V1 UUIDs ** These implement the BinaryMarshaller and BinaryUnmarshaller interfaces
  • New was added to create a base UUID from a []byte slice - this uses UUIDArray
  • ParseHex was renamed to ParseUUID
  • NewHex now performs unsafe creation of UUID from a hex string
  • NewV3 and NewV5 now take anything that implements the Stringer interface
  • V1 UUIDs can now be created
  • The printing format can be changed

Installation

Use the go tool:

$ go get github.com/twinj/uuid

Usage

See documentation and examples for more information.

This is a derivative work

Orginal version from Copyright (C) 2011 by Krzysztof Kowalik chris@nu7hat.ch. See COPYING file for details.

Also see: Algorithm details in RFC 4122.

Copyright (C) 2014 twinj@github.com See LICENSE file for details.

Documentation

Overview

This package provides RFC4122 UUID capabilities. Also included in the package is a distinctly go way of creating a unique id.

NewV1, NewV3, NewV4, NewV5, for generating versions 1, 3, 4 and 5 UUIDs as specified in RFC 4122.

New([]byte), unsafe NewHex(string) and safe ParseUUID(string) for creating UUIDs from existing data

The original version was from Krzysztof Kowalik <chris@nu7hat.ch> Although his version was non compliant with RFC4122 and bugged. I forked it but have since heavily redesigned it to suit my purposes The example code in the specification was also used to help design this as such I have started a new repository. 

Copyright (C) 2014 twinj@github.com  2014 MIT style licence

Index

Constants

View Source 
const (
	ReservedNCS       byte = 0x00
	ReservedRFC4122   byte = 0x80 // or and A0 if masked with 1F
	ReservedMicrosoft byte = 0xC0
	ReservedFuture    byte = 0xE0
	TakeBack          byte = 0xF0
)
View Source 
const (
	// If true uuid V1 will save state in a temp dir
	V1Save = true
)

Variables

View Source 
var (
	// The following standard UUIDs are for use with V3 or V5 UUIDs.
	NamespaceDNS  = &UUIDStruct{0x6ba7b810, 0x9dad, 0x11d1, 0x80, 0xb4, nodeId, length}
	NamespaceURL  = &UUIDStruct{0x6ba7b811, 0x9dad, 0x11d1, 0x80, 0xb4, nodeId, length}
	NamespaceOID  = &UUIDStruct{0x6ba7b812, 0x9dad, 0x11d1, 0x80, 0xb4, nodeId, length}
	NamespaceX500 = &UUIDStruct{0x6ba7b814, 0x9dad, 0x11d1, 0x80, 0xb4, nodeId, length}
)
View Source 
var (
	// Print save log
	Report = false

	// Save every x seconds
	SaveSchedule uint64 = 10

	V1SaveState = SaveStateOS{}
)

Functions

func Digest 

func Digest(o, pNs UUID, pName UniqueName, pHash hash.Hash)

Digest a namespace UUID and a UniqueName, which then marshals to a new UUID

func Equal 

func Equal(p1 UUID, p2 UUID) bool

Compares whether each UUID is the same

func ForceRandomNodeId 

func ForceRandomNodeId(pRandomNode bool)

Set whether teh system forces random nodeId generation

func Formatter 

func Formatter(pUUID UUID, pFormat Format) string

Format a UUID into a human readable string

func Now 

func Now() (sec int64, nsec int32)

TODO Create c version same as package runtime and time

func SwitchFormat 

func SwitchFormat(pFormat Format)

Switches the printing format for UUID strings When String() is called it will get the current format Default is CurlyHyphen A valid format will have 6 groups

func SwitchFormatUpper 

func SwitchFormatUpper(pFormat Format)

Same as SwitchFormat but will make it uppercase: will ruin GoId formatting

func UnmarshalBinary 

func UnmarshalBinary(o UUID, pData []byte) error

Checks for length

Types

type Format 

type Format string
const (
	Clean         Format = "%x%x%x%x%x%x"
	Curly         Format = "{%x%x%x%x%x%x}"
	Bracket       Format = "(%x%x%x%x%x%x)"
	CleanHyphen   Format = "%x-%x-%x-%x%x-%x"
	CurlyHyphen   Format = "{%x-%x-%x-%x%x-%x}"
	BracketHyphen Format = "(%x-%x-%x-%x%x-%x)"
	GoIdFormat    Format = "[%X-%X-%x-%X%X-%x]"
)

func GetFormat 

func GetFormat() Format

Gets the current default format string

type Name 

type Name string

Name is a simple string which implements UniqueName

func (Name) String 

func (o Name) String() string

type SaveState 

type SaveState interface {
	// Init is run if Setup() is false
	// Init should setup the system to save the state
	Init(*State)

	// Save saves the state and is called only if const V1Save and
	// Setup() is true
	Save(*State)

	// Should return whether Saving has been initialised.
	Setup() bool
}

type SaveStateOS 

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

func (*SaveStateOS) Init 

func (o *SaveStateOS) Init(pState *State)

func (*SaveStateOS) Save 

func (o *SaveStateOS) Save(pState *State)

Saves the current state of the generator If the scheduled file save is reached then the file is synced

func (*SaveStateOS) Setup 

func (o *SaveStateOS) Setup() bool

type State 

type State struct {

	// save state interface
	SaveState
	// contains filtered or unexported fields
}

Holds package information about the current state of the UUID generator

type Timestamp 

type Timestamp uint64

func (Timestamp) Unix 

func (o Timestamp) Unix() time.Time

type UUID 

type UUID interface {

	// Marshals the UUID bytes or data
	Bytes() (data []byte)

	// Organises data into a new UUID
	Unmarshal(pData []byte)

	// Size is used where different implementations require
	// different sizes. Should return the number of bytes in
	// the implementation.
	// Enables unmarshal and Bytes to screen for size
	Size() int

	// Version returns a version number of the algorithm used
	// to generate the UUID.
	// This may may behave independently across non RFC4122 UUIDs
	Version() int

	// Variant returns the UUID Variant
	// This will be one of the constants:
	// ReservedRFC4122,
	// ReservedMicrosoft,
	// ReservedFuture,
	// ReservedNCS.
	// This may behave differently across non RFC4122 UUIDs
	Variant() byte

	// UUID can be used as a Name within a namespace
	// Is simply just a String() string method
	// Returns a formatted version of the UUID.
	String() string
}

The main interface for UUIDs Each implementation must also implement the UniqueName interface

func GoId 

func GoId(pNs UUID, pName UniqueName, pHash hash.Hash) UUID

GoId creates a UUID object based on timestamps and a hash. It will truncate any bytes past the length of the initial hash. This creates a UUID based on a Namespace, UniqueName and an existing hash.

func New 

func New(pData []byte) UUID

New creates a UUID object from a data byte slice. It will truncate any bytes past the default length of 16 It will panic if data slice is too small

func NewHex 

func NewHex(pUuid string) UUID

Creates a UUID from a valid hex string Will panic if hex string is invalid - will panic even with hyphens and brackets

func NewV1 

func NewV1() UUID

NewV1 will generate a new RFC4122 version 1 UUID

func NewV3 

func NewV3(pNs UUID, pName UniqueName) UUID

NewV3 will generate a new RFC4122 version 3 UUID V3 is based on the MD5 hash of a namespace identifier UUID and any type which implements the UniqueName interface for the name. For strings and slices cast to a Name type

func NewV4 

func NewV4() UUID

NewV4 will generate a new RFC4122 version 4 UUID A cryptographically secure random UUID.

func NewV5 

func NewV5(pNs UUID, pName UniqueName) UUID

NewV5 will generate a new RFC4122 version 5 UUID Generate a UUID based on the SHA-1 hash of a namespace identifier and a name.

func ParseUUID 

func ParseUUID(pUUID string) (UUID, error)

ParseUUID creates a UUID object from a valid string representation. Accepts UUID string in following formats: 

6ba7b8149dad11d180b400c04fd430c8
6ba7b814-9dad-11d1-80b4-00c04fd430c8
{6ba7b814-9dad-11d1-80b4-00c04fd430c8}
urn:uuid:6ba7b814-9dad-11d1-80b4-00c04fd430c8
[6ba7b814-9dad-11d1-80b4-00c04fd430c8]

type UUIDArray 

type UUIDArray [length]byte

A clean UUID type for simpler UUID versions

func (*UUIDArray) Bytes 

func (o *UUIDArray) Bytes() []byte

func (UUIDArray) Format 

func (o UUIDArray) Format(pFormat Format) string

func (*UUIDArray) MarshalBinary 

func (o *UUIDArray) MarshalBinary() ([]byte, error)

Marshals the UUID bytes into a slice

func (UUIDArray) Size 

func (UUIDArray) Size() int

func (UUIDArray) String 

func (o UUIDArray) String() string

func (*UUIDArray) Unmarshal 

func (o *UUIDArray) Unmarshal(pData []byte)

func (*UUIDArray) UnmarshalBinary 

func (o *UUIDArray) UnmarshalBinary(pData []byte) error

Un-marshals the data bytes into the UUID.

func (*UUIDArray) Variant 

func (o *UUIDArray) Variant() byte

func (UUIDArray) Version 

func (o UUIDArray) Version() int

type UUIDStruct 

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

UUIDStruct is used for RFC4122 Version 1 UUIDs

func (*UUIDStruct) Bytes 

func (o *UUIDStruct) Bytes() (data []byte)

func (UUIDStruct) Format 

func (o UUIDStruct) Format(pFormat Format) string

func (*UUIDStruct) MarshalBinary 

func (o *UUIDStruct) MarshalBinary() ([]byte, error)

Marshals the UUID bytes into a slice

func (UUIDStruct) Size 

func (o UUIDStruct) Size() int

func (UUIDStruct) String 

func (o UUIDStruct) String() string

func (*UUIDStruct) Unmarshal 

func (o *UUIDStruct) Unmarshal(pData []byte)

func (*UUIDStruct) UnmarshalBinary 

func (o *UUIDStruct) UnmarshalBinary(pData []byte) error

Un-marshals the data bytes into the UUID struct. Implements the BinaryUn-marshaller interface

func (UUIDStruct) Variant 

func (o UUIDStruct) Variant() byte

func (UUIDStruct) Version 

func (o UUIDStruct) Version() int

type UUIDVersion 

type UUIDVersion int
const (
	NONE UUIDVersion = iota
	RFC4122v1
	DunnoYetv2
	RFC4122v3
	RFC4122v4
	RFC4122v5
)

type UniqueName 

type UniqueName interface {

	// Many go types implement this method for use with printing
	// Will convert the current type to its native string format
	String() string
}

UniqueName is a Stinger interface Made for easy passing of IPs, URLs, the several Address types, Buffers and any other type which implements Stringer string, []byte types and Hash sums will need to be cast to the Name type or some other type which implements Stringer or UniqueName

func NewName 

func NewName(salt string, pNames ...UniqueName) UniqueName

NewName will create a name from several sources

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.