uuid

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: May 17, 2024 License: MIT Imports: 9 Imported by: 1

README

uuid

Faster, more flexible v4 and v7 UUIDs in Go

Features

  • Generate and parse v4 and v7 UUIDs
  • Canonical, hash, and base58 encoding
  • Select a default string format (i.e. base58, hash, canonical)
  • SQL scanning and JSON marshaling
  • The fastest UUID parsing available in Golang

Installation

go get github.com/flexstack/uuid

Usage

import "github.com/flexstack/uuid"

// Optionally set a default format
uuid.DefaultFormat = uuid.FormatBase58

// Generate a new v4 UUID
u := uuid.Must(uuid.NewV4())

// Generate a new v7 UUID
u := uuid.Must(uuid.NewV7())

// Parse a UUID
u, err := uuid.FromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8")

// Parse a UUID from a byte slice
u, err := uuid.FromBytes([]byte{0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8})

// Format a UUID
asHash := u.Format(uuid.FormatHash)
asBase58 := u.Format(uuid.FormatBase58)
asCanonical := u.Format(uuid.FormatCanonical)

// Scan a SQL UUID
var u uuid.UUID
err := db.QueryRow("SELECT id FROM users WHERE email = $1", email).Scan(&u)
if u.IsNil() {
    // Handle nil UUID
}

Setting a default format

Changing the default format will affect how UUIDs are marshaled to strings from MarshalText, and MarshalJSON.

import (
	"encoding/json"
	"fmt"

	"github.com/flexstack/uuid"
)

func main() {
	uuid.DefaultFormat = uuid.FormatBase58

	u := uuid.FromStringOrNil("ffffffff-ffff-ffff-ffff-ffffffffffff")

	// Marshal to base58
	m := map[string]uuid.UUID{"id": u}
	b, _ := json.Marshal(m)
	fmt.Println(string(b)) // {"id": "YcVfxkQb6JRzqk5kF2tNLv"}
}

Credit

This package is a fork of github.com/gofrs/uuid with the following changes:

  • 2x improvement to FromString, UnmarshalText, and UnmarshalJSON performance
  • Adds base58 encoding.
  • Allows people to set a default format (i.e. base58, hash, canonical)
  • Scans nil UUIDs from SQL databases as nil UUIDs (00000000-0000-0000-0000-000000000000) instead of nil.
  • Fixes issue with TimestampFromV7 not being spec compliant.
  • Removed v1, v3, v5 UUIDs.
  • Removed support for braced and URN string formats.

Benchmarks

MacBook Air (15-inch, M2, 2023) Apple M2, 24GB RAM, MacOS 14.4.1

Format()
Format(FormatCanonical)        44625793         26.54 ns/op           48 B/op          1 allocs/op
Format(FormatHash)             44022964         26.85 ns/op           32 B/op          1 allocs/op
Format(FormatBase58)           5350190          224.0 ns/op           24 B/op          1 allocs/op
FromString()
FromString(FormatCanonical)    70893008         16.88 ns/op           0 B/op           0 allocs/op
FromString(FormatBase58)       16760137         71.77 ns/op           0 B/op           0 allocs/op
NewVx()
NewV4()                        2961621          401.6 ns/op           16 B/op          1 allocs/op
NewV7()                        3859464          308.7 ns/op           16 B/op          1 allocs/op

Contributing

Read the CONTRIBUTING.md guide to learn how to contribute to this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Overview

Copyright (C) 2013-2018 by Maxim Bublis <b@codemonkey.ru>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Copyright (C) 2013-2018 by Maxim Bublis <b@codemonkey.ru>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Copyright (C) 2013-2018 by Maxim Bublis <b@codemonkey.ru>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Package uuid provides implementations of the Universally Unique Identifier (UUID), as specified in RFC-4122 and the Peabody RFC Draft (revision 03).

RFC-4122[1] provides the specification for versions 1, 3, 4, and 5. The Peabody UUID RFC Draft[2] provides the specification for the new k-sortable UUIDs, versions 6 and 7.

DCE 1.1[3] provides the specification for version 2, but version 2 support was removed from this package in v4 due to some concerns with the specification itself. Reading the spec, it seems that it would result in generating UUIDs that aren't very unique. In having read the spec it seemed that our implementation did not meet the spec. It also seems to be at-odds with RFC 4122, meaning we would need quite a bit of special code to support it. Lastly, there were no Version 2 implementations that we could find to ensure we were understanding the specification correctly.

