time.Date normalization

.gitignore

@@ -4,8 +4,11 @@
 *.so
 
 # Folders
-_obj
-_test
+.idea/
+_obj/
+_test/
+reports/
+vendor/
 
 # Architecture specific extensions/prefixes
 *.[568vq]
@@ -22,3 +25,4 @@ _testmain.go
 *.exe
 *.test
 *.prof
+*.out

.travis.yml

@@ -1,16 +1,13 @@
 language: go
 
 go:
-  - tip
+  - '1.17'
 
 install:
   - go get -t -v ./...
   - go get github.com/mattn/goveralls
 
 script:
-  - go test -v -covermode=count -coverprofile=coverage.out ./...
-  - go tool cover -func=coverage.out
-  - $(go env GOPATH | awk 'BEGIN{FS=":"} {print $1}')/bin/goveralls -coverprofile=coverage.out -service=travis-ci -repotoken $COVERALLS_TOKEN
+  - ./build+test.sh amd64
+  - ./build+test.sh 386
 
-env:
-  secure: "kcksCWXVeZKmFUWcyi2S/j87iwUmXMxZXxA2DG9ymc11QP43QoPNSG9pBjA/DDjvzt4WdKIFphTrxVfvawii/9j3oXA1aPmAcHGu87i4iOVg4IIZ4bPZLfUo0e7s6XP5FakzegYvPP6HWV5Xr5h+Q6osrjq3czOnPY+rVII6MRrxXMOfsqo8HEER+YIOOD6vj5LV2/quY8d0XHtThqgGvQ1cz4OB3vbd4KFBl48kmfXKefTrRG1NoqoQMMpwUVzU395JIEAg1eWbGkquhWU5v13gRwk3VMVWF75jZna8TSiqWha0P5iQdaED30kNCz3poIaBI1MLdxktJxwUQJZ5AaYIMCxh7ZCiW0FXTYCRu3EoeYusTPMLqy1ghK+gIlA46sNd26cKk5/OngXRrHo/J0aF5NWjydlk5FLHfKm9ih/Y426M9nV2zYNQAcVKgO8zVNb2IkJ3e7aTB2NH4DpkvjSV4D4hlnmW9xxmo14TKF+gXJ9Hw9ssKbigRHoL6S92aQHcpkdjGGnI5YSTy1fZh/nIE3HDmx+hcK4/ZtPHj9KnXopKYxBGyNswN5Eko+q6h3BB/Q7LwALtEexdDbznwsRmcZXJsOU4chvcjAKgIAi6cbeTwq8kG5E/w8TTY2wGeRm2ZFysQu6Jf8hgTZDQTV343RG80STWeUbiD0o7/WY="

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015 The Go Authors. All rights reserved.
+Copyright (c) 2015 The Go Authors & Rick Beton. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
@@ -24,4 +24,4 @@ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,21 +1,39 @@
 # date
 
