commit 2baaa31d2ee81a87ca28bb2e057b67a98264b296
parent d54820a1ed937e055d4267c244581dfa7149726a
Author: francoispqt <francois@parquet.ninja>
Date: Sun, 28 Oct 2018 22:45:10 +0800
add examples files with godoc format
Diffstat:
5 files changed, 106 insertions(+), 98 deletions(-)
diff --git a/decode.go b/decode.go
@@ -51,10 +51,8 @@ func UnmarshalJSONObject(data []byte, v UnmarshalerJSONObject) error {
// Unmarshal parses the JSON-encoded data and stores the result in the value pointed to by v.
// If v is nil, not an implementation of UnmarshalerJSONObject or UnmarshalerJSONArray or not one of the following types:
-//
-// *string, **string, *int, **int, *int8, **int8, *int16, **int16, *int32, **int32, *int64, **int64, *uint8, **uint8, *uint16, **uint16,
-// *uint32, **uint32, *uint64, **uint64, *float64, **float64, *float32, **float32, *bool, **bool,
-//
+// *string, **string, *int, **int, *int8, **int8, *int16, **int16, *int32, **int32, *int64, **int64, *uint8, **uint8, *uint16, **uint16,
+// *uint32, **uint32, *uint64, **uint64, *float64, **float64, *float32, **float32, *bool, **bool
// Unmarshal returns an InvalidUnmarshalError.
//
//
@@ -62,20 +60,6 @@ func UnmarshalJSONObject(data []byte, v UnmarshalerJSONObject) error {
// overflows the target type, Unmarshal skips that field and completes the unmarshaling as best it can.
// If no more serious errors are encountered, Unmarshal returns an UnmarshalTypeError describing the earliest such error.
// In any case, it's not guaranteed that all the remaining fields following the problematic one will be unmarshaled into the target object.
-//
-// Example with a valid `*string` type:
-// var data = []byte(`"gojay"`)
-// var str string
-// var err = gojay.Unmarshal(data, &str)
-//
-// fmt.Println(err) // nil
-//
-// Example with an unknown `*struct{}` type:
-// var data = []byte(`"gojay"`)
-// var someStruct = struct{}{}
-// var err = gojay.Unmarshal(data, &someStruct)
-//
-// fmt.Println(err) // "Cannot unmarshal JSON to type '*struct{}'"
func Unmarshal(data []byte, v interface{}) error {
var err error
var dec *Decoder
@@ -266,11 +250,8 @@ type Decoder struct {
//
// See the documentation for Unmarshal for details about the conversion of JSON into a Go value.
// The differences between Decode and Unmarshal are:
-//
-// - Decode reads from an io.Reader in the Decoder, whereas Unmarshal reads from a []byte
-//
-// - Decode leaves to the user the option of borrowing and releasing a Decoder, whereas Unmarshal internally always
-// borrows a Decoder and releases it when the unmarshaling is completed
+// - Decode reads from an io.Reader in the Decoder, whereas Unmarshal reads from a []byte
+// - Decode leaves to the user the option of borrowing and releasing a Decoder, whereas Unmarshal internally always borrows a Decoder and releases it when the unmarshaling is completed
func (dec *Decoder) Decode(v interface{}) error {
if dec.isPooled == 1 {
panic(InvalidUsagePooledDecoderError("Invalid usage of pooled decoder"))
diff --git a/decode_array.go b/decode_array.go
@@ -181,12 +181,12 @@ func (dec *Decoder) skipArray() (int, error) {
// strSlice := make([]string, 0)
// dec := gojay.NewDecoder(io.Reader)
//
-// err := dec.DecodeArray( dec.DecodeArray(gojay.DecodeArrayFunc(func(dec *gojay.Decoder) error {
+// err := dec.DecodeArray( dec.DecodeArray(gojay.DecodeArrayFunc(func(dec *gojay.Decoder) error {
// var str string
// if err := dec.AddString(&str); err != nil {
// return err
// }
-// strSlice = append(strSplice, str)
+// strSlice = append(strSplice, str)
// return nil
// })))
type DecodeArrayFunc func(*Decoder) error
diff --git a/decode_example_test.go b/decode_example_test.go
@@ -0,0 +1,49 @@
+package gojay_test
+
+import (
+ "fmt"
+ "log"
+ "strings"
+
+ "github.com/francoispqt/gojay"
+)
+
+func ExampleUnmarshal_string() {
+ data := []byte(`"gojay"`)
+ var str string
+ err := gojay.Unmarshal(data, &str)
+ if err != nil {
+ log.Fatal(err)
+ }
+ fmt.Println(str) // true
+}
+
+func ExampleUnmarshal_bool() {
+ data := []byte(`true`)
+ var b bool
+ err := gojay.Unmarshal(data, &b)
+ if err != nil {
+ log.Fatal(err)
+ }
+ fmt.Println(b) // true
+}
+
+func ExampleUnmarshal_invalidType() {
+ data := []byte(`"gojay"`)
+ someStruct := struct{}{}
+ err := gojay.Unmarshal(data, &someStruct)
+
+ fmt.Println(err) // "Cannot unmarshal JSON to type '*struct{}'"
+}
+
+func ExampleDecode_string() {
+ var str string
+ dec := gojay.BorrowDecoder(strings.NewReader(`"gojay"`))
+ err := dec.Decode(&str)
+ dec.Release()
+
+ if err != nil {
+ log.Fatal(err)
+ }
+ fmt.Println(str) // "gojay"
+}
diff --git a/encode.go b/encode.go
@@ -4,45 +4,14 @@ import (
"encoding/json"
"fmt"
"io"
- "reflect"
)
var nullBytes = []byte("null")
-// MarshalJSONObject returns the JSON encoding of v.
+// MarshalJSONArray returns the JSON encoding of v, an implementation of MarshalerJSONArray.
//
-// It takes a struct implementing Marshaler to a JSON slice of byte
-// it returns a slice of bytes and an error.
-// Example with an Marshaler:
-// type TestStruct struct {
-// id int
-// }
-// func (s *TestStruct) MarshalJSONObject(enc *gojay.Encoder) {
-// enc.AddIntKey("id", s.id)
-// }
-// func (s *TestStruct) IsNil() bool {
-// return s == nil
-// }
//
-// func main() {
-// test := &TestStruct{
-// id: 123456,
-// }
-// b, _ := gojay.Marshal(test)
-// fmt.Println(b) // {"id":123456}
-// }
-func MarshalJSONObject(v MarshalerJSONObject) ([]byte, error) {
- enc := BorrowEncoder(nil)
- enc.grow(512)
- defer enc.Release()
- return enc.encodeObject(v)
-}
-
-// MarshalJSONArray returns the JSON encoding of v.
-//
-// It takes an array or a slice implementing Marshaler to a JSON slice of byte
-// it returns a slice of bytes and an error.
-// Example with an Marshaler:
+// Example:
// type TestSlice []*TestStruct
//
// func (t TestSlice) MarshalJSONArray(enc *Encoder) {
@@ -69,64 +38,47 @@ func MarshalJSONArray(v MarshalerJSONArray) ([]byte, error) {
return enc.buf, nil
}
-// Marshal returns the JSON encoding of v.
-//
-// Marshal takes interface v and encodes it according to its type.
-// Basic example with a string:
-// b, err := gojay.Marshal("test")
-// fmt.Println(b) // "test"
+// MarshalJSONObject returns the JSON encoding of v, an implementation of MarshalerJSONObject.
//
-// If v implements Marshaler or Marshaler interface
-// it will call the corresponding methods.
-//
-// If a struct, slice, or array is passed and does not implement these interfaces
-// it will return a a non nil InvalidUnmarshalError error.
-// Example with an Marshaler:
-// type TestStruct struct {
+// Example:
+// type Object struct {
// id int
// }
-// func (s *TestStruct) MarshalJSONObject(enc *gojay.Encoder) {
-// enc.AddIntKey("id", s.id)
+// func (s *Object) MarshalJSONObject(enc *gojay.Encoder) {
+// enc.IntKey("id", s.id)
// }
-// func (s *TestStruct) IsNil() bool {
+// func (s *Object) IsNil() bool {
// return s == nil
// }
//
// func main() {
-// test := &TestStruct{
+// test := &Object{
// id: 123456,
// }
// b, _ := gojay.Marshal(test)
// fmt.Println(b) // {"id":123456}
// }
+func MarshalJSONObject(v MarshalerJSONObject) ([]byte, error) {
+ enc := BorrowEncoder(nil)
+ enc.grow(512)
+ defer enc.Release()
+ return enc.encodeObject(v)
+}
+
+// Marshal returns the JSON encoding of v.
+//
+// If v is nil, not an implementation MarshalerJSONObject or MarshalerJSONArray or not one of the following types:
+// string, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float64, float32, bool
+// Marshal returns an InvalidMarshalError.
func Marshal(v interface{}) ([]byte, error) {
return marshal(v, false)
}
// MarshalAny returns the JSON encoding of v.
//
-// MarshalAny takes interface v and encodes it according to its type.
-// Basic example with a string:
-// b, err := gojay.Marshal("test")
-// fmt.Println(b) // "test"
-//
-// If v implements Marshaler or Marshaler interface
-// it will call the corresponding methods.
-//
-// If it cannot find any supported type it will be marshalled though default Go "json" package.
-// Warning, this function can be slower, than a default "Marshal"
-//
-// type TestStruct struct {
-// id int
-// }
-//
-// func main() {
-// test := &TestStruct{
-// id: 123456,
-// }
-// b, _ := gojay.Marshal(test)
-// fmt.Println(b) // {"id": 123456}
-// }
+// If v is nil, not an implementation MarshalerJSONObject or MarshalerJSONArray or not one of the following types:
+// string, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float64, float32, bool
+// MarshalAny falls back to "json/encoding" package to marshal the value.
func MarshalAny(v interface{}) ([]byte, error) {
return marshal(v, true)
}
@@ -178,7 +130,7 @@ func marshal(v interface{}, any bool) ([]byte, error) {
return json.Marshal(vt)
}
- return nil, InvalidMarshalError(fmt.Sprintf(invalidMarshalErrorMsg, reflect.TypeOf(vt).String()))
+ return nil, InvalidMarshalError(fmt.Sprintf(invalidMarshalErrorMsg, vt))
}
}()
diff --git a/encode_example_test.go b/encode_example_test.go
@@ -0,0 +1,26 @@
+package gojay_test
+
+import (
+ "fmt"
+ "log"
+
+ "github.com/francoispqt/gojay"
+)
+
+func ExampleMarshal_string() {
+ str := "gojay"
+ d, err := gojay.Marshal(str)
+ if err != nil {
+ log.Fatal(err)
+ }
+ fmt.Println(string(d)) // "gojay"
+}
+
+func ExampleMarshal_bool() {
+ b := true
+ d, err := gojay.Marshal(b)
+ if err != nil {
+ log.Fatal(err)
+ }
+ fmt.Println(string(d)) // true
+}
