datetime

Documentation

Overview

The datetime package contains utilities for time and date related functions. It is a wrapper for the time.Time package, with expanded functionality and routines to help shepard between the types, and to provide localization and better timezone support in the context of a web application.

Index

• Constants
• type DateTime
  • func Date(year int, month Month, day, hour, min, sec, nsec int, loc *time.Location) DateTime
  • func FromSqlDateTime(s string) DateTime
  • func NewDateTime(args ...interface{}) DateTime
  • func NewZeroDate() DateTime
  • func Now() DateTime
  • func Parse(layout, value string) (DateTime, error)
  • func Time(hour, min, sec, nsec int) DateTime
  • func (d DateTime) Equal(d2 DateTime) bool
  • func (d DateTime) GetDate() DateTime
  • func (d DateTime) GetTime() DateTime
  • func (d DateTime) GoTime() time.Time
  • func (d DateTime) In(location *time.Location) DateTime
  • func (d DateTime) IsTimestamp() bool
  • func (d DateTime) JavaScript() string
  • func (d DateTime) Local() DateTime
  • func (d DateTime) MarshalJSON() (buf []byte, err error)
  • func (d DateTime) Month() Month
  • func (d DateTime) UTC() DateTime
• type Month
  • func (m Month) String() string
• type Weekday
  • func (d Weekday) String() string

Constants

const (
	Current           = "now"
	Zero              = "zero"
	UsDate            = "1/2/2006"
	EuroDate          = "2/1/2006"
	UsDateTime        = "1/2/2006 3:04 PM"
	UsDateTimeSeconds = "1/2/2006 3:04:05 PM"
	LongDateDOW       = "Monday, January 2, 2006"
	LongDate          = "January 2, 2006"
)

const (
	ANSIC       = "Mon Jan _2 15:04:05 2006"
	UnixDate    = "Mon Jan _2 15:04:05 MST 2006"
	RubyDate    = "Mon Jan 02 15:04:05 -0700 2006"
	RFC822      = "02 Jan 06 15:04 MST"
	RFC822Z     = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone
	RFC850      = "Monday, 02-Jan-06 15:04:05 MST"
	RFC1123     = "Mon, 02 Jan 2006 15:04:05 MST"
	RFC1123Z    = "Mon, 02 Jan 2006 15:04:05 -0700" // RFC1123 with numeric zone
	RFC3339     = "2006-01-02T15:04:05Z07:00"
	RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"
	Kitchen     = "3:04PM"
	// Handy time stamps.
	Stamp      = "Jan _2 15:04:05"
	StampMilli = "Jan _2 15:04:05.000"
	StampMicro = "Jan _2 15:04:05.000000"
	StampNano  = "Jan _2 15:04:05.000000000"
)

Types

type DateTime

type DateTime struct {
	time.Time
}

DateTime is the default time value for the system (as opposed to the built in time.Time). DateTime has a number of enhancements over time.Time DateTime is designed to interact nicely with dates and times stored in databases. In particular, SQL databases can store a date-time as either a DATETIME, or a TIMESTAMP. It also has DATE only and TIME only representations.

A DATETIME and TIME are for situations where the time is independent of the timezone. For example, in a scheduling application when you have scheduled a future event at 8:00 am, but in between now and then, there is a change int daylight savings time. The event should still be at 8:00 am. These amounts are stored as UTC time, since UTC is not associated with any real timezone and has no DST issues. Convert to GMT if you truly mean a TIMESTAMP at zero offset.

A TIMESTAMP is for recording particular moments in world time. When the event is moved to another location, the time will be displayed in the local timezone as opposed to the timezone it was created in. Some databases store these internally in UTC time, so that if the database is moved to a machine in another location, the actual time is preserved, and then converted to local time when read from the database. So for our purposes, these times are always associated with a particular timezone.

