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 DateOnly(year int, month Month, day int) DateTime
  • func FromSqlDateTime(s string) (t DateTime, err error)
  • func NewDateTime(args ...interface{}) DateTime
  • func NewTimestamp(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) DebugString() string
  • 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) SetIsTimestamp(t bool)
  • func (d DateTime) String() string
  • func (d DateTime) ToJsonString() string
  • func (d DateTime) UTC() DateTime
  • func (d *DateTime) UnmarshalJSON(data []byte) (err error)
• type Month
  • func (m Month) String() string
• type Weekday
  • func (d Weekday) String() string

Examples

• DateTime.JavaScript
• DateTime.MarshalJSON

Constants

const (
	Current           = "now"
	Zero              = "zero"
	UsDate            = "1/2/2006"
	EuroDate          = "2/1/2006"
	UsDateTime        = "1/2/2006 3:04 PM"
	EuroDateTime      = "1/2/2006 15:04"
	UsTime            = "3:04 PM"
	EuroTime          = "15:04"
	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
	// contains filtered or unexported fields
}

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.

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 equal, and a Date only representation at the zero date, and a DATETIME representation at time zero are also equal, 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 hour, min, sec, nsec and loc to zeros for a date-only representation. Set year to 0, and month and day to 1's for a time-only representation. Pass nil to loc to indicate a non-timestamp value . Otherwise it will create a timestamp in the given timezone.

func DateOnly

func DateOnly(year int, month Month, day int) DateTime

func FromSqlDateTime

func FromSqlDateTime(s string) (t DateTime, err error)

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, will not be a timestamp, and we are assuming that the SQL itself is in UTC. If it DOES have timezone information, we will assume its a timestamp. If an error occurs, the returned value will be the zero date.

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 string representation of the date and time, followed by a time.Parse layout string

func NewTimestamp

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

NewTimestamp is the same as NewDateTime, but also sets it as a Timestamp

func NewZeroDate

func NewZeroDate() DateTime

Return a date-time that represents an empty date and time

func Now

func Now() DateTime

Now returns the current time as a timestamp, but with the time in local time.

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) DebugString

func (d DateTime) DebugString() string

DebugString returns the datetime in human readable form.

func (DateTime) Equal

func (d DateTime) Equal(d2 DateTime) bool

Returns true if the given DateTime object is equal to the current one. Timestamps are evaluated as being at the same instant in world time. Non-timestamps are compared just for their values ignoring timestamp.

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. Be careful, as this returns the time in whatever timestamp it currently is set to. Consider converting to UTC time before getting this.

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 whether the DateTime is a timestamp, representing a particular moment in world time.

func (DateTime) JavaScript

func (d DateTime) JavaScript() string

Satisfies the javacript.JavaScripter interface to output the date as a javascript value. TIMESTAMPS are converted to the local time corresponding to the given world time. Non-timestamps are transmitted as if they were in the browser's local time.

Example

d := NewDateTime("2012-11-01T22:08:41+00:00")
v := d.JavaScript()
fmt.Println(v)

Output:

new Date(2012, 10, 1, 22, 8, 41, 0)

func (DateTime) Local

func (d DateTime) Local() DateTime

Local returns a new DateTime with the date and time converted to local values in the server's timezone.

func (DateTime) MarshalJSON

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

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

The JSON "standard" behavior is to output an ISO8601 string in UTC time. There are a bunch of problems with this.

1. You cannot use this to represent a display date and time in local time. It will get converted to world time. even if you try to output a time without timezone information, or with timezone information that is not UTC, which is what the built-in GO Time object does, most browsers will ignore that part of the string and completely botch the time transfer. We would need to create our own interpreter to make that work.
2. Its a string. Unless you know in advance you want a date, or you look for an ISO8601 pattern in every string, you cannot just tell the other side its a date.

So, we have taken the approach of outputting an object that self-identifies as a goradd date, and already breaks apart the time components so its easily reassembled on the other side.

Example

d := NewDateTime("2012-11-01T22:08:41+00:00")
v, _ := d.MarshalJSON()
fmt.Println(string(v))

Output:

{"d":1,"goraddObject":"date","h":22,"m":8,"mo":10,"ms":0,"s":41,"t":false,"y":2012,"z":false}

func (DateTime) Month

func (d DateTime) Month() Month

Month returns the month value of the datetime

func (*DateTime) SetIsTimestamp

func (d *DateTime) SetIsTimestamp(t bool)

SetIsTimestamp will change the state of the date time to the given value. Timestamps are communicated to the server as a UTC time, whereas non-timestamp times are communicated in whatever value is currently in the DateTime without changing the timezone

func (DateTime) String

func (d DateTime) String() string

String returns the datetime in string form, suitable for sending to the NewDateTime function.

func (DateTime) ToJsonString

func (d DateTime) ToJsonString() string

ToJsonString outputs the date in ISO8601, which is the generally excepted representation of a date. The problem with this is that the receiver must know to look for a date instead of a string, so it is not actually the best way of transmitting a date to the other side. This is here for use by the ORM, which will send standard dates in the expected JSON format for potential consumption by REST services.

func (DateTime) UTC

func (d DateTime) UTC() DateTime

UTC returns a new datetime in UTC time.

func (*DateTime) UnmarshalJSON

func (d *DateTime) UnmarshalJSON(data []byte) (err error)

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