Implement duration formatting.

Author: joe-mann

duration.go

@@ -1,32 +1,18 @@
 package chrono
 
-import "math"
+import (
+	"math"
+	"strconv"
+)
 
 type Duration struct {
-	secs uint64
+	secs int64
 	nsec uint32
 }
 
-type Extent float64
-
-// Common time-based durations relative to 1 nanosecond.
-const (
-	Nanosecond  Extent = 1
-	Microsecond        = 1000 * Nanosecond
-	Millisecond        = 1000 * Microsecond
-	Second             = 1000 * Millisecond
-	Minute             = 60 * Second
-	Hour               = 60 * Minute
-)
-
 func DurationOf(v Extent) Duration {
-	secs := v / 1e9
-	if secs > math.MaxUint64 {
-		panic("v overflows Duration")
-	}
-
 	return Duration{
-		secs: uint64(v / 1e9),
+		secs: int64(v / 1e9),
 		nsec: uint32(math.Mod(float64(v), 1e9)),
 	}
 }
@@ -38,7 +24,7 @@ func (d Duration) Add(d2 Duration) Duration {
 	}
 
 	return Duration{
-		secs: uint64(nsec / 1e9),
+		secs: int64(nsec / 1e9),
 		nsec: uint32(math.Mod(nsec, 1e9)),
 	}
 }
@@ -67,6 +53,84 @@ func (d Duration) Hours() float64 {
 	return float64(d.secs)/(60*60) + float64(d.nsec)/(1e9*60*60)
 }
 
