diff --git a/time.go b/time.go index 310b112..7952aba 100644 --- a/time.go +++ b/time.go @@ -29,7 +29,8 @@ import ( ) var ( - // UnixZero sets the zero unix timestamp we want to compare against. + // UnixZero sets the zero unix UTC timestamp we want to compare against. + // // Unix 0 for an EST timezone is not equivalent to a UTC timezone. UnixZero = time.Unix(0, 0).UTC() ) @@ -121,7 +122,8 @@ func ParseDateTime(data string) (DateTime, error) { return DateTime{}, lastError } -// DateTime is a time but it serializes to ISO8601 format with millis +// DateTime is a time but it serializes to ISO8601 format with millis. +// // It knows how to read 3 different variations of a RFC3339 date time. // Most APIs we encounter want either millisecond or second precision times. // This just tries to make it worry-free. @@ -129,11 +131,22 @@ func ParseDateTime(data string) (DateTime, error) { // swagger:strfmt date-time type DateTime time.Time -// NewDateTime is a representation of zero value for DateTime type +// NewDateTime is a representation of the UNIX epoch (January 1, 1970 00:00:00 UTC) for the [DateTime] type. +// +// Notice that this is not the zero value of the [DateTime] type. +// +// You may use [DateTime.IsUNIXZero] to check against this value. func NewDateTime() DateTime { return DateTime(time.Unix(0, 0).UTC()) } +// MakeDateTime is a representation of the zero value of the [DateTime] type (January 1, year 1, 00:00:00 UTC). +// +// You may use [Datetime.IsZero] to check against this value. +func MakeDateTime() DateTime { + return DateTime(time.Time{}) +} + // String converts this time to a string func (t DateTime) String() string { return NormalizeTimeForMarshal(time.Time(t)).Format(MarshalFormat) diff --git a/time_test.go b/time_test.go index 6f2edd5..212f592 100644 --- a/time_test.go +++ b/time_test.go @@ -56,13 +56,24 @@ func TestNewDateTime(t *testing.T) { } func TestIsZero(t *testing.T) { - var empty DateTime - assert.True(t, empty.IsZero()) - assert.False(t, DateTime(time.Unix(100, 5)).IsZero()) - - // time.Unix(0,0) does not produce a true zero value struct, - // so this is expected to fail. - assert.False(t, NewDateTime().IsZero()) + t.Run("time.Unix(100,5) should not be zero", func(t *testing.T) { + assert.False(t, DateTime(time.Unix(100, 5)).IsZero()) + }) + + t.Run("NewDateTime() should not be zero", func(t *testing.T) { + // time.Unix(0,0) does not produce a true zero value struct, + // so this is expected to fail. + assert.False(t, NewDateTime().IsZero()) + }) + + t.Run("MakeDateTime() should be zero", func(t *testing.T) { + assert.True(t, MakeDateTime().IsZero()) + }) + + t.Run("empty DateTime should be zero", func(t *testing.T) { + dt := DateTime{} + assert.True(t, dt.IsZero()) + }) } func TestIsUnixZero(t *testing.T) {