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