package codec

Import Path
	golang.org/x/pkgsite/internal/godoc/codec (on go.dev)

Dependency Relation
	imports 12 packages, and imported by one package


Involved Source Files

	      codec.go
	
		Package codec implements the general-purpose part of an encoder for Go
		values. It relies on code generation rather than reflection so it is
		significantly faster than reflection-based encoders like gob. It also
		preserves sharing among struct pointers (but not other forms of sharing, like
		other pointer types or sub-slices). These features are sufficient for
		encoding the structures of the go/ast package, which is its sole purpose.

		Encoding Scheme

		Every encoded value begins with a single byte that describes what (if
		anything) follows. There is enough information to skip over the value, since
		the decoder must be able to do that if it encounters a struct field it
		doesn't know.

		Most of the values of that initial byte can be devoted to small unsigned
		integers. For example, the number 17 is represented by the single byte 17.
		Only a few byte values have special meaning.

		The nil code indicates that the value is nil. We don't absolutely need this:
		we could always represent the nil value for a type as something that couldn't
		be mistaken for an encoded value of that type. For instance, we could use 0
		for nil in the case of slices (which always begin with the nValues code), and
		for pointers to numbers like *int, we could use something like "nBytes 0".
		But it is simpler to have a reserved value for nil.

		The nBytes code indicates that an unsigned integer N is encoded next,
		followed by N bytes of data. This is used to represent strings and byte
		slices, as well numbers bigger than can fit into the initial byte. For
		example, the string "hi" is represented as:
		  nBytes 2 'h' 'i'

		Unsigned integers that can't fit into the initial byte are encoded as byte
		sequences of length 4 or 8, holding little-endian uint32 or uint64 values. We
		use uint32s where possible to save space. We could have saved more space by
		also considering 16-byte numbers, or using a variable-length encoding like
		varints or gob's representation, but it didn't seem worth the additional
		complexity.

		The nValues code is for sequences of values whose size is known beforehand,
		like a Go slice or array. The slice []string{"hi", "bye"} is encoded as
		  nValues 2 nBytes 2 'h' 'i' nBytes 3 'b' 'y' 'e'

		The ref code is used to refer to an earlier encoded value. It is followed by
		a uint denoting the index data of the value to use.

		The start and end codes delimit a value whose length is unknown beforehand.
		It is used for structs.

	      generate.go


Package-Level Type Names (total 8, in which 2 are exported)


	/* sort exporteds by:  |  */
	
		A Decoder decodes a Go value encoded by an Encoder.
		To use a Decoder:
		- Pass NewDecoder the return value of Encoder.Bytes.
		- Call the Decode method once for each call to Encoder.Encode.

		
			
		
			
				Decode decodes a value encoded with Encoder.Encode.

			
				DecodeAny decodes a value encoded by EncodeAny.

			
				DecodeBool decodes a bool.

			
				DecodeBytes decodes a byte slice.
				It does no copying.

			
				DecodeFloat decodes a float64.

			
				DecodeInt decodes a signed integer.

			
				DecodeString decodes a string.

			
				DecodeUint decodes a uint64.

			
				NextStructField should be called by a struct decoder in a loop.
				It returns the field number of the next encoded field, or -1
				if there are no more fields.

			
				StartList should be called before decoding any sequence of variable-length
				values. It returns -1 if the encoded list was nil. Otherwise, it returns the
				length of the sequence.

			
				StartStruct should be called before decoding a struct pointer. If it returns
				false, decoding should not proceed. If it returns true and the second return
				value is non-nil, it is a reference to a previous value and should be used
				instead of proceeding with decoding.

			
				StoreRef should be called by a struct decoder immediately after it allocates
				a struct pointer.

			
				UnknownField should be called by a struct decoder
				when it sees a field number that it doesn't know.

			
		
			func NewDecoder(data []byte) *Decoder
		
			


	
		An Encoder encodes Go values into a sequence of bytes.
		To use an Encoder:
		- Create one with NewEncoder.
		- Call the Encode method one or more times.
		- Retrieve the resulting bytes by calling Bytes.

		
			
		
			
				Bytes returns the encoded byte slice.

			
				Encode encodes x.

			
				EncodeAny encodes a Go type. The type must have
				been registered with Register.

			
				EncodeBool encodes a bool.

			
				EncodeBytes encodes a byte slice.

			
				EncodeFloat encodes a float64.

			
				EncodeInt encodes a signed integer.

			(*T) EncodeNil()
			
				EncodeString encodes a string.

			
				EncodeUint encodes a uint64.

			
				EndStruct should be called after encoding a struct.

			
				StartList should be called before encoding any sequence of variable-length
				values.

			
				StartStruct should be called before encoding a struct pointer. The isNil
				argument says whether the pointer is nil. The p argument is the struct
				pointer. If StartStruct returns false, encoding should not proceed.

			
		
			func NewEncoder() *Encoder
		
			


	


Package-Level Functions (total 16, in which 4 are exported)


	
		GenerateFile writes encoders and decoders to filename.
		It generates code for the type of each given value, as well
		as any types they depend on.
		packageName is the name following the file's package declaration.


	
		NewDecoder returns a Decoder for the given bytes.


	
		NewEncoder returns an Encoder.


	
		Register records the type of x for use by Encoders and Decoders.


	


Package-Level Variables (total 4, none are exported)

	


Package-Level Constants (total 18, none are exported)