README
¶
date
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
(including years outside the [0,9999] interval).
See package documentation for full documentation and examples.
Installation
go get -u github.com/fxtlabs/date
Credits
This package follows very closely the design of package
time in the standard library;
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.
Documentation
¶
Overview ¶
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 (including years outside the [0,9999] interval).
Credits ¶
This package follows very closely the design of package time (http://golang.org/pkg/time/) in the standard library, 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.
References ¶
https://golang.org/src/time/time.go
https://en.wikipedia.org/wiki/Gregorian_calendar
https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
https://en.wikipedia.org/wiki/Astronomical_year_numbering
https://en.wikipedia.org/wiki/ISO_8601
https://tools.ietf.org/html/rfc822
https://tools.ietf.org/html/rfc850
Index ¶
- Constants
- type Date
- func (d Date) Add(days int) Date
- func (d Date) AddDate(years, months, days int) Date
- func (d Date) After(u Date) bool
- func (d Date) Before(u Date) bool
- func (d Date) Date() (year int, month time.Month, day int)
- func (d Date) Day() int
- func (d Date) Equal(u Date) bool
- func (d Date) Format(layout string) string
- func (d Date) FormatISO(yearDigits int) string
- func (d *Date) GobDecode(data []byte) error
- func (d Date) GobEncode() ([]byte, error)
- func (d Date) ISOWeek() (year, week int)
- func (d Date) In(loc *time.Location) time.Time
- func (d Date) IsZero() bool
- func (d Date) Local() time.Time
- func (d Date) MarshalBinary() ([]byte, error)
- func (d Date) MarshalJSON() ([]byte, error)
- func (d Date) MarshalText() ([]byte, error)
- func (d Date) Month() time.Month
- func (d Date) String() string
- func (d Date) Sub(u Date) (days int)
- func (d Date) UTC() time.Time
- func (d *Date) UnmarshalBinary(data []byte) error
- func (d *Date) UnmarshalJSON(data []byte) (err error)
- func (d *Date) UnmarshalText(data []byte) error
- func (d Date) Weekday() time.Weekday
- func (d Date) Year() int
- func (d Date) YearDay() int
Examples ¶
Constants ¶
const ( ISO8601 = "2006-01-02" // ISO 8601 extended format ISO8601B = "20060102" // ISO 8601 basic format RFC822 = "02-Jan-06" RFC822W = "Mon, 02-Jan-06" // RFC822 with day of the week RFC850 = "Monday, 02-Jan-06" RFC1123 = "02 Jan 2006" RFC1123W = "Mon, 02 Jan 2006" // RFC1123 with day of the week RFC3339 = "2006-01-02" )
These are predefined layouts for use in Date.Format and Date.Parse. The reference date used in the layouts is the same date used by the time package in the standard library:
Monday, Jan 2, 2006
To define your own format, write down what the reference date would look like formatted your way; see the values of the predefined layouts for examples. The model is to demonstrate what the reference date looks like so that the Parse function and Format method can apply the same transformation to a general date value.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Date ¶
type Date struct {
// contains filtered or unexported fields
}
A Date represents a date under the (proleptic) Gregorian calendar as used by ISO 8601. This calendar uses astronomical year numbering, so it includes a year 0 and represents earlier years as negative numbers (i.e. year 0 is 1 BC; year -1 is 2 BC, and so on).
A Date value requires 4 bytes of storage and can represent dates from Tue, 23 Jun -5,877,641 (5,877,642 BC) to Fri, 11 Jul 5,881,580. Dates outside that range will "wrap around".
Programs using dates should typically store and pass them as values, not pointers. That is, date variables and struct fields should be of type date.Date, not *date.Date. A Date value can be used by multiple goroutines simultaneously.
Date values can be compared using the Before, After, and Equal methods as well as the == and != operators. The Sub method subtracts two dates, returning the number of days between them. The Add method adds a Date and a number of days, producing a Date.
The zero value of type Date is Thursday, January 1, 1970. As this date is unlikely to come up in practice, the IsZero method gives a simple way of detecting a date that has not been initialized explicitly.
func Max ¶
func Max() Date
Max returns the largest representable date.
Example ¶
package main
import (
"fmt"
"github.com/fxtlabs/date"
)
func main() {
d := date.Max()
fmt.Println(d)
}
Output: +5881580-07-11
func Min ¶
func Min() Date
Min returns the smallest representable date.
Example ¶
package main
import (
"fmt"
"github.com/fxtlabs/date"
)
func main() {
d := date.Min()
fmt.Println(d)
}
Output: -5877641-06-23
func New ¶
New returns the Date value corresponding to the given year, month, and day.
The month and day may be outside their usual ranges and will be normalized during the conversion.
Example ¶
package main
import (
"fmt"
"time"
"github.com/fxtlabs/date"
)
func main() {
d := date.New(9999, time.December, 31)
fmt.Printf("The world ends on %s\n", d)
}
Output: The world ends on 9999-12-31
func NewAt ¶
NewAt returns the Date value corresponding to the given time. Note that the date is computed relative to the time zone specified by the given Time value.
func Parse ¶
Parse parses a formatted string and returns the Date value it represents. The layout defines the format by showing how the reference date, defined to be
Monday, Jan 2, 2006
would be interpreted if it were the value; it serves as an example of the input format. The same interpretation will then be made to the input string.
This function actually uses time.Parse to parse the input and can use any layout accepted by time.Parse, but returns only the date part of the parsed Time value.
This function cannot currently parse ISO 8601 strings that use the expanded year format; you should use Date.ParseISO to parse those strings correctly.
Example ¶
package main
import (
"fmt"
"github.com/fxtlabs/date"
)
func main() {
// longForm shows by example how the reference date would be
// represented in the desired layout.
const longForm = "Mon, January 2, 2006"
d, _ := date.Parse(longForm, "Tue, February 3, 2013")
fmt.Println(d)
// shortForm is another way the reference date would be represented
// in the desired layout.
const shortForm = "2006-Jan-02"
d, _ = date.Parse(shortForm, "2013-Feb-03")
fmt.Println(d)
}
Output: 2013-02-03 2013-02-03
func ParseISO ¶
ParseISO parses an ISO 8601 formatted string and returns the date value it represents. In addition to the common extended format (e.g. 2006-01-02), this function accepts date strings using the expanded year representation with possibly extra year digits beyond the prescribed four-digit minimum and with a + or - sign prefix (e.g. , "+12345-06-07", "-0987-06-05").
Note that ParseISO is a little looser than the ISO 8601 standard and will be happy to parse dates with a year longer than the four-digit minimum even if they are missing the + sign prefix.
Function Date.Parse can be used to parse date strings in other formats, but it is currently not able to parse ISO 8601 formatted strings that use the expanded year format.
Example ¶
package main
import (
"fmt"
"github.com/fxtlabs/date"
)
func main() {
d, _ := date.ParseISO("+12345-06-07")
year, month, day := d.Date()
fmt.Println(year)
fmt.Println(month)
fmt.Println(day)
}
Output: 12345 June 7
func TodayIn ¶
TodayIn returns today's date according to the current time relative to the specified location.
func TodayUTC ¶
func TodayUTC() Date
TodayUTC returns today's date according to the current UTC time.
func (Date) AddDate ¶
AddDate returns the date corresponding to adding the given number of years, months, and days to d. For example, AddData(-1, 2, 3) applied to January 1, 2011 returns March 4, 2010.
Example ¶
package main
import (
"fmt"
"time"
"github.com/fxtlabs/date"
)
func main() {
d := date.New(1000, time.January, 1)
// Months and days do not need to be constrained to [1,12] and [1,365].
u := d.AddDate(0, 14, -1)
fmt.Println(u)
}
Output: 1001-02-28
func (Date) Format ¶
Format returns a textual representation of the date value formatted according to layout, which defines the format by showing how the reference date, defined to be
Mon, Jan 2, 2006
would be displayed if it were the value; it serves as an example of the desired output.
This function actually uses time.Format to format the input and can use any layout accepted by time.Format by extending its date to a time at 00:00:00.000 UTC.
This function cannot currently format Date values according to the expanded year variant of ISO 8601; you should use Date.FormatISO to that effect.
Example ¶
package main
import (
"fmt"
"time"
"github.com/fxtlabs/date"
)
func main() {
// layout shows by example how the reference time should be represented.
const layout = "Jan 2, 2006"
d := date.New(2009, time.November, 10)
fmt.Println(d.Format(layout))
}
Output: Nov 10, 2009
func (Date) FormatISO ¶
FormatISO returns a textual representation of the date value formatted according to the expanded year variant of the ISO 8601 extended format; the year of the date is represented as a signed integer using the specified number of digits (ignored if less than four). The string representation of the year will take more than the specified number of digits if the magnitude of the year is too large to fit.
Function Date.Format can be used to format Date values in other formats, but it is currently not able to format dates according to the expanded year variant of the ISO 8601 format.
Example ¶
package main
import (
"fmt"
"time"
"github.com/fxtlabs/date"
)
func main() {
// According to legend, Rome was founded on April 21, 753 BC.
// Note that with astronomical year numbering, 753 BC becomes -752
// because 1 BC is actually year 0.
d := date.New(-752, time.April, 21)
fmt.Println(d.FormatISO(5))
}
Output: -00752-04-21
func (Date) ISOWeek ¶
ISOWeek returns the ISO 8601 year and week number in which d occurs. Week ranges from 1 to 53. Jan 01 to Jan 03 of year n might belong to week 52 or 53 of year n-1, and Dec 29 to Dec 31 might belong to week 1 of year n+1.
func (Date) In ¶
In returns a Time value corresponding to midnight on the given date, relative to the specified time zone. Note that midnight is the beginning of the day rather than the end.
func (Date) Local ¶
Local returns a Time value corresponding to midnight on the given date, local time. Note that midnight is the beginning of the day rather than the end.
func (Date) MarshalBinary ¶
MarshalBinary implements the encoding.BinaryMarshaler interface.
func (Date) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface. The date is a quoted string in ISO 8601 extended format (e.g. "2006-01-02"). If the year of the date falls outside the [0,9999] range, this format produces an expanded year representation with possibly extra year digits beyond the prescribed four-digit minimum and with a + or - sign prefix (e.g. , "+12345-06-07", "-0987-06-05").
func (Date) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface. The date is given in ISO 8601 extended format (e.g. "2006-01-02"). If the year of the date falls outside the [0,9999] range, this format produces an expanded year representation with possibly extra year digits beyond the prescribed four-digit minimum and with a + or - sign prefix (e.g. , "+12345-06-07", "-0987-06-05").
func (Date) String ¶
String returns the time formatted in ISO 8601 extended format (e.g. "2006-01-02"). If the year of the date falls outside the [0,9999] range, this format produces an expanded year representation with possibly extra year digits beyond the prescribed four-digit minimum and with a + or - sign prefix (e.g. , "+12345-06-07", "-0987-06-05").
func (Date) UTC ¶
UTC returns a Time value corresponding to midnight on the given date, UTC time. Note that midnight is the beginning of the day rather than the end.
func (*Date) UnmarshalBinary ¶
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
func (*Date) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface. The date is expected to be a quoted string in ISO 8601 extended format (e.g. "2006-01-02", "+12345-06-07", "-0987-06-05"); the year must use at least 4 digits and if outside the [0,9999] range must be prefixed with a + or - sign.
func (*Date) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface. The date is expected to be in ISO 8601 extended format (e.g. "2006-01-02", "+12345-06-07", "-0987-06-05"); the year must use at least 4 digits and if outside the [0,9999] range must be prefixed with a + or - sign.
Source Files