README
¶
XXID Unique ID Generator
Package xxid is a specific kind of unique id generator, originally forked from xid.
The v2 version has been totally redesigned and rewritten.
Introduction
TODO
Install
go get github.com/jxskiss/xxid/v2@latest
Usage
id := xxid.New()
fmt.Printf("%d %s %s\n", id.Short(), id.Base62(), id.String())
// 107306765558351289 0MTmSIz6YnbzdVsgK5S7SE 20211120092140634056218b67c800abe705b9
ip := net.ParseIP("10.9.8.7")
gen := xxid.NewGenerator().UseIPv4(ip).UsePort(8888).UseFlag(123)
id = gen.New()
fmt.Println(id.Time(), id.IP(), id.Port(), id.Flag())
// 2021-11-20 09:21:40.634 +0800 CST 10.9.8.7 8888 123
Documentation
¶
Index ¶
- type Generator
- func (g *Generator) New() ID
- func (g *Generator) NewWithTime(t time.Time) ID
- func (g *Generator) UseFlag(flag uint16) *Generator
- func (g *Generator) UseIPv4(ip net.IP) *Generator
- func (g *Generator) UseIPv6(ip net.IP) *Generator
- func (g *Generator) UseMachineID(id []byte) *Generator
- func (g *Generator) UsePort(port uint16) *Generator
- type ID
- func (id ID) Base62() []byte
- func (id ID) Binary() []byte
- func (id ID) Counter() uint16
- func (id ID) Flag() uint16
- func (id ID) IP() net.IP
- func (id ID) IPPortAddr() string
- func (id ID) MachineID() []byte
- func (id ID) MachineIDType() MachineIDType
- func (id ID) MarshalJSON() ([]byte, error)
- func (id ID) Pid() uint16
- func (id ID) Port() uint16
- func (id ID) SetFlag(flag uint16) ID
- func (id ID) Short() int64
- func (id ID) String() string
- func (id ID) Time() time.Time
- func (id *ID) UnmarshalJSON(buf []byte) error
- type MachineIDType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
A Generator holds some machine information which is used to generate unique IDs. Some information can be configured by user.
func NewGenerator ¶
func NewGenerator() *Generator
NewGenerator makes a new generator initialized with same machineID and pid as the default generator, this is useful to specify machine ID, IP, port and flag value instead of the defaults.
For general purpose without configuring machine ID, IP, port or flag, New and NewWithTime are recommended in most cases.
func (*Generator) NewWithTime ¶
NewWithTime generates an ID with the given time.
func (*Generator) UseFlag ¶
UseFlag sets the generator to use the given flag.
Note that only 15 bits are allowed for flag, if the highest bit is set, it will be discarded.
func (*Generator) UseMachineID ¶
UseMachineID changes the machine ID of the generator to user specified bytes.
Length of the provided bytes must be 4, 8 or 16, else it panics, the corresponding MachineIDType will be Specified4, Specified8 or Specified16.
type ID ¶
type ID struct {
// contains filtered or unexported fields
}
ID is a specific kind of unique identifier.
The marshaled form of ID values are ordered by their generation time (in millisecond precision). Additionally, you may encode some machine information or even some business information into an ID.
An ID consists of the following parts: 1. millisecond timestamp; 2. machine ID, which may host identifier, IP address or user specified bytes; 3. process ID or user specified port number; 4. a counter, starts at a random value; 5. a flag value, random or user specified;
An ID can be encoded into binary, base62 or string form. The binary form is short and takes less space, the base62 form encodes the binary form with base62 encoding, and the string form is friendly to human, it encodes the ID using number digits and hex, user can read the content of an ID from the string form, the string form is good for scenes where user may need to inspect the content frequently (e.g. logging or tracing identifier).
func NewWithTime ¶
NewWithTime generates an ID with the given time.
func ParseBase62 ¶
ParseBase62 parses an ID from its base62 form.
func ParseBinary ¶
ParseBinary parses an ID from its binary form.
func ParseString ¶
ParseString parses an ID from its string form.
func (ID) Base62 ¶
Base62 encodes the ID into its base62 form. The returned bytes may be of length 22, 27, or 38 according to the machine ID type.
func (ID) Binary ¶
Binary encodes the ID into its binary form. The returned bytes may be of length 16, 20, or 28 according to the machine ID type.
func (ID) IP ¶
IP returns the ID's machine ID as an IP, the return value may be an IPv4 address or IPv6 address.
If the machine ID is not an IP address, it returns nil.
func (ID) IPPortAddr ¶
IPPortAddr returns and address string consists of the IP address and the port number if the machine ID is an IP address, else it returns "".
func (ID) MachineID ¶
MachineID returns the ID's machine ID in bytes. The returned bytes may be of length 4, 8, or 16 according to the machine ID type.
func (ID) MachineIDType ¶
func (id ID) MachineIDType() MachineIDType
MachineIDType returns the ID's machine ID type.
func (ID) MarshalJSON ¶
MarshalJSON encodes ID to a JSON string using its base62 form.
func (ID) Pid ¶
Pid returns the ID's pid value, note that the returned value may be a port number if the Generator is configured by UsePort.
func (ID) Port ¶
Port returns the ID's port number, note that the returned value may be a pid if the Generator is not configured by UsePort.
func (ID) SetFlag ¶
SetFlag returns a new ID value with the given flag.
Note that the function receiver is an ID value, which means that the receiver ID value won't be changed, the caller need to save the returned value to somewhere, calling this function without using the returned value is a no-op.
func (ID) Short ¶
Short returns the time and counter value of the ID as an int64, the returned value is guaranteed to be unique inside a process.
func (ID) String ¶
String encodes the ID into its string form. The returned string may be of length 38, 46, or 62 according to the machine ID type,
func (*ID) UnmarshalJSON ¶
UnmarshalJSON decodes ID from a JSON string in its base62 form.
type MachineIDType ¶
type MachineIDType uint8
MachineIDType indicates the type of and ID's machine ID.
const ( // Random indicates the machine ID is auto-generated random bytes, // it's used only when the host identifier can not be read from the // operating system. Random MachineIDType = 0 // HostID indicates the machine ID is the hash digest of the host // identifier read from the operating system. HostID MachineIDType = 1 // IPv4 indicates the machine ID is an IPv4 address specified by user. IPv4 MachineIDType = 2 // IPv6 indicates the machine ID is an IPv6 address specified by user. IPv6 MachineIDType = 3 // Specified4 indicates the machine ID is a 4 bytes value specified // by user. Specified4 MachineIDType = 4 // Specified8 indicates the machine ID is an 8 bytes value specified // by user. Specified8 MachineIDType = 5 // Specified16 indicates the machine ID is a 16 bytes value specified // by user. Specified16 MachineIDType = 6 )
Source Files
Directories