uuid

package
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2022 License: MIT Imports: 5 Imported by: 0

README

UUID

Universally Unique Identifier

Several uuid libraries are commonly used for integration.

Compare

Name Binary Size String Size Features Notes
go.uuid 16 bytes 36 chars configuration free, not sortable recommended V4
ksuid 20 bytes 27 chars configuration free, sortable collision-free, coordination-free, dependency-free
xid 12 bytes 20 chars configuration free, sortable not cryptographically secure

Notes

  • xid: dependent on the system time, a monotonic counter and so is not cryptographically secure.

Features

go.uuid

  • Version 1, based on timestamp and MAC address (RFC 4122)
  • Version 2, based on timestamp, MAC address and POSIX UID/GID (DCE 1.1)
  • Version 3, based on MD5 hashing (RFC 4122)
  • Version 4, based on random numbers (RFC 4122)
  • Version 5, based on SHA-1 hashing (RFC 4122)

ksuid

  1. Naturally ordered by generation time
  2. Collision-free, coordination-free, dependency-free
  3. Highly portable representations
  4. 20-bytes: a 32-bit unsigned integer UTC timestamp and a 128-bit randomly generated payload.
    1. The timestamp uses big-endian encoding, to support lexicographic sorting.
    2. The timestamp epoch is adjusted to May 13th, 2014, providing over 100 years of life.
    3. The payload is generated by a cryptographically-strong pseudorandom number generator.

xid

  • Size: 12 bytes (96 bits), smaller than UUID, larger than snowflake
  • Base32 hex encoded by default (20 chars when transported as printable string, still sortable)
  • Non configured, you don't need set a unique machine and/or data center id
  • K-ordered
  • Embedded time with 1 second precision
  • Unicity guaranteed for 16,777,216 (24 bits) unique ids per second and per host/process
  • Lock-free (i.e.: unlike UUIDv1 and v2)

Benchmarks

goos: darwin
goarch: amd64
pkg: github.com/v8fg/kit4go/uuid
cpu: Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz
BenchmarkRequestID
BenchmarkRequestID-8                     1525274               778.1 ns/op            48 B/op          2 allocs/op
BenchmarkRequestIDCanonicalFormat
BenchmarkRequestIDCanonicalFormat-8      1529751               788.2 ns/op            64 B/op          2 allocs/op
BenchmarkNewV4
BenchmarkNewV4-8                         1677464               740.2 ns/op            16 B/op          1 allocs/op
BenchmarkNewKSUID
BenchmarkNewKSUID-8                      1453513               794.9 ns/op             0 B/op          0 allocs/op
BenchmarkNewKSUIDRandomWithTime
BenchmarkNewKSUIDRandomWithTime-8        1534045               760.3 ns/op             0 B/op          0 allocs/op
BenchmarkNewXID
BenchmarkNewXID-8                       13338049                85.44 ns/op            0 B/op          0 allocs/op
BenchmarkNewXIDWithTime
BenchmarkNewXIDWithTime-8               14852886                80.44 ns/op            0 B/op          0 allocs/op

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Equal 

func Equal(u1 uid.UUID, u2 uid.UUID) bool

Equal returns true if u1 and u2 equals, otherwise returns false.

func FromBytes 

func FromBytes(input []byte) (u uid.UUID, err error)

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

func FromBytesOrNil 

func FromBytesOrNil(input []byte) uid.UUID

FromBytesOrNil returns UUID converted from raw byte slice input. Same behavior as FromBytes, but returns a Nil UUID on error.

func FromString 

func FromString(input string) (u uid.UUID, err error)

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

func FromStringOrNil 

func FromStringOrNil(input string) uid.UUID

FromStringOrNil returns UUID parsed from string input. Same behavior as FromString, but returns a Nil UUID on error.

func KSUIDCompare 

func KSUIDCompare(a, b ksuid.KSUID) int

KSUIDCompare implements comparison for KSUID type.

func KSUIDFromBytes 

func KSUIDFromBytes(b []byte) (ksuid.KSUID, error)

KSUIDFromBytes constructs a KSUID from a 20-byte binary representation.

func KSUIDFromParts 

func KSUIDFromParts(t time.Time, payload []byte) (ksuid.KSUID, error)

KSUIDFromParts constructs a KSUID from constituent parts.

func KSUIDIsSorted 

func KSUIDIsSorted(ids []ksuid.KSUID) bool

KSUIDIsSorted checks whether a slice of KSUIDs is sorted

func KSUIDParse 

func KSUIDParse(s string) (ksuid.KSUID, error)

KSUIDParse decodes a string-encoded representation of a KSUID object.

func KSUIDSort 

func KSUIDSort(ids []ksuid.KSUID)

KSUIDSort the given slice of KSUIDs.

func NewKSUID 

func NewKSUID() ksuid.KSUID

NewKSUID generates a new KSUID.

Example 
package main

import (
	"encoding/hex"
	"fmt"
	"strings"

	"github.com/segmentio/ksuid"

	"github.com/v8fg/kit4go/uuid"
)

func printKSUIDInspect(id ksuid.KSUID) {
	const inspectFormat = `
REPRESENTATION:
  String: %v
     Raw: %v
COMPONENTS:
       Time: %v
  Timestamp: %v
    Payload: %v
`
	fmt.Printf(inspectFormat,
		id.String(),
		strings.ToUpper(hex.EncodeToString(id.Bytes())),
		id.Time().UTC().String(),
		id.Timestamp(),
		strings.ToUpper(hex.EncodeToString(id.Payload())),
	)
}

func main() {
	testKSUIDStr := "2FwgbLS72ILDWFEhMSFKCRJBN7M"
	testKSUID, _ := uuid.KSUIDParse(testKSUIDStr)
	printKSUIDInspect(testKSUID)

}

