jsonstream

Documentation

Overview

Package jsonstream is a deprecated implementation of sequential JSON encoding and tokenizing.

Deprecated: this implementation is no longer used by the LaunchDarkly SDK, but is retained for backward compatibility. It has been replaced by the go-jsonstream project: https://github.com/launchdarkly/go-jsonstream

Index

• func WriteToJSONBufferThroughWriter(writable jwriter.Writable, jsonBuffer *JSONBuffer)
• type JSONBuffer
  • func NewJSONBuffer() *JSONBuffer
  • func NewStreamingJSONBuffer(w io.Writer, chunkSize int) *JSONBuffer
  • func (j *JSONBuffer) BeginArray()
  • func (j *JSONBuffer) BeginObject()
  • func (j *JSONBuffer) EndArray()
  • func (j *JSONBuffer) EndObject()
  • func (j *JSONBuffer) Flush() error
  • func (j *JSONBuffer) Get() ([]byte, error)
  • func (j *JSONBuffer) GetError() error
  • func (j *JSONBuffer) GetPartial() []byte
  • func (j *JSONBuffer) Grow(n int)
  • func (j *JSONBuffer) SetSeparator(separator []byte)
  • func (j *JSONBuffer) WriteBool(value bool)
  • func (j *JSONBuffer) WriteFloat64(value float64)
  • func (j *JSONBuffer) WriteInt(value int)
  • func (j *JSONBuffer) WriteName(name string)
  • func (j *JSONBuffer) WriteNull()
  • func (j *JSONBuffer) WriteRaw(value json.RawMessage)
  • func (j *JSONBuffer) WriteString(value string)
  • func (j *JSONBuffer) WriteUint64(value uint64)

Functions

func WriteToJSONBufferThroughWriter

func WriteToJSONBufferThroughWriter(writable jwriter.Writable, jsonBuffer *JSONBuffer)

WriteToJSONBufferThroughWriter is a convenience method that allows marshaling logic written against the newer jsonstream API to be used with this deprecated package.

Types

type JSONBuffer

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

JSONBuffer is a fast JSON encoder for manual generation of sequential output, writing one token at a time. Output is written to an in-memory buffer.

Any invalid operation (such as trying to write a property name when a value is expected, or vice versa) causes the JSONBuffer to enter a failed state where all subsequent write operations are ignored. The error will be returned by Get() or GetError().

If the caller write smore than one JSON value at the top level (that is, not inside an array or object), the values will be separated by whatever byte sequence was specified with SetSeparator(), or, if not specified, by a newline.

JSONBuffer is not safe for concurrent access by multiple goroutines.

var buf jsonstream.JSONBuffer
buf.BeginObject()
buf.WriteName("a")
buf.WriteInt(2)
buf.EndObject()
bytes, err := buf.Get() // bytes == []byte(`{"a":2}`)

func NewJSONBuffer

func NewJSONBuffer() *JSONBuffer

NewJSONBuffer creates a new JSONBuffer on the heap. This is not strictly necessary; declaring a local value of JSONBuffer{} will also work.

func NewStreamingJSONBuffer

func NewStreamingJSONBuffer(w io.Writer, chunkSize int) *JSONBuffer

NewStreamingJSONBuffer creates a JSONBuffer that, instead of accumulating all of the output in memory, writes it in chunks to the specified Writer.

In this mode, operations that write data to the JSONBuffer will accumulate the output in memory until either at least chunkSize bytes have been written, or Flush() is called. At that point, the buffered output is written to the Writer, and then the buffer is cleared. The amount of data written at a time may be more than chunkSize bytes, but will not be less unless you force a Flush().

If the Writer returns an error at any point, the JSONBuffer enters a failed state and will not try to write any more data. The error can be checked by calling GetError().

It is important to call Flush() after you are done with the JSONBuffer to ensure that everything has been written to the Writer.

func (*JSONBuffer) BeginArray

func (j *JSONBuffer) BeginArray()

BeginArray begins writing a JSON array.

All subsequent values written will be delimited by commas. Call EndArray to finish the array. The array may contain any types of values, including nested arrays or objects.

