DOCSEARCHbyAlgolia
Submit Docs

google/uuid

repository·master·Indexed 27 days ago

https://github.com/google/uuid

A Go implementation for generating and inspecting UUIDs following RFC 9562 and DCE 1.1 standards. The package supports multiple UUID versions, including Version 1 (time-based), Version 2 (DCE Security), Version 3 (MD5), Version 4 (random), and Version 5 (SHA1). It provides utilities for parsing various UUID formats, binary and text marshaling, SQL and JSON integration via the NullUUID type, and custom configuration for Node IDs and random number generators.

Tokens
3.4K
Snippets
4
Records
43
Agent score
88%

What's inside google-uuid

  1. Overview of the uuid package

    master

    The uuid package provides functionality to generate and inspect UUIDs (Universally Unique Identifiers) compliant with RFC 9562 and DCE 1.1.

    Key implementation detail: In this package, a UUID is represented as a 16-byte array ([16]byte) rather than a byte slice. Note that this design choice means the package cannot represent an invalid UUID state separately from a NIL UUID.

  3. Generate a Version 1 (time-based) UUID with NewUUID

    master

    Use NewUUID() to generate a Version 1 UUID based on the current time, clock sequence, and NodeID.

    • NodeID: If the NodeID has not been previously configured via SetNodeID or SetNodeInterface, it will be set automatically. If it cannot be set, NewUUID returns nil.
    • Clock Sequence: If the clock sequence has not been set via SetClockSequence, it will be set automatically.
    • Errors: If GetTime() fails to return the current time, NewUUID returns nil and an error.

  4. Extract Domain and ID from a Version 2 UUID

    master

    If you have a Version 2 UUID, you can extract its domain and ID using the following methods:

    • Domain(): Returns the Domain (Person, Group, or Org).
    • ID(): Returns the uint32 ID associated with the UUID.

  5. Convert Time to Unix seconds and nanoseconds

    master
    The Time type represents time as the number of 100-nanosecond intervals since 15 Oct 1582. You can convert this value into standard Unix epoch seconds and nanoseconds using the UnixTime() method.

  6. Generate a Version 7 UUID from an io.Reader with NewV7FromReader

    master
    Use NewV7FromReader(r io.Reader) to generate a Version 7 UUID using a provided reader to fill the random bits. This is useful when you need to provide a specific source of entropy. On error, it returns a Nil UUID and an error.

  7. Unmarshal UUID from binary

    master
    The *UUID type implements the encoding.BinaryUnmarshaler interface. Use UnmarshalBinary(data []byte) to parse a 16-byte slice into a UUID. If the input data length is not exactly 16 bytes, it returns an error: invalid UUID (got %d bytes).

  8. Parse UUID strings and byte slices

    master

    Use Parse to decode a string into a UUID or ParseBytes to decode a byte slice. These functions support multiple formats defined in RFC 9562:

    • Standard: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    • URN: urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    • Microsoft style: {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
    • Raw hex: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    Note: Parse should not be used for strict validation as it accepts non-standard encodings.

  9. Generate DCE Person and Group UUIDs

    master

    The package provides convenience functions to generate Version 2 UUIDs based on the current process's identity on POSIX systems:

    • NewDCEPerson(): Returns a DCE Security UUID in the Person domain using the current user's UID (os.Getuid()).
    • NewDCEGroup(): Returns a DCE Security UUID in the Group domain using the current user's GID (os.Getgid()).

  10. Generate a Version 5 (SHA1) UUID

    master
    Use NewSHA1 to create a name-based UUID using the SHA1 algorithm. It requires a namespace UUID and the data to be hashed. This is equivalent to calling NewHash(sha1.New(), space, data, 5).

  11. Inspect UUID Version and Variant

    master

    You can inspect the properties of a UUID using the .Version() and .Variant() methods.

    • Version() returns a Version type representing the UUID version.
    • Variant() returns a Variant type representing the UUID variant.

    Both types implement the String() method for human-readable output.