Output:

REPRESENTATION:
  String: 2FwgbLS72ILDWFEhMSFKCRJBN7M
     Raw: 0FD1D076606A0AB5DC14C70CD26FD2B6ED2A2D9C
COMPONENTS:
       Time: 2022-10-10 13:30:30 +0000 UTC
  Timestamp: 265408630
    Payload: 606A0AB5DC14C70CD26FD2B6ED2A2D9C

func NewKSUIDRandom 

func NewKSUIDRandom() (uid ksuid.KSUID, err error)

NewKSUIDRandom generates a new KSUID with now timestamp.

func NewKSUIDRandomWithTime 

func NewKSUIDRandomWithTime(t time.Time) (uid ksuid.KSUID, err error)

NewKSUIDRandomWithTime generates a new KSUID with the given timestamp.

func NewV1 

func NewV1() uid.UUID

NewV1 returns UUID based on current timestamp and MAC address.

func NewV2 

func NewV2(domain byte) uid.UUID

NewV2 returns DCE Security UUID based on POSIX UID/GID.

func NewV3 

func NewV3(ns uid.UUID, name string) uid.UUID

NewV3 returns UUID based on MD5 hash of namespace UUID and name.

func NewV4 

func NewV4() uid.UUID

NewV4 returns random generated UUID.

func NewV5 

func NewV5(ns uid.UUID, name string) uid.UUID

NewV5 returns UUID based on SHA-1 hash of namespace UUID and name.

func NewXID 

func NewXID() xid.ID

NewXID generates a globally unique ID.

Example 
package main

import (
	"encoding/hex"
	"fmt"
	"strings"

	"github.com/rs/xid"

	"github.com/v8fg/kit4go/uuid"
)

func printXIDInspect(id xid.ID) {
	const inspectFormat = `
REPRESENTATION:
  String: %v
     Raw: %v
COMPONENTS:
       Time: %v
    Counter: %v
    Machine: %v
        Pid: %v
`
	fmt.Printf(inspectFormat,
		id.String(),
		strings.ToUpper(hex.EncodeToString(id.Bytes())),
		id.Time().UTC().String(),
		id.Counter(),
		strings.ToUpper(hex.EncodeToString(id.Machine())),
		id.Pid(),
	)
}

func main() {
	testXIDStr := "cd1qnegnhc7lcditguhg"
	testXID, _ := uuid.XIDFromString(testXIDStr)
	printXIDInspect(testXID)

}

Output:

REPRESENTATION:
  String: cd1qnegnhc7lcditguhg
     Raw: 6343ABBA178B0F56365D87A3
COMPONENTS:
       Time: 2022-10-10 05:20:58 +0000 UTC
    Counter: 6129571
    Machine: 178B0F
        Pid: 22070

func NewXIDWithTime 

func NewXIDWithTime(time time.Time) xid.ID

NewXIDWithTime generates a globally unique ID with the passed in time.

func RequestID 

func RequestID() string

RequestID returns the request ID with UUID V4, in hash-like format, 32 chars.

Example 
package main

import (
	"fmt"

	"github.com/v8fg/kit4go/uuid"
)

func main() {
	testUIDHashLikeFormat := "10da441c38704f06a78c4dfef1c9acea"
	testUIDCanonicalFormat := "10da441c-3870-4f06-a78c-4dfef1c9acea"
	testUUID, _ := uuid.FromString(testUIDHashLikeFormat)
	testUUID2, _ := uuid.FromString(testUIDCanonicalFormat)
	fmt.Printf("[ExampleRequestID] %v\n", uuid.ToRequestID(testUUID))
	fmt.Printf("[ExampleRequestID] %v\n", uuid.ToRequestID(testUUID2))

}

Output:

[ExampleRequestID] 10da441c38704f06a78c4dfef1c9acea
[ExampleRequestID] 10da441c38704f06a78c4dfef1c9acea

func RequestIDCanonicalFormat 

func RequestIDCanonicalFormat() string

RequestIDCanonicalFormat returns the request ID with UUID V4, in canonical format, 36 chars.

Example 
package main

import (
	"fmt"

	"github.com/v8fg/kit4go/uuid"
)

func main() {
	testUIDHashLikeFormat := "10da441c38704f06a78c4dfef1c9acea"
	testUIDCanonicalFormat := "10da441c-3870-4f06-a78c-4dfef1c9acea"
	testUUID, _ := uuid.FromString(testUIDHashLikeFormat)
	testUUID2, _ := uuid.FromString(testUIDCanonicalFormat)
	fmt.Printf("[ExampleRequestIDCanonicalFormat] %v\n", testUUID.String())
	fmt.Printf("[ExampleRequestIDCanonicalFormat] %v\n", testUUID2.String())

}

Output:

[ExampleRequestIDCanonicalFormat] 10da441c-3870-4f06-a78c-4dfef1c9acea
[ExampleRequestIDCanonicalFormat] 10da441c-3870-4f06-a78c-4dfef1c9acea

func ToRequestID 

func ToRequestID(u uid.UUID) string

ToRequestID converts the uuid with UUID V4 to a request ID, in hash-like format, 32 chars.

func XIDFromBytes 

func XIDFromBytes(b []byte) (xid.ID, error)

XIDFromBytes convert the byte array representation of `ID` back to `ID`

func XIDFromString 

func XIDFromString(id string) (xid.ID, error)

XIDFromString reads an ID from its string representation

func XIDSort 

func XIDSort(ids []xid.ID)

XIDSort sorts an array of IDs inplace. It works by wrapping `[]ID` and use `sort.Sort`.

Types

This section is empty.

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.