jutil

README

jutil

Note
Segment has paused maintenance on this project, but may return it to an active status in the future. Issues and pull requests from external contributors are not being considered, although internal contributions may appear from time to time. The project remains available under its open source license for anyone to use.

Go package providing utilities for dealing with JSON content that are missing from the standard library.

Documentation

Index

• func Escape(b []byte) []byte
• func EscapeString(s string) string
• func IsEmptyValue(v interface{}) bool
• func Length(v interface{}) (n int, err error)
• func Quote(b []byte) []byte
• func QuoteString(s string) string
• func WriteEscaped(w io.Writer, b []byte) (n int, err error)
• func WriteQuoted(w io.Writer, b []byte) (n int, err error)
• type Lengther
• type Struct
  • func LookupStruct(t reflect.Type) Struct
  • func MakeStruct(t reflect.Type) Struct
• type StructCache
  • func NewStructCache() *StructCache
  • func (cache *StructCache) Lookup(t reflect.Type) (s Struct)
• type StructField
  • func MakeStructField(f reflect.StructField) StructField
• type Tag
  • func ParseStructField(f reflect.StructField) Tag
  • func ParseTag(tag string) Tag

Functions

func Escape

func Escape(b []byte) []byte

Escape takes a byte slice as argument and returns the copy of that slice where every special characters have been escaped according to the JSON formatting rules.

func EscapeString

func EscapeString(s string) string

EscapeString takes a string as argument and returns the version of that string where every special characters have been escaped according to the JSON formatting rules.

func IsEmptyValue

func IsEmptyValue(v interface{}) bool

IsEmptyValue returns true if the value given as argument would be considered empty by the standard json package, and therefore not serialized if `omitempty` is set on a struct field with this value.

func Length

func Length(v interface{}) (n int, err error)

Length computes the length of the JSON representation of a value of arbitrary type, it's ~10x faster than serializing the content with the standard json package and avoid the extra memory allocations.

func Quote

func Quote(b []byte) []byte

Quote takes a byte slice as argument and returns the copy of that slice quoted according to the JSON formatting rules.

func QuoteString

func QuoteString(s string) string

QuoteString takes a string as argument and returns the version of that string quoted according to the JSON formatting rules.

func WriteEscaped

func WriteEscaped(w io.Writer, b []byte) (n int, err error)

WriteEscaped outputs a byte slice into an io.Writer where every special character has been escaped according to the JSON formatting rules.

func WriteQuoted

func WriteQuoted(w io.Writer, b []byte) (n int, err error)

WriteQuoted outputs a byte slice into an io.Writer, quoted according to the JSON formatting rules.

Types

type Lengther

type Lengther interface {
	// LengthJSON returns the length of the value once serialized to JSON.
	LengthJSON() int
}

Lengther can be implemented by a value to override the default length deduction algorithm implemented by Length.

type Struct

type Struct []StructField

Struct is used to represent a Go structure in internal data structures that cache meta information to make field lookups faster and avoid having to use reflection to lookup the same type information over and over again.

func LookupStruct

func LookupStruct(t reflect.Type) Struct

LookupStruct behaves like MakeStruct but uses a global cache to avoid having to recreate the struct values when not needed.

As much as possible you should be using this function instead of calling MakeStruct or maintaining your own cache so the program can efficiently make use of the cache and avoid storing duplicate information in different parts of the program.

func MakeStruct

func MakeStruct(t reflect.Type) Struct

MakeStruct takes a Go type as argument and extract information to make a new Struct value. The type has to be a struct type or a panic will be raised.

type StructCache

type StructCache struct {
	// contains filtered or unexported fields
}

StructCache is a simple cache for mapping Go types to Struct values.

func NewStructCache

func NewStructCache() *StructCache

NewStructCache creates and returns a new StructCache value.

func (*StructCache) Lookup

func (cache *StructCache) Lookup(t reflect.Type) (s Struct)

Lookup takes a Go type as argument and returns the matching Struct value, potentially creating it if it didn't already exist. This method is safe to call from multiple goroutines.

type StructField

type StructField struct {
	// The index of the field in the structure.
	Index []int

	// The name of the field once serialized to JSON.
	Name string

	// True if the field has to be omitted when it has an empty value.
	Omitempty bool

	// True if the field should be skipped entirely.
	Skip bool
}

StructField represents a single field of a struct and carries information useful to the algorithms of the jutil package.

func MakeStructField

func MakeStructField(f reflect.StructField) StructField

MakeStructField takes a Go struct field as argument argument and returns its StructType representation.

type Tag

type Tag struct {
	// Name is the field name that should be used when serializing JSON.
	Name string

	// Omitempty is true if the struct field json tag had `omitempty` set.
	Omitempty bool

	// Skip is true if the struct field json tag started with `-`.
	Skip bool
}

Tag represents the result of parsing the json tag of a struct field.

func ParseStructField

func ParseStructField(f reflect.StructField) Tag

ParseStructField parses the tag of a struct field that may or may not have a `json` tag set, returing the result as a Tag field.

func ParseTag

func ParseTag(tag string) Tag

ParseTag parses a raw json tag obtained from a struct field, returining the results as a Tag value.