snowflake

README

Snowflake

This lib supports signed numbers, but will convert them to uint64.

Does not hold functionality to connect a snowflake service, nor generating snowflakes. But supports parsing snowflakes sent by Discord (both integer and string), and renders zero value as "null" and higher values as a string version to comply with Discord.

For module usage you must utilise the suffix found in the go.mod file (/v2 for v2.x.x releases, /v3 for v3.x.x releases, etc.).

Usage:

Note: if you are against dot imports, which I can understand, instead of writing snowflake.Snowflake, you can write snowflake.ID. ID is just an alias for Snowflake.

import . "github.com/andersfylling/snowflake/v5"

type DiscordRole struct {
    ID          Snowflake    `json:"id"`
    Name        string       `json:"name"`
    Managed     bool         `json:"managed"`
    Mentionable bool         `json:"mentionable"`
    Hoist       bool         `json:"hoist"`
    Color       int          `json:"color"`
    Position    int          `json:"position"`
    Permissions uint64       `json:"permissions"`
}

If you're creating an API that sends JSON, the snowflake will automatically be converted to/from a string for you.

Benchmarks

name                              time/op
UnmarshalJSON/string-8            52.5ns ±14%
UnmarshalJSON/snowflake-8         23.0ns ± 6%
UnmarshalJSON/string-struct-8     1.23µs ± 5%
UnmarshalJSON/snowflake-struct-8  1.15µs ±10%
NullCheck/string-8                0.58ns ± 8%

Documentation

Index

• Constants
• type ID
• type Snowflake
  • func GetSnowflake(v interface{}) (s Snowflake, err error)
  • func NewSnowflake(id uint64) Snowflake
  • func ParseSnowflakeString(v string) Snowflake
  • func ParseSnowflakeUint(v string, base int) (Snowflake, error)
  • func (s Snowflake) Date() time.Time
  • func (s Snowflake) HexPrettyString() string
  • func (s Snowflake) HexString() string
  • func (s Snowflake) IsZero() bool
  • func (s Snowflake) MarshalBinary() (data []byte, err error)
  • func (s Snowflake) MarshalJSON() (data []byte, err error)
  • func (s Snowflake) MarshalText() (text []byte, err error)
  • func (s Snowflake) String() string
  • func (s *Snowflake) UnmarshalBinary(text []byte) (err error)
  • func (s *Snowflake) UnmarshalJSON(data []byte) (err error)
  • func (s *Snowflake) UnmarshalText(text []byte) (err error)
  • func (s Snowflake) Valid() bool

Constants

const (
	EpochDiscord uint64 = 1420070400000
)

Types

type ID

type ID = Snowflake

type Snowflake

type Snowflake uint64

Snowflake twitter snowflake design

func GetSnowflake

func GetSnowflake(v interface{}) (s Snowflake, err error)

func NewSnowflake

func NewSnowflake(id uint64) Snowflake

NewID creates a new Snowflake Snowflake from a uint64.

func ParseSnowflakeString

func ParseSnowflakeString(v string) Snowflake

ParseSnowflakeString interprets a string with a decimal number.

Note that in contrast to ParseUint, this function assumes the given string is
always valid and thus will panic rather than return an error.
This should only be used on checks that can be done at compile time,
unless you want to trust other modules to returns valid data.

func ParseSnowflakeUint

func ParseSnowflakeUint(v string, base int) (Snowflake, error)

ParseUint converts a string and given base to a Snowflake

func (Snowflake) Date

func (s Snowflake) Date() time.Time

func (Snowflake) HexPrettyString

func (s Snowflake) HexPrettyString() string

HexPrettyString converts the Snowflake into a hexadecimal string with the hex prefix 0x

func (Snowflake) HexString

func (s Snowflake) HexString() string

HexString converts the Snowflake into a hexadecimal string

func (Snowflake) IsZero

func (s Snowflake) IsZero() bool

IsZero since snowflake exists of several parts, including a timestamp,

I assume a valid snowflake Snowflake is never 0.

func (Snowflake) MarshalBinary

func (s Snowflake) MarshalBinary() (data []byte, err error)

MarshalBinary create a binary literal representation as a string

func (Snowflake) MarshalJSON

func (s Snowflake) MarshalJSON() (data []byte, err error)

func (Snowflake) MarshalText

func (s Snowflake) MarshalText() (text []byte, err error)

func (Snowflake) String

func (s Snowflake) String() string

String returns the decimal representation of the snowflake Snowflake.

func (*Snowflake) UnmarshalBinary

func (s *Snowflake) UnmarshalBinary(text []byte) (err error)

func (*Snowflake) UnmarshalJSON

func (s *Snowflake) UnmarshalJSON(data []byte) (err error)

func (*Snowflake) UnmarshalText

func (s *Snowflake) UnmarshalText(text []byte) (err error)

func (Snowflake) Valid

func (s Snowflake) Valid() bool

Valid makes sure the snowflake is after the fixed epoch