Documentation ¶
Overview ¶
Package rid provides a performant, k-sortable, scalable unique ID generator suitable for applications where ID generation coordination between machines or other processes is not required. ID generation is goroutine safe and scales well with CPU cores. Providing unique non-sequential keys for embeddable databases like SQLIte or BoltDB or key-value stores are typical use-cases.
Binary IDs Base-32 encode as a 16-character URL and human-friendly representation like dfp7qt0v2pwt0v2x.
The 10-byte binary representation of an ID is comprised of:
- 4-byte timestamp value representing seconds since the Unix epoch
- 6-byte random value; as of release v1.1.6 this package uses math/rand/v2 introduced with Go 1.22
Key features:
- K-orderable in both binary and string representations
- Encoded IDs are short (16 characters)
- Automatic (de)serialization for SQL and JSON
- Scalable performance as cores increase; ID generation is fast and remains so
- URL and human friendly Base32 encoding using a custom character set to avoid unintended rude words if humans are to be exposed to IDs
Example usage:
id := rid.New() fmt.Printf("%s", id.String()) // Output: dfp7qt97menfv8ll id, err := id.FromString("dfp7qt97menfv8ll") // ID{0x63,0xac,0x7b,0xe9,0x27,0xa3,0x6a,0xed,0xa2,0x73}, nil
Acknowledgement: This source file is based on work in package github.com/rs/xid, a zero-configuration globally-unique ID generator. See LICENSE.rs-xid. The same API has been maintained.
Index ¶
- Variables
- func Sort(ids []ID)
- type ID
- func (id ID) Bytes() []byte
- func (id ID) Compare(other ID) int
- func (id ID) Encode(dst []byte) []byte
- func (id ID) IsNil() bool
- func (id ID) IsZero() bool
- func (id ID) MarshalJSON() ([]byte, error)
- func (id ID) MarshalText() ([]byte, error)
- func (id ID) Random() uint64
- func (id *ID) Scan(value interface{}) (err error)
- func (id ID) String() string
- func (id ID) Time() time.Time
- func (id ID) Timestamp() int64
- func (id *ID) UnmarshalJSON(b []byte) error
- func (id *ID) UnmarshalText(text []byte) error
- func (id ID) Value() (driver.Value, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidID represents errors returned when converting from invalid // []byte, string or json representations ErrInvalidID = errors.New("rid: invalid id") )
Functions ¶
Types ¶
type ID ¶
type ID [rawLen]byte
ID represents a unique identifier
func FromBytes ¶
FromBytes copies []bytes into an ID value. For validity, only a length-check is possible and performed.
func FromString ¶
FromString decodes a Base32-encoded string to return an ID.
Example ¶
// dfp7emzzzzy30ey2 ts:1672246995 rnd:281474912761794 2022-12-28 09:03:15 -0800 PST ID{0x63,0xac,0x76,0xd3,0xff,0xff,0xfc,0x30,0x37,0xc2} id, err := FromString("dfp7emzzzzy30ey2") if err != nil { panic(err) } fmt.Println(id.Timestamp(), id.Random())
Output: 1672246995 281474912761794
func New ¶
func New() ID
New returns a new ID using the current time.
Example ¶
examples
id := New() fmt.Printf(`ID: String() %s Timestamp() %d Random() %d Time() %v Bytes() %3v\n`, id.String(), id.Timestamp(), id.Random(), id.Time().UTC(), id.Bytes())
Output:
func NewWithTime ¶
NewWithTime returns a new ID using the supplied time.
The time value component of an ID is a Unix timestamp with seconds resolution; Go timestamp values reflect UTC and are not location aware.
Example ¶
id := NewWithTime(time.Date(2020, time.January, 1, 0, 0, 0, 0, time.UTC)) fmt.Printf(`ID: Timestamp() %d Time() %v`, id.Timestamp(), id.Time().UTC())
Output: ID: Timestamp() 1577836800 Time() 2020-01-01 00:00:00 +0000 UTC
func (ID) Compare ¶
Compare makes IDs k-sortable, returning an integer comparing only the first 4 bytes of two IDs.
Recall that an ID is comprized of a:
- 4-byte timestamp - 6-byte random value
Otherwise, it behaves just like `bytes.Compare(b1[:], b2[:])`.
The result will be 0 if two IDs are identical, -1 if current id is less than the other one, and 1 if current id is greater than the other.
func (ID) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface. https://golang.org/pkg/encoding/json/#Marshaler
func (ID) MarshalText ¶
MarshalText implements encoding.TextMarshaler. https://golang.org/pkg/encoding/#TextMarshaler
func (*ID) Scan ¶
Scan implements the sql.Scanner interface. https://golang.org/pkg/database/sql/#Scanner
func (ID) Timestamp ¶
Timestamp returns the ID's timestamp component as seconds since the Unix epoch.
func (*ID) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface. https://golang.org/pkg/encoding/json/#Unmarshaler
func (*ID) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler https://golang.org/pkg/encoding/#TextUnmarshaler All decoding is called from here.
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
rid
A utility to generate or inspect IDs.
|
A utility to generate or inspect IDs. |
eval
|
|
compare
Package main produces for documentation a markdown formatted table illustrating key differences between a number of unique ID packages.
|
Package main produces for documentation a markdown formatted table illustrating key differences between a number of unique ID packages. |
uniqcheck
Package main seeks to determine if the approach used delivers sufficiently unique IDs in go applications potentially running multiple goroutines.
|
Package main seeks to determine if the approach used delivers sufficiently unique IDs in go applications potentially running multiple goroutines. |