docs and tweaks

README.md

@@ -1,3 +1,15 @@
 null is a library with opinions on how to deal with nullable SQL and JSON values
 
-BSD licensed.
+### String
+A nullable string. Implements `sql.Scanner`, `encoding.Marshaler` and `encoding.TextUnmarshaler`, providing support for JSON and XML. 
+
+Will marshal to a blank string if null. Blank string input produces a null String. In other words, null values and empty values are considered equivalent.
+
+`UnmarshalJSON` supports `sql.NullString` input. 
+
+### Bugs
+`json`'s `",omitempty"` struct tag does not work correctly right now. It will never omit a null or empty String. This should be [fixed in Go 1.4](https://code.google.com/p/go/issues/detail?id=4357).
+
+
+### License
+BSD

string.go

@@ -1,3 +1,4 @@
+// Package null provides an opinionated yet reasonable way of handling null values.
 package null
 
 import (
@@ -5,11 +6,18 @@ import (
 	"encoding/json"
 )
 
+// String is a nullable string.
 type String struct {
 	sql.NullString
 }
 
+// StringFrom creates a new String that will be null if s is blank.
 func StringFrom(s string) String {
+	return NewString(s, s != "")
+}
+
+// NewString creates a new String
+func NewString(s string, valid bool) String {
 	return String{
 		NullString: sql.NullString{
 			String: s,
@@ -18,6 +26,9 @@ func StringFrom(s string) String {
 	}
 }
 
+// UnmarshalJSON implements json.Unmarshaler.
+// It supports string and null input. Blank string input produces a null String.
+// It also supports unmarshalling a sql.NullString.
 func (s *String) UnmarshalJSON(data []byte) error {
 	var err error
 	var v interface{}
@@ -31,14 +42,28 @@ func (s *String) UnmarshalJSON(data []byte) error {
 		s.Valid = false
 		return nil
 	}
-	s.Valid = err == nil
+	s.Valid = (err == nil) && (s.String != "")
 	return err
 }
 
-func (s String) MarshalJSON() ([]byte, error) {
-	return json.Marshal(s.String)
+// MarshalText implements encoding.TextMarshaler.
+// It will encode a blank string when this String is null.
+func (s String) MarshalText() ([]byte, error) {
+	if !s.Valid {
+		return []byte{}, nil
+	}
+	return []byte(s.String), nil
 }
 
+// UnmarshalText implements encoding.TextUnmarshaler.
+// It will unmarshal to a null String if the input is a blank string.
+func (s *String) UnmarshalText(text []byte) error {
+	s.String = string(text)
+	s.Valid = s.String != ""
+	return nil
+}
+
+// Pointer returns a pointer to this String's value, or a nil pointer if this String is null.
 func (s String) Pointer() *string {
 	if s.String == "" {
 		return nil
@@ -46,7 +71,7 @@ func (s String) Pointer() *string {
 	return &s.String
 }
 
-// IsZero returns true for invalid strings, for future omitempty support (Go 1.4?)
+// IsZero returns true for null strings, for future omitempty support. (Go 1.4?)
 func (s String) IsZero() bool {
 	return !s.Valid
 }

string_test.go

@@ -6,11 +6,16 @@ import (
 )
 
 var (
-	stringJSON     = []byte(`"test"`)
-	nullStringJSON = []byte(`{"String":"test","Valid":true}`)
-	nullJSON       = []byte(`null`)
+	stringJSON      = []byte(`"test"`)
+	blankStringJSON = []byte(`""`)
+	nullStringJSON  = []byte(`{"String":"test","Valid":true}`)
+	nullJSON        = []byte(`null`)
 )
 
+type stringInStruct struct {
+	Test String `json:"test,omitempty"`
+}
+
 func TestStringFrom(t *testing.T) {
 	str := StringFrom("test")
 	assert(t, str, "StringFrom() string")
@@ -30,6 +35,11 @@ func TestUnmarshalString(t *testing.T) {
 	maybePanic(err)
 	assert(t, ns, "null string object json")
 
+	var blank String
+	err = json.Unmarshal(blankStringJSON, &blank)
+	maybePanic(err)
+	assertNull(t, blank, "blank string json")
+
 	var null String
 	err = json.Unmarshal(nullJSON, &null)
 	maybePanic(err)
@@ -46,9 +56,17 @@ func TestMarshalString(t *testing.T) {
 	null := StringFrom("")
 	data, err = json.Marshal(null)
 	maybePanic(err)
-	assertJSONEquals(t, data, `""`, "non-empty json marshal")
+	assertJSONEquals(t, data, `""`, "empty json marshal")
 }
 
+// Tests omitempty... broken until Go 1.4
+// func TestMarshalStringInStruct(t *testing.T) {
+// 	obj := stringInStruct{Test: StringFrom("")}
+// 	data, err := json.Marshal(obj)
+// 	maybePanic(err)
+// 	assertJSONEquals(t, data, `{}`, "null string in struct")
+// }
+
 func TestPointer(t *testing.T) {
 	str := StringFrom("test")
 	ptr := str.Pointer()