README
¶
Civil date and time
Package civil provides types for representing civil dates, and times.
Sometimes it is useful to be able to represent a date or time without reference to an instance in time within a timezone.
For example, when recording a person's date of birth all that is needed is a date. There is no requirement to specify an instant in time within a timezone.
There are also circumstances where an event will be scheduled for a date and time in the local timezone, whatever that may be. And example of this might be a schedule for taking medication.
Like the standard library time package, the civil package uses the proleptic Gregorian calendar for all calculations. The civil package makes use of the time package for all of its date-time calculations. Because some of this code is based on the standard time package, it has the identical license to the Go project.
For usage examples, refer to the GoDoc documentation.
Documentation
¶
Overview ¶
Package civil provides types for representing civil dates, and times.
Sometimes it is useful to be able to represent a date or time without reference to an instance in time within a timezone.
For example, when recording a person's date of birth all that is needed is a date. There is no requirement to specify an instant in time within a timezone.
There are also circumstances where an event will be scheduled for a date and time in the local timezone, whatever that may be. And example of this might be a schedule for taking medication.
Index ¶
- type Date
- func (d Date) Add(duration time.Duration) Date
- func (d Date) AddDate(years int, months int, days int) Date
- func (d Date) After(e Date) bool
- func (d Date) Before(e Date) bool
- func (d Date) Date() (year int, month time.Month, day int)
- func (d Date) Day() int
- func (d Date) Equal(e Date) bool
- func (d Date) Format(layout string) string
- func (d Date) ISOWeek() (year, week int)
- func (d Date) IsZero() bool
- 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) Scan(src interface{}) error
- func (d Date) String() string
- func (d Date) Sub(e Date) time.Duration
- func (d Date) Unix() int64
- func (d *Date) UnmarshalBinary(data []byte) error
- func (d *Date) UnmarshalJSON(data []byte) (err error)
- func (d *Date) UnmarshalText(data []byte) (err error)
- func (d Date) Value() (driver.Value, error)
- func (d Date) Weekday() time.Weekday
- func (d Date) Year() int
- func (d Date) YearDay() int
- type DateTime
- func (dt DateTime) Add(duration time.Duration) DateTime
- func (dt DateTime) AddDate(years int, months int, days int) DateTime
- func (dt DateTime) After(e DateTime) bool
- func (dt DateTime) Before(e DateTime) bool
- func (dt DateTime) Clock() (hour int, minute int, second int)
- func (dt DateTime) Date() (year int, month time.Month, day int)
- func (dt DateTime) DateTime() (year int, month time.Month, day int, hour int, minute int, second int)
- func (dt DateTime) Day() int
- func (dt DateTime) Equal(e DateTime) bool
- func (dt DateTime) Format(layout string) string
- func (dt DateTime) Hour() int
- func (dt DateTime) ISOWeek() (year, week int)
- func (dt DateTime) IsZero() bool
- func (dt DateTime) MarshalBinary() ([]byte, error)
- func (dt DateTime) MarshalJSON() ([]byte, error)
- func (dt DateTime) MarshalText() ([]byte, error)
- func (dt DateTime) Minute() int
- func (dt DateTime) Month() time.Month
- func (dt *DateTime) Scan(src interface{}) error
- func (dt DateTime) Second() int
- func (dt DateTime) String() string
- func (dt DateTime) Sub(e DateTime) time.Duration
- func (dt DateTime) Unix() int64
- func (dt *DateTime) UnmarshalBinary(data []byte) error
- func (dt *DateTime) UnmarshalJSON(data []byte) (err error)
- func (dt *DateTime) UnmarshalText(data []byte) (err error)
- func (dt DateTime) Value() (driver.Value, error)
- func (dt DateTime) Weekday() time.Weekday
- func (dt DateTime) Year() int
- func (dt DateTime) YearDay() int
- type NullDate
- type NullDateTime
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Date ¶
type Date struct {
// contains filtered or unexported fields
}
Date represents a date without a time or a timezone. Useful for representing date of birth, for example.
Calculations on Date are performed using the standard library's time.Time type. For these calculations the time is midnight and the timezone is UTC.
func DateFor ¶
DateFor returns the Date corresponding to year, month and date.
The month and day values may be outside their usual ranges and will be normalized during the conversion. For example, October 32 converts to November 1.
Example ¶
package main
import (
"fmt"
"time"
"github.com/jjeffery/civil"
)
func main() {
d := civil.DateFor(2009, time.November, 10)
fmt.Printf("Go launched on %s\n", d)
}
Output: Go launched on 2009-11-10
func ParseDate ¶
ParseDate attempts to parse a string into a civil date. Leading and trailing space and quotation marks are ignored. The following date formats are recognized: yyyy-mm-dd, yyyymmdd, yyyy.mm.dd, yyyy/mm/dd, yyyy-ddd, yyyyddd.
ParseDate is used to parse dates where no layout is provided, for example when marshaling and unmarshaling JSON and XML.
func ParseDateLayout ¶
ParseDateLayout parses a formatted string and returns the date value it represents. The layout is based on the standard library time package and for civil dates the reference is
Mon Jan 2 2006
If the layout contains time or timezone fields, they are parsed and discarded.
func Today ¶
func Today() Date
Today returns the current civil date.
Example ¶
package main
import (
"fmt"
"time"
"github.com/jjeffery/civil"
)
func main() {
_, month, day := civil.Today().Date()
if month == time.November && day == 10 {
fmt.Println("Happy Go day!")
}
}
Output:
func (Date) AddDate ¶
AddDate returns the civil date corresponding to adding the given number of years, months, and days to t. For example, AddDate(-1, 2, 3) applied to January 1, 2011 returns March 4, 2010.
AddDate normalizes its result in the same way that Date does, so, for example, adding one month to October 31 yields December 1, the normalized form for November 31.
func (Date) Format ¶
Format returns a textual representation of the time value formatted according to layout, which takes the same form as the standard library time package. Note that with a Date the reference time is
Mon Jan 2 2006
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) MarshalBinary ¶
MarshalBinary implements the encoding.BinaryMarshaler interface.
func (Date) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface. The date is a quoted string in an ISO 8601 format (yyyy-mm-dd).
func (Date) MarshalText ¶
MarshalText implements the encoding.TextMarshaller interface. The date format is yyyy-mm-dd.
func (Date) String ¶
String returns a string representation of d. The date format returned is compatible with ISO 8601: yyyy-mm-dd.
func (Date) Sub ¶
Sub returns the duration d-e, which will be an integral number of days. If the result exceeds the maximum (or minimum) value that can be stored in a Duration, the maximum (or minimum) duration will be returned. To compute d-duration, use d.Add(-duration).
func (Date) Unix ¶
Unix returns d as a Unix time, the number of seconds elapsed since January 1, 1970 UTC to midnight of the date UTC.
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 an ISO 8601 format (calendar or ordinal).
func (*Date) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaller interface. The date is expected to an ISO 8601 format (calendar or ordinal).
type DateTime ¶
type DateTime struct {
// contains filtered or unexported fields
}
DateTime represents a date-time without a timezone. Calculations on DateTime are performed using the standard library's time.Time type. For these calculations the timezone is UTC.
DateTime is useful in situations where a date and time are specified, without reference to a timezone. Although not common, it can be useful. For example, a dose of medication may be scheduled for a particular date and time, regardless of the timezone that the patient is residing in at the time.
Because DateTime does not specify a unique instant in time, it has never been necessary to specify to sub-second accuracy. For this reason DateTime only specifies the time to second accuracy. In actual fact, DateTime would probably be fine if it only specified to minute accuracy.
func DateTimeFor ¶
DateTimeFor returns the DateTime corresponding to year, month, day, hour, minute and second.
The month and day values may be outside their usual ranges and will be normalized during the conversion. For example, October 32 converts to November 1.
func DateTimeOf ¶
DateTimeOf returns the DateTime corresponding to t in t's location.
func ParseDateTime ¶
ParseDateTime attempts to parse a string into a civil date-time. Leading and trailing space and quotation marks are ignored. The following date formats are recognized: yyyy-mm-dd, yyyymmdd, yyyy.mm.dd, yyyy/mm/dd, yyyy-ddd, yyyyddd. The following time formats are recognized: HH:MM:SS, HH:MM, HHMMSS, HHMM.
func ParseDateTimeLayout ¶
ParseDateTimeLayout parses a formatted string and returns the date value it represents. The layout is based on the standard library time package and for civil date-times the reference is
Mon Jan 2 2006 15:04:05
If the layout contains a timezone field, it is parsed and discarded.
func (DateTime) AddDate ¶
AddDate returns the civil date-time corresponding to adding the given number of years, months, and days to t. For example, AddDate(-1, 2, 3) applied to January 1, 2011 returns March 4, 2010.
AddDate normalizes its result in the same way that Date does, so, for example, adding one month to October 31 yields December 1, the normalized form for November 31.
func (DateTime) DateTime ¶
func (dt DateTime) DateTime() (year int, month time.Month, day int, hour int, minute int, second int)
DateTime returns the year, month, day, hour minute, second and nanosecond on which dt occurs.
func (DateTime) Format ¶
Format returns a textual representation of the time value formatted according to layout, which takes the same form as the standard library time package. Note that with a Date the reference time is
Mon Jan 2 2006 15:04:05.
func (DateTime) 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 (DateTime) IsZero ¶
IsZero reports whether dt represents the zero civil date-time, Midnight, January 1, year 1.
func (DateTime) MarshalBinary ¶
MarshalBinary implements the encoding.BinaryMarshaler interface.
func (DateTime) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface. The date is a quoted string in an ISO 8601 format (yyyy-mm-ddTHH:MM:SS).
func (DateTime) MarshalText ¶
MarshalText implements the encoding.TextMarshaller interface. The date format is yyyy-mm-dd.
func (DateTime) String ¶
String returns a string representation of d. The date format returned is compatible with ISO 8601: yyyy-mm-ddTHH:MM:SS.
func (DateTime) Sub ¶
Sub returns the duration dt-e, which will be an integral number of seconds. If the result exceeds the maximum (or minimum) value that can be stored in a Duration, the maximum (or minimum) duration will be returned. To compute dt-duration, use dt.Add(-duration).
func (DateTime) Unix ¶
Unix returns d as a Unix time, the number of seconds elapsed since January 1, 1970 UTC to midnight of the date-time UTC.
func (*DateTime) UnmarshalBinary ¶
UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
func (*DateTime) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface. The date is expected to be a quoted string in an ISO 8601 format (calendar or ordinal).
func (*DateTime) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaller interface. The date is expected to an ISO 8601 format (calendar or ordinal).
type NullDate ¶
NullDate represents a Date that may be null. NullDate implements the sql Scanner interface so it can be used as a scan destination, similar to sql.NullString.
func NullDateFrom ¶
NullDateFrom returns a NullDate whose value is obtained from the pointer.
func (NullDate) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface.
func (*NullDate) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface.
type NullDateTime ¶
NullDateTime represents a DateTime that may be null. NullDateTime implements the sql Scanner interface so it can be used as a scan destination, similar to sql.NullString.
func NullDateTimeFrom ¶
func NullDateTimeFrom(ptr *DateTime) NullDateTime
NullDateTimeFrom returns a NullDateTime whose value is obtained from the pointer.
func (NullDateTime) MarshalJSON ¶
func (n NullDateTime) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface.
func (NullDateTime) Ptr ¶
func (n NullDateTime) Ptr() *DateTime
Ptr returns a pointer to DateTime. The pointer will be nil if Valid is false.
func (*NullDateTime) Scan ¶
func (n *NullDateTime) Scan(value interface{}) error
Scan implements the sql Scanner interface
func (*NullDateTime) UnmarshalJSON ¶
func (n *NullDateTime) UnmarshalJSON(p []byte) error
UnmarshalJSON implements the json.Unmarshaler interface.
Source Files