vector

package module
v1.2.9 Latest Latest
Warning

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

 Go to latest Published: Jan 2, 2026 License: MIT Imports: 18 Imported by: 13

README

Vector API

Provide Vector API for vector parsers.

The main idea: popular data interchange formats (such as JSON, XML, ...) stores data as a tree. Parsers of that formats reproduces that tree in a memory somehow or other. This makes a lot of pointers in the heap and GC does a lot of work during marking. Moreover, each of them makes a copy of source data, it's often is redundant.

This parser uses different way: it stores all parsed nodes (key-value pairs) in a special array (vector). Instead of pointers to child nodes, each node stores adjacency list of indices of childs. In fact (to reduce pointers) node stores not an array of indices, but offset/length of child indices in special struct calls Index (see picture #2 below).

Thus, the main purpose of the whole project is minimizing of pointers and thereby cut the costs of GC work. An additional purpose is a memory economy.

Let's check difference of that approaches on example. Source document:

{
  "a":{"c":"foobar","d":3.1415},
  "b":["asdfgh","zxcvb"]
}

Typical parser will make a tree in memory like this:

NOTE: Each arrow represents a pointer, same as each non-empty string in nodes.

, each node will an instance of struct like this:

type Node struct {
	typ Type    // [null, object, array, string, number, true, false]
	obj Object  // one pointer to slice and N*2 pointers inside KeyValue struct, see below
	arr []*Node // one pointer for the slice and N pointers for each array item
	str string  // one pointer
}

type Object []KeyValue

type KeyValue struct {
	key string // one pointer
	val *Node  // one pointer to node
}

That way produces a too many pointers and on complex source document that count will grow even more.

Vector in memory will look like:

NOTE: In opposite to previous picture, arrows represents not a pointers, but integer indices.

Looks redundant and strange, isn't it? But that way allow for any type of source document produces constant number of pointers:

  • one for array of nodes
  • one for index
  • one for each row in index

Of course, this advantage has a cost - writing new parser using vector API is a hard challenge. Also, debug of vector instance is non-trivial, due to debugger shows not a data (e.g strings), but offset/length of data in arrays outside.

API

Parsing

Vector API provides four methods to parsing:

func (Vector) Parse([]byte) error
func (Vector) ParseCopy([]byte) error
func (Vector) ParseString(string) error
func (Vector) ParseCopyString(string) error

Copy-versions allow to make a copy of source data explicitly. By default, vector not makes a copy and nodes "points" to memory outside of vector. It's a developer responsibility to extend a life of a source data at least the same as vector's life. If it's impossible, the better way is to use a copy-methods.

The exclusive feature of vector is a possibility to parse many source documents using one vector instance:

vec.ParseString(`{"a":{"b":{"c":"foobar"}}}`)
vec.ParseString(`{"x":{"y":{"z":"asdfgh"}}}`)
s0 := vec.RootByIndex(0).DotString("a.b.c")
s1 := vec.RootByIndex(1).DotString("x.y.z")
println(s0, s1) // foobar asdfgh

Thus, vector minimizes pointers count on multiple source data as if parse only one source document.

Reading

The basic reading methods:

func (Vector) Get(path ...string) *Node
func (Vector) GetObject(path ...string) *Node
func (Vector) GetArray(path ...string) *Node
func (Vector) GetBytes(path ...string) []byte
func (Vector) GetString(path ...string) string
func (Vector) GetBool(path ...string) bool
func (Vector) GetFloat(path ...string) (float64, error)
func (Vector) GetInt(path ...string) (int64, error)
func (Vector) GetUint(path ...string) (uint64, error)

They take a variadic path to field you require to read. Methods with exact types (GetInt, GetBool, ...) additionally check a type of fields in source documents.

Vector API allows avoiding variadic usage using path with separator:

func (Vector) GetPS(path, separator string) *Node
func (Vector) GetObjectPS(path, separator string) *Node
func (Vector) GetArrayPS(path, separator string) *Node
func (Vector) GetBytesPS(path, separator string) []byte
func (Vector) GetStringPS(path, separator string) string
func (Vector) GetBoolPS(path, separator string) bool
func (Vector) GetFloatPS(path, separator string) (float64, error)
func (Vector) GetIntPS(path, separator string) (int64, error)
func (Vector) GetUintPS(path, separator string) (uint64, error)

Example:

vec.ParseString(`{"a":{"b":{"c":"foobar"}}}`)
s := vec.GetStringPS("a.b.c", ".")
println(s) // foobar

Due to most popular separator is a dot (".") there are special alias-methods:

func (Vector) Dot(path string) *Node
func (Vector) DotObject(path string) *Node
func (Vector) DotArray(path string) *Node
func (Vector) DotBytes(path string) []byte
func (Vector) DotString(path string) string
func (Vector) DotBool(path string) bool
func (Vector) DotFloat(path string) (float64, error)
func (Vector) DotInt(path string) (int64, error)
func (Vector) DotUint(path string) (uint64, error)

Example:

vec.ParseString(`{"a":{"b":{"c":"foobar"}}}`)
s := vec.DotString("a.b.c")
println(s) // foobar
Serialization

Vector API allows to do the opposite operation - compose original document from parsed data:

func (Vector) Beautify(writer io.Writer) error
func (Vector) Marshal(writer io.Writer) error

Beautify method writer to writer a human-readable view of the document, Marshal - minimized version.

Error handling

vector may return an error during parsing. The error may be impersonal, like "unexpected identifier" and provides no information about the exact position in the document where error occurred. The following method may help in that case:

func (Vector) ErrorOffset() int
Iterating

If vector was used to parse more than one document, you may iterate them avoiding use of RootByIndex method:

func (Vector) Each(fn func(index int, node *Node))

Example:

vec.ParseString(`{"a":{"b":{"c":"foobar"}}}`)
vec.ParseString(`{"x":{"y":{"z":"asdfgh"}}}`)
vec.Each(func(i int, node *Node) {
	node.Get("...")
})

node API

Reading

Similar to vector API, there are three groups of methods in node API:

  • Get-methods
  • GetPS-methods
  • Dot-methods

In addition, node can return key/value separately as Byteptr object:

func (Node) Key() *Byteptr
func (Node) Value() *Byteptr

or directly convert them to exact types:

// key
func (Node) KeyBytes() []byte
func (Node) KeyString() string
// value
func (Node) Bytes() []byte
func (Node) ForceBytes() []byte
func (Node) RawBytes() []byte
func (Node) String() string
func (Node) ForceString()
func (Node) Bool() bool
func (Node) Float() (float64, error)
func (Node) Int() (int64, error)
func (Node) Uint() (uint64, error)
func (Node) Object() *Node
func (Node) Array() *Node

func (Node) Type() Type
func (Node) Exists(key string) bool
Iterating

If node has a type array or object, you may iterate through children nodes:

func (Node) Each(fn func(index int, node *Node))
Sorting

Nodes of type array or object may be sorted by keys or values:

func (Node) SortKeys() *Node // by keys
func (Node) Sort() *Node     // by values
Removing

Node API supports predicating deletion:

func (Node) RemoveIf(cond func(index int, node *Node) bool)
Child nodes access
func (Node) Children() []Node
func (Node) ChildrenIndices() []int
Serialization

Serialization is similar to vector API, but allows serializing only current node and its childrens (recursively):

func (Node) Beautify(writer io.Writer) error
func (Node) Marshal(writer io.Writer) error

Thus, you may serialize not the whole object, but only necessary part of it.

Helper

The important part of the API. It must realize the interface:

type Helper interface {
	Indirect(ptr *Byteptr) []byte        // in-place unescape
	Beautify(writer io.Writer, node *Node) error
	Marshal(writer io.Writer, node *Node) error 
}

Since vector API is a common API for parsers, the concrete realization if that interface provides support for concrete data formats (JSON, XML, ...).

Note: unescaping (indirect) is happening in-place, not additional memory required.

Pooling

Vector was implemented as high-load solution by design and therefore requires pooling to use:

vec := jsonvector.Acquire()
defer jsonvector.Release(vec)
// or
vec := xmlvector.Acquire()
defer xmlvector.Release(vec)
// ...

Vector package doesn't provide pooling (because it is a common API), but high level packages provides Acquire/Release methods (working with sync.Pool implicitly).

In fact, you may use vectors not exactly in high-loaded project. In that case pooling may be omitted:

vec := jsonvector.NewVector()
// or
vec := xmlvector.NewVector()
// ...

Performance

There are versus-projects for each of the existing vector parsers:

The most interesting is jsonvector, due to worthy opponents. Thus, let's focus on jsonvector.

Testing dataset
Testing stages

All stages works on Ubuntu 22.04, Go version 1.22.

Competitors
The result

Server CPU Xeon 4214 is the most interested due to its closeness to production conditions:

sec/op:
DS/lib fastjson jsonvector simdjson
small.json 31.61n ± 10% 30.21n ± 7% 162.2n ± 7%
medium.json 214.0n ± 9% 221.7n ± 2% 590.9n ± 8%
large.json 2.452µ ± 1% 3.168µ ± 2% 5.910µ ± 14%
canada.json 1.087m ± 3% 1.253m ± 0% 948.1µ ± 1%
citm.json 375.2µ ± 1% 280.6µ ± 1% 212.0µ ± 4%
twitter.json 101.88µ ± 3% 80.80µ ± 1% 114.8µ ± 10%
B/s
DS/lib fastjson jsonvector simdjson
small.json 5.598Gi ± 11% 5.858Gi ± 8% 1.091Gi ± 6%
medium.json 10.14Gi ± 10% 9.784Gi ± 2% 3.671Gi ± 8%
large.json 10.68Gi ± 1% 8.267Gi ± 2% 4.431Gi ± 13%
canada.json 1.928Gi ± 3% 1713.4Mi ± 0% 2.211Gi ± 1%
citm.json 4.287Gi ± 1% 5.732Gi ± 1% 7.587Gi ± 4%
twitter.json 5.773Gi ± 3% 7.279Gi ± 1% 5.124Gi ± 9%

Results are similar to each other, and this is a good achievement for vector, because the main advantage of vector - long work outside of synthetic tests and optimizations for pointers. The similar speed is an extra bonus.

Documentation

Index

Constants

View Source 
const (
	// FlagInit points vector is properly initialized.
	FlagInit = iota
	// FlagNoClear disables clear step.
	FlagNoClear
	// FlagExtraBool enables YAML style bool check [On, Off] in addition to [true, false].
	FlagExtraBool
)

Variables

View Source 
var (
	ErrEmptySrc     = errors.New("can't parse empty source")
	ErrShortSrc     = errors.New("source is too short to parse")
	ErrNotImplement = errors.New("method not implemented")
	ErrIncompatType = errors.New("incompatible type")
	ErrNotFound     = errors.New("node not found")
	ErrInternal     = errors.New("internal vector error")
	ErrNoHelper     = errors.New("helper not found")
	ErrUnparsedTail = errors.New("unparsed tail")
	ErrUnexpId      = errors.New("unexpected identifier")
	ErrUnexpEOF     = errors.New("unexpected end of file")
	ErrUnexpEOS     = errors.New("unexpected end of string")
)

Functions

func IndexByte added in v1.2.8 

func IndexByte(s []byte, b byte) int

IndexByte returns position of b in s. Return -1 if not found.

func IndexByteAt added in v1.2.8 

func IndexByteAt(s []byte, b byte, at int) int

IndexByteAt returns position of b in s starting from position at. Return -1 if not found.

func IndexByteAtNE added in v1.2.8 

func IndexByteAtNE(s []byte, b byte, at int) int

IndexByteAtNE returns position of non-escaped b in s from position at. Return -1 if not found.

func IndexByteNE added in v1.2.8 

func IndexByteNE(s []byte, b byte) int

IndexByteNE returns position of non-escaped b in s. Return -1 if not found.

Types

type Byteptr 

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

func (*Byteptr) Bytes 

func (p *Byteptr) Bytes() []byte

func (*Byteptr) CheckBit added in v1.2.5 

func (p *Byteptr) CheckBit(pos int) bool

func (*Byteptr) Init added in v1.2.5 

func (p *Byteptr) Init(s []byte, offset, len int) *Byteptr

func (*Byteptr) InitRaw added in v1.2.5 

func (p *Byteptr) InitRaw(addr uintptr, offset, len int) *Byteptr

func (*Byteptr) InitStr added in v1.2.5 

func (p *Byteptr) InitStr(s string, offset, len int) *Byteptr

DEPRECATED: use InitString instead.

func (*Byteptr) InitString added in v1.2.5 

func (p *Byteptr) InitString(s string, offset, len int) *Byteptr

func (*Byteptr) Len added in v1.2.5 

func (p *Byteptr) Len() int

func (*Byteptr) Offset added in v1.2.5 

func (p *Byteptr) Offset() int

func (*Byteptr) RawBytes 

func (p *Byteptr) RawBytes() []byte

func (*Byteptr) RawString added in v1.2.5 

func (p *Byteptr) RawString() string

func (*Byteptr) Reset 

func (p *Byteptr) Reset()

func (*Byteptr) SetAddr added in v1.2.5 

func (p *Byteptr) SetAddr(addr uintptr, cap int) *Byteptr

func (*Byteptr) SetBit added in v1.2.5 

func (p *Byteptr) SetBit(pos int, value bool)

func (*Byteptr) SetLen added in v1.2.5 

func (p *Byteptr) SetLen(len int) *Byteptr

func (*Byteptr) SetOffset added in v1.2.5 

func (p *Byteptr) SetOffset(offset int) *Byteptr

func (*Byteptr) String 

func (p *Byteptr) String() string

func (*Byteptr) TakeAddr added in v1.2.5 

func (p *Byteptr) TakeAddr(s []byte) *Byteptr

func (*Byteptr) TakeStrAddr added in v1.2.5 

func (p *Byteptr) TakeStrAddr(s string) *Byteptr

DEPRECATED: use TakeStringAddr instead.

func (*Byteptr) TakeStringAddr added in v1.2.5 

func (p *Byteptr) TakeStringAddr(s string) *Byteptr

type Helper 

type Helper interface {
	// Indirect convert byteptr to byte slice and apply custom logic.
	Indirect(*Byteptr) []byte
	// Beautify makes a beauty view of node.
	Beautify(io.Writer, *Node) error
	// Marshal serializes node.
	Marshal(io.Writer, *Node) error
}

Helper object interface.

type Index 

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

Index represents nodes index matrix.

Contain indexes of nodes in the vector divided by depth. Y-axis means depth, X-axis means position in index.

func (*Index) GetRow 

func (idx *Index) GetRow(depth int) []int

GetRow returns indices row registered at given depth.

func (*Index) Len 

func (idx *Index) Len(depth int) int

Len returns length of index row registered on depth.

func (*Index) Register 

func (idx *Index) Register(depth, i int) int

Register new index for given depth.

func (*Index) Reset 

func (idx *Index) Reset(depth, offset int)

Reset rest of the index starting of given depth and offset in the tree.

type Interface 

type Interface interface {
	// SetHelper provides Helper to escape/unescape strings.
	SetHelper(helper Helper)

	// Parse parses source bytes.
	Parse(source []byte) error
	// ParseCopy makes a copy of source bytes and parse it.
	ParseCopy(source []byte) error
	// ParseString parses source string.
	// Note, string parsing may be unsafe due to in-place unescape issues. Use ParseCopyString or Parse in that case.
	ParseString(source string) error
	// ParseCopyString makes a copy of string and parse it.
	// This method is safe to parse immutable strings.
	ParseCopyString(source string) error
	// ParseStr is a legacy version of ParseString.
	// DEPRECATED: use ParseString instead.
	ParseStr(source string) error
	// ParseCopyStr is a legacy version of ParseCopyString.
	// DEPRECATED: use ParseCopyString instead.
	ParseCopyStr(source string) error
	// ParseFile reads file contents and parse it.
	ParseFile(path string) error
	// ParseReader takes source from r and parse it.
	ParseReader(r io.Reader) error

	// Root returns first root node.
	Root() *Node
	// RootByIndex returns root node by given index. If index overflows count of root nodes, the NULL node will return.
	RootByIndex(idx int) *Node
	// RootTop returns last root node.
	RootTop() *Node
	// Each applies closure to each root node.
	Each(fn func(idx int, fn *Node))
	// Exists checks if root node contains a child with given key.
	// The NULL node will return if node doesn't exist.
	Exists(key string) bool

	// Get returns node by given keys.
	Get(keys ...string) *Node
	// GetObject looks and get object node by given keys.
	GetObject(keys ...string) *Node
	// GetArray looks and get array node by given keys.
	GetArray(keys ...string) *Node
	// GetBytes looks and get bytes value by given keys.
	GetBytes(keys ...string) []byte
	// GetString looks and get string value by given keys.
	GetString(keys ...string) string
	// GetBool looks and get bool value by given keys.
	GetBool(keys ...string) bool
	// GetFloat looks and get float value by given keys.
	GetFloat(keys ...string) (float64, error)
	// GetInt looks and get integer value by given keys.
	GetInt(keys ...string) (int64, error)
	// GetUint looks and get unsigned integer value by given keys.
	GetUint(keys ...string) (uint64, error)

	// GetPS returns node by given path and separator.
	GetPS(path, separator string) *Node
	// GetObjectPS looks and get object node by given path and separator.
	GetObjectPS(path, separator string) *Node
	// GetArrayPS looks and get array node by given path and separator.
	GetArrayPS(path, separator string) *Node
	// GetBytesPS looks and get bytes value by given path and separator.
	GetBytesPS(path, separator string) []byte
	// GetStringPS looks and get string value by given path and separator.
	GetStringPS(path, separator string) string
	// GetBoolPS looks and get bool value by given path and separator.
	GetBoolPS(path, separator string) bool
	// GetFloatPS looks and get float value by given path and separator.
	GetFloatPS(path, separator string) (float64, error)
	// GetIntPS looks and get integer value by given path and separator.
	GetIntPS(path, separator string) (int64, error)
	// GetUintPS looks and get unsigned integer value by given path and separator.
	GetUintPS(path, separator string) (uint64, error)

	// Dot looks and get node by given path and "." separator.
	Dot(path string) *Node
	// DotObject looks and get object node by given path and "." separator.
	DotObject(path string) *Node
	// DotArray looks and get array node by given path and "." separator.
	DotArray(path string) *Node
	// DotBytes looks and get bytes value by given path and "." separator.
	DotBytes(path string) []byte
	// DotString looks and get string value by given path and "." separator.
	DotString(path string) string
	// DotBool looks and get bool value by given path and "." separator.
	DotBool(path string) bool
	// DotFloat looks and get float value by given path and "." separator.
	DotFloat(path string) (float64, error)
	// DotInt looks and get integer value by given path and "." separator.
	DotInt(path string) (int64, error)
	// DotUint looks and get unsigned integer value by given path and "." separator.
	DotUint(path string) (uint64, error)

	// KeepPtr guarantees that vector object wouldn't be collected by GC.
	KeepPtr()

	// Beautify formats first root node in human-readable representation to w.
	Beautify(w io.Writer) error
	// Marshal serializes first root node to w.
	Marshal(w io.Writer) error

	// ErrorOffset returns last error offset.
	ErrorOffset() int
	// Prealloc prepares space for further parse.
	Prealloc(size uint)
	// Reset vector data.
	Reset()
}

type Node 

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

Node object.

func (*Node) AcquireChild added in v1.2.7 

func (n *Node) AcquireChild(depth int) (*Node, int)

AcquireChild allocates new child of current node and return it with index.

func (*Node) AcquireChildWithType added in v1.2.7 

func (n *Node) AcquireChildWithType(depth int, typ Type) (*Node, int)

AcquireChildWithType allocates new child of current node, set the type at once and return it with index.

func (*Node) AliasOf added in v1.2.7 

func (n *Node) AliasOf(node *Node) *Node

AliasOf registers given node as alias of n.

func (*Node) Array 

func (n *Node) Array() *Node

Array checks node is array and return it.

func (*Node) At 

func (n *Node) At(idx int) *Node

At returns node from array at position idx.

May be used only for array nodes.

func (*Node) Beautify 

func (n *Node) Beautify(w io.Writer) error

Beautify formats node in human-readable representation.

func (*Node) Bool 

func (n *Node) Bool() bool

Bool returns value as boolean.

func (*Node) Bytes 

func (n *Node) Bytes() []byte

Bytes returns value as bytes.

Allow only for [string, number, bool, attribute] types.

func (*Node) Children 

func (n *Node) Children() []Node

Children returns list of children nodes.

func (*Node) ChildrenIndices added in v1.2.3 

func (n *Node) ChildrenIndices() []int

ChildrenIndices returns list of indices of children nodes.

func (*Node) Depth 

func (n *Node) Depth() int

Depth returns node depth in index matrix.

func (*Node) Dot 

func (n *Node) Dot(path string) *Node

Dot looks and get child node by given path and "." separator.

func (*Node) DotArray 

func (n *Node) DotArray(path string) *Node

DotArray looks and get child array by given path and "." separator.

func (*Node) DotBool 

func (n *Node) DotBool(path string) bool

DotBool looks and get child bool by given path and "." separator.

func (*Node) DotBytes 

func (n *Node) DotBytes(path string) []byte

DotBytes looks and get child bytes by given path and "." separator.

func (*Node) DotFloat 

func (n *Node) DotFloat(path string) (float64, error)

DotFloat looks and get child float by given path and "." separator.

func (*Node) DotInt 

func (n *Node) DotInt(path string) (int64, error)

DotInt looks and get child integer by given path and "." separator.

func (*Node) DotObject 

func (n *Node) DotObject(path string) *Node

DotObject looks and get child object by given path and "." separator.

func (*Node) DotString 

func (n *Node) DotString(path string) string

DotString looks and get child string by given path and "." separator.

func (*Node) DotUint 

func (n *Node) DotUint(path string) (uint64, error)

DotUint looks and get child unsigned int by given path and "." separator.

func (*Node) Each 

func (n *Node) Each(fn func(idx int, node *Node))

Each applies custom function to each child of the node.

func (*Node) EqualWith added in v1.2.3 

func (n *Node) EqualWith(exp *Node) bool

EqualWith compares node with exp.

func (*Node) Exists 

func (n *Node) Exists(key string) bool

Exists checks if given key exists in the node.

func (*Node) FirstChild added in v1.2.7 

func (n *Node) FirstChild() *Node

FirstChild returns first child node of node n. If node has no childs then non-empty null will return.

func (*Node) Float 

func (n *Node) Float() (float64, error)

Float returns value as float number.

func (*Node) ForceBytes 

func (n *Node) ForceBytes() []byte

ForceBytes returns value as bytes independent of the type.

func (*Node) ForceString 

func (n *Node) ForceString() string

ForceString returns value as string independent of the type.

func (*Node) Get 

func (n *Node) Get(keys ...string) *Node

Get returns child node by given keys.

func (*Node) GetArray 

func (n *Node) GetArray(keys ...string) *Node

GetArray looks and get child array by given keys.

func (*Node) GetArrayPS 

func (n *Node) GetArrayPS(path, separator string) *Node

GetArrayPS looks and get child array by given path and separator.

func (*Node) GetBool 

func (n *Node) GetBool(keys ...string) bool

GetBool looks and get child bool by given keys.

func (*Node) GetBoolPS 

func (n *Node) GetBoolPS(path, separator string) bool

GetBoolPS looks and get child bool by given path and separator.

func (*Node) GetBytes 

func (n *Node) GetBytes(keys ...string) []byte

GetBytes looks and get child bytes by given keys.

func (*Node) GetBytesPS 

func (n *Node) GetBytesPS(path, separator string) []byte

GetBytesPS looks and get child bytes by given path and separator.

func (*Node) GetFloat 

func (n *Node) GetFloat(keys ...string) (float64, error)

GetFloat looks and get child float by given keys.

func (*Node) GetFloatPS 

func (n *Node) GetFloatPS(path, separator string) (float64, error)

GetFloatPS looks and get child float by given path and separator.

func (*Node) GetInt 

func (n *Node) GetInt(keys ...string) (int64, error)

GetInt looks and get child integer by given keys.

func (*Node) GetIntPS 

func (n *Node) GetIntPS(path, separator string) (int64, error)

GetIntPS looks and get child integer by given path and separator.

func (*Node) GetObject 

func (n *Node) GetObject(keys ...string) *Node

GetObject looks and get child object by given keys.

func (*Node) GetObjectPS 

func (n *Node) GetObjectPS(path, separator string) *Node

GetObjectPS looks and get child object by given path and separator.

func (*Node) GetPS 

func (n *Node) GetPS(path, separator string) *Node

GetPS returns child node by path and separator.

func (*Node) GetString 

func (n *Node) GetString(keys ...string) string

GetString looks and get child string by given keys.

func (*Node) GetStringPS 

func (n *Node) GetStringPS(path, separator string) string

GetStringPS looks and get child string by given path and separator.

func (*Node) GetUint 

func (n *Node) GetUint(keys ...string) (uint64, error)

GetUint looks and get child unsigned integer by given keys.

func (*Node) GetUintPS 

func (n *Node) GetUintPS(path, separator string) (uint64, error)

GetUintPS looks and get child unsigned int by given path and separator.

func (*Node) Index 

func (n *Node) Index() int

Index returns node index in the array of nodes.

func (*Node) Int 

func (n *Node) Int() (int64, error)

Int returns value as integer.

func (*Node) Key 

func (n *Node) Key() *Byteptr

Key returns key as byteptr object.

func (*Node) KeyBytes 

func (n *Node) KeyBytes() []byte

KeyBytes returns key as bytes.

func (*Node) KeyString 

func (n *Node) KeyString() string

KeyString returns key as string.

func (*Node) LastChild added in v1.2.7 

func (n *Node) LastChild() *Node

LastChild returns last child node of node n. If node has no childs then non-empty null will return.

func (*Node) Limit 

func (n *Node) Limit() int

Limit returns limit of childs in index row.

func (*Node) Look 

func (n *Node) Look(key string) *Node

Look for the child node by given key.

May be used only for object nodes.

func (*Node) Marshal added in v1.2.4 

func (n *Node) Marshal(w io.Writer) error

Marshal serializes node.

func (*Node) Object 

func (n *Node) Object() *Node

Object checks node is object and return it.

func (*Node) Offset 

func (n *Node) Offset() int

Offset returns offset of childs in the index row.

func (*Node) RawBytes 

func (n *Node) RawBytes() []byte

RawBytes returns value as bytes without implement any conversion logic.

func (*Node) ReleaseChild added in v1.2.7 

func (n *Node) ReleaseChild(idx int, node *Node) *Node

ReleaseChild return node back to vector ownes current node.

func (*Node) RemoveIf added in v1.2.3 

func (n *Node) RemoveIf(cond func(idx int, node *Node) bool)

RemoveIf deletes all children nodes satisfies condition cond.

func (*Node) Reset 

func (n *Node) Reset() *Node

Reset the node.

func (*Node) SetLimit 

func (n *Node) SetLimit(limit int) *Node

SetLimit sets limit of childs in index row.

func (*Node) SetOffset 

func (n *Node) SetOffset(offset int) *Node

SetOffset sets offset in the index row.

func (*Node) SetType 

func (n *Node) SetType(typ Type)

SetType sets type of the node.

func (*Node) Sort 

func (n *Node) Sort() *Node

Sort sorts child nodes by value in AB order.

func (*Node) SortKeys 

func (n *Node) SortKeys() *Node

SortKeys sorts child nodes by key in AB order.

func (*Node) String 

func (n *Node) String() string

Get value as string.

Allow only for [string, number, bool, attribute] types.

func (*Node) SwapWith 

func (n *Node) SwapWith(node *Node)

SwapWith swaps node with another given node in the nodes array.

func (*Node) Type 

func (n *Node) Type() Type

Type returns node type.

func (*Node) Uint 

func (n *Node) Uint() (uint64, error)

Uint returns value as unsigned integer.

func (*Node) Value 

func (n *Node) Value() *Byteptr

Value returns value as byteptr object.

type Type 

type Type int

Type represents Node type. 

const (
	TypeUnknown Type = iota
	TypeNull
	TypeObject
	TypeArray
	TypeString
	TypeNumber
	TypeBool
	TypeAttribute
	TypeAlias
)
const (
	// TypeUnk is a legacy version of TypeUnknown.
	// DEPRECATED: use TypeUnknown instead.
	TypeUnk Type = 0
	// TypeObj is a legacy version of TypeObject.
	// DEPRECATED: use TypeObject instead.
	TypeObj Type = 1
	// TypeArr is a legacy version of TypeArray.
	// DEPRECATED: use TypeArray instead.
	TypeArr Type = 3
	// TypeStr is a legacy version of TypeString.
	// DEPRECATED: use TypeString instead.
	TypeStr Type = 4
	// TypeNum is a legacy version of TypeNumber.
	// DEPRECATED: use TypeNumber instead.
	TypeNum Type = 5
	// TypeAttr is a legacy version of TypeAttribute.
	// DEPRECATED: use TypeAttribute instead.
	TypeAttr Type = 7
)

Legacy types.

type Vector 

type Vector struct {
	bitset.Bitset

	// Nodes index.
	Index Index
	// External helper object.
	Helper Helper
	// contains filtered or unexported fields
}

Vector parser object.

func (*Vector) AcquireChild added in v1.2.7 

func (vec *Vector) AcquireChild(root *Node, depth int) (*Node, int)

AcquireChild allocates new node and marks it as a child of root node.

Similar to AcquireNode.

func (*Vector) AcquireChildWithType added in v1.2.7 

func (vec *Vector) AcquireChildWithType(root *Node, depth int, typ Type) (*Node, int)

AcquireChildWithType allocates new node, mark it as child of root and set type at once.

func (*Vector) AcquireNode added in v1.2.7 

func (vec *Vector) AcquireNode(depth int) (node *Node, idx int)

AcquireNode allocates new node on given depth and returns it with index.

func (*Vector) AcquireNodeWithType added in v1.2.7 

func (vec *Vector) AcquireNodeWithType(depth int, typ Type) (*Node, int)

AcquireNodeWithType allocates new node on given depth and returns it with index. Similar to AcquireNode but sets node's type at once.

func (*Vector) Beautify 

func (vec *Vector) Beautify(w io.Writer) error

Beautify formats first root node in human-readable representation.

Second and next roots must beautify manually by call Beautify method of each node.

func (*Vector) Buf 

func (vec *Vector) Buf() []byte

Buf returns raw buffer bytes.

func (*Vector) BufAppend 

func (vec *Vector) BufAppend(s []byte)

BufAppend is a legacy version of Bufferize. DEPRECATED: use Bufferize instead.

func (*Vector) BufAppendByte 

func (vec *Vector) BufAppendByte(b byte)

BufAppendByte is a legacy version of BufferizeByte. DEPRECATED: use BufferizeByte instead.

func (*Vector) BufAppendFloat 

func (vec *Vector) BufAppendFloat(f float64)

BufAppendFloat is a legacy version of BufferizeFloat. DEPRECATED: use BufferizeFloat instead.

func (*Vector) BufAppendFloatTune 

func (vec *Vector) BufAppendFloatTune(f float64, fmt byte, prec, bitSize int)

BufAppendFloatTune is a legacy version of BufferizeFloatTune. DEPRECATED: use BufferizeFloatTune instead.

func (*Vector) BufAppendInt 

func (vec *Vector) BufAppendInt(i int64)

BufAppendInt is a legacy version of BufferizeInt. DEPRECATED: use BufferizeInt instead.

func (*Vector) BufAppendStr 

func (vec *Vector) BufAppendStr(s string)

BufAppendStr is a legacy version of BufferizeString. DEPRECATED: use BufferizeString instead.

func (*Vector) BufAppendUint 

func (vec *Vector) BufAppendUint(u uint64)

BufAppendUint is a legacy version of BufferizeUint. DEPRECATED: use BufferizeUint instead.

func (*Vector) BufLen 

func (vec *Vector) BufLen() int

BufLen returns length of buffer.

func (*Vector) BufReplaceWith added in v1.2.7 

func (vec *Vector) BufReplaceWith(b []byte)

BufReplaceWith replaces buffer with b. Use with caution! Buffer replacing may break copy-versions of parsing methods.

func (*Vector) BufUpdateWith 

func (vec *Vector) BufUpdateWith(b []byte)

BufUpdateWith is a legacy version of BufReplaceWith. DEPRECATED: use BufReplaceWith instead.

func (*Vector) Bufferize added in v1.2.7 

func (vec *Vector) Bufferize(b []byte) []byte

Bufferize appends b to internal buffer and returns buffered value.

func (*Vector) BufferizeByte added in v1.2.7 

func (vec *Vector) BufferizeByte(b byte) []byte

BufferizeByte appends b to internal buffer and returns buffered value.

func (*Vector) BufferizeFloat added in v1.2.7 

func (vec *Vector) BufferizeFloat(f float64) []byte

BufferizeFloat appends unsigned integer to internal buffer and returns buffered value.

func (*Vector) BufferizeFloatTune added in v1.2.7 

func (vec *Vector) BufferizeFloatTune(f float64, fmt byte, prec, bitSize int) []byte

BufferizeFloatTune appends float to internal buffer and returns buffered value.

func (*Vector) BufferizeInt added in v1.2.7 

func (vec *Vector) BufferizeInt(i int64) []byte

BufferizeInt appends integer to internal buffer and returns buffered value.

func (*Vector) BufferizeString added in v1.2.7 

func (vec *Vector) BufferizeString(s string) []byte

BufferizeString appends string to internal buffer and returns buffered value.

func (*Vector) BufferizeUint added in v1.2.7 

func (vec *Vector) BufferizeUint(u uint64) []byte

BufferizeUint appends unsigned integer to internal buffer and returns buffered value.

func (*Vector) Dot 

func (vec *Vector) Dot(path string) *Node

Dot looks and get node by given path and "." separator.

func (*Vector) DotArray 

func (vec *Vector) DotArray(path string) *Node

DotArray looks and get array by given path and "." separator.

func (*Vector) DotBool 

func (vec *Vector) DotBool(path string) bool

DotBool looks and get bool by given path and "." separator.

func (*Vector) DotBytes 

func (vec *Vector) DotBytes(path string) []byte

DotBytes looks and get bytes by given path and "." separator.

func (*Vector) DotFloat 

func (vec *Vector) DotFloat(path string) (float64, error)

DotFloat looks and get float by given path and "." separator.

func (*Vector) DotInt 

func (vec *Vector) DotInt(path string) (int64, error)

DotInt looks and get integer by given path and "." separator.

func (*Vector) DotObject 

func (vec *Vector) DotObject(path string) *Node

DotObject looks and get object by given path and "." separator.

func (*Vector) DotString 

func (vec *Vector) DotString(path string) string

DotString looks and get string by given path and "." separator.

func (*Vector) DotUint 

func (vec *Vector) DotUint(path string) (uint64, error)

DotUint looks and get unsigned integer by given path and "." separator.

func (*Vector) Each 

func (vec *Vector) Each(fn func(idx int, node *Node))

Each applies custom function to each root node.

func (*Vector) EqualWith added in v1.2.3 

func (vec *Vector) EqualWith(exp *Vector) bool

EqualWith compares vector with exp.

func (*Vector) ErrorOffset 

func (vec *Vector) ErrorOffset() int

ErrorOffset returns last error offset.

func (*Vector) Exists 

func (vec *Vector) Exists(key string) bool

Exists checks if node exists by given key.

func (*Vector) ForgetFrom 

func (vec *Vector) ForgetFrom(idx int)

ForgetFrom forgets nodes from given position to the end of the array.

func (*Vector) Get 

func (vec *Vector) Get(keys ...string) *Node

Get returns node by given keys.

func (*Vector) GetArray 

func (vec *Vector) GetArray(keys ...string) *Node

GetArray looks and get array by given keys.

func (*Vector) GetArrayPS 

func (vec *Vector) GetArrayPS(path, separator string) *Node

GetArrayPS looks and get array by given path and separator.

func (*Vector) GetBool 

func (vec *Vector) GetBool(keys ...string) bool

GetBool looks and get bool by given keys.

func (*Vector) GetBoolPS 

func (vec *Vector) GetBoolPS(path, separator string) bool

GetBoolPS looks and get bool by given path and separator.

func (*Vector) GetByIdx 

func (vec *Vector) GetByIdx(idx int) *Node

GetByIdx returns node by known index in nodes array.

func (*Vector) GetBytes 

func (vec *Vector) GetBytes(keys ...string) []byte

GetBytes looks and get bytes by given keys.

func (*Vector) GetBytesPS 

func (vec *Vector) GetBytesPS(path, separator string) []byte

GetBytesPS looks and get bytes by given path and separator.

func (*Vector) GetChild 

func (vec *Vector) GetChild(root *Node, depth int) (*Node, int)

GetChild is a legacy version of AcquireChild. DEPRECATED: use AcquireChild instead.

func (*Vector) GetChildWT 

func (vec *Vector) GetChildWT(root *Node, depth int, typ Type) (*Node, int)

GetChildWT is a legacy version of AcquireChildWithType. DEPRECATED: use AcquireChildWithType instead.

func (*Vector) GetFloat 

func (vec *Vector) GetFloat(keys ...string) (float64, error)

GetFloat looks and get float by given keys.

func (*Vector) GetFloatPS 

func (vec *Vector) GetFloatPS(path, separator string) (float64, error)

GetFloatPS looks and get float by given path and separator.

func (*Vector) GetInt 

func (vec *Vector) GetInt(keys ...string) (int64, error)

GetInt looks and get integer by given keys.

func (*Vector) GetIntPS 

func (vec *Vector) GetIntPS(path, separator string) (int64, error)

GetIntPS looks and get integer by given path and separator.

func (*Vector) GetNode 

func (vec *Vector) GetNode(depth int) (node *Node, idx int)

GetNode is a legacy version of AcquireNode. DEPRECATED: use AcquireNode instead.

func (*Vector) GetNodeWT 

func (vec *Vector) GetNodeWT(depth int, typ Type) (*Node, int)

GetNodeWT is a legacy version of AcquireNodeWithType. DEPRECATED: use AcquireNodeWithType instead.

func (*Vector) GetObject 

func (vec *Vector) GetObject(keys ...string) *Node

GetObject looks and get object by given keys.

func (*Vector) GetObjectPS 

func (vec *Vector) GetObjectPS(path, separator string) *Node

GetObjectPS looks and get object by given path and separator.

func (*Vector) GetPS 

func (vec *Vector) GetPS(path, separator string) *Node

GetPS returns node by given path and separator.

func (*Vector) GetString 

func (vec *Vector) GetString(keys ...string) string

GetString looks and get string by given keys.

func (*Vector) GetStringPS 

func (vec *Vector) GetStringPS(path, separator string) string

GetStringPS looks and get string by given path and separator.

func (*Vector) GetUint 

func (vec *Vector) GetUint(keys ...string) (uint64, error)

GetUint looks and get unsigned integer by given keys.

func (*Vector) GetUintPS 

func (vec *Vector) GetUintPS(path, separator string) (uint64, error)

GetUintPS looks and get unsigned integer by given path and separator.

func (*Vector) KeepPtr 

func (vec *Vector) KeepPtr()

KeepPtr guarantees that vector object wouldn't be collected by GC.

Typically, vector objects uses together with pools and GC doesn't collect them. But for cases like vec := &Vector{...} node := vec.Get("foo", "bar") <- here GC may collect vec fmt.Println(node.String()) <- invalid operation due to vec already has been collected vec.KeepPtr() <- just call me to avoid that trouble

func (*Vector) Len 

func (vec *Vector) Len() int

Len returns length of nodes array.

func (*Vector) Marshal added in v1.2.4 

func (vec *Vector) Marshal(w io.Writer) error

Marshal serializes first root node.

Second and next roots must beautify manually by call Marshal method of each node.

func (*Vector) NodeAt 

func (vec *Vector) NodeAt(idx int) *Node

NodeAt returns node at given position.

func (*Vector) Parse 

func (vec *Vector) Parse(_ []byte) error

Parse parses source bytes.

func (*Vector) ParseCopy 

func (vec *Vector) ParseCopy(_ []byte) error

ParseCopy copies source bytes and parse it.

func (*Vector) ParseCopyStr 

func (vec *Vector) ParseCopyStr(_ string) error

ParseCopyStr is a legacy version of ParseCopyString. DEPRECATED: use ParseCopyString instead.

func (*Vector) ParseCopyString added in v1.2.7 

func (vec *Vector) ParseCopyString(_ string) error

ParseCopyString copies source string and parse it.

func (*Vector) ParseFile added in v1.2.7 

func (vec *Vector) ParseFile(path string) error

ParseFile reads file contents and parse it.

func (*Vector) ParseReader added in v1.2.7 

func (vec *Vector) ParseReader(r io.Reader) (err error)

ParseReader reads source from r and parse it.

func (*Vector) ParseStr 

func (vec *Vector) ParseStr(_ string) error

ParseStr is a legacy version of ParseString. DEPRECATED: use ParseString instead.

func (*Vector) ParseString added in v1.2.7 

func (vec *Vector) ParseString(_ string) error

ParseString parses source string.

func (*Vector) Prealloc added in v1.2.5 

func (vec *Vector) Prealloc(size uint)

Prealloc prepares space for further parse.

func (*Vector) PutNode 

func (vec *Vector) PutNode(idx int, node *Node)

PutNode is a legacy version of ReleaseNode. DEPRECATED: use ReleaseNode instead.

func (*Vector) ReadRuneAt added in v1.2.7 

func (vec *Vector) ReadRuneAt(i int) (r rune, w int, err error)

ReadRuneAt returns rune at position i. Please note, it's your responsibility to specify right position `i`.

func (*Vector) ReleaseNode added in v1.2.7 

func (vec *Vector) ReleaseNode(idx int, node *Node)

ReleaseNode returns node back to the vector.

func (*Vector) RemoveIf added in v1.2.3 

func (vec *Vector) RemoveIf(cond func(idx int, node *Node) bool)

RemoveIf deletes all root nodes satisfies condition cond.

func (*Vector) Reset 

func (vec *Vector) Reset()

Reset vector data.

func (*Vector) Root 

func (vec *Vector) Root() *Node

Root returns root node.

func (*Vector) RootByIndex 

func (vec *Vector) RootByIndex(index int) *Node

RootByIndex returns root node by given index.

For cases when one vector instance uses for parse many sources.

func (*Vector) RootLen 

func (vec *Vector) RootLen() int

RootLen returns count of root nodes.

func (*Vector) RootTop 

func (vec *Vector) RootTop() *Node

RootTop returns last root node.

func (*Vector) SetErrOffset 

func (vec *Vector) SetErrOffset(offset int)

SetErrOffset sets error offset.

func (*Vector) SetHelper 

func (vec *Vector) SetHelper(helper Helper)

SetHelper sets helper to vector object.

func (*Vector) SetSrc 

func (vec *Vector) SetSrc(s []byte, copy bool) error

SetSrc sets source bytes.

func (*Vector) Src 

func (vec *Vector) Src() []byte

Src returns raw source bytes.

Please note, source bytes may be "corrupt" when unescaped.

func (*Vector) SrcAddr 

func (vec *Vector) SrcAddr() uintptr

SrcAddr returns source address in virtual memory.

func (*Vector) SrcAt 

func (vec *Vector) SrcAt(i int) byte

SrcAt returns byte at position i.

func (*Vector) SrcLen 

func (vec *Vector) SrcLen() int

SrcLen returns length of source bytes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.