types

package module
Version: v0.0.0-...-2deba1f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 23, 2021 License: MIT Imports: 6 Imported by: 192

README

go-types

This is a library of types that are useful for dealing with JSON API's, and/or database fields. Currently supports NullString and NullTime, both of which can be serialized to/from JSON or a database.

Documentation

Overview

Package types implements several types for dealing with REST API's and databases.

PrefixUUID

UUID's are very useful, but you often need to attach context to them; e.g. you cannot look at a UUID and know whether it points to a record in the accounts table or in the messages table. A PrefixUUID solves this problem, by embedding the additional useful information as part of the string.

a, _ := types.NewPrefixUUID("account6740b44e-13b9-475d-af06-979627e0e0d6")
fmt.Println(a.Prefix) // "account"
fmt.Println(a.UUID.String()) "6740b44e-13b9-475d-af06-979627e0e0d6"
fmt.Println(a.String()) "account6740b44e-13b9-475d-af06-979627e0e0d6"

If we had to write this value to the database as a string it would take up 43 bytes. Instead we use a UUID type and strip the prefix before saving it.

The converse, Value(), only returns the UUID part by default, since this is the only thing the database knows about. You can also attach the prefix manually in your SQL, like so:

SELECT 'job_' || id, created_at FROM jobs;

This will get parsed as part of the Scan(), and then you don't need to do anything. Alternatively, you can attach the prefix in your model, immediately after the query.

func Get(id types.PrefixUUID) *User {
	var uid types.PrefixUUID
	var email string
	db.Conn.QueryRow("SELECT * FROM users WHERE id = $1").Scan(&uid, &email)
	uid.Prefix = "usr"
	return &User{
		ID: uid,
		Email: email
	}
}

NullString

A NullString is like the null string in `database/sql`, but can additionally be encoded/decoded via JSON.

json.NewEncoder(os.Stdout).Encode(NullString{Valid: false})
// Output: null
json.NewEncoder(os.Stdout).Encode(NullString{Valid: true, String: "hello"})
// Output: "hello"

NullTime

A NullTime behaves exactly like NullString, but the value is a time.Time.

json.NewEncoder(os.Stdout).Encode(NullTime{Valid: false})
// Output: null
json.NewEncoder(os.Stdout).Encode(NullTime{Valid: true, Time: time.Now()})
// Output: "2016-05-02T08:33:46.005852482-07:00"

Index

Examples

Constants

View Source
const (
	Bit  Bits = 1
	Byte      = 8 * Bit
	// https://en.wikipedia.org/wiki/Orders_of_magnitude_(data)
	Kilobyte = 1000 * Byte
	Megabyte = 1000 * Kilobyte
	Gigabyte = 1000 * Megabyte
	Terabyte = 1000 * Gigabyte
	Petabyte = 1000 * Terabyte
	Exabyte  = 1000 * Petabyte
)
View Source
const Version = "1.2"

Variables

This section is empty.

Functions

This section is empty.

Types

type Bits

type Bits int64

Bits represents a quantity of bits, bytes, kilobytes or megabytes. Bits are parsed and formatted using the IEEE / SI standards, which use multiples of 1000 to represent kilobytes and megabytes (instead of multiples of 1024). For more information see https://en.wikipedia.org/wiki/Megabyte#Definitions.

func ParseBits

func ParseBits(s string) (Bits, error)

ParseBits parses a quantity of bits. A bit size is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix. Valid units are "bit", "B", "kB", "MB", "GB", "TB". Kilobytes are converted to bytes by dividing by 1000, not 1024, per the IEEE standard.

func (Bits) Bytes

func (b Bits) Bytes() float64

Bytes returns the size as a floating point number of bytes.

func (Bits) Gigabytes

func (b Bits) Gigabytes() float64

Gigabytes returns the size as a floating point number of gigabytes.

func (Bits) Kilobytes

func (b Bits) Kilobytes() float64

Kilobytes returns the size as a floating point number of kilobytes.

func (Bits) Megabytes

func (b Bits) Megabytes() float64

Megabytes returns the size as a floating point number of megabytes.

func (Bits) String

func (b Bits) String() string

String returns a string representation of b using the largest unit that has a positive number before the decimal. At most three decimal places of precision are printed.

type NullString

type NullString struct {
	Valid  bool
	String string
}

A NullString is a String that may be null. It can be encoded or decoded from JSON or the database.

Example
n := NullString{Valid: true, String: "foo"}
json.NewEncoder(os.Stdout).Encode(n)
Output:

"foo"

func (NullString) MarshalJSON

func (ns NullString) MarshalJSON() ([]byte, error)

func (*NullString) Scan

func (ns *NullString) Scan(value interface{}) error

Scan implements the Scanner interface.

func (*NullString) UnmarshalJSON

func (ns *NullString) UnmarshalJSON(b []byte) error

func (NullString) Value

func (ns NullString) Value() (driver.Value, error)

Value implements the driver Valuer interface.

type NullTime

type NullTime struct {
	Valid bool
	Time  time.Time
}

A NullTime is a Time that may be null. It can be encoded or decoded from JSON or the database.

Example
t, _ := time.Parse(time.RFC3339, "2016-05-02T09:03:04-07:00")
nt := NullTime{Valid: true, Time: t}
json.NewEncoder(os.Stdout).Encode(nt)
Output:

"2016-05-02T09:03:04-07:00"

func (NullTime) MarshalJSON

func (nt NullTime) MarshalJSON() ([]byte, error)

func (*NullTime) Scan

func (nt *NullTime) Scan(value interface{}) error

Scan implements the Scanner interface.

func (*NullTime) UnmarshalJSON

func (nt *NullTime) UnmarshalJSON(b []byte) error

func (NullTime) Value

func (nt NullTime) Value() (driver.Value, error)

Value implements the driver Valuer interface.

type PrefixUUID

type PrefixUUID struct {
	Prefix string
	UUID   uuid.UUID
}

A PrefixUUID stores an additional prefix as part of a UUID type.

Example
p, _ := NewPrefixUUID("usr_6740b44e-13b9-475d-af06-979627e0e0d6")
fmt.Println(p.Prefix)
fmt.Println(p.UUID.String())
fmt.Println(p.String())
Output:

usr_
6740b44e-13b9-475d-af06-979627e0e0d6
usr_6740b44e-13b9-475d-af06-979627e0e0d6

func GenerateUUID

func GenerateUUID(prefix string) PrefixUUID

GenerateUUID generates a UUID with the given prefix.

func NewPrefixUUID

func NewPrefixUUID(caboodle string) (PrefixUUID, error)

NewPrefixUUID creates a PrefixUUID from the prefix and string uuid. Returns an error if uuidstr cannot be parsed as a valid UUID.

func (PrefixUUID) MarshalJSON

func (pu PrefixUUID) MarshalJSON() ([]byte, error)

func (*PrefixUUID) Scan

func (pu *PrefixUUID) Scan(value interface{}) error

Scan implements the Scanner interface. Note only the UUID gets scanned/set here, we can't determine the prefix from the database. `value` should be a [16]byte

func (PrefixUUID) String

func (u PrefixUUID) String() string

func (*PrefixUUID) UnmarshalJSON

func (pu *PrefixUUID) UnmarshalJSON(b []byte) error

func (PrefixUUID) Value

func (pu PrefixUUID) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL