DateTime and the different zero values used. (#148)

* DateTime and the different zero values used.

* fixed the documentation for NewDateTime() to state explicitly that it does
  not yield the zero value. This value is checked against IsUNIXZero().
* introduced a new method MakeDateTime() for users who want a zero value
  that checks against IsZero().
* fixes #141

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

* addressed review comments

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

---------

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

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,19 +122,31 @@ 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.
 //
 // 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)

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) {