json

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: MIT Imports: 3 Imported by: 0

README

json

import "github.com/kitsunium/sdk/pkg/v1/data/codec/json"

Package json registers the JSON codec with the SDK's codec registry — and no other codec — when it is imported (ADR 0134):

import _ "github.com/kitsunium/sdk/pkg/v1/data/codec/json"

Everything that dispatches through the registry by format name then reads and writes JSON: config.FileSource and config.FSSource, i18n.LoadFS, and the codec package's Marshal and Unmarshal. Importing github.com/kitsunium/sdk/pkg/v1/data/codec instead registers every format the SDK ships — BSON, CBOR, MessagePack and the rest — which a program that only reads JSON does not need to link. This package links the JSON codec, the core package declaring its codes, the standard library's encoding/json and internal/kernel/jsonenc (the standard library again), and nothing else.

A time.Duration is the integer of its nanoseconds, as encoding/json writes it: the codec's contract is the standard library's own output (#1126).

Importing both packages is harmless: a format is registered by the package that implements it, which Go initialises once however many packages import it.

Appenders

For a program that writes JSON by hand, the package re-exports the appenders the SDK's own emitters use (ADR 0186 §D10):

out := json.BeginObject(buf[:0]).
	String("level", "info").
	Int("n", 7).
	End()
stringOut := json.AppendString(nil, "a \"quoted\" word")

A string is escaped as encoding/json escapes it — U+2028 and U+2029 included, an invalid UTF-8 byte written as U+FFFD — with one difference: '<', '>' and '&' are NOT escaped, so the literal is not safe to embed in HTML as it is. The appenders register no codec and read no value by reflection, and Marshal is unchanged.

Errors

Failures carry the range 0.3.2.*; match them with errs.HasCode, or the sentinels with errors.Is:

CodeMarshalFailed    0.3.2.1  encoding/json could not encode the value
CodeUnmarshalFailed  0.3.2.2  the input is not JSON the target can hold
CodeSizeExceeded     0.3.2.3  a value longer than NewBoundedDecoder's byte ceiling

Index

Constants

const CodeMarshalFailed errs.Code = 197121

CodeMarshalFailed identifies a value encoding/json could not encode (0.3.2.1).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/json.CodeJSONMarshalFailed.

Code 0.3.2.1

const CodeSizeExceeded errs.Code = 197123

CodeSizeExceeded is 0.3.2.3: a value longer than NewBoundedDecoder's byte ceiling (#891).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/json.CodeJSONSizeExceeded.

Code 0.3.2.3

const CodeUnmarshalFailed errs.Code = 197122

CodeUnmarshalFailed identifies input that is not JSON the target can hold (0.3.2.2).

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/json.CodeJSONUnmarshalFailed.

Code 0.3.2.2

const Format = "json"

Format is the name JSON is registered under. It is an untyped constant, so it goes wherever a format name is taken — config.FSSource's string, i18n.LoadFS's codec.Format — without a conversion.

Variables

var MarshalFailed *errs.Error

MarshalFailed is the sentinel of CodeMarshalFailed.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/json.MarshalFailed.

Code 0.3.2.1 · reason MARSHAL_FAILED · public "JSON encoding failed"

var SizeExceeded *errs.Error

SizeExceeded is the sentinel of CodeSizeExceeded.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/json.SizeExceeded.

Code 0.3.2.3 · reason SIZE_EXCEEDED · public "JSON input exceeds a size limit"

var UnmarshalFailed *errs.Error

UnmarshalFailed is the sentinel of CodeUnmarshalFailed.

Initialised with github.com/kitsunium/sdk/internal/core/data/codec/json.UnmarshalFailed.

Code 0.3.2.2 · reason UNMARSHAL_FAILED · public "JSON decoding failed"

func AppendEscaped

func AppendEscaped(dst []byte, s string) []byte

AppendEscaped appends the body of the JSON string literal of s, without its quotes, so a caller can join several pieces into one literal.

func AppendFloat

func AppendFloat(dst []byte, f float64) (number []byte, ok bool)

AppendFloat appends f to dst as the JSON number encoding/json writes for a float64 and reports true; for NaN and ±Inf it appends nothing and reports false.

func AppendInt

func AppendInt(dst []byte, v int64) []byte

AppendInt appends v to dst in decimal, as a JSON number.

func AppendString

func AppendString(dst []byte, s string) []byte

AppendString appends s to dst as a JSON string literal, quotes included. An invalid UTF-8 byte becomes U+FFFD, U+2028 and U+2029 are escaped, and '<', '>' and '&' are NOT: the literal is not safe to embed in HTML.

func AppendUint

func AppendUint(dst []byte, v uint64) []byte

AppendUint appends v to dst in decimal, as a JSON number.

func BeginObject

func BeginObject(dst []byte) Object

BeginObject appends the opening brace of an object to dst and returns the Object that writes its members after it, in the order they are named.

type Object

Object is a JSON object being written by BeginObject: members land in the order they are named, and nothing allocates but the caller's slice.

type Object = svcjson.Object

Object is an alias of github.com/kitsunium/sdk/internal/kernel/jsonenc.Object, declared as:

type Object struct{}

func (Object) Bool
func (Object) Bool(key string, v bool) Object

Bool writes the member key with the literal true or false.

func (Object) End
func (Object) End() []byte

End appends the closing brace and returns the slice.

func (Object) Float
func (Object) Float(key string, f float64) Object

Float writes the member key with f as AppendFloat writes it, or with the literal null when f is NaN or infinite, which JSON cannot write as a number.

func (Object) Int
func (Object) Int(key string, v int64) Object

Int writes the member key with the number v.

func (Object) Null
func (Object) Null(key string) Object

Null writes the member key with the literal null.

func (Object) Raw
func (Object) Raw(key string, raw []byte) Object

Raw writes the member key with raw, which the caller guarantees is one valid JSON value: it is copied as it is, so a nested object built by another Object, or a number the caller formatted, goes in without a second escape.

func (Object) String
func (Object) String(key string, value string) Object

String writes the member key with the string value, both escaped as AppendString escapes.

func (Object) Uint
func (Object) Uint(key string, v uint64) Object

Uint writes the member key with the unsigned number v, as AppendUint writes it.

Generated from docs/api by tools/genindex.

Documentation

Overview

Package json registers the JSON codec with the SDK's codec registry — and no other codec — when it is imported (ADR 0134): 

import _ "github.com/kitsunium/sdk/pkg/v1/data/codec/json"

Everything that dispatches through the registry by format name then reads and writes JSON: config.FileSource and config.FSSource, i18n.LoadFS, and the codec package's Marshal and Unmarshal. Importing github.com/kitsunium/sdk/pkg/v1/data/codec instead registers every format the SDK ships — BSON, CBOR, MessagePack and the rest — which a program that only reads JSON does not need to link. This package links the JSON codec, the core package declaring its codes, the standard library's encoding/json and internal/kernel/jsonenc (the standard library again), and nothing else.

A time.Duration is the integer of its nanoseconds, as encoding/json writes it: the codec's contract is the standard library's own output (#1126).

Importing both packages is harmless: a format is registered by the package that implements it, which Go initialises once however many packages import it.

Appenders

For a program that writes JSON by hand, the package re-exports the appenders the SDK's own emitters use (ADR 0186 §D10): 

out := json.BeginObject(buf[:0]).
	String("level", "info").
	Int("n", 7).
	End()
stringOut := json.AppendString(nil, "a \"quoted\" word")

A string is escaped as encoding/json escapes it — U+2028 and U+2029 included, an invalid UTF-8 byte written as U+FFFD — with one difference: '<', '>' and '&' are NOT escaped, so the literal is not safe to embed in HTML as it is. The appenders register no codec and read no value by reflection, and Marshal is unchanged.

Errors

Failures carry the range 0.3.2.*; match them with errs.HasCode, or the sentinels with errors.Is: 

CodeMarshalFailed    0.3.2.1  encoding/json could not encode the value
CodeUnmarshalFailed  0.3.2.2  the input is not JSON the target can hold
CodeSizeExceeded     0.3.2.3  a value longer than NewBoundedDecoder's byte ceiling

Index

Constants

View Source 
const (
	// CodeMarshalFailed identifies a value encoding/json could not encode (0.3.2.1).
	CodeMarshalFailed errs.Code = corejson.CodeJSONMarshalFailed
	// CodeUnmarshalFailed identifies input that is not JSON the target can hold (0.3.2.2).
	CodeUnmarshalFailed errs.Code = corejson.CodeJSONUnmarshalFailed
	// CodeSizeExceeded is 0.3.2.3: a value longer than NewBoundedDecoder's byte ceiling (#891).
	CodeSizeExceeded errs.Code = corejson.CodeJSONSizeExceeded
)

The error codes, range 0.3.2.*, declared in the core (ADR 0160).

View Source 
const Format = "json"

Format is the name JSON is registered under. It is an untyped constant, so it goes wherever a format name is taken — config.FSSource's string, i18n.LoadFS's codec.Format — without a conversion.

Variables

View Source 
var (
	// MarshalFailed is the sentinel of [CodeMarshalFailed].
	MarshalFailed = corejson.MarshalFailed
	// UnmarshalFailed is the sentinel of [CodeUnmarshalFailed].
	UnmarshalFailed = corejson.UnmarshalFailed
	// SizeExceeded is the sentinel of [CodeSizeExceeded].
	SizeExceeded = corejson.SizeExceeded
)

The sentinels, for errors.Is: each carries the code of the same name.

Functions

func AppendEscaped added in v0.11.2 

func AppendEscaped(dst []byte, s string) []byte

AppendEscaped appends the body of the JSON string literal of s, without its quotes, so a caller can join several pieces into one literal.

func AppendFloat added in v0.12.0 

func AppendFloat(dst []byte, f float64) (number []byte, ok bool)

AppendFloat appends f to dst as the JSON number encoding/json writes for a float64 and reports true; for NaN and ±Inf it appends nothing and reports false.

func AppendInt added in v0.11.2 

func AppendInt(dst []byte, v int64) []byte

AppendInt appends v to dst in decimal, as a JSON number.

func AppendString added in v0.11.2 

func AppendString(dst []byte, s string) []byte

AppendString appends s to dst as a JSON string literal, quotes included. An invalid UTF-8 byte becomes U+FFFD, U+2028 and U+2029 are escaped, and '<', '>' and '&' are NOT: the literal is not safe to embed in HTML.

func AppendUint added in v0.11.2 

func AppendUint(dst []byte, v uint64) []byte

AppendUint appends v to dst in decimal, as a JSON number.

Types

type Object added in v0.11.2 

type Object = svcjson.Object

Object is a JSON object being written by BeginObject: members land in the order they are named, and nothing allocates but the caller's slice.

func BeginObject added in v0.11.2 

func BeginObject(dst []byte) Object

BeginObject appends the opening brace of an object to dst and returns the Object that writes its members after it, in the order they are named.

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.