Time only and Date only representations are always stored in UTC time. Time only times have a date of January 1, year 1. Date only values have zero times at UTC. This means that a Time only representation at time zero and zero time are ambiguous, and a Date only representation and a DATETIME representation at time zero are also ambiguous, and you should resolve that ambiguity by the context you are using these in.

func Date

func Date(year int, month Month, day, hour, min, sec, nsec int, loc *time.Location) DateTime

Date creates a DateTime with the given information. Set loc to nil or UTC to treat it as a datetime with no timezone information. Set hour, min, sec, nsec and loc to zeros for a date-only representation.

func FromSqlDateTime

func FromSqlDateTime(s string) DateTime

FromSqlDateTime will receive a Date, Time, DateTime or Timestamp type of string that is typically output by SQL and convert it to our own DateTime object. If the SQL date time string does not have timezone information, the resulting value will be in UTC time, and we are assuming that the SQL itself is in UTC.

func NewDateTime

func NewDateTime(args ...interface{}) DateTime

NewDateTime creates a new date time from the given information. You can give it the following: () = zero time (DateTime) = copy the given datetime (time.Time or *time.Time) = copy the given time (string), as follows:

datetime.Current - same as calling datetime.Now()
datetime.Zero - same as calling datetime.NewZeroDate()
anything else - RFC3339 string

(string, string) = a time.Parse format string, followed by a string representation of the date and time

func NewZeroDate

func NewZeroDate() DateTime

Return a date-time that represents an empty date

func Now

func Now() DateTime

func Parse

func Parse(layout, value string) (DateTime, error)

func Time

func Time(hour, min, sec, nsec int) DateTime

Time creates a DateTime that only represents a time of day.

func (DateTime) Equal

func (d DateTime) Equal(d2 DateTime) bool

Returns true if the given DateTime object is equal to the current one. TIMESTAMP objects will take timezone into consideration.

func (DateTime) GetDate

func (d DateTime) GetDate() DateTime

GetDate returns a new DateTime object set to only the date portion of the given DateTime object.

func (DateTime) GetTime

func (d DateTime) GetTime() DateTime

GetTime returns a new DateTime object set to only the time portion of the given DateTime object.

func (DateTime) GoTime

func (d DateTime) GoTime() time.Time

GoTime returns a GO time.Time value.

func (DateTime) In

func (d DateTime) In(location *time.Location) DateTime

In converts the datetime to the given locale.

func (DateTime) IsTimestamp

func (d DateTime) IsTimestamp() bool

IsTimestamp returns true if the DateTime is being treated as a moment in world time. False indicates it is being treated as a datetime or time in whatever the current locale is, but when that locale changes, or there is a daylight savings time change, it will not change the displayed time.

func (DateTime) JavaScript

func (d DateTime) JavaScript() string

Satisfies the javacript.JavaScripter interface to output the date as a javascript value. Javascript stores dates internally as UTC times, and then you can print them out in local time if needed.

func (DateTime) Local

func (d DateTime) Local() DateTime

Local converts the date and time to local values in the local locale.

func (DateTime) MarshalJSON

func (d DateTime) MarshalJSON() (buf []byte, err error)

Satisfies the json.Marshaller interface to output the date as a value embedded in JSON and that will be unpacked by our javascript file.

func (DateTime) Month

func (d DateTime) Month() Month

Month returns the month value of the datetime

func (DateTime) UTC

func (d DateTime) UTC() DateTime

UTC returns a datetime in UTC time. Note that this will then begin treating it as not having timezone information. Convert it to a local to re-establish it as a point in world time.

type Month

type Month int

A Month specifies a month of the year (January = 1, ...).

const (
	January Month = 1 + iota
	February
	March
	April
	May
	June
	July
	August
	September
	October
	November
	December
)

func (Month) String

func (m Month) String() string

type Weekday

type Weekday int

const (
	Sunday Weekday = iota
	Monday
	Tuesday
	Wednesday
	Thursday
	Friday
	Saturday
)

func (Weekday) String

func (d Weekday) String() string