feat(civil): implement database/sql.Scanner|Valuer (#1145) (#11808)

Fixes #1145. I wasn't sure how to test these in the context of this repo.

Questions:
- I tried to be comprehensive in the Scan functions, I'm not sure exactly what types of values to expect
- For the Valuer, I assumed that most/all databases should accept the ISO string values, but that may not be globally true

Author: derekperkins

civil/civil.go

@@ -22,6 +22,7 @@
 package civil
 
 import (
+	"database/sql/driver"
 	"fmt"
 	"time"
 )
@@ -158,6 +159,46 @@ func (d *Date) UnmarshalText(data []byte) error {
 	return err
 }
 
+// Value implements the database/sql/driver Valuer interface.
+func (d Date) Value() (driver.Value, error) {
+	return d.String(), nil
+}
+
+// Scan implements the database/sql Scanner interface.
+func (d *Date) Scan(v any) error {
+	switch vt := v.(type) {
+	case time.Time:
+		*d = DateOf(vt)
+	case *time.Time:
+		if vt != nil {
+			*d = DateOf(*vt)
+		}
+	case string:
+		var err error
+		*d, err = ParseDate(vt)
+		return err
+	case *string:
+		var err error
+		if vt != nil {
+			*d, err = ParseDate(*vt)
+		}
+		return err
+	case []byte:
+		var err error
+		*d, err = ParseDate(string(vt))
+		return err
+	case *[]byte:
+		var err error
+		if vt != nil {
+			*d, err = ParseDate(string(*vt))
+		}
+		return err
+	default:
+		return fmt.Errorf("unsupported scan type for Date: %T", v)
+	}
+	return nil
+}
+
 // A Time represents a time with nanosecond precision.
 //
 // This type does not include location information, and therefore does not
@@ -262,6 +303,46 @@ func (t *Time) UnmarshalText(data []byte) error {
 	return err
 }
 
+// Value implements the database/sql/driver Valuer interface.
+func (t Time) Value() (driver.Value, error) {
+	return t.String(), nil
+}
+
+// Scan implements the database/sql Scanner interface.
+func (t *Time) Scan(v any) error {
+	switch vt := v.(type) {
+	case time.Time:
+		*t = TimeOf(vt)
+	case *time.Time:
+		if vt != nil {
+			*t = TimeOf(*vt)
+		}
+	case string:
+		var err error
+		*t, err = ParseTime(vt)
+		return err
+	case *string:
+		var err error
+		if vt != nil {
+			*t, err = ParseTime(*vt)
+		}
+		return err
+	case []byte:
+		var err error
+		*t, err = ParseTime(string(vt))
+		return err
+	case *[]byte:
+		var err error
+		if vt != nil {
+			*t, err = ParseTime(string(*vt))
+		}
+		return err
+	default:
+		return fmt.Errorf("unsupported scan type for Time: %T", v)
+	}
+	return nil
+}
+
 // A DateTime represents a date and time.
 //
 // This type does not include location information, and therefore does not
@@ -365,3 +446,43 @@ func (dt *DateTime) UnmarshalText(data []byte) error {
 	*dt, err = ParseDateTime(string(data))
 	return err
 }
+
+// Value implements the database/sql/driver Valuer interface.
+func (dt DateTime) Value() (driver.Value, error) {
+	return dt.String(), nil
+}
+
+// Scan implements the database/sql Scanner interface.
+func (dt *DateTime) Scan(v any) error {
+	switch vt := v.(type) {
+	case time.Time:
+		*dt = DateTimeOf(vt)
+	case *time.Time:
+		if vt != nil {
+			*dt = DateTimeOf(*vt)
+		}
+	case string:
+		var err error
+		*dt, err = ParseDateTime(vt)
+		return err
+	case *string:
+		var err error
+		if vt != nil {
+			*dt, err = ParseDateTime(*vt)
+		}
+		return err
+	case []byte:
+		var err error
+		*dt, err = ParseDateTime(string(vt))
+		return err
+	case *[]byte:
+		var err error
+		if vt != nil {
+			*dt, err = ParseDateTime(string(*vt))
+		}
+		return err
+	default:
+		return fmt.Errorf("unsupported scan type for DateTime: %T", v)
+	}
+	return nil
+}

civil/civil_test.go

@@ -15,6 +15,8 @@
 package civil
 
 import (
+	"database/sql"
+	"database/sql/driver"
 	"encoding/json"
 	"testing"
 	"time"
@@ -705,3 +707,105 @@ func TestUnmarshalJSON(t *testing.T) {
 		}
 	}
 }