-[![GoDoc](https://img.shields.io/badge/api-Godoc-blue.svg?style=flat-square)](https://godoc.org/github.com/fxtlabs/date)
-[![Build Status](https://api.travis-ci.org/fxtlabs/date.svg?branch=master)](https://travis-ci.org/fxtlabs/date)
-[![Coverage Status](https://coveralls.io/repos/fxtlabs/date/badge.svg?branch=master&service=github)](https://coveralls.io/github/fxtlabs/date?branch=master)
+[![GoDoc](https://img.shields.io/badge/api-Godoc-blue.svg)](https://pkg.go.dev/github.com/rickb777/date)
+[![Build Status](https://api.travis-ci.org/rickb777/date.svg?branch=master)](https://travis-ci.org/rickb777/date/builds)
+[![Coverage Status](https://coveralls.io/repos/rickb777/date/badge.svg?branch=master&service=github)](https://coveralls.io/github/rickb777/date?branch=master)
+[![Go Report Card](https://goreportcard.com/badge/github.com/rickb777/date)](https://goreportcard.com/report/github.com/rickb777/date)
+[![Issues](https://img.shields.io/github/issues/rickb777/date.svg)](https://github.com/rickb777/date/issues)
 
 Package `date` provides functionality for working with dates.
 
 This package introduces a light-weight `Date` type that is storage-efficient
-and covenient for calendrical calculations and date parsing and formatting
+and convenient for calendrical calculations and date parsing and formatting
 (including years outside the [0,9999] interval).
 
-See [package documentation](https://godoc.org/github.com/fxtlabs/date) for
+It also provides
+
+ * `clock.Clock` which expresses a wall-clock style hours-minutes-seconds with millisecond precision.
+ * `period.Period` which expresses a period corresponding to the ISO-8601 form (e.g. "PT30S").
+ * `timespan.DateRange` which expresses a period between two dates.
+ * `timespan.TimeSpan` which expresses a duration of time between two instants.
+ * `view.VDate` which wraps `Date` for use in templates etc.
+
+See [package documentation](https://godoc.org/github.com/rickb777/date) for
 full documentation and examples.
 
 ## Installation
 
-    go get -u github.com/fxtlabs/date
+    go get -u github.com/rickb777/date
+
+or
+
+    dep ensure -add github.com/rickb777/date
+
+## Status
+
+This library has been in reliable production use for some time. Versioning follows the well-known semantic version pattern.
 
 ## Credits
 
@@ -25,3 +43,5 @@ many of the `Date` methods are implemented using the corresponding methods
 of the `time.Time` type and much of the documentation is copied directly
 from that package.
 
+The original [Good Work](https://github.com/fxtlabs/date) on which this was
+based was done by Filippo Tampieri at Fxtlabs.

build+test.sh

@@ -0,0 +1,46 @@
+#!/bin/bash -e
+cd "$(dirname $0)"
+PATH=$HOME/go/bin:$PATH
+unset GOPATH
+export GOARCH=${1}
+
+function v
+{
+  echo
+  echo $@
+  $@
+}
+
+if ! type -p goveralls; then
+  v go install github.com/mattn/goveralls
+fi
+
+if ! type -p shadow; then
+  v go get     golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow
+  v go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow
+fi
+
+if ! type -p goreturns; then
+  v go get     github.com/sqs/goreturns
+  v go install github.com/sqs/goreturns
+fi
+
+echo date...
+v go test -v -covermode=count -coverprofile=date.out .
+v go tool cover -func=date.out
+#[ -z "$COVERALLS_TOKEN" ] || goveralls -coverprofile=date.out -service=travis-ci -repotoken $COVERALLS_TOKEN
+
+for d in clock period timespan view; do
+  echo $d...
+  v go test -v -covermode=count -coverprofile=$d.out ./$d
+  v go tool cover -func=$d.out
+  #[ -z "$COVERALLS_TOKEN" ] || goveralls -coverprofile=$d.out -service=travis-ci -repotoken $COVERALLS_TOKEN
+done
+
+v goreturns -l -w *.go */*.go
+
+v go vet ./...
+
+v shadow ./...
+
+v go install ./datetool

clock/clock.go

@@ -0,0 +1,182 @@
+// Copyright 2015 Rick Beton. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package clock specifies a time of day with resolution to the nearest millisecond.
+package clock
+
+import (
+	"math"
+	"time"
+)
+
+// Clock specifies a time of day. It complements the existing time.Duration, applying
+// that to the time since midnight (on some arbitrary day in some arbitrary timezone).
+// The resolution is to the nearest millisecond, unlike time.Duration (which has nanosecond
+// resolution).
+//
+// It is not intended that Clock be used to represent periods greater than 24 hours nor
+// negative values. However, for such lengths of time, a fixed 24 hours per day
+// is assumed and a modulo operation Mod24 is provided to discard whole multiples of 24 hours.
+//
+// Clock is a type of integer (actually int32), so values can be compared and sorted as
+// per other integers. The constants Second, Minute, Hour and Day can be added and subtracted
+// with obvious outcomes.
+//
+// See https://en.wikipedia.org/wiki/ISO_8601#Times
+type Clock int32
+
+// Common durations - second, minute, hour and day.
+const (
+	// Second is one second; it has a similar meaning to time.Second.
+	Second Clock = Clock(time.Second / time.Millisecond)
+
+	// Minute is one minute; it has a similar meaning to time.Minute.
+	Minute Clock = Clock(time.Minute / time.Millisecond)
+
+	// Hour is one hour; it has a similar meaning to time.Hour.
+	Hour Clock = Clock(time.Hour / time.Millisecond)
+
+	// Day is a fixed period of 24 hours. This does not take account of daylight savings,
+	// so is not fully general.
+	Day Clock = Clock(time.Hour * 24 / time.Millisecond)
+)
+
+// Midnight is the zero value of a Clock.
+const Midnight Clock = 0
+
+// Noon is at 12pm.
+const Noon Clock = Hour * 12
+
+// Undefined is provided because the zero value of a Clock *is* defined (i.e. Midnight).
+// So a special value is chosen, which is math.MinInt32.
+const Undefined Clock = Clock(math.MinInt32)
+
+// New returns a new Clock with specified hour, minute, second and millisecond.
+func New(hour, minute, second, millisec int) Clock {
+	hx := Clock(hour) * Hour
+	mx := Clock(minute) * Minute
+	sx := Clock(second) * Second
+	return Clock(hx + mx + sx + Clock(millisec))
+}
+
+// NewAt returns a new Clock with specified hour, minute, second and millisecond.
+func NewAt(t time.Time) Clock {
+	hour, minute, second := t.Clock()
+	hx := Clock(hour) * Hour
+	mx := Clock(minute) * Minute
+	sx := Clock(second) * Second
+	ms := Clock(t.Nanosecond() / int(time.Millisecond))
+	return Clock(hx + mx + sx + ms)
+}
+
+// SinceMidnight returns a new Clock based on a duration since some arbitrary midnight.
+func SinceMidnight(d time.Duration) Clock {
+	return Clock(d / time.Millisecond)
+}
+
+// DurationSinceMidnight convert a clock to a time.Duration since some arbitrary midnight.
+func (c Clock) DurationSinceMidnight() time.Duration {
+	return time.Duration(c) * time.Millisecond
+}
+
+// Add returns a new Clock offset from this clock specified hour, minute, second and millisecond.
+// The parameters can be negative.
+//
+// If required, use Mod24() to correct any overflow or underflow.
+func (c Clock) Add(h, m, s, ms int) Clock {
+	hx := Clock(h) * Hour
+	mx := Clock(m) * Minute
+	sx := Clock(s) * Second
+	return c + hx + mx + sx + Clock(ms)
+}
+
+// AddDuration returns a new Clock offset from this clock by a duration.
+// The parameters can be negative.
+//
+// If required, use Mod24() to correct any overflow or underflow.
+//
+// AddDuration is also useful for adding period.Period values.
+func (c Clock) AddDuration(d time.Duration) Clock {
+	return c + Clock(d/time.Millisecond)
+}
+
+// ModSubtract returns the duration between two clock times.
+//
+// If c2 is before c (i.e. c2 < c), the result is the duration computed from c - c2.
+//
+// But if c is before c2, it is assumed that c is after midnight and c2 is before midnight. The
+// result is the sum of the evening time from c2 to midnight with the morning time from midnight to c.
+// This is the same as Mod24(c - c2).
+func (c Clock) ModSubtract(c2 Clock) time.Duration {
+	ms := c - c2
+	return ms.Mod24().DurationSinceMidnight()
+}
+
+// IsInOneDay tests whether a clock time is in the range 0 to 24 hours, inclusive. Inside this
+// range, a Clock is generally well-behaved. But outside it, there may be errors due to daylight
+// savings. Note that 24:00:00 is included as a special case as per ISO-8601 definition of midnight.
+func (c Clock) IsInOneDay() bool {
+	return Midnight <= c && c <= Day
+}
+
+// IsMidnight tests whether a clock time is midnight. This is shorthand for c.Mod24() == 0.
+// For large values, this assumes that every day has 24 hours.
+func (c Clock) IsMidnight() bool {
+	return c.Mod24() == Midnight
+}
+
+// Mod24 calculates the remainder vs 24 hours using Euclidean division, in which the result
+// will be less than 24 hours and is never negative. Note that this imposes the assumption that
+// every day has 24 hours (not correct when daylight saving changes in any timezone).
+//
+// https://en.wikipedia.org/wiki/Modulo_operation
+func (c Clock) Mod24() Clock {
+	if Midnight <= c && c < Day {
+		return c
+	}
+	if c < Midnight {
+		q := 1 - c/Day
+		m := c + (q * Day)
+		if m == Day {
+			m = Midnight
+		}
+		return m
+	}
+	q := c / Day
+	return c - (q * Day)
+}
+
+// Days gets the number of whole days represented by the Clock, assuming that each day is a fixed
+// 24 hour period. Negative values are treated so that the range -23h59m59s to -1s is fully
+// enclosed in a day numbered -1, and so on. This means that the result is zero only for the
+// clock range 0s to 23h59m59s, for which IsInOneDay() returns true.
+func (c Clock) Days() int {
+	if c < Midnight {
+		return int(c/Day) - 1
+	}
+	return int(c / Day)
+}
+
+// Hours gets the clock-face number of hours (calculated from the modulo time, see Mod24).
+func (c Clock) Hours() int {
+	return int(clockHours(c.Mod24()))
+}
+
+// Minutes gets the clock-face number of minutes (calculated from the modulo time, see Mod24).
+// For example, for 22:35 this will return 35.
+func (c Clock) Minutes() int {
+	return int(clockMinutes(c.Mod24()))
+}
+
+// Seconds gets the clock-face number of seconds (calculated from the modulo time, see Mod24).
+// For example, for 10:20:30 this will return 30.
+func (c Clock) Seconds() int {
+	return int(clockSeconds(c.Mod24()))
+}
+
+// Millisec gets the clock-face number of milliseconds (calculated from the modulo time, see Mod24).
+// For example, for 10:20:30.456 this will return 456.
+func (c Clock) Millisec() int {
+	return int(clockMillisec(c.Mod24()))
+}