An ULID is a 16 byte Universally Unique Lexicographically Sortable Identifier
The components are encoded as 16 octets.
Each component is encoded with the MSB first (network byte order).
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 32_bit_uint_time_high |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 16_bit_uint_time_low | 16_bit_uint_random |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 32_bit_uint_random |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 32_bit_uint_random |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Compare returns an integer comparing id and other lexicographically.
The result will be 0 if id==other, -1 if id < other, and +1 if id > other. Entropy returns the entropy from the ULID. MarshalBinary implements the encoding.BinaryMarshaler interface by
returning the ULID as a byte slice. MarshalBinaryTo writes the binary encoding of the ULID to the given buffer.
ErrBufferSize is returned when the len(dst) != 16. MarshalText implements the encoding.TextMarshaler interface by
returning the string encoded ULID. MarshalTextTo writes the ULID as a string to the given buffer.
ErrBufferSize is returned when the len(dst) != 26. Scan implements the sql.Scanner interface. It supports scanning
a string or byte slice. SetEntropy sets the ULID entropy to the passed byte slice.
ErrDataSize is returned if len(e) != 10. SetTime sets the time component of the ULID to the given Unix time
in milliseconds. String returns a lexicographically sortable string encoded ULID
(26 characters, non-standard base 32) e.g. 01AN4Z07BY79KA1307SR9X4MV3
Format: tttttttttteeeeeeeeeeeeeeee where t is time and e is entropy Time returns the Unix time in milliseconds encoded in the ULID.
Use the top level Time function to convert the returned value to
a time.Time. UnmarshalBinary implements the encoding.BinaryUnmarshaler interface by
copying the passed data and converting it to an ULID. ErrDataSize is
returned if the data length is different from ULID length. UnmarshalText implements the encoding.TextUnmarshaler interface by
parsing the data as string encoded ULID.
ErrDataSize is returned if the len(v) is different from an encoded
ULID's length. Invalid encodings produce undefined ULIDs. Value implements the sql/driver.Valuer interface. This returns the value
represented as a byte slice. If instead a string is desirable, a wrapper
type can be created that calls String().
// stringValuer wraps a ULID as a string-based driver.Valuer.
type stringValuer ULID
func (id stringValuer) Value() (driver.Value, error) {
return ULID(id).String(), nil
}
// Example usage.
db.Exec("...", stringValuer(id))
*ULID : database/sql.Scanner
ULID : database/sql/driver.Valuer
ULID : encoding.BinaryMarshaler
*ULID : encoding.BinaryUnmarshaler
ULID : encoding.TextMarshaler
*ULID : encoding.TextUnmarshaler
ULID : expvar.Var
ULID : fmt.Stringer
func MustNew(ms uint64, entropy io.Reader) ULID
func MustParse(ulid string) ULID
func MustParseStrict(ulid string) ULID
func New(ms uint64, entropy io.Reader) (id ULID, err error)
func Parse(ulid string) (id ULID, err error)
func ParseStrict(ulid string) (id ULID, err error)
func ULID.Compare(other ULID) int
Package-Level Functions (total 11)
MaxTime returns the maximum Unix time in milliseconds that
can be encoded in an ULID.
Monotonic returns an entropy source that is guaranteed to yield
strictly increasing entropy bytes for the same ULID timestamp.
On conflicts, the previous ULID entropy is incremented with a
random number between 1 and `inc` (inclusive).
The provided entropy source must actually yield random bytes or else
monotonic reads are not guaranteed to terminate, since there isn't
enough randomness to compute an increment number.
When `inc == 0`, it'll be set to a secure default of `math.MaxUint32`.
The lower the value of `inc`, the easier the next ULID within the
same millisecond is to guess. If your code depends on ULIDs having
secure entropy bytes, then don't go under this default unless you know
what you're doing.
The returned io.Reader isn't safe for concurrent use.
MustNew is a convenience function equivalent to New that panics on failure
instead of returning an error.
MustParse is a convenience function equivalent to Parse that panics on failure
instead of returning an error.
MustParseStrict is a convenience function equivalent to ParseStrict that
panics on failure instead of returning an error.
New returns an ULID with the given Unix milliseconds timestamp and an
optional entropy source. Use the Timestamp function to convert
a time.Time to Unix milliseconds.
ErrBigTime is returned when passing a timestamp bigger than MaxTime.
Reading from the entropy source may also return an error.
Now is a convenience function that returns the current
UTC time in Unix milliseconds. Equivalent to:
Timestamp(time.Now().UTC())
Parse parses an encoded ULID, returning an error in case of failure.
ErrDataSize is returned if the len(ulid) is different from an encoded
ULID's length. Invalid encodings produce undefined ULIDs. For a version that
returns an error instead, see ParseStrict.
ParseStrict parses an encoded ULID, returning an error in case of failure.
It is like Parse, but additionally validates that the parsed ULID consists
only of valid base32 characters. It is slightly slower than Parse.
ErrDataSize is returned if the len(ulid) is different from an encoded
ULID's length. Invalid encodings return ErrInvalidCharacters.
Time converts Unix milliseconds in the format
returned by the Timestamp function to a time.Time.
Timestamp converts a time.Time to Unix milliseconds.
Because of the way ULID stores time, times from the year
10889 produces undefined results.
Package-Level Variables (total 7)
ErrBigTime is returned when constructing an ULID with a time that is larger
than MaxTime.
ErrBufferSize is returned when marshalling ULIDs to a buffer of insufficient
size.
ErrDataSize is returned when parsing or unmarshaling ULIDs with the wrong
data size.
ErrInvalidCharacters is returned when parsing or unmarshaling ULIDs with
invalid Base32 encodings.
ErrMonotonicOverflow is returned by a Monotonic entropy source when
incrementing the previous ULID's entropy bytes would result in overflow.
ErrOverflow is returned when unmarshaling a ULID whose first character is
larger than 7, thereby exceeding the valid bit depth of 128.
ErrScanValue is returned when the value passed to scan cannot be unmarshaled
into the ULID.
Package-Level Constants (total 2)
EncodedSize is the length of a text encoded ULID.
Encoding is the base 32 encoding alphabet used in ULID strings.
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
