The *Append, *WithRegistry, and *WithContext functions in the bson package are redundant and can be replaced by creating and configuring an Encoder or Decoder.

Replacement Examples

Marshal

The MarshalAppend function can be replaced with:

dst := new(bytes.Buffer)
bson.NewEncoder(dst).Encode(val)

The MarshalExtJSONAppend function can be replaced with:

dst := new(bytes.Buffer)
bson.NewExtJSONEncoder(dst).Encode(val)

The Marshal*WithRegistry functions can be replaced with:

dst := new(bytes.Buffer)
enc := bson.NewEncoder(dst)
enc.SetRegistry(reg)
enc.Encode(val)

The MarshalExtJSON*WithRegistry functions can be replaced with:

dst := new(bytes.Buffer)
enc := bson.NewExtJSONEncoder(dst)
enc.SetRegistry(reg)
enc.Encode(val)

The Marshal*WithContext functions can be replaced with:

dst := new(bytes.Buffer)
enc := bson.NewEncoder(dst)
enc.SetRegistry(reg)
enc.SetMinSize(true)
enc.Encode(val)

Unmarshal

The UnmarshalAppend function can be replaced with:

dec := bson.NewDecoder(bytes.NewReader(data))
dec.Decode(val)

The UnmarshalExtJSONAppend function can be replaced with:

dec := bson.NewExtJSONDecoder(bytes.NewReader(data))
dec.Decode(val)

The Unmarshal*WithRegistry functions can be replaced with:

dec := bson.NewDecoder(bytes.NewReader(data))
dec.SetRegistry(reg)
dec.Decode(val)

The UnmarshalExtJSON*WithRegistry functions can be replaced with:

dec := bson.NewExtJSONDecoder(bytes.NewReader(data))
dec.SetRegistry(reg)
dec.Decode(val)

The Unmarshal*WithContext functions can be replaced with:

dec := bson.NewDecoder(bytes.NewReader(data))
dec.SetRegistry(reg)
dec.SetTruncate(true)
dec.DefaultDocumentM()
dec.Decode(val)

Encoder/Decoder

The NewEncoderWithContext function can be replaced with:

dst := new(bytes.Buffer)
enc := NewEncoder(dst)
enc.SetRegistry(reg)
enc.SetMinSize(true)

The NewDecoderWithContext function can be replaced with:

dec := bson.NewDecoder(bytes.NewReader(data))
dec.SetRegistry(reg)
dec.SetTruncate(true)
dec.DefaultDocumentM()

Definition of done

• Deprecate all package functions and RawValue methods ending with *Append, *WithRegistry, or *WithContext.
• Add example tests that describe how to replace the functionality offered by all deprecated functions.