+type Designator string
+
+const (
+	Hours   Designator = "H"
+	Minutes Designator = "M"
+	Seconds Designator = "S"
+)
+
+// Format the duration according to ISO 8601.
+// The output consists of only the time component - the period component is never included.
+// Thus the output always consists of "PT" followed by at least one unit of the time component (hours, minutes, seconds).
+//
+// The default format, obtained by calling the function with no arguments, consists of the most significant non-zero units,
+// presented non-breaking but trimmed.
+// 5 minutes is formatted as PT5M, trimming 0-value hours and seconds.
+// 1 hour and 5 seconds is formatted at PT1H0M5S, ensuring the sequence of units is not broken.
+//
+// A list of designators can be optionally passed to the function in order to configure which units are included.
+// When passed, only those specified units are included in the formatted string, and are present regardless of whether their value is 0.
+//
+// Fractional values are automatically applied to the least significant unit, if applicable.
+// In order to format only integers, the round functions should be used before calling this function.
+func (d Duration) Format(exclusive ...Designator) string {
+	var values map[Designator]float64
+	if len(exclusive) >= 1 {
+		values = make(map[Designator]float64, 3)
+		for _, d := range exclusive {
+			values[d] = 0
+		}
+	}
+
+	_, h := values[Hours]
+	_, m := values[Minutes]
+	_, s := values[Seconds]
+
+	switch {
+	case h && (m || s):
+		values[Hours] = float64(d.secs / 3600)
+	case h:
+		values[Hours] = (float64(d.secs) / 3600) + (float64(d.nsec) / 3.6e12)
+	}
+
+	switch {
+	case m && s && h:
+		values[Minutes] = float64((d.secs % 3600) / 60)
+	case m && s:
+		values[Minutes] = float64(d.secs / 60)
+	case m && h:
+		values[Minutes] = (float64(d.secs%3600) / 60) + (float64(d.nsec) / 6e10)
+	case m:
+		values[Minutes] = (float64(d.secs) / 60) + (float64(d.nsec) / 6e10)
+	}
+
+	switch {
+	case s && m:
+		values[Seconds] = float64(d.secs%60) + (float64(d.nsec) / 1e9)
+	case s && h:
+		values[Seconds] = float64(d.secs%3600) + (float64(d.nsec) / 1e9)
+	case s:
+		values[Seconds] = float64(d.secs) + (float64(d.nsec) / 1e9)
+	}
+
+	out := "PT"
+	if v, ok := values[Hours]; ok {
+		out += strconv.FormatFloat(v, 'f', -1, 64) + "H"
+	}
+
+	if v, ok := values[Minutes]; ok {
+		out += strconv.FormatFloat(v, 'f', -1, 64) + "M"
+	}
+
+	if v, ok := values[Seconds]; ok {
+		out += strconv.FormatFloat(v, 'f', -1, 64) + "S"
+	}
+
+	return out
+}
+
 // MinDuration returns the minimum allowed Duration of 0 ns.
 func MinDuration() *Duration {
 	return &minDuration
@@ -79,4 +143,4 @@ func MaxDuration() *Duration {
 
 var minDuration = Duration{secs: 0, nsec: 0}
 
-var maxDuration = Duration{secs: math.MaxUint64, nsec: 1e9 - 1}
+var maxDuration = Duration{secs: math.MaxInt64, nsec: 1e9 - 1}

duration_test.go

@@ -8,7 +8,7 @@ import (
 	"github.com/go-chrono/chrono"
 )
 
-func TestOfDuration(t *testing.T) {
+func TestDurationOf(t *testing.T) {
 	for _, tt := range []struct {
 		name string
 		of   chrono.Extent
@@ -41,8 +41,8 @@ func TestOfDuration(t *testing.T) {
 		},
 		{
 			name: "of hours",
-			of:   2.5 * chrono.Hour,
-			nsec: 9000000000000,
+			of:   2 * chrono.Hour,
+			nsec: 7200000000000,
 		},
 	} {
 		t.Run(tt.name, func(t *testing.T) {
@@ -108,3 +108,62 @@ func TestDurationUnits(t *testing.T) {
 		})
 	}
 }
+
+func TestDurationFormat(t *testing.T) {
+	for _, tt := range []struct {
+		name      string
+		of        chrono.Extent
+		exclusive []chrono.Designator
+		expected  string
+	}{
+		{
+			name:      "exclusive hms",
+			of:        1*chrono.Hour + 15*chrono.Minute + 30*chrono.Second + 500*chrono.Millisecond,
+			exclusive: []chrono.Designator{chrono.Hours, chrono.Minutes, chrono.Seconds},
+			expected:  "PT1H15M30.5S",
+		},
+		{
+			name:      "exclusive hm",
+			of:        1*chrono.Hour + 15*chrono.Minute + 30*chrono.Second + 600*chrono.Millisecond,
+			exclusive: []chrono.Designator{chrono.Hours, chrono.Minutes},
+			expected:  "PT1H15.51M",
+		},
+		{
+			name:      "exclusive hs",
+			of:        12*chrono.Hour + 1*chrono.Minute + 30*chrono.Second + 500*chrono.Millisecond,
+			exclusive: []chrono.Designator{chrono.Hours, chrono.Seconds},
+			expected:  "PT12H90.5S",
+		},
+		{
+			name:      "exclusive h",
+			of:        1*chrono.Hour + 30*chrono.Minute + 36*chrono.Second + 36*chrono.Millisecond,
+			exclusive: []chrono.Designator{chrono.Hours},
+			expected:  "PT1.51001H",
+		},
+		{
+			name:      "exclusive ms",
+			of:        1*chrono.Hour + 15*chrono.Minute + 30*chrono.Second + 500*chrono.Millisecond,
+			exclusive: []chrono.Designator{chrono.Minutes, chrono.Seconds},
+			expected:  "PT75M30.5S",
+		},
+		{
+			name:      "exclusive m",
+			of:        1*chrono.Hour + 15*chrono.Minute + 30*chrono.Second + 600*chrono.Millisecond,
+			exclusive: []chrono.Designator{chrono.Minutes},
+			expected:  "PT75.51M",
+		},
+		{
+			name:      "exclusive s",
+			of:        1*chrono.Hour + 15*chrono.Minute + 30*chrono.Second + 500*chrono.Millisecond,
+			exclusive: []chrono.Designator{chrono.Seconds},
+			expected:  "PT4530.5S",
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			d := chrono.DurationOf(tt.of)
+			if out := d.Format(tt.exclusive...); out != tt.expected {
+				t.Fatalf("formatted duration = %s, want %s", out, tt.expected)
+			}
+		})
+	}
+}

extent.go

@@ -0,0 +1,54 @@
+package chrono
+
+type Extent int64
+
+// Common time-based durations relative to 1 nanosecond.
+const (
+	Nanosecond  Extent = 1
+	Microsecond        = 1000 * Nanosecond
+	Millisecond        = 1000 * Microsecond
+	Second             = 1000 * Millisecond
+	Minute             = 60 * Second
+	Hour               = 60 * Minute
+)
+
+func (e Extent) Nanoseconds() int64 {
+	return int64(e)
+}
+
+func (e Extent) Microseconds() float64 {
+	micros := e / Second
+	nsec := e % Second
+	return float64(micros) + float64(nsec)/1e3
+}
+
+func (e Extent) Milliseconds() float64 {
+	millis := e / Second
+	nsec := e % Second
+	return float64(millis) + float64(nsec)/1e6
+}
+
+func (e Extent) Seconds() float64 {
+	sec := e / Second
+	nsec := e % Second
+	return float64(sec) + float64(nsec)/1e9
+}
+
+func (e Extent) Minutes() float64 {
+	min := e / Minute
+	nsec := e % Minute
+	return float64(min) + float64(nsec)/(60*1e9)
+}
+
+func (e Extent) Hours() float64 {
+	hour := e / Hour
+	nsec := e % Hour
+	return float64(hour) + float64(nsec)/(60*60*1e9)
+}
+
+func (e Extent) Truncate(m Extent) Extent {
+	if e <= 0 {
+		return e + e%m
+	}
+	return e - e%m
+}

instant.go

@@ -4,14 +4,14 @@ import "strconv"
 
 // Instant represents an instantaneous point in time with nanosecond resolution.
 type Instant struct {
-	*int64
+	v *int64
 }
 
 // Now returns the Instant that represents the current point in time.
 func Now() Instant {
 	now := monotime()
 	return Instant{
-		int64: &now,
+		v: &now,
 	}
 }
 
@@ -21,32 +21,32 @@ func (i Instant) Elapsed() Duration {
 }
 
 func (i Instant) String() string {
-	return strconv.FormatInt(*i.int64, 10)
+	return strconv.FormatInt(*i.v, 10)
 }
 
 // Until returns the Duration that represents the elapsed time from i to v.
 func (i Instant) Until(v Instant) Duration {
 	switch {
-	case i.int64 == nil:
+	case i.v == nil:
 		panic("i is not initialized")
-	case v.int64 == nil:
+	case v.v == nil:
 		panic("v is not initialized")
 	}
 
-	iv, vv := *i.int64, *v.int64
+	iv, vv := *i.v, *v.v
 	if vv < iv {
 		panic("v is smaller than i")
 	}
 
 	d := vv - iv
 	return Duration{
-		secs: uint64(d / 1e9),
+		secs: d / 1e9,
 		nsec: uint32(d % 1e9),
 	}
 }
 
 func instant(t int64) Instant {
 	return Instant{
-		int64: &t,
+		v: &t,
 	}
 }