buf.BeginArray()
buf.WriteInt(1)
buf.WriteString("b")
buf.EndArray() // produces [1,"b"]

func (*JSONBuffer) BeginObject

func (j *JSONBuffer) BeginObject()

BeginObject begins writing a JSON object.

Until this object is ended, you must call WriteName before each value. Call EndObject to finish the object. The object may contain any types of values, including nested objects or arrays.

buf.BeginObject()
buf.WriteName("a")
buf.WriteInt(1)
buf.WriteName("b")
buf.WriteBool(true)
buf.EndObject() // produces {"a":1,"b":true}

func (*JSONBuffer) EndArray

func (j *JSONBuffer) EndArray()

EndArray finishes writing the current JSON array.

func (*JSONBuffer) EndObject

func (j *JSONBuffer) EndObject()

EndObject finishes writing the current JSON object.

func (*JSONBuffer) Flush

func (j *JSONBuffer) Flush() error

Flush writes any remaining in-memory output to the underlying Writer, if this is a streaming buffer created with NewStreamingJSONBuffer. It has no effect otherwise.

func (*JSONBuffer) Get

func (j *JSONBuffer) Get() ([]byte, error)

Get returns the full encoded byte slice.

If the buffer is in a failed state from a previous invalid operation, or cannot be ended at this point because of an unfinished array or object, Get() returns a nil slice and the error. In that case, the data written so far can be accessed with GetPartial().

func (*JSONBuffer) GetError

func (j *JSONBuffer) GetError() error

GetError returns an error if the buffer is in a failed state from a previous invalid operation, or nil otherwise.

func (*JSONBuffer) GetPartial

func (j *JSONBuffer) GetPartial() []byte

GetPartial returns the data written to the buffer so far, regardless of whether it is in a failed or incomplete state.

func (*JSONBuffer) Grow

func (j *JSONBuffer) Grow(n int)

Grow expands the internal buffer by the specified number of bytes. It is the same as calling Grow on a bytes.Buffer.

func (*JSONBuffer) SetSeparator

func (j *JSONBuffer) SetSeparator(separator []byte)

SetSeparator specifies a byte sequence that should be added to the buffer in between values if more than one value is written outside of an array or object. If not specified, a newline is used.

var buf jsonstream.JSONBuffer
buf.SetSeparator([]byte("! "))
buf.WriteInt(1)
buf.WriteInt(2)
buf.WriteInt(3)
bytes, err := buf.Get() // bytes == []byte(`1! 2! 3`)

func (*JSONBuffer) WriteBool

func (j *JSONBuffer) WriteBool(value bool)

WriteBool writes a JSON boolean value to the output.

func (*JSONBuffer) WriteFloat64

func (j *JSONBuffer) WriteFloat64(value float64)

WriteFloat64 writes a JSON numeric value to the output.

func (*JSONBuffer) WriteInt

func (j *JSONBuffer) WriteInt(value int)

WriteInt writes a JSON numeric value to the output.

func (*JSONBuffer) WriteName

func (j *JSONBuffer) WriteName(name string)

WriteName writes a property name within an object.

It is an error to call this method outside of an object, or immediately after another WriteName. Each WriteName should be followed by some JSON value (WriteBool, WriteString, BeginArray, etc.).

func (*JSONBuffer) WriteNull

func (j *JSONBuffer) WriteNull()

WriteNull writes a JSON null value to the output.

func (*JSONBuffer) WriteRaw

func (j *JSONBuffer) WriteRaw(value json.RawMessage)

WriteRaw writes a pre-encoded JSON value to the output as-is. Its format is assumed to be correct; this operation will not fail unless it is not permitted to write a value at this point.

func (*JSONBuffer) WriteString

func (j *JSONBuffer) WriteString(value string)

WriteString writes a JSON string value to the output, with quotes and escaping.

JSONBuffer assumes that multi-byte UTF8 characters are allowed in the output, so it will not escape any characters other than control characters, double quotes, and backslashes.

func (*JSONBuffer) WriteUint64

func (j *JSONBuffer) WriteUint64(value uint64)

WriteUint64 writes a JSON numeric value to the output.