type Timer(struct)
The Timer type represents a single event.
When the Timer expires, the current time will be sent on C,
unless the Timer was created by AfterFunc.
A Timer must be created with NewTimer or AfterFunc.
C<-chan Time
(*T) Reset(d Duration) bool
(*T) Stop() bool
func AfterFunc(d Duration, f func()) *Timer
func NewTimer(d Duration) *Timer
func After(d Duration) <-chan Time
After waits for the duration to elapse and then sends the current time
on the returned channel.
It is equivalent to NewTimer(d).C.
The underlying Timer is not recovered by the garbage collector
until the timer fires. If efficiency is a concern, use NewTimer
instead and call Timer.Stop if the timer is no longer needed.
func AfterFunc(d Duration, f func()) *Timer
AfterFunc waits for the duration to elapse and then calls f
in its own goroutine. It returns a Timer that can
be used to cancel the call using its Stop method.
const ANSIC = "Mon Jan _2 15:04:05 2006"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time
Date returns the Time corresponding to
yyyy-mm-dd hh:mm:ss + nsec nanoseconds
in the appropriate zone for that time in the given location.
The month, day, hour, min, sec, and nsec values may be outside
their usual ranges and will be normalized during the conversion.
For example, October 32 converts to November 1.
A daylight savings time transition skips or repeats times.
For example, in the United States, March 13, 2011 2:15am never occurred,
while November 6, 2011 1:15am occurred twice. In such cases, the
choice of time zone, and therefore the time, is not well-defined.
Date returns a time that is correct in one of the two zones involved
in the transition, but it does not guarantee which.
Date panics if loc is nil.
const HourDuration = 3600000000000
Common durations. There is no definition for units of Day or larger
to avoid confusion across daylight savings time zone transitions.
To count the number of units in a Duration, divide:
second := time.Second
fmt.Print(int64(second/time.Millisecond)) // prints 1000
To convert an integer number of units to a Duration, multiply:
seconds := 10
fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
const Kitchen = "3:04PM"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
func LoadLocation(name string) (*Location, error)
LoadLocation returns the Location with the given name.
If the name is "" or "UTC", LoadLocation returns UTC.
If the name is "Local", LoadLocation returns Local.
Otherwise, the name is taken to be a location name corresponding to a file
in the IANA Time Zone database, such as "America/New_York".
The time zone database needed by LoadLocation may not be
present on all systems, especially non-Unix systems.
LoadLocation looks in the directory or uncompressed zip file
named by the ZONEINFO environment variable, if any, then looks in
known installation locations on Unix systems,
and finally looks in $GOROOT/lib/time/zoneinfo.zip.
func LoadLocationFromTZData(name string, data []byte) (*Location, error)
LoadLocationFromTZData returns a Location with the given name
initialized from the IANA Time Zone database-formatted data.
The data should be in the format of a standard IANA time zone file
(for example, the content of /etc/localtime on Unix systems).
var Local *Location
Local represents the system's local time zone.
On Unix systems, Local consults the TZ environment
variable to find the time zone to use. No TZ means
use the system default /etc/localtime.
TZ="" means use UTC.
TZ="foo" means use file foo in the system timezone directory.
const MicrosecondDuration = 1000
Common durations. There is no definition for units of Day or larger
to avoid confusion across daylight savings time zone transitions.
To count the number of units in a Duration, divide:
second := time.Second
fmt.Print(int64(second/time.Millisecond)) // prints 1000
To convert an integer number of units to a Duration, multiply:
seconds := 10
fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
const MillisecondDuration = 1000000
Common durations. There is no definition for units of Day or larger
to avoid confusion across daylight savings time zone transitions.
To count the number of units in a Duration, divide:
second := time.Second
fmt.Print(int64(second/time.Millisecond)) // prints 1000
To convert an integer number of units to a Duration, multiply:
seconds := 10
fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
const MinuteDuration = 60000000000
Common durations. There is no definition for units of Day or larger
to avoid confusion across daylight savings time zone transitions.
To count the number of units in a Duration, divide:
second := time.Second
fmt.Print(int64(second/time.Millisecond)) // prints 1000
To convert an integer number of units to a Duration, multiply:
seconds := 10
fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
const NanosecondDuration = 1
Common durations. There is no definition for units of Day or larger
to avoid confusion across daylight savings time zone transitions.
To count the number of units in a Duration, divide:
second := time.Second
fmt.Print(int64(second/time.Millisecond)) // prints 1000
To convert an integer number of units to a Duration, multiply:
seconds := 10
fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
func NewTicker(d Duration) *Ticker
NewTicker returns a new Ticker containing a channel that will send the
time with a period specified by the duration argument.
It adjusts the intervals or drops ticks to make up for slow receivers.
The duration d must be greater than zero; if not, NewTicker will panic.
Stop the ticker to release associated resources.
func NewTimer(d Duration) *Timer
NewTimer creates a new Timer that will send
the current time on its channel after at least duration d.
func Parse(layout, value string) (Time, error)
Parse parses a formatted string and returns the time value it represents.
The layout defines the format by showing how the reference time,
defined to be
Mon Jan 2 15:04:05 -0700 MST 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.
Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
and convenient representations of the reference time. For more information
about the formats and the definition of the reference time, see the
documentation for ANSIC and the other constants defined by this package.
Also, the executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Elements omitted from the value are assumed to be zero or, when
zero is impossible, one, so parsing "3:04pm" returns the time
corresponding to Jan 1, year 0, 15:04:00 UTC (note that because the year is
0, this time is before the zero Time).
Years must be in the range 0000..9999. The day of the week is checked
for syntax but it is otherwise ignored.
For layouts specifying the two-digit year 06, a value NN >= 69 will be treated
as 19NN and a value NN < 69 will be treated as 20NN.
In the absence of a time zone indicator, Parse returns a time in UTC.
When parsing a time with a zone offset like -0700, if the offset corresponds
to a time zone used by the current location (Local), then Parse uses that
location and zone in the returned time. Otherwise it records the time as
being in a fabricated location with time fixed at the given zone offset.
When parsing a time with a zone abbreviation like MST, if the zone abbreviation
has a defined offset in the current location, then that offset is used.
The zone abbreviation "UTC" is recognized as UTC regardless of location.
If the zone abbreviation is unknown, Parse records the time as being
in a fabricated location with the given zone abbreviation and a zero offset.
This choice means that such a time can be parsed and reformatted with the
same layout losslessly, but the exact instant used in the representation will
differ by the actual zone offset. To avoid such problems, prefer time layouts
that use a numeric zone offset, or use ParseInLocation.
func ParseDuration(s string) (Duration, error)
ParseDuration parses a duration string.
A duration string is a possibly signed sequence of
decimal numbers, each with optional fraction and a unit suffix,
such as "300ms", "-1.5h" or "2h45m".
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
func ParseInLocation(layout, value string, loc *Location) (Time, error)
ParseInLocation is like Parse but differs in two important ways.
First, in the absence of time zone information, Parse interprets a time as UTC;
ParseInLocation interprets the time as in the given location.
Second, when given a zone offset or abbreviation, Parse tries to match it
against the Local location; ParseInLocation uses the given location.
const RFC1123 = "Mon, 02 Jan 2006 15:04:05 MST"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const RFC1123Z = "Mon, 02 Jan 2006 15:04:05 -0700" // RFC1123 with numeric zone
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const RFC3339 = "2006-01-02T15:04:05Z07:00"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const RFC822 = "02 Jan 06 15:04 MST"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const RFC822Z = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const RFC850 = "Monday, 02-Jan-06 15:04:05 MST"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const RubyDate = "Mon Jan 02 15:04:05 -0700 2006"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const SecondDuration = 1000000000
Common durations. There is no definition for units of Day or larger
to avoid confusion across daylight savings time zone transitions.
To count the number of units in a Duration, divide:
second := time.Second
fmt.Print(int64(second/time.Millisecond)) // prints 1000
To convert an integer number of units to a Duration, multiply:
seconds := 10
fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
func Since(t Time) Duration
Since returns the time elapsed since t.
It is shorthand for time.Now().Sub(t).
func Sleep(d Duration)
Sleep pauses the current goroutine for at least the duration d.
A negative or zero duration causes Sleep to return immediately.
const Stamp = "Jan _2 15:04:05"
Handy time stamps.
const StampMicro = "Jan _2 15:04:05.000000"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const StampMilli = "Jan _2 15:04:05.000"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
const StampNano = "Jan _2 15:04:05.000000000"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
func Tick(d Duration) <-chan Time
Tick is a convenience wrapper for NewTicker providing access to the ticking
channel only. While Tick is useful for clients that have no need to shut down
the Ticker, be aware that without a way to shut it down the underlying
Ticker cannot be recovered by the garbage collector; it "leaks".
Unlike NewTicker, Tick will return nil if d <= 0.
func Unix(sec int64, nsec int64) Time
Unix returns the local Time corresponding to the given Unix time,
sec seconds and nsec nanoseconds since January 1, 1970 UTC.
It is valid to pass nsec outside the range [0, 999999999].
Not all sec values have a corresponding time value. One such
value is 1<<63-1 (the largest int64 value).
const UnixDate = "Mon Jan _2 15:04:05 MST 2006"
These are predefined layouts for use in Time.Format and time.Parse.
The reference time used in the layouts is the specific time:
Mon Jan 2 15:04:05 MST 2006
which is Unix time 1136239445. Since MST is GMT-0700,
the reference time can be thought of as
01/02 03:04:05PM '06 -0700
To define your own format, write down what the reference time would look
like formatted your way; see the values of constants like ANSIC,
StampMicro or Kitchen for examples. The model is to demonstrate what the
reference time looks like so that the Format and Parse methods can apply
the same transformation to a general time value.
Some valid layouts are invalid time values for time.Parse, due to formats
such as _ for space padding and Z for zone information.
Within the format string, an underscore _ represents a space that may be
replaced by a digit if the following number (a day) has two digits; for
compatibility with fixed-width Unix time formats.
A decimal point followed by one or more zeros represents a fractional
second, printed to the given number of decimal places. A decimal point
followed by one or more nines represents a fractional second, printed to
the given number of decimal places, with trailing zeros removed.
When parsing (only), the input may contain a fractional second
field immediately after the seconds field, even if the layout does not
signify its presence. In that case a decimal point followed by a maximal
series of digits is parsed as a fractional second.
Numeric time zone offsets format as follows:
-0700 ±hhmm
-07:00 ±hh:mm
-07 ±hh
Replacing the sign in the format with a Z triggers
the ISO 8601 behavior of printing Z instead of an
offset for the UTC zone. Thus:
Z0700 Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07 Z or ±hh
The recognized day of week formats are "Mon" and "Monday".
The recognized month formats are "Jan" and "January".
The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded
day of month. The formats __2 and 002 are space-padded and zero-padded
three-character day of year; there is no unpadded day of year format.
Text in the format string that is not recognized as part of the reference
time is echoed verbatim during Format and expected to appear verbatim
in the input to Parse.
The executable example for Time.Format demonstrates the working
of the layout string in detail and is a good reference.
Note that the RFC822, RFC850, and RFC1123 formats should be applied
only to local times. Applying them to UTC times will use "UTC" as the
time zone abbreviation, while strictly speaking those RFCs require the
use of "GMT" in that case.
In general RFC1123Z should be used instead of RFC1123 for servers
that insist on that format, and RFC3339 should be preferred for new protocols.
RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
when used with time.Parse they do not accept all the time formats
permitted by the RFCs and they do accept time formats not formally defined.
The RFC3339Nano format removes trailing zeros from the seconds field
and thus may not sort correctly once formatted.
func Until(t Time) Duration
Until returns the duration until t.
It is shorthand for t.Sub(time.Now()).
var UTC *Location
UTC represents Universal Coordinated Time (UTC).
The pages are generated with Goldsv0.1.6. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project and developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.
