This package is under continuous development, but the APIs are fairly stable.
JSON
Value (aka gson)
[]interface{}
.map[string]interface{}
.nil
, bool
,
byte, int8, int16, uint16, int32, uint32, int, uint, int64, uint64
,
float32, float64
,
string
, []interface{}
, map[string]interface{}
,
[][2]interface{}
.[][2]interface{}
, first item is treated as key (string) and
second item is treated as value, hence equivalent to
map[string]interface{}
.CBOR
Binary-Collation
JSON-Pointer
Following Benchmark is made on a map data which has a shape similar to:
{"key1": nil, "key2": true, "key3": false,
"key4": "hello world", "key5": 10.23122312}
or,
{"a":null,"b":true,"c":false,"d\"":10,"e":"tru\"e", "f":[1,2]}
BenchmarkVal2JsonMap5-8 3000000 461 ns/op 0 B/op 0 allocs/op
BenchmarkVal2CborMap5-8 5000000 262 ns/op 0 B/op 0 allocs/op
BenchmarkVal2CollMap-8 1000000 1321 ns/op 128 B/op 2 allocs/op
BenchmarkJson2CborMap-8 2000000 838 ns/op 0 B/op 0 allocs/op
BenchmarkCbor2JsonMap-8 2000000 1010 ns/op 0 B/op 0 allocs/op
BenchmarkJson2CollMap-8 1000000 1825 ns/op 202 B/op 2 allocs/op
BenchmarkColl2JsonMap-8 1000000 2028 ns/op 434 B/op 6 allocs/op
BenchmarkCbor2CollMap-8 1000000 1692 ns/op 131 B/op 2 allocs/op
BenchmarkColl2CborMap-8 1000000 1769 ns/op 440 B/op 6 allocs/op
Though converting to golang value incurs cost.
BenchmarkJson2ValMap5 1000000 1621 ns/op 699 B/op 14 allocs/op
BenchmarkCbor2ValMap5 1000000 1711 ns/op 496 B/op 18 allocs/op
BenchmarkColl2ValMap 1000000 2235 ns/op 1440 B/op 33 allocs/op
Configuration APIs are not re-entrant. For concurrent use of Gson, please
create a gson.Config{}
per routine, or protect them with a mutex.
NumberKind
There are two ways to treat numbers in Gson, as integers (upto 64-bit width) or floating-point (float64).
FloatNumber configuration can be used to tell Gson to treat all numbers as floating point. This has the convenience of having precision between discrete values, but suffers round of errors and inability to represent integer values greater than 2^53. DEFAULT choice.
SmartNumber will use int64, uint64 for representing integer values and use float64 when decimal precision is required. Choosing this option, Gson might incur a slight performance penalty.
Can be configured per configuration instance via SetNumberKind()
.
MaxKeys
Maximum number of keys allowed in a property object. This can be configured
globally via gson.MaxKeys
or per configuration via SetMaxkeys()
.
Memory-pools
Gson uses memory pools:
Memory foot print of gson depends on the pools size, maximum length of input string, number keys in input property-map.
Mempools can be configured globally via
gson.MaxStringLen, gson.MaxKeys, gson.MaxCollateLen, gson.MaxJsonpointerLen
package variables or per configuration instance via ResetPools()
.
CBOR ContainerEncoding
In CBOR both map and array (called container types) can be encoded as length followed by items, or items followed by end-marker.
Can be configured per configuration instance via SetContainerEncoding
JSON Strict
Can be configured per configuration instance via SetStrict
.
JSON SpaceKind
How to interpret space characters ? There are two options:
Can be configured per configuration instance via SetSpaceKind
.
Collate ArrayLenPrefix
While sorting array, which is a container type, should collation algorithm consider the arity of the array ? If ArrayLenPrefix prefix is configured as true, arrays with more number of items will sort after arrays with lesser number of items.
Can be configured per configuration instance via SortbyArrayLen
.
Collate PropertyLenPrefix
While sorting property-map, which is a container type, should collation algorithm consider number of entries in the map ? If PropertyLenPrefix is configured as true, maps with more number of items will sort after maps with lesser number of items.
Can be configured per configuration instance via SortbyPropertyLen
.
JSON-Pointer JsonpointerLength
Maximum length a JSON-pointer string can take. Can be configured globally
via MaxJsonpointerLen or per configuration instance via SetJptrlen
.
NOTE: JSON pointers are composed of path segments, there is an upper limit to the number of path-segments a JSON pointer can have. If your configuration exceeds that limit, try increasing the JsonpointerLength.
Value to CBOR
nil
, true
, false
are encodable into CBOR
format.number
types, including signed, unsigned, and
floating-point variants, are encodable into CBOR format.[]byte
is encoded as CBOR byte-string.string
is encoded as CBOR text.array
is interpreted as Golang []interface{}
and
encoded as CBOR array.
LengthPrefix
option for ContainerEncoding, arrays and
maps are encoded with its length.Stream
option, arrays and maps are encoded using
Indefinite and Breakstop encoding.property
is interpreted as golang [][2]interface{}
and encoded as CBOR array of 2-element array, where the first item
is key represented as string and second item is any valid JSON
value.map[string]interface{}
type, use
GolangMap2cborMap()
function to transform them to
[][2]interface{}
.time.Time
encoded with tag-0.Epoch
type supplied by CBOR package, encoded
with tag-1.EpochMicro
type supplied by CBOR package, encoded
with tag-1.math/big.Int
positive numbers are encoded with tag-2, and
negative numbers are encoded with tag-3.DecimalFraction
type supplied by CBOR package,
encoded with tag-4.BigFloat
type supplied by CBOR package, encoded
with tag-5.CborTagBytes
type supplied by CBOR package, encoded with
tag-24.regexp.Regexp
encoded with tag-35.CborTagPrefix
type supplied by CBOR package, encoded
with tag-55799.Value to collate
nil
, true
, false
, float64
, int64
, int
,
string
, []byte
, []interface{}
, map[string]interface{}
are supported for collation.JSON to Value
FloatNumber
to interpret JSON number as 64-bit floating point.SmartNumber
to interpret JSON number as int64, or uint64, or float64.SpaceKind
.
SpaceKind can be one of the following AnsiSpace
or UnicodeSpace
.
AnsiSpace
that should be fasterUnicodeSpace
supports unicode white-spaces as well.JSON to collate
JSON to CBOR
null
, true
, false
are encodable into CBOR format.number
are encoded based on configuration type NumberKind
,
which can be one of the following.
string
will be parsed and translated into UTF-8, and subsequently
encoded as CBOR-text.arrays
can be encoded in Stream
mode, using CBOR's
indefinite-length scheme, or in LengthPrefix
mode.properties
can be encoded either using CBOR's indefinite-length
scheme (Stream
), or using CBOR's LengthPrefix
.CBOR to Value
value to CBOR
encoding, described above, are
supported.float16
type and int64 > 9223372036854775807.IsIndefinite*()
and IsBreakstop()
APIs.CBOR to JSON
nil
, true
, false
are transformed back to equivalent
JSON types.float32
and float64
are transformed back to 32 bit
JSON-float and 64 bit JSON-float respectively, in
non-exponent format.integer
is transformed back to JSON-integer representation,
and integers exceeding 9223372036854775807 are not supported.array
either with length prefix or with indefinite encoding
are converted back to JSON array.map
either with length prefix or with indefinite encoding
are converted back to JSON property.For transforming to and from binary-collation refer here
CBOR to Collate
null
, true
, false
, float32
, float64
, integer
,
string
, []byte
(aka binary), array
, object
can be
collated.Collate to CBOR
Missing
, null
, true
, false
, floating-point
, small-decimal
,
integer
, string
, []byte
(aka binary), array
, object
types
from its collated from can be converted back to CBOR.Collate to JSON
Collate to Value
master
is the development branch.Task list
Config
instances, and its APIs, are neither re-entrant nor thread safe.list of changes from github.com/prataprc/collatejson