encoding.go

     1  // Copyright 2013 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package encoding defines interfaces shared by other packages that
     6  // convert data to and from byte-level and textual representations.
     7  // Packages that check for these interfaces include encoding/gob,
     8  // encoding/json, and encoding/xml. As a result, implementing an
     9  // interface once can make a type useful in multiple encodings.
    10  // Standard types that implement these interfaces include time.Time and net.IP.
    11  // The interfaces come in pairs that produce and consume encoded data.
    12  //
    13  // Adding encoding/decoding methods to existing types may constitute a breaking change,
    14  // as they can be used for serialization in communicating with programs
    15  // written with different library versions.
    16  // The policy for packages maintained by the Go project is to only allow
    17  // the addition of marshaling functions if no existing, reasonable marshaling exists.
    18  package encoding
    19  
    20  // BinaryMarshaler is the interface implemented by an object that can
    21  // marshal itself into a binary form.
    22  //
    23  // MarshalBinary encodes the receiver into a binary form and returns the result.
    24  type BinaryMarshaler interface {
    25  	MarshalBinary() (data []byte, err error)
    26  }
    27  
    28  // BinaryUnmarshaler is the interface implemented by an object that can
    29  // unmarshal a binary representation of itself.
    30  //
    31  // UnmarshalBinary must be able to decode the form generated by MarshalBinary.
    32  // UnmarshalBinary must copy the data if it wishes to retain the data
    33  // after returning.
    34  type BinaryUnmarshaler interface {
    35  	UnmarshalBinary(data []byte) error
    36  }
    37  
    38  // BinaryAppender is the interface implemented by an object
    39  // that can append the binary representation of itself.
    40  // If a type implements both [BinaryAppender] and [BinaryMarshaler],
    41  // then v.MarshalBinary() must be semantically identical to v.AppendBinary(nil).
    42  type BinaryAppender interface {
    43  	// AppendBinary appends the binary representation of itself to the end of b
    44  	// (allocating a larger slice if necessary) and returns the updated slice.
    45  	//
    46  	// Implementations must not retain b, nor mutate any bytes within b[:len(b)].
    47  	AppendBinary(b []byte) ([]byte, error)
    48  }
    49  
    50  // TextMarshaler is the interface implemented by an object that can
    51  // marshal itself into a textual form.
    52  //
    53  // MarshalText encodes the receiver into UTF-8-encoded text and returns the result.
    54  type TextMarshaler interface {
    55  	MarshalText() (text []byte, err error)
    56  }
    57  
    58  // TextUnmarshaler is the interface implemented by an object that can
    59  // unmarshal a textual representation of itself.
    60  //
    61  // UnmarshalText must be able to decode the form generated by MarshalText.
    62  // UnmarshalText must copy the text if it wishes to retain the text
    63  // after returning.
    64  type TextUnmarshaler interface {
    65  	UnmarshalText(text []byte) error
    66  }
    67  
    68  // TextAppender is the interface implemented by an object
    69  // that can append the textual representation of itself.
    70  // If a type implements both [TextAppender] and [TextMarshaler],
    71  // then v.MarshalText() must be semantically identical to v.AppendText(nil).
    72  type TextAppender interface {
    73  	// AppendText appends the textual representation of itself to the end of b
    74  	// (allocating a larger slice if necessary) and returns the updated slice.
    75  	//
    76  	// Implementations must not retain b, nor mutate any bytes within b[:len(b)].
    77  	AppendText(b []byte) ([]byte, error)
    78  }
    79
View as plain text