// Marshal returns the JSON encoding of v. // // Marshal traverses the value v recursively. // If an encountered value implements [Marshaler] // and is not a nil pointer, Marshal calls [Marshaler.MarshalJSON] // to produce JSON. If no [Marshaler.MarshalJSON] method is present but the // value implements [encoding.TextMarshaler] instead, Marshal calls // [encoding.TextMarshaler.MarshalText] and encodes the result as a JSON string. // The nil pointer exception is not strictly necessary // but mimics a similar, necessary exception in the behavior of // [Unmarshaler.UnmarshalJSON]. // // Otherwise, Marshal uses the following type-dependent default encodings: // // Boolean values encode as JSON booleans. // // Floating point, integer, and [Number] values encode as JSON numbers. // NaN and +/-Inf values will return an [UnsupportedValueError]. // // String values encode as JSON strings coerced to valid UTF-8, // replacing invalid bytes with the Unicode replacement rune. // So that the JSON will be safe to embed inside HTML <script> tags, // the string is encoded using [HTMLEscape], // which replaces "<", ">", "&", U+2028, and U+2029 are escaped // to "\u003c","\u003e", "\u0026", "\u2028", and "\u2029". // This replacement can be disabled when using an [Encoder], // by calling [Encoder.SetEscapeHTML](false). // // Array and slice values encode as JSON arrays, except that // []byte encodes as a base64-encoded string, and a nil slice // encodes as the null JSON value. // // Struct values encode as JSON objects. // Each exported struct field becomes a member of the object, using the // field name as the object key, unless the field is omitted for one of the // reasons given below. // // The encoding of each struct field can be customized by the format string // stored under the "json" key in the struct field's tag. // The format string gives the name of the field, possibly followed by a // comma-separated list of options. The name may be empty in order to // specify options without overriding the default field name. // // The "omitempty" option specifies that the field should be omitted // from the encoding if the field has an empty value, defined as // false, 0, a nil pointer, a nil interface value, and any empty array, // slice, map, or string. // // As a special case, if the field tag is "-", the field is always omitted. // Note that a field with name "-" can still be generated using the tag "-,". // // Examples of struct field tags and their meanings: // // // Field appears in JSON as key "myName". // Field int `json:"myName"` // // // Field appears in JSON as key "myName" and // // the field is omitted from the object if its value is empty, // // as defined above. // Field int `json:"myName,omitempty"` // // // Field appears in JSON as key "Field" (the default), but // // the field is skipped if empty. // // Note the leading comma. // Field int `json:",omitempty"` // // // Field is ignored by this package. // Field int `json:"-"` // // // Field appears in JSON as key "-". // Field int `json:"-,"` // // The "string" option signals that a field is stored as JSON inside a // JSON-encoded string. It applies only to fields of string, floating point, // integer, or boolean types. This extra level of encoding is sometimes used // when communicating with JavaScript programs: // // Int64String int64 `json:",string"` // // The key name will be used if it's a non-empty string consisting of // only Unicode letters, digits, and ASCII punctuation except quotation // marks, backslash, and comma. // // Embedded struct fields are usually marshaled as if their inner exported fields // were fields in the outer struct, subject to the usual Go visibility rules amended // as described in the next paragraph. // An anonymous struct field with a name given in its JSON tag is treated as // having that name, rather than being anonymous. // An anonymous struct field of interface type is treated the same as having // that type as its name, rather than being anonymous. // // The Go visibility rules for struct fields are amended for JSON when // deciding which field to marshal or unmarshal. If there are // multiple fields at the same level, and that level is the least // nested (and would therefore be the nesting level selected by the // usual Go rules), the following extra rules apply: // // 1) Of those fields, if any are JSON-tagged, only tagged fields are considered, // even if there are multiple untagged fields that would otherwise conflict. // // 2) If there is exactly one field (tagged or not according to the first rule), that is selected. // // 3) Otherwise there are multiple fields, and all are ignored; no error occurs. // // Handling of anonymous struct fields is new in Go 1.1. // Prior to Go 1.1, anonymous struct fields were ignored. To force ignoring of // an anonymous struct field in both current and earlier versions, give the field // a JSON tag of "-". // // Map values encode as JSON objects. The map's key type must either be a // string, an integer type, or implement [encoding.TextMarshaler]. The map keys // are sorted and used as JSON object keys by applying the following rules, // subject to the UTF-8 coercion described for string values above: // - keys of any string type are used directly // - keys that implement [encoding.TextMarshaler] are marshaled // - integer keys are converted to strings // // Pointer values encode as the value pointed to. // A nil pointer encodes as the null JSON value. // // Interface values encode as the value contained in the interface. // A nil interface value encodes as the null JSON value. // // Channel, complex, and function values cannot be encoded in JSON. // Attempting to encode such a value causes Marshal to return // an [UnsupportedTypeError]. // // JSON cannot represent cyclic data structures and Marshal does not // handle them. Passing cyclic structures to Marshal will result in // an error. func Marshal(v any) ([]byte, error) { … } // MarshalIndent is like [Marshal] but applies [Indent] to format the output. // Each JSON element in the output will begin on a new line beginning with prefix // followed by one or more copies of indent according to the indentation nesting. func MarshalIndent(v any, prefix, indent string) ([]byte, error) { … } type Marshaler … type UnsupportedTypeError … func (e *UnsupportedTypeError) Error() string { … } type UnsupportedValueError … func (e *UnsupportedValueError) Error() string { … } type InvalidUTF8Error … func (e *InvalidUTF8Error) Error() string { … } type MarshalerError … func (e *MarshalerError) Error() string { … } // Unwrap returns the underlying error. func (e *MarshalerError) Unwrap() error { … } const hex … type encodeState … const startDetectingCyclesAfter … var encodeStatePool … func newEncodeState() *encodeState { … } type jsonError … func (e *encodeState) marshal(v any, opts encOpts) (err error) { … } // error aborts the encoding by panicking with err wrapped in jsonError. func (e *encodeState) error(err error) { … } func isEmptyValue(v reflect.Value) bool { … } func (e *encodeState) reflectValue(v reflect.Value, opts encOpts) { … } type encOpts … type encoderFunc … var encoderCache … func valueEncoder(v reflect.Value) encoderFunc { … } func typeEncoder(t reflect.Type) encoderFunc { … } var marshalerType … var textMarshalerType … // newTypeEncoder constructs an encoderFunc for a type. // The returned encoder only checks CanAddr when allowAddr is true. func newTypeEncoder(t reflect.Type, allowAddr bool) encoderFunc { … } func invalidValueEncoder(e *encodeState, v reflect.Value, _ encOpts) { … } func marshalerEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } func addrMarshalerEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } func textMarshalerEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } func addrTextMarshalerEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } func boolEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } func intEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } func uintEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } type floatEncoder … func (bits floatEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) { … } var float32Encoder … var float64Encoder … func stringEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } // isValidNumber reports whether s is a valid JSON number literal. func isValidNumber(s string) bool { … } func interfaceEncoder(e *encodeState, v reflect.Value, opts encOpts) { … } func unsupportedTypeEncoder(e *encodeState, v reflect.Value, _ encOpts) { … } type structEncoder … type structFields … func (se structEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) { … } func newStructEncoder(t reflect.Type) encoderFunc { … } type mapEncoder … func (me mapEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) { … } func newMapEncoder(t reflect.Type) encoderFunc { … } func encodeByteSlice(e *encodeState, v reflect.Value, _ encOpts) { … } type sliceEncoder … func (se sliceEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) { … } func newSliceEncoder(t reflect.Type) encoderFunc { … } type arrayEncoder … func (ae arrayEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) { … } func newArrayEncoder(t reflect.Type) encoderFunc { … } type ptrEncoder … func (pe ptrEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) { … } func newPtrEncoder(t reflect.Type) encoderFunc { … } type condAddrEncoder … func (ce condAddrEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) { … } // newCondAddrEncoder returns an encoder that checks whether its value // CanAddr and delegates to canAddrEnc if so, else to elseEnc. func newCondAddrEncoder(canAddrEnc, elseEnc encoderFunc) encoderFunc { … } func isValidTag(s string) bool { … } func typeByIndex(t reflect.Type, index []int) reflect.Type { … } type reflectWithString … func resolveKeyName(k reflect.Value) (string, error) { … } func appendString[Bytes []byte | string](dst []byte, src Bytes, escapeHTML bool) []byte { … } type field … // typeFields returns a list of fields that JSON should recognize for the given type. // The algorithm is breadth-first search over the set of structs to include - the top struct // and then any reachable anonymous structs. func typeFields(t reflect.Type) structFields { … } // dominantField looks through the fields, all of which are known to // have the same name, to find the single field that dominates the // others using Go's embedding rules, modified by the presence of // JSON tags. If there are multiple top-level fields, the boolean // will be false: This condition is an error in Go and we skip all // the fields. func dominantField(fields []field) (field, bool) { … } var fieldCache … // cachedTypeFields is like typeFields but uses a cache to avoid repeated work. func cachedTypeFields(t reflect.Type) structFields { … } func mayAppendQuote(b []byte, quoted bool) []byte { … }