If the user provides a JSON-to-CBOR transcode function, a value whose type implements json.Marshaler
and not cbor.Marshaler will be encoded by first calling its MarshalJSON method, then transcoding the
result to CBOR.
Signed-off-by: Ben Luddy <bluddy@redhat.com>
Mention that:
- time encoding options provided by cbor.TimeMode comply with RFC 8949.
- user apps that prefer to encode time in other ways (e.g. not specified by RFC 8949) can use a CBOR tag number not assigned by IANA and implement cbor.Marshal and cbor.Unmarshal interfaces.
Also, update the comments for each time encoding option to be more useful to programmers who did not read RFC 8949. The old comments were meant to be stop-gaps due to schedule.
This commit adds features related to allowing user to specify
a buffer rather than using built-in buffer pool:
- cbor.MarshalToBuffer() uses codec's default options to encode
to user provided buffer instead of using built-in buffer pool.
- UserBufferEncMode interface extends EncMode interface with
MarshalToBuffer() so user can provide buffer for encoding
instead of using built-in buffer pool.
- EncOptions.UserBufferEncMode() returns UserBufferEncMode
- EncOptions.UserBufferEncModeWithTags() returns UserBufferEncMode
- EncOptions.UserBufferEncModeWithSharedTags() returns UserBufferEncMode
Encode options, especially those that control the mapping from Go type to CBOR type, can result in
output containing tag validity errors. For tag numbers that are built in, it's possible to "do the
right thing" and override those options on a case-by-case basis. This can't and does not prevent tag
validity errors for unrecognized tag numbers.
Signed-off-by: Ben Luddy <bluddy@redhat.com>
By default, values whose type implements BinaryMarshaler encode to a byte string whose contents are
the result of calling MarshalBinary, and decoding a byte string into a BinaryUnmarshaler calls
UnmarshalBinary on the contents of the byte string. These options make it possible to disable both
behaviors.
Signed-off-by: Ben Luddy <bluddy@redhat.com>
The application calling Marshal has more information about the object it wants to marshal than this
library does (e.g. what type is it, what is the 95th-percentile serialized size of similar objects,
etc.). It can use this information to increase the utilization of encode buffers beyond what is
possible with a shared buffer pool for all calls to Marshal.
To avoid the backwards-incompatible change of expanding the method set of the EncMode interface,
invoking this method from an external package will require a type assertion, and there is currently
no exported "optional interface" declaration to make that more convenient.
Signed-off-by: Ben Luddy <bluddy@redhat.com>
With its only remaining field being an embedded bytes.Buffer, there's no reason to retain the
encoderBuffer type.
Signed-off-by: Ben Luddy <bluddy@redhat.com>
This commit removes encodeFixedLengthStruct() and reuses
encodeStruct() to simplify code.
Previously, encodeStruct() used extra buffer to encode elements
to get actual encoded element count. To avoid this overhead,
encodeFixedLengthStruct() was created to encode fixed
length struct (struct without any "omitempty" fields) since
encoded element count is always known in this use case.
With PR #519 (https://github.com/fxamacker/cbor/pull/519),
encodeStruct() doesn't use extra buffer any more, and
encodeFixedLengthStruct() isn't necessary.
These options improve interoperability with programs that use JSON to encode and decode objects to
and from both struct types and empty interface values.
Signed-off-by: Ben Luddy <bluddy@redhat.com>
The motivation is to prevent programs that consume the output from assuming (incorrectly) that it
was encoded deterministically, even when implementation details make the output apparently stable.
Signed-off-by: Ben Luddy <bluddy@redhat.com>
This commit checks Marshaler data for well-formedness
(and very limited partial validation) by reusing one
of four DecModes created during startup. These modes
are safe for parallel use by different Marshalers.
MarshalerError is returned if CBOR data item returned from
MarshalCBOR() fails either:
- well-formedness check, or
- tag validation for builtin tags 0-3
The StringType encode option supports use cases that must not produce invalid CBOR (even if
well-formed) and must be able to encode Go strings that do not contain valid UTF-8 sequences,
without the overhead of sanitizing all input Go values. The default value of the option is
TextStringType and encodes Go strings to CBOR major type 3, which is identical to the preexisting
behavior.
Signed-off-by: Ben Luddy <bluddy@redhat.com>
This commit resolves two issues:
1. Encoding cbor.SimpleValue with values 24..31 should fail because
CBOR simple values 24..31 are reserved and they MUST NOT be encoded
according to RFC 8949.
This commit makes encoder return UnsupportedValueError when encoding
cbor.SimpleValue with values 24..31 because that would not be
a well-formed CBOR data item.
2. Decoding other CBOR types to cbor.SimpleValue should fail because
cbor.SimpleValue represents CBOR simple value (major type 7) which is
different from CBOR integers and shouldn't be used interchangeably.
This commit makes decoder return UnmarshalTypeError when decoding
other CBOR types to cbor.SimpleValue.