+
+func TestValuer(t *testing.T) {
+	for _, test := range []struct {
+		data driver.Valuer
+		want interface{}
+	}{
+		{&Date{1987, 4, 15}, `1987-04-15`},
+		{&Time{18, 54, 2, 0}, `18:54:02`},
+		{&DateTime{Date{1987, 4, 15}, Time{18, 54, 2, 0}}, `1987-04-15T18:54:02`},
+	} {
+		got, err := test.data.Value()
+		if err != nil {
+			t.Fatalf("%s: %v", test.data, err)
+		}
+		if !cmp.Equal(got, test.want) {
+			t.Errorf("%s: got %#v, want %#v", test.data, test.data, test.want)
+		}
+	}
+}
+
+func TestScanner(t *testing.T) {
+	var d Date
+	var tm Time
+	var dt DateTime
+	for _, test := range []struct {
+		data interface{}
+		ptr  sql.Scanner
+		want interface{}
+	}{
+		// time input
+		{time.Date(1987, 4, 15, 18, 54, 2, 0, time.UTC), &d, &Date{1987, 4, 15}},
+		{time.Date(1987, 4, 15, 18, 54, 2, 0, time.UTC), &tm, &Time{18, 54, 2, 0}},
+		{time.Date(1987, 4, 15, 18, 54, 2, 0, time.UTC), &dt, &DateTime{Date{1987, 4, 15}, Time{18, 54, 2, 0}}},
+
+		// *time input
+		{toPtr(time.Date(1987, 4, 15, 18, 54, 2, 0, time.UTC)), &d, &Date{1987, 4, 15}},
+		{toPtr(time.Date(1987, 4, 15, 18, 54, 2, 0, time.UTC)), &tm, &Time{18, 54, 2, 0}},
+		{toPtr(time.Date(1987, 4, 15, 18, 54, 2, 0, time.UTC)), &dt, &DateTime{Date{1987, 4, 15}, Time{18, 54, 2, 0}}},
+
+		// string input
+		{`1987-04-15`, &d, &Date{1987, 4, 15}},
+		{`18:54:02`, &tm, &Time{18, 54, 2, 0}},
+		{`1987-04-15T18:54:02`, &dt, &DateTime{Date{1987, 4, 15}, Time{18, 54, 2, 0}}},
+
+		// *string input
+		{toPtr(`1987-04-15`), &d, &Date{1987, 4, 15}},
+		{toPtr(`18:54:02`), &tm, &Time{18, 54, 2, 0}},
+		{toPtr(`1987-04-15T18:54:02`), &dt, &DateTime{Date{1987, 4, 15}, Time{18, 54, 2, 0}}},
+
+		// []byte input
+		{[]byte(`1987-04-15`), &d, &Date{1987, 4, 15}},
+		{[]byte(`18:54:02`), &tm, &Time{18, 54, 2, 0}},
+		{[]byte(`1987-04-15T18:54:02`), &dt, &DateTime{Date{1987, 4, 15}, Time{18, 54, 2, 0}}},
+
+		// *[]byte input
+		{toPtr([]byte(`1987-04-15`)), &d, &Date{1987, 4, 15}},
+		{toPtr([]byte(`18:54:02`)), &tm, &Time{18, 54, 2, 0}},
+		{toPtr([]byte(`1987-04-15T18:54:02`)), &dt, &DateTime{Date{1987, 4, 15}, Time{18, 54, 2, 0}}},
+	} {
+		if err := test.ptr.Scan(test.data); err != nil {
+			t.Fatalf("%s: %v", test.data, err)
+		}
+		if !cmp.Equal(test.ptr, test.want) {
+			t.Errorf("%s: got %#v, want %#v", test.data, test.ptr, test.want)
+		}
+	}
+
+	// expected test failures
+	for _, test := range []struct {
+		data interface{}
+		ptr  sql.Scanner
+		want string
+	}{
+		// int64 input
+		{int64(12345), &d, "unsupported scan type for Date: int64"},
+		{int64(12345), &tm, "unsupported scan type for Time: int64"},
+		{int64(12345), &dt, "unsupported scan type for DateTime: int64"},
+
+		// float64 input
+		{float64(0.9876), &d, "unsupported scan type for Date: float64"},
+		{float64(0.9876), &tm, "unsupported scan type for Time: float64"},
+		{float64(0.9876), &dt, "unsupported scan type for DateTime: float64"},
+
+		// bool input
+		{true, &d, "unsupported scan type for Date: bool"},
+		{true, &tm, "unsupported scan type for Time: bool"},
+		{true, &dt, "unsupported scan type for DateTime: bool"},
+	} {
+		err := test.ptr.Scan(test.data)
+		if err == nil {
+			t.Errorf("%q, got nil, want error", test.data)
+			continue
+		}
+		if err.Error() != test.want {
+			t.Errorf("%v: got %s, want %s", test.data, err, test.want)
+		}
+	}
+}
+
+func toPtr[V any](v V) *V {
+	return &v
+}