uid

package module
v1.8.0 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2025 License: MIT Imports: 11 Imported by: 16

README

UID (Unique ID) Open in Gitpod

Tests Status Go Report Card PkgGoDev

This package generates unique identifying strings. Largest attention is paid on human friendly unique identifiers (dated digits).

Installation

go get -u github.com/dracory/uid

Usage

package main

import (
    "fmt"
    "github.com/dracory/uid"
)

func main() {
    // HumanUid generates a UID (32 digits)
    // Format: YYYYMMDD-HHMM-SSMM-MMMMNNNRRRRRRRRR
    human := uid.HumanUid()          // unformatted, length: 32
    humanF := uid.HumanUid(true)     // formatted (8-4-4-16), length: 35

    // NanoUid generates a UID (23 digits)
    // Format: YYYYMMDD-HHMMSS-MMMMMM-NNN
    nano := uid.NanoUid()            // unformatted, length: 23
    nanoF := uid.NanoUid(true)       // formatted (8-6-6-3), length: 26

    // MicroUid generates a UID (20 digits)
    // Format: YYYYMMDD-HHMMSS-MMMMMM
    micro := uid.MicroUid()          // unformatted, length: 20
    microF := uid.MicroUid(true)     // formatted (8-6-6), length: 22

    // SecUid generates a UID (14 digits)
    // Format: YYYYMMDD-HHMMSS
    sec := uid.SecUid()              // unformatted, length: 14
    secF := uid.SecUid(true)         // formatted (8-6), length: 15

    // Unix timestamps as strings
    ts := uid.Timestamp()            // seconds, length: 10
    tsu := uid.TimestampMicro()      // microseconds, length: 16
    tsn := uid.TimestampNano()       // nanoseconds, length: 19

    // UUIDs (implemented via standard library)
    u4 := uid.Uuid()                 // v4 unformatted, length: 32
    u4f := uid.Uuid(true)            // v4 formatted, length: 36
    v1 := uid.UuidV1()               // v1 unformatted, length: 32
    v1f := uid.UuidV1(true)          // v1 formatted, length: 36
    v3, _ := uid.UuidV3("1234567890abcdef", []byte("name"))     // v3 unformatted
    v3f, _ := uid.UuidV3("1234567890abcdef", []byte("name"), true)
    v5, _ := uid.UuidV5("1234567890abcdef", []byte("name"))     // v5 unformatted
    v5f, _ := uid.UuidV5("1234567890abcdef", []byte("name"), true)
    v6 := uid.UuidV6()               // v6 unformatted, length: 32
    v6f := uid.UuidV6(true)          // v6 formatted, length: 36
    v7 := uid.UuidV7()               // v7 unformatted, length: 32
    v7f := uid.UuidV7(true)          // v7 formatted, length: 36

    fmt.Println(human, humanF, nano, nanoF, micro, microF, sec, secF,
        ts, tsu, tsn, u4, u4f, v1, v1f, v3, v3f, v5, v5f, v6, v6f, v7, v7f)
}

Supported UID Types

It supports several types of unique identifiers.

The type you want to use will usually depends on two considerations:

  1. How random you want it to be? The longer the identifier, the more the chances of collision reduce
  2. How long you want the identifier to be? The longer the identifier, reduces the readability, as well as the storage space to store it.

For most of the user cases a Micro UID (20 chars) should be fine. A human UID (32 chars) should be avoided where a human is involved as too "mind bogging" to work with.

  1. Human UID (32 digits)

    Format: YYYYMMDD-HHMM-SSMM-MMMMNNNRRRRRRRRR

    2017111908492665991498485465 (with dashes: 20171119-0849-2665-991498485465)

  2. Nano UID (23 digits)

    Format: YYYYMMDD-HHMMSS-MMMMMM-NNN

    Examples:

    20171119084926659914984 (with dashes: 20171119-084926-659914-984)

  3. Micro UID (20 digits)

    Format: YYYYMMDD-HHMMSS-MMMMMM

    Examples:

    20171119084926659914 (with dashes: 20171119-084926-659914)

  4. Seconds UID (14 digits)

    Format: YYYYMMDD-HHMMSS

    Examples:

    20171119084926 (with dashes: 20171119-084926)

  5. Timestamp (10 digits) Unit timestamp, seconds precision

    Format: 1234567890

    Examples:

    1704524414

  6. TimestampMicro (16 digits) Unit timestamp, microseconds precision

    Format: 1234567890123456

    Examples:

    1704524414548721

  7. TimestampNano (19 digits) Unit timestamp, nanoseconds precision

    Format: 1234567890123456789

    Examples:

    1704524414548721308

  8. Uuid (32 characters) Random V4 UUID. UUID (Universally Unique IDentifier), also known as GUID (Globally Unique IDentifier)

    Format: abcdef1234567890abcdef1234567890

    Examples:

    459e2999bd071151a23d643da42c2cc2

