document public symbols

Author: taowen

extra/fuzzy_decoder.go

@@ -160,8 +160,8 @@ type tolerateEmptyArrayDecoder struct {
 func (decoder *tolerateEmptyArrayDecoder) Decode(ptr unsafe.Pointer, iter *jsoniter.Iterator) {
 	if iter.WhatIsNext() == jsoniter.Array {
 		iter.Skip()
-		newIter := iter.Config().BorrowIterator([]byte("{}"))
-		defer iter.Config().ReturnIterator(newIter)
+		newIter := iter.Pool().BorrowIterator([]byte("{}"))
+		defer iter.Pool().ReturnIterator(newIter)
 		decoder.valDecoder.Decode(ptr, newIter)
 	} else {
 		decoder.valDecoder.Decode(ptr, iter)
@@ -202,8 +202,8 @@ func (decoder *fuzzyIntegerDecoder) Decode(ptr unsafe.Pointer, iter *jsoniter.It
 	default:
 		iter.ReportError("fuzzyIntegerDecoder", "not number or string")
 	}
-	newIter := iter.Config().BorrowIterator([]byte(str))
-	defer iter.Config().ReturnIterator(newIter)
+	newIter := iter.Pool().BorrowIterator([]byte(str))
+	defer iter.Pool().ReturnIterator(newIter)
 	isFloat := strings.IndexByte(str, '.') != -1
 	decoder.fun(isFloat, ptr, newIter)
 	if newIter.Error != nil {
@@ -222,8 +222,8 @@ func (decoder *fuzzyFloat32Decoder) Decode(ptr unsafe.Pointer, iter *jsoniter.It
 		*((*float32)(ptr)) = iter.ReadFloat32()
 	case jsoniter.String:
 		str = iter.ReadString()
-		newIter := iter.Config().BorrowIterator([]byte(str))
-		defer iter.Config().ReturnIterator(newIter)
+		newIter := iter.Pool().BorrowIterator([]byte(str))
+		defer iter.Pool().ReturnIterator(newIter)
 		*((*float32)(ptr)) = newIter.ReadFloat32()
 		if newIter.Error != nil {
 			iter.Error = newIter.Error
@@ -244,8 +244,8 @@ func (decoder *fuzzyFloat64Decoder) Decode(ptr unsafe.Pointer, iter *jsoniter.It
 		*((*float64)(ptr)) = iter.ReadFloat64()
 	case jsoniter.String:
 		str = iter.ReadString()
-		newIter := iter.Config().BorrowIterator([]byte(str))
-		defer iter.Config().ReturnIterator(newIter)
+		newIter := iter.Pool().BorrowIterator([]byte(str))
+		defer iter.Pool().ReturnIterator(newIter)
 		*((*float64)(ptr)) = newIter.ReadFloat64()
 		if newIter.Error != nil {
 			iter.Error = newIter.Error

feature_adapter.go

@@ -1,14 +1,3 @@
-// Package jsoniter implements encoding and decoding of JSON as defined in
-// RFC 4627 and provides interfaces with identical syntax of standard lib encoding/json.
-// Converting from encoding/json to jsoniter is no more than replacing the package with jsoniter
-// and variable type declarations (if any).
-// jsoniter interfaces gives 100% compatibility with code using standard lib.
-//
-// "JSON and Go"
-// (https://golang.org/doc/articles/json_and_go.html)
-// gives a description of how Marshal/Unmarshal operate
-// between arbitrary or predefined json objects and bytes,
-// and it applies to jsoniter.Marshal/Unmarshal as well.
 package jsoniter
 
 import (
@@ -96,7 +85,7 @@ func (adapter *Decoder) Buffered() io.Reader {
 func (decoder *Decoder) UseNumber() {
 	origCfg := decoder.iter.cfg.configBeforeFrozen
 	origCfg.UseNumber = true
-	decoder.iter.cfg = origCfg.Froze()
+	decoder.iter.cfg = origCfg.Froze().(*frozenConfig)
 }
 
 func NewEncoder(writer io.Writer) *Encoder {
@@ -119,6 +108,6 @@ func (adapter *Encoder) SetIndent(prefix, indent string) {
 
 func (adapter *Encoder) SetEscapeHTML(escapeHtml bool) {
 	config := adapter.stream.cfg.configBeforeFrozen
-	config.EscapeHtml = escapeHtml
-	adapter.stream.cfg = config.Froze()
+	config.EscapeHTML = escapeHtml
+	adapter.stream.cfg = config.Froze().(*frozenConfig)
 }

feature_config.go

@@ -9,10 +9,12 @@ import (
 	"unsafe"
 )
 
+// Config customize how the API should behave.
+// The API is created from Config by Froze.
 type Config struct {
 	IndentionStep           int
 	MarshalFloatWith6Digits bool
-	EscapeHtml              bool
+	EscapeHTML              bool
 	SortMapKeys             bool
 	UseNumber               bool
 }
@@ -28,7 +30,11 @@ type frozenConfig struct {
 	iteratorPool       chan *Iterator
 }
 
-type Api interface {
+// API the public interface of this package.
+// Primary Marshal and Unmarshal.
+type API interface {
+	IteratorPool
+	StreamPool
 	MarshalToString(v interface{}) (string, error)
 	Marshal(v interface{}) ([]byte, error)
 	MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
@@ -39,22 +45,25 @@ type Api interface {
 	NewDecoder(reader io.Reader) *Decoder
 }
 
+// ConfigDefault the default API
 var ConfigDefault = Config{
-	EscapeHtml: true,
+	EscapeHTML: true,
 }.Froze()
 
-// Trying to be 100% compatible with standard library behavior
+// ConfigCompatibleWithStandardLibrary tries to be 100% compatible with standard library behavior
 var ConfigCompatibleWithStandardLibrary = Config{
-	EscapeHtml:  true,
+	EscapeHTML:  true,
 	SortMapKeys: true,
 }.Froze()
 
+// ConfigFastest marshals float with only 6 digits precision
 var ConfigFastest = Config{
-	EscapeHtml:              false,
+	EscapeHTML:              false,
 	MarshalFloatWith6Digits: true,
 }.Froze()
 
-func (cfg Config) Froze() *frozenConfig {
+// Froze forge API from config
+func (cfg Config) Froze() API {
 	// TODO: cache frozen config
 	frozenConfig := &frozenConfig{
 		sortMapKeys:   cfg.SortMapKeys,
@@ -67,8 +76,8 @@ func (cfg Config) Froze() *frozenConfig {
 	if cfg.MarshalFloatWith6Digits {
 		frozenConfig.marshalFloatWith6Digits()
 	}
-	if cfg.EscapeHtml {
-		frozenConfig.escapeHtml()
+	if cfg.EscapeHTML {
+		frozenConfig.escapeHTML()
 	}
 	if cfg.UseNumber {
 		frozenConfig.useNumber()
@@ -145,7 +154,7 @@ func (encoder *htmlEscapedStringEncoder) IsEmpty(ptr unsafe.Pointer) bool {
 	return *((*string)(ptr)) == ""
 }
 
-func (cfg *frozenConfig) escapeHtml() {
+func (cfg *frozenConfig) escapeHTML() {
 	cfg.addEncoderToCache(reflect.TypeOf((*string)(nil)).Elem(), &htmlEscapedStringEncoder{})
 }
 
@@ -189,18 +198,16 @@ func (cfg *frozenConfig) getEncoderFromCache(cacheKey reflect.Type) ValEncoder {
 	return cache[cacheKey]
 }
 
-// cleanDecoders cleans decoders registered or cached
 func (cfg *frozenConfig) cleanDecoders() {
 	typeDecoders = map[string]ValDecoder{}
 	fieldDecoders = map[string]ValDecoder{}
-	*cfg = *cfg.configBeforeFrozen.Froze()
+	*cfg = *(cfg.configBeforeFrozen.Froze().(*frozenConfig))
 }
 
-// cleanEncoders cleans encoders registered or cached
 func (cfg *frozenConfig) cleanEncoders() {
 	typeEncoders = map[string]ValEncoder{}
 	fieldEncoders = map[string]ValEncoder{}
-	*cfg = *cfg.configBeforeFrozen.Froze()
+	*cfg = *(cfg.configBeforeFrozen.Froze().(*frozenConfig))
 }
 
 func (cfg *frozenConfig) MarshalToString(v interface{}) (string, error) {

feature_iter.go

@@ -1,25 +1,27 @@
-//
-// Besides, jsoniter.Iterator provides a different set of interfaces
-// iterating given bytes/string/reader
-// and yielding parsed elements one by one.
-// This set of interfaces reads input as required and gives
-// better performance.
 package jsoniter
 
 import (
 	"fmt"
 	"io"
 )
 
+// ValueType the type for JSON element
 type ValueType int
 
 const (
+	// Invalid invalid JSON element
 	Invalid ValueType = iota
+	// String JSON element "string"
 	String
+	// Number JSON element 100 or 0.10
 	Number
+	// Nil JSON element null
 	Nil
+	// Bool JSON element true or false
 	Bool
+	// Array JSON element []
 	Array
+	// Object JSON element {}
 	Object
 )
 
@@ -63,7 +65,8 @@ func init() {
 	valueTypes['{'] = Object
 }
 
-// Iterator is a fast and flexible JSON parser
+// Iterator is a io.Reader like object, with JSON specific read functions.
+// Error is not returned as return value, but stored as Error member on this iterator instance.
 type Iterator struct {
 	cfg              *frozenConfig
 	reader           io.Reader
@@ -75,57 +78,58 @@ type Iterator struct {
 	Error            error
 }
 
-// Create creates an empty Iterator instance
-func NewIterator(cfg *frozenConfig) *Iterator {
+// NewIterator creates an empty Iterator instance
+func NewIterator(cfg API) *Iterator {
 	return &Iterator{
-		cfg:    cfg,
+		cfg:    cfg.(*frozenConfig),
 		reader: nil,
 		buf:    nil,
 		head:   0,
 		tail:   0,
 	}
 }
 
-// Parse parses a json buffer in io.Reader into an Iterator instance
-func Parse(cfg *frozenConfig, reader io.Reader, bufSize int) *Iterator {
+// Parse creates an Iterator instance from io.Reader
+func Parse(cfg API, reader io.Reader, bufSize int) *Iterator {
 	return &Iterator{
-		cfg:    cfg,
+		cfg:    cfg.(*frozenConfig),
 		reader: reader,
 		buf:    make([]byte, bufSize),
 		head:   0,
 		tail:   0,
 	}
 }
 
-// ParseBytes parses a json byte slice into an Iterator instance
-func ParseBytes(cfg *frozenConfig, input []byte) *Iterator {
+// ParseBytes creates an Iterator instance from byte array
+func ParseBytes(cfg API, input []byte) *Iterator {
 	return &Iterator{
-		cfg:    cfg,
+		cfg:    cfg.(*frozenConfig),
 		reader: nil,
 		buf:    input,
 		head:   0,
 		tail:   len(input),
 	}
 }
 
-// ParseString parses a json string into an Iterator instance
-func ParseString(cfg *frozenConfig, input string) *Iterator {
+// ParseString creates an Iterator instance from string
+func ParseString(cfg API, input string) *Iterator {
 	return ParseBytes(cfg, []byte(input))
 }
 
-func (iter *Iterator) Config() *frozenConfig {
+// Pool returns a pool can provide more iterator with same configuration
+func (iter *Iterator) Pool() IteratorPool {
 	return iter.cfg
 }
 
-// Reset can reset an Iterator instance for another json buffer in io.Reader
+// Reset reuse iterator instance by specifying another reader
 func (iter *Iterator) Reset(reader io.Reader) *Iterator {
 	iter.reader = reader
 	iter.head = 0
 	iter.tail = 0
 	return iter
 }
 
-// ResetBytes can reset an Iterator instance for another json byte slice
+// ResetBytes reuse iterator instance by specifying another byte array as input
 func (iter *Iterator) ResetBytes(input []byte) *Iterator {
 	iter.reader = nil
 	iter.buf = input
@@ -134,7 +138,7 @@ func (iter *Iterator) ResetBytes(input []byte) *Iterator {
 	return iter
 }
 
-// WhatIsNext gets ValueType of relatively next json object
+// WhatIsNext gets ValueType of relatively next json element
 func (iter *Iterator) WhatIsNext() ValueType {
 	valueType := valueTypes[iter.nextToken()]
 	iter.unreadByte()
@@ -184,6 +188,7 @@ func (iter *Iterator) nextToken() byte {
 	}
 }
 
+// ReportError record a error in iterator instance with current position.
 func (iter *Iterator) ReportError(operation string, msg string) {
 	if iter.Error != nil {
 		if iter.Error != io.EOF {
@@ -198,7 +203,7 @@ func (iter *Iterator) ReportError(operation string, msg string) {
 		string(iter.buf[peekStart:iter.head]), string(iter.buf[0:iter.tail]))
 }
 
-// CurrentBuffer gets current buffer as string
+// CurrentBuffer gets current buffer as string for debugging purpose
 func (iter *Iterator) CurrentBuffer() string {
 	peekStart := iter.head - 10
 	if peekStart < 0 {
@@ -261,6 +266,7 @@ func (iter *Iterator) unreadByte() {
 	return
 }
 
+// Read read the next JSON element as generic interface{}.
 func (iter *Iterator) Read() interface{} {
 	valueType := iter.WhatIsNext()
 	switch valueType {

feature_iter_array.go

@@ -1,5 +1,6 @@
 package jsoniter
 
+// ReadArray read array element, tells if the array has more element to read.
 func (iter *Iterator) ReadArray() (ret bool) {
 	c := iter.nextToken()
 	switch c {
@@ -23,6 +24,7 @@ func (iter *Iterator) ReadArray() (ret bool) {
 	}
 }
 
+// ReadArrayCB read array with callback
 func (iter *Iterator) ReadArrayCB(callback func(*Iterator) bool) (ret bool) {
 	c := iter.nextToken()
 	if c == '[' {

feature_iter_float.go

@@ -30,6 +30,7 @@ func init() {
 	floatDigits['.'] = dotInNumber
 }
 
+// ReadBigFloat read big.Float
 func (iter *Iterator) ReadBigFloat() (ret *big.Float) {
 	str := iter.readNumberAsString()
 	if iter.Error != nil && iter.Error != io.EOF {
@@ -47,6 +48,7 @@ func (iter *Iterator) ReadBigFloat() (ret *big.Float) {
 	return val
 }
 
+// ReadBigInt read big.Int
 func (iter *Iterator) ReadBigInt() (ret *big.Int) {
 	str := iter.readNumberAsString()
 	if iter.Error != nil && iter.Error != io.EOF {
@@ -62,14 +64,14 @@ func (iter *Iterator) ReadBigInt() (ret *big.Int) {
 	return ret
 }
 
+//ReadFloat32 read float32
 func (iter *Iterator) ReadFloat32() (ret float32) {
 	c := iter.nextToken()
 	if c == '-' {
 		return -iter.readPositiveFloat32()
-	} else {
-		iter.unreadByte()
-		return iter.readPositiveFloat32()
 	}
+	iter.unreadByte()
+	return iter.readPositiveFloat32()
 }
 
 func (iter *Iterator) readPositiveFloat32() (ret float32) {
@@ -165,14 +167,14 @@ func (iter *Iterator) readFloat32SlowPath() (ret float32) {
 	return float32(val)
 }
 
+// ReadFloat64 read float64
 func (iter *Iterator) ReadFloat64() (ret float64) {
 	c := iter.nextToken()
 	if c == '-' {
 		return -iter.readPositiveFloat64()
-	} else {
-		iter.unreadByte()
-		return iter.readPositiveFloat64()
 	}
+	iter.unreadByte()
+	return iter.readPositiveFloat64()
 }
 
 func (iter *Iterator) readPositiveFloat64() (ret float64) {