snowflake

README

snowflake

snowflake is a golang library for parsing snowflake IDs from discord. This package provides a custom snowflake.ID type which has various utility methods for parsing discord snowflakes.

Installing

go get github.com/disgoorg/snowflake/v2

Usage

id := snowflake.ID(123456789012345678)

// deconstructs the snowflake ID into its components timestamp, worker ID, process ID, and increment
id.Deconstruct()

// the time.Time when the snowflake ID was generated
id.Time()

// the worker ID which the snowflake ID was generated
id.WorkerID()

// the process ID which the snowflake ID was generated
id.ProcessID()

// tje sequence when the snowflake ID was generated
id.Sequence()

// returns the string representation of the snowflake ID
id.String()

// returns a new snowflake ID with worker ID, process ID, and sequence set to 0
// this can be used for various pagination requests to the discord api
id := snowflake.New(time.Now())

// returns a snowflake ID from an environment variable
id := snowflake.GetEnv("guild_id")

// returns a snowflake ID from an environment variable and a bool indicating if the key was found
id, found := snowflake.LookupEnv("guild_id")

// returns the string as a snowflake ID or an error
id, err := snowflake.Parse("123456789012345678")

// returns the string as a snowflake ID or panics if an error occurs
id := snowflake.MustParse("123456789012345678")

License

Distributed under the . See LICENSE for more information.

Documentation

Index

• Constants
• Variables
• type DeconstructedSnowflake
• type ID
  • func GetEnv(key string) ID
  • func LookupEnv(key string) (ID, bool)
  • func MustParse(str string) ID
  • func New(timestamp time.Time) ID
  • func Parse(str string) (ID, error)
  • func (id ID) Deconstruct() DeconstructedSnowflake
  • func (id ID) MarshalJSON() ([]byte, error)
  • func (id ID) ProcessID() uint8
  • func (id ID) Sequence() uint16
  • func (id ID) String() string
  • func (id ID) Time() time.Time
  • func (id *ID) UnmarshalJSON(data []byte) error
  • func (id ID) WorkerID() uint8

Constants

const Epoch = 1420070400000

Epoch is the discord epoch in milliseconds.

Variables

var AllowUnquoted = false

Types

type DeconstructedSnowflake

type DeconstructedSnowflake struct {
	Time      time.Time
	WorkerID  uint8
	ProcessID uint8
	Sequence  uint16
}

DeconstructedSnowflake contains the properties used by Discord for each snowflake ID.

type ID

type ID uint64

ID represents a unique snowflake ID.

func GetEnv

func GetEnv(key string) ID

GetEnv returns the value of the environment variable named by the key and parses it as a snowflake. returns ID(0) if the environment variable is not set.

func LookupEnv

func LookupEnv(key string) (ID, bool)

LookupEnv returns the value of the environment variable named by the key and parses it as a snowflake. returns false if the environment variable is not set.

func MustParse

func MustParse(str string) ID

MustParse parses a string into a snowflake ID and panics on error. returns ID(0) if the string is "null"

func New

func New(timestamp time.Time) ID

New creates a new snowflake ID from the provided timestamp with worker id and sequence 0.

func Parse

func Parse(str string) (ID, error)

Parse parses a string into a snowflake ID. returns ID(0) if the string is "null"

func (ID) Deconstruct

func (id ID) Deconstruct() DeconstructedSnowflake

Deconstruct returns DeconstructedID (https://discord.com/developers/docs/reference#snowflakes-snowflake-id-format-structure-left-to-right).

func (ID) MarshalJSON

func (id ID) MarshalJSON() ([]byte, error)

MarshalJSON marshals the snowflake ID into a JSON string.

func (ID) ProcessID

func (id ID) ProcessID() uint8

func (ID) Sequence

func (id ID) Sequence() uint16

Sequence returns the sequence of the snowflake.

func (ID) String

func (id ID) String() string

String returns a string representation of the snowflake ID.

func (ID) Time

func (id ID) Time() time.Time

Time returns the time.Time the snowflake was created.

func (*ID) UnmarshalJSON

func (id *ID) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the snowflake ID from a JSON string.

func (ID) WorkerID

func (id ID) WorkerID() uint8

WorkerID returns the id of the worker the snowflake was created on.