UUID functions

UUIDs are implemented using only the Go standard library (no external deps).

  • Uuid(formatted ...bool) → version 4 (random) Examples: 550e8400e29b41d4a716446655440000 (32) • 550e8400-e29b-41d4-a716-446655440000 (36)

  • UuidV1(formatted ...bool) → version 1 (time-based) Examples: 6ba7b8109dad11d180b400c04fd430c8 (32) • 6ba7b810-9dad-11d1-80b4-00c04fd430c8 (36)

  • UuidV3(namespace string, data []byte, formatted ...bool) → version 3 (MD5 name-based) Examples: 3d813cbb47fb32ba91df831e1593ac29 (32) • 3d813cbb-47fb-32ba-91df-831e1593ac29 (36)

  • UuidV4(formatted ...bool) → version 4 (random) Examples: 550e8400e29b41d4a716446655440000 (32) • 550e8400-e29b-41d4-a716-446655440000 (36)

  • UuidV5(namespace string, data []byte, formatted ...bool) → version 5 (SHA-1 name-based) Examples: 21f7f8de80515b8986800195ef798b6a (32) • 21f7f8de-8051-5b89-8680-0195ef798b6a (36)

  • UuidV6(formatted ...bool) → version 6 (time-ordered) Examples: 1ed0c9e48f7b6b2c9c3b6a6c7a9d5e12 (32) • 1ed0c9e4-8f7b-6b2c-9c3b-6a6c7a9d5e12 (36)

  • UuidV7(formatted ...bool) → version 7 (Unix time-based) Examples: 01890f5f3d9c7a0e8a7b6c5d4e3f2a10 (32) • 01890f5f-3d9c-7a0e-8a7b-6c5d4e3f2a10 (36)

Change Log

2025.09.01 - Add optional hyphen formatting 2025.08.31 - Move UUID functions/tests into separate files 2024.01.06 - Added Timestamp and Uuid functions 2021.12.19 - Master branch changed to main 2021.12.19 - Added tests

Similar Packages

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HumanUid 

func HumanUid(formatted ...bool) string

HumanUid generates a 32-character time-prefixed unique ID.

Format (conceptual): YYYYMMDDHHMMSSMMMMMMM + random suffix, truncated to 32.

Example (unformatted): 20250831151133000012345678901234 (length: 32) Example (formatted): 20171119-0849-2665-991498485465 (length: 35)

Parameters: - formatted: when true, include hyphens in groups 8-4-4-16 (length becomes 35)

Returns: - A 32-character uppercase numeric string suitable for human-readable IDs

func MicroUid 

func MicroUid(formatted ...bool) string

MicroUid generates a 20-character time-prefixed unique ID.

Format (conceptual): YYYYMMDDHHMMSSMMMMMMM + random suffix, truncated to 20.

Example (unformatted): 20250831151133000012 (length: 20) Example (formatted): 20171119-084926-659914 (length: 22)

Parameters: - formatted: when true, include hyphens in groups 8-6-6 (length becomes 22)

Returns: - A 20-character numeric string

func NanoUid 

func NanoUid(formatted ...bool) string

NanoUid generates a 23-character time-prefixed unique ID.

Format (conceptual): YYYYMMDDHHMMSSMMMMMMM + random suffix, truncated to 23.

Example (unformatted): 20250831151133000012345 (length: 23) Example (formatted): 20171119-084926-659914-984 (length: 26)

Parameters: - formatted: when true, include hyphens in groups 8-6-6-3 (length becomes 26)

Returns: - A 23-character numeric string

func SecUid 

func SecUid(formatted ...bool) string

SecUid generates a 14-character time-based ID.