[1] https://tools.ietf.org/html/rfc4122 [2] https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-03 [3] http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01

Index

Constants

View Source 
const (
	V1 byte // Version 1 (date-time and MAC address)
	V2      // Version 2 (date-time and MAC address, DCE security version)
	V3      // Version 3 (namespace name-based)
	V4      // Version 4 (random)
	V5      // Version 5 (namespace name-based)
	V6      // Version 6 (k-sortable timestamp and node ID) [peabody draft]
	V7      // Version 7 (k-sortable timestamp and random data) [peabody draft]
)

UUID versions.

View Source 
const (
	VariantNCS byte = iota
	VariantRFC4122
	VariantMicrosoft
	VariantFuture
)

UUID layout variants.

View Source 
const Size = 16

Size of a UUID in bytes.

Variables

View Source 
var (
	NamespaceDNS  = Must(FromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8"))
	NamespaceURL  = Must(FromString("6ba7b811-9dad-11d1-80b4-00c04fd430c8"))
	NamespaceOID  = Must(FromString("6ba7b812-9dad-11d1-80b4-00c04fd430c8"))
	NamespaceX500 = Must(FromString("6ba7b814-9dad-11d1-80b4-00c04fd430c8"))
)

Predefined namespace UUIDs.

View Source 
var DefaultFormat = FormatCanonical
View Source 
var Nil = UUID{}

Nil is the nil UUID, as specified in RFC-4122, that has all 128 bits set to zero.

View Source 
var Omni = UUID{
	0xff, 0xff, 0xff, 0xff,
	0xff, 0xff,
	0xff, 0xff,
	0xff, 0xff,
	0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
}

Functions

func TimestampFromV7 

func TimestampFromV7(u UUID) (int64, error)

TimestampFromV7 returns the Timestamp embedded within a V7 UUID. This function returns an error if the UUID is any version other than 7.

This is implemented based on revision 03 of the Peabody UUID draft, and may be subject to change pending further revisions. Until the final specification revision is finished, changes required to implement updates to the spec will not be considered a breaking change. They will happen as a minor version releases until the spec is final.

Types

type EpochFunc 

type EpochFunc func() time.Time

EpochFunc is the function type used to provide the current time.

type Format 

type Format string
const (
	FormatCanonical Format = "canonical"
	FormatHash      Format = "hash"
	FormatBase58    Format = "base58"
)

type Gen 

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

Gen is a reference UUID generator based on the specifications laid out in RFC-4122 and DCE 1.1: Authentication and Security Services. This type satisfies the Generator interface as defined in this package.

For consumers who are generating V1 UUIDs, but don't want to expose the MAC address of the node generating the UUIDs, the NewGenWithHWAF() function has been provided as a convenience. See the function's documentation for more info.

The authors of this package do not feel that the majority of users will need to obfuscate their MAC address, and so we recommend using NewGen() to create a new generator.

func NewGen 

func NewGen() *Gen

NewGen returns a new instance of Gen with some default values set. Most people should use this.

func (*Gen) NewV4 

func (g *Gen) NewV4() (UUID, error)

NewV4 returns a randomly generated UUID.

func (*Gen) NewV7 

func (g *Gen) NewV7() (UUID, error)

NewV7 returns a k-sortable UUID based on the current millisecond precision UNIX epoch and 74 bits of pseudorandom data.

This is implemented based on revision 04 of the Peabody UUID draft, and may be subject to change pending further revisions. Until the final specification revision is finished, changes required to implement updates to the spec will not be considered a breaking change. They will happen as a minor version releases until the spec is final.

type GenOption 

type GenOption func(*Gen)

GenOption is a function type that can be used to configure a Gen generator.

type Generator 

type Generator interface {
	NewV4() (UUID, error)
	NewV7() (UUID, error)
}

Generator provides an interface for generating UUIDs. 

var DefaultGenerator Generator = NewGen()

DefaultGenerator is the default UUID Generator used by this package.

type NullUUID 

type NullUUID struct {
	UUID  UUID
	Valid bool
}

NullUUID can be used with the standard sql package to represent a UUID value that can be NULL in the database.

func (NullUUID) MarshalJSON 

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

MarshalJSON marshals the NullUUID as null or the nested UUID as a string. The string format is determined by the global DefaultFormat variable.

func (*NullUUID) Scan 

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

Scan implements the sql.Scanner interface.

func (*NullUUID) UnmarshalJSON 

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

UnmarshalJSON unmarshals a NullUUID

func (NullUUID) Value 

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

Value implements the driver.Valuer interface.

type UUID 

type UUID [Size]byte

UUID is an array type to represent the value of a UUID, as defined in RFC-4122.

func FromBytes 

func FromBytes(input []byte) (UUID, error)

FromBytes returns a UUID generated from the raw byte slice input. It will return an error if the slice isn't 16 bytes long.

func FromBytesOrNil 

func FromBytesOrNil(input []byte) UUID

FromBytesOrNil returns a UUID generated from the raw byte slice input. Same behavior as FromBytes(), but returns uuid.Nil instead of an error.

func FromString 

func FromString(text string) (UUID, error)

FromString returns a UUID parsed from the input string. Input is expected in a form accepted by UnmarshalText.

func FromStringOrNil 

func FromStringOrNil(input string) UUID

FromStringOrNil returns a UUID parsed from the input string. Same behavior as FromString(), but returns uuid.Nil instead of an error.

func Must 

func Must(u UUID, err error) UUID

Must is a helper that wraps a call to a function returning (UUID, error) and panics if the error is non-nil. It is intended for use in variable initializations such as 

var packageUUID = uuid.Must(uuid.FromString("123e4567-e89b-12d3-a456-426655440000"))

func NewV4 

func NewV4() (UUID, error)

NewV4 returns a randomly generated UUID.

func NewV7 

func NewV7() (UUID, error)

NewV7 returns a k-sortable UUID based on the current millisecond precision UNIX epoch and 74 bits of pseudorandom data. It supports single-node batch generation (multiple UUIDs in the same timestamp) with a Monotonic Random counter.

This is implemented based on revision 04 of the Peabody UUID draft, and may be subject to change pending further revisions. Until the final specification revision is finished, changes required to implement updates to the spec will not be considered a breaking change. They will happen as a minor version releases until the spec is final.

func (UUID) Bytes 

func (u UUID) Bytes() []byte

Bytes returns a byte slice representation of the UUID.

func (UUID) Format 

func (u UUID) Format(format ...Format) string

Format returns a string representation of the UUID in the specified format. If no format is specified, DefaultFormat is used.

func (UUID) IsNil 

func (u UUID) IsNil() bool

IsNil returns if the UUID is equal to the nil UUID

func (UUID) MarshalBinary 

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

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (UUID) MarshalText 

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

MarshalText implements the encoding.TextMarshaler interface. Creates a string representation of the UUID in the format specified by DefaultFormat.

func (*UUID) Parse 

func (u *UUID) Parse(s string) error

Parse parses the UUID stored in the string text. Parsing and supported formats are the same as UnmarshalText.

func (*UUID) Scan 

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

Scan implements the sql.Scanner interface. A 16-byte slice will be handled by UnmarshalBinary, while a longer byte slice or a string will be handled by UnmarshalText.

func (*UUID) SetVariant 

func (u *UUID) SetVariant(v byte)

SetVariant sets the variant bits.

func (*UUID) SetVersion 

func (u *UUID) SetVersion(v byte)

SetVersion sets the version bits.

func (UUID) String 

func (u UUID) String() string

Returns a string representation of the UUID in the form of a canonical RFC-4122 string.

func (*UUID) UnmarshalBinary 

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

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface. It will return an error if the slice isn't 16 bytes long.

func (*UUID) UnmarshalText 

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

UnmarshalText implements the encoding.TextUnmarshaler interface. Following formats are supported: 

"6ba7b810-9dad-11d1-80b4-00c04fd430c8" (canonical)
"6ba7b8109dad11d180b400c04fd430c8" (hash)
"1C9z3nFjeJ44HMBeuqGNxt" (base58)

func (UUID) Value 

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

Value implements the driver.Valuer interface.

func (UUID) Variant 

func (u UUID) Variant() byte

Variant returns the UUID layout variant.

func (UUID) Version 

func (u UUID) Version() byte

Version returns the algorithm version used to generate the UUID.

Source Files

View all Source files

Directories

Path Synopsis

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.