Format: YYYYMMDDHHMMSS

Example (unformatted): 20250831151133 (length: 14) Example (formatted): 20171119-084926 (length: 15)

Parameters: - formatted: when true, include hyphens in groups 8-6 (length becomes 15)

Returns: - A 14-character numeric string representing UTC date/time to the second

func Timestamp 

func Timestamp() string

Timestamp returns the current Unix timestamp in seconds as a string.

Example: 1725111153 (length: 10)

Parameters: - None

Returns: - Unix timestamp in seconds (base-10 string)

func TimestampMicro 

func TimestampMicro() string

TimestampMicro returns the current Unix timestamp in microseconds as a string.

Example: 1725111153123456 (length: 16)

Parameters: - None

Returns: - Unix timestamp in microseconds (base-10 string)

func TimestampNano 

func TimestampNano() string

TimestampNano returns the current Unix timestamp in nanoseconds as a string.

Example: 1725111153123456789 (length: 19)

Parameters: - None

Returns: - Unix timestamp in nanoseconds (base-10 string)

func Uuid 

func Uuid(formatted ...bool) string

Uuid returns a random UUID (version 4) without hyphens.

Example: 550e8400e29b41d4a716446655440000 (length: 32)

https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)

Parameters: - formatted: when true, include hyphens

Returns: - A random UUID (version 4) without hyphens

func UuidV1 

func UuidV1(formatted ...bool) string

UuidV1 returns a version 1 (time-based) UUID without hyphens.

Example: 6ba7b8109dad11d180b400c04fd430c8 (length: 32)

https://en.wikipedia.org/wiki/Universally_unique_identifier#Versions_1_and_6_(date-time_and_MAC_address)

Parameters: - formatted: when true, include hyphens

Returns: - The UUID v1 as a string

func UuidV3 

func UuidV3(namespace string, data []byte, formatted ...bool) (string, error)

UuidV3 returns a version 3 (MD5 name-based) UUID. Provide a 16-byte namespace UUID and arbitrary data.

Example (no hyphens): 3d813cbb47fb32ba91df831e1593ac29 (length: 32)

https://en.wikipedia.org/wiki/Universally_unique_identifier#Versions_3_and_5_(namespace_name-based)

Parameters: - namespace: a 16-byte UUID (as bytes) used as the namespace - data: the name bytes to hash - formatted: when true, include hyphens

Returns: - The UUID v3 as a string, or an error

func UuidV4 

func UuidV4(formatted ...bool) string

UuidV4 returns a random UUID (version 4) without hyphens.

Example: 550e8400e29b41d4a716446655440000 (length: 32)

https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)

Parameters: - formatted: when true, include hyphens

Returns: - A random UUID (version 4) without hyphens

func UuidV5 

func UuidV5(namespace string, data []byte, formatted ...bool) (string, error)

UuidV5 returns a version 5 (SHA-1 name-based) UUID. Provide a 16-byte namespace UUID and arbitrary data.

Example (no hyphens): 21f7f8de80515b8986800195ef798b6a (length: 32)

https://en.wikipedia.org/wiki/Universally_unique_identifier#Versions_3_and_5_(namespace_name-based)

Parameters: - namespace: a 16-byte UUID (as bytes) used as the namespace - data: the name bytes to hash - formatted: when true, include hyphens

Returns: - The UUID v5 as a string, or an error

func UuidV6 

func UuidV6(formatted ...bool) string

UuidV6 returns a version 6 (time-ordered) UUID without hyphens.

Example: 1ed0c9e48f7b6b2c9c3b6a6c7a9d5e12 (length: 32)

Draft: https://en.wikipedia.org/wiki/Universally_unique_identifier#Versions_1_and_6_(date-time_and_MAC_address)

Parameters: - formatted: when true, include hyphens

Returns: - A UUID v6 (time-ordered) without hyphens

func UuidV7 

func UuidV7(formatted ...bool) string

UuidV7 returns a version 7 (Unix time-based) UUID without hyphens.

Example: 01890f5f3d9c7a0e8a7b6c5d4e3f2a10 (length: 32)

Draft: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_7_(timestamp_and_random)

Parameters: - formatted: when true, include hyphens

Returns: - A UUID v7 (Unix time-based) without hyphens

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.