Пакет time
Обзор
Пакет time предоставляет средства для измерения и отображения времени.
Календарные вычисления всегда предполагают григорианский календарь без високосных секунд.
Монотонные часы
Операционные системы предоставляют как «настенные часы», которые могут изменяться при синхронизации, так и «монотонные часы», которые не подвержены таким изменениям. Общее правило таково: настенные часы предназначены для определения времени, а монотонные — для его измерения. Вместо разделения API объект Time, возвращаемый функцией time.Now, содержит показания и настенных, и монотонных часов; последующие операции определения времени используют показания настенных часов, а операции измерения времени, а именно сравнение и вычитание, — показания монотонных часов.
Например, этот код всегда вычисляет положительное прошедшее время приблизительно в 20 миллисекунд, даже если настенные часы изменятся во время измеряемой операции:
start := time.Now() ... operation that takes 20 milliseconds ... t := time.Now() elapsed := t.Sub(start)
Другие идиомы, такие как time.Since(start), time.Until(deadline) и time.Now().Before(deadline), также устойчивы к сбросу настенных часов.
В остальной части этого раздела подробно описано использование монотонных часов операциями, но для применения этого пакета понимание этих деталей не требуется.
Объект Time, возвращаемый функцией time.Now, содержит показания монотонных часов. Если объект Time t содержит показания монотонных часов, t.Add прибавляет одну и ту же длительность к показаниям настенных и монотонных часов, чтобы вычислить результат. Поскольку t.AddDate(y, m, d), t.Round(d) и t.Truncate(d) выполняют вычисления по настенному времени, они всегда удаляют показания монотонных часов из результатов. Поскольку t.In, t.Local и t.UTC используются для изменения интерпретации настенного времени, они также удаляют показания монотонных часов из результатов. Стандартный способ удалить показания монотонных часов — использовать t = t.Round(0).
Если объекты Time t и u оба содержат показания монотонных часов, операции t.After(u), t.Before(u), t.Equal(u), t.Compare(u) и t.Sub(u) выполняются только с использованием показаний монотонных часов, без учета показаний настенных часов. Если хотя бы один из объектов t или u не содержит показаний монотонных часов, эти операции используют показания настенных часов.
В некоторых системах монотонные часы останавливаются, когда компьютер переходит в спящий режим. В такой системе t.Sub(u) может неточно отражать фактическое время, прошедшее между t и u. То же относится к другим функциям и методам, вычитающим значения времени, таким как Since, Until, Time.Before, Time.After, Time.Add, Time.Equal и Time.Compare. В некоторых случаях для получения точных результатов может потребоваться удалить показания монотонных часов.
Поскольку показания монотонных часов не имеют смысла вне текущего процесса, сериализованные представления, созданные с помощью t.GobEncode, t.MarshalBinary, t.MarshalJSON и t.MarshalText, не содержат показаний монотонных часов, а t.Format не предоставляет для них формат. Аналогично, конструкторы time.Date, time.Parse, time.ParseInLocation и time.Unix, а также функции десериализации t.GobDecode, t.UnmarshalBinary, t.UnmarshalJSON и t.UnmarshalText всегда создают значения времени без показаний монотонных часов.
Показания монотонных часов существуют только в значениях Time. Они не являются частью значений Duration или времени Unix, возвращаемого t.Unix и аналогичными функциями.
Обратите внимание: оператор Go == сравнивает не только момент времени, но также Location и показания монотонных часов. Обсуждение проверки равенства значений Time см. в документации по типу Time.
Для отладки результат t.String включает показания монотонных часов, если они есть. Если t != u из-за разных показаний монотонных часов, это различие будет видно при выводе t.String() и u.String().
Разрешение таймеров
Разрешение Timer зависит от среды выполнения Go, операционной системы и используемого оборудования. В Unix разрешение составляет ~1 мс. В Windows версии 1803 и новее разрешение составляет ~0,5 мс. В более ранних версиях Windows разрешение по умолчанию составляет ~16 мс, однако можно запросить более высокое разрешение с помощью golang.org/x/sys/windows.TimeBeginPeriod.
Указатель
Примеры
- After
- Date
- Duration
- Duration.Abs
- Duration.Hours
- Duration.Microseconds
- Duration.Milliseconds
- Duration.Minutes
- Duration.Nanoseconds
- Duration.Round
- Duration.Seconds
- Duration.String
- Duration.Truncate
- FixedZone
- LoadLocation
- Location
- Month
- NewTicker
- Parse
- ParseDuration
- ParseInLocation
- Since
- Sleep
- Tick
- Time.Add
- Time.AddDate
- Time.After
- Time.AppendBinary
- Time.AppendFormat
- Time.AppendText
- Time.Before
- Time.Date
- Time.Day
- Time.Equal
- Time.Format
- Time.Format (дополнение)
- Time.GoString
- Time.Round
- Time.String
- Time.Sub
- Time.Truncate
- Time.Unix
- Unix
- UnixMicro
- UnixMilli
- Until
Файлы пакета
format.go format_rfc3339.go sleep.go sys_unix.go tick.go time.go zoneinfo.go zoneinfo_goroot.go zoneinfo_read.go zoneinfo_unix.go
Константы
Это предопределенные шаблоны для использования в Time.Format и time.Parse. В качестве опорного времени в этих шаблонах используется конкретная временная метка:
01/02 03:04:05PM '06 -0700
(2 января 2006 года, 15:04:05, часовой пояс на семь часов западнее GMT). Это значение записано в константе с именем Layout, приведенной ниже. В формате времени Unix это 1136239445. Поскольку MST — это GMT-0700, команда Unix date выведет опорное время так:
Mon Jan 2 15:04:05 MST 2006
Прискорбная историческая ошибка: в дате используется американский формат, в котором числовое значение месяца стоит перед днем.
Пример для Time.Format подробно демонстрирует работу строки шаблона и служит хорошим справочным материалом.
Обратите внимание, что форматы RFC822, RFC850 и RFC1123 следует применять только к местному времени. При применении к времени UTC в качестве сокращения часового пояса будет использоваться "UTC", хотя, строго говоря, соответствующие RFC требуют в этом случае "GMT". При использовании форматов RFC1123 или RFC1123Z для разбора учтите, что эти форматы задают ведущий ноль для дня месяца, что строго говоря не разрешено RFC 1123. В результате при разборе строк дат, попадающих на первые 9 дней месяца, возникнет ошибка. В общем случае для серверов, требующих этот формат, вместо RFC1123 следует использовать RFC1123Z, а для новых протоколов предпочтителен RFC3339. Форматы RFC3339, RFC822, RFC822Z, RFC1123 и RFC1123Z полезны для форматирования; при использовании с time.Parse они не принимают все форматы времени, разрешенные соответствующими RFC, и принимают форматы времени, официально не определенные в них. Формат RFC3339Nano удаляет завершающие нули из поля секунд и поэтому после форматирования может сортироваться некорректно.
Большинство программ могут использовать одну из определенных констант в качестве шаблона, передаваемого в Format или Parse. Остальную часть этого комментария можно не читать, если вы не создаете собственную строку шаблона.
Чтобы определить собственный формат, запишите, как выглядело бы опорное время, отформатированное нужным вам способом; примеры см. в значениях таких констант, как ANSIC, StampMicro или Kitchen. Этот образец демонстрирует, как выглядит опорное время, чтобы методы Format и Parse могли применить такое же преобразование к произвольному значению времени.
Ниже приводится сводка компонентов строки шаблона. Каждый элемент показывает на примере форматирование компонента опорного времени. Распознаются только эти значения. Текст строки шаблона, который не распознается как часть опорного времени, при форматировании выводится без изменений и должен без изменений присутствовать во входных данных для Parse.
Year: "2006" "06" Month: "Jan" "January" "01" "1" Day of the week: "Mon" "Monday" Day of the month: "2" "_2" "02" Day of the year: "__2" "002" Hour: "15" "3" "03" (PM or AM) Minute: "4" "04" Second: "5" "05" AM/PM mark: "PM"
Числовые смещения часовых поясов форматируются следующим образом:
"-0700" ±hhmm "-07:00" ±hh:mm "-07" ±hh "-070000" ±hhmmss "-07:00:00" ±hh:mm:ss
Замена знака в формате на Z включает поведение ISO 8601, при котором для часового пояса UTC вместо смещения выводится Z. Например:
"Z0700" Z or ±hhmm "Z07:00" Z or ±hh:mm "Z07" Z or ±hh "Z070000" Z or ±hhmmss "Z07:00:00" Z or ±hh:mm:ss
В строке формата символы подчеркивания в "_2" и "__2" обозначают пробелы, которые могут заменяться цифрами, если следующее число состоит из нескольких цифр; это обеспечивает совместимость с форматами времени Unix фиксированной ширины. Начальный ноль обозначает значение с дополнением нулями.
Форматы __2 и 002 обозначают день года из трех символов с дополнением пробелами и нулями соответственно; формата дня года без дополнения нет.
Запятая или десятичная точка, за которой следует один или несколько нулей, обозначает дробную часть секунды, выводимую с указанным количеством знаков после запятой. Запятая или десятичная точка, за которой следует одна или несколько девяток, обозначает дробную часть секунды, выводимую с указанным количеством знаков после запятой с удалением завершающих нулей. Например, формат "15:04:05,000" или "15:04:05.000" выполняет форматирование и разбор с точностью до миллисекунд.
Некоторые корректные шаблоны задают недопустимые значения времени для time.Parse из-за таких форматов, как _ для дополнения пробелами и Z для сведений о часовом поясе.
const (
Layout = "01/02 03:04:05PM '06 -0700" // The reference time, in numerical order.
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"
DateTime = "2006-01-02 15:04:05"
DateOnly = "2006-01-02"
TimeOnly = "15:04:05"
) Распространенные единицы длительности. Единицы дня и крупнее не определены, чтобы избежать неоднозначности при переходе на летнее время.
Чтобы посчитать количество единиц в значении Duration, разделите его:
second := time.Second fmt.Print(int64(second/time.Millisecond)) // prints 1000
Чтобы преобразовать целое число единиц в Duration, умножьте его:
seconds := 10 fmt.Print(time.Duration(seconds)*time.Second) // prints 10s
const (
Nanosecond Duration = 1
Microsecond = 1000 * Nanosecond
Millisecond = 1000 * Microsecond
Second = 1000 * Millisecond
Minute = 60 * Second
Hour = 60 * Minute
) func After
func After(d Duration) <-chan Time
After ожидает истечения указанной длительности, а затем отправляет текущее время в возвращаемый канал. Эта функция эквивалентна NewTimer(d).C.
До Go 1.23 в этой документации предупреждалось, что сборщик мусора не освободит базовый Timer, пока не сработает таймер, и что при необходимости повысить эффективность следует вместо этого использовать NewTimer и вызывать Timer.Stop, если таймер больше не нужен. Начиная с Go 1.23 сборщик мусора может освобождать неиспользуемые таймеры, даже если их не останавливали. Если достаточно After, нет причин предпочитать NewTimer.
Пример
Код:
select {
case m := <-c:
handle(m)
case <-time.After(10 * time.Second):
fmt.Println("timed out")
}
func Sleep
func Sleep(d Duration)
Sleep приостанавливает текущую горутину как минимум на длительность d. При отрицательной или нулевой длительности Sleep немедленно возвращает управление.
Пример
Код:
time.Sleep(100 * time.Millisecond)
func Tick
func Tick(d Duration) <-chan Time
Tick — это вспомогательная обертка для NewTicker, предоставляющая доступ только к каналу тиков. В отличие от NewTicker, Tick возвращает nil, если d <= 0.
До Go 1.23 в этой документации предупреждалось, что сборщик мусора никогда не освободит базовый Ticker, и что при необходимости повысить эффективность следует вместо этого использовать NewTicker и вызывать Ticker.Stop, когда тикер больше не нужен. Начиная с Go 1.23 сборщик мусора может освобождать неиспользуемые тикеры, даже если они не были остановлены. Метод Stop больше не требуется для помощи сборщику мусора. Если достаточно Tick, больше нет причин предпочитать NewTicker.
Пример
Код:
c := time.Tick(5 * time.Second)
for next := range c {
fmt.Printf("%v %s\n", next, statusUpdate())
}
type Duration
Duration представляет прошедшее между двумя моментами время в виде количества наносекунд типа int64. Такое представление ограничивает максимальную длительность приблизительно 290 годами.
type Duration int64
Пример
Код:
t0 := time.Now()
expensiveCall()
t1 := time.Now()
fmt.Printf("The call took %v to run.\n", t1.Sub(t0))
func ParseDuration
func ParseDuration(s string) (Duration, error)
ParseDuration разбирает строку длительности. Строка длительности состоит из последовательности десятичных чисел, перед каждым из которых может стоять знак, а после каждого может указываться дробная часть и суффикс единицы измерения, например "300ms", "-1.5h" или "2h45m". Допустимые единицы времени: "ns", "us" (или "µs"), "ms", "s", "m", "h".
Пример
Код:
hours, _ := time.ParseDuration("10h")
complex, _ := time.ParseDuration("1h10m10s")
micro, _ := time.ParseDuration("1µs")
// The package also accepts the incorrect but common prefix u for micro.
micro2, _ := time.ParseDuration("1us")
fmt.Println(hours)
fmt.Println(complex)
fmt.Printf("There are %.0f seconds in %v.\n", complex.Seconds(), complex)
fmt.Printf("There are %d nanoseconds in %v.\n", micro.Nanoseconds(), micro)
fmt.Printf("There are %6.2e seconds in %v.\n", micro2.Seconds(), micro2)
Вывод:
10h0m0s 1h10m10s There are 4210 seconds in 1h10m10s. There are 1000 nanoseconds in 1µs. There are 1.00e-06 seconds in 1µs.
func Since
func Since(t Time) Duration
Since возвращает время, прошедшее с момента t. Это сокращенная запись для time.Now().Sub(t).
Пример
Код:
start := time.Now()
expensiveCall()
elapsed := time.Since(start)
fmt.Printf("The call took %v to run.\n", elapsed)
func Until 1.8
func Until(t Time) Duration
Until возвращает длительность до момента t. Это сокращенная запись для t.Sub(time.Now()).
Пример
Код:
futureTime := time.Now().Add(5 * time.Second)
durationUntil := time.Until(futureTime)
fmt.Printf("Duration until future time: %.0f seconds", math.Ceil(durationUntil.Seconds()))
Вывод:
Duration until future time: 5 seconds
func (Duration) Abs 1.19
func (d Duration) Abs() Duration
Abs возвращает абсолютное значение d. В особом случае Duration(math.MinInt64) преобразуется в Duration(math.MaxInt64), поэтому его величина уменьшается на 1 наносекунду.
Пример
Код:
positiveDuration := 5 * time.Second
negativeDuration := -3 * time.Second
minInt64CaseDuration := time.Duration(math.MinInt64)
absPositive := positiveDuration.Abs()
absNegative := negativeDuration.Abs()
absSpecial := minInt64CaseDuration.Abs() == time.Duration(math.MaxInt64)
fmt.Printf("Absolute value of positive duration: %v\n", absPositive)
fmt.Printf("Absolute value of negative duration: %v\n", absNegative)
fmt.Printf("Absolute value of MinInt64 equal to MaxInt64: %t\n", absSpecial)
Вывод:
Absolute value of positive duration: 5s Absolute value of negative duration: 3s Absolute value of MinInt64 equal to MaxInt64: true
func (Duration) Hours
func (d Duration) Hours() float64
Hours возвращает длительность в виде числа часов с плавающей точкой.
Пример
Код:
h, _ := time.ParseDuration("4h30m")
fmt.Printf("I've got %.1f hours of work left.", h.Hours())
Вывод:
I've got 4.5 hours of work left.
func (Duration) Microseconds 1.13
func (d Duration) Microseconds() int64
Microseconds возвращает длительность в виде целого количества микросекунд.
Пример
Код:
u, _ := time.ParseDuration("1s")
fmt.Printf("One second is %d microseconds.\n", u.Microseconds())
Вывод:
One second is 1000000 microseconds.
func (Duration) Milliseconds 1.13
func (d Duration) Milliseconds() int64
Milliseconds возвращает длительность в виде целого количества миллисекунд.
Пример
Код:
u, _ := time.ParseDuration("1s")
fmt.Printf("One second is %d milliseconds.\n", u.Milliseconds())
Вывод:
One second is 1000 milliseconds.
func (Duration) Minutes
func (d Duration) Minutes() float64
Minutes возвращает длительность в виде числа минут с плавающей точкой.
Пример
Код:
m, _ := time.ParseDuration("1h30m")
fmt.Printf("The movie is %.0f minutes long.", m.Minutes())
Вывод:
The movie is 90 minutes long.
func (Duration) Nanoseconds
func (d Duration) Nanoseconds() int64
Nanoseconds возвращает длительность в виде целого количества наносекунд.
Пример
Код:
u, _ := time.ParseDuration("1µs")
fmt.Printf("One microsecond is %d nanoseconds.\n", u.Nanoseconds())
Вывод:
One microsecond is 1000 nanoseconds.
func (Duration) Round 1.9
func (d Duration) Round(m Duration) Duration
Round возвращает результат округления d до ближайшего кратного m. При округлении половинных значений выполняется округление от нуля. Если результат превышает максимальное (или минимальное) значение, которое можно сохранить в Duration, Round возвращает максимальную (или минимальную) длительность. Если m <= 0, Round возвращает d без изменений.
Пример
Код:
d, err := time.ParseDuration("1h15m30.918273645s")
if err != nil {
panic(err)
}
round := []time.Duration{
time.Nanosecond,
time.Microsecond,
time.Millisecond,
time.Second,
2 * time.Second,
time.Minute,
10 * time.Minute,
time.Hour,
}
for _, r := range round {
fmt.Printf("d.Round(%6s) = %s\n", r, d.Round(r).String())
}
Вывод:
d.Round( 1ns) = 1h15m30.918273645s d.Round( 1µs) = 1h15m30.918274s d.Round( 1ms) = 1h15m30.918s d.Round( 1s) = 1h15m31s d.Round( 2s) = 1h15m30s d.Round( 1m0s) = 1h16m0s d.Round( 10m0s) = 1h20m0s d.Round(1h0m0s) = 1h0m0s
func (Duration) Seconds
func (d Duration) Seconds() float64
Seconds возвращает длительность в виде числа секунд с плавающей точкой.
Пример
Код:
m, _ := time.ParseDuration("1m30s")
fmt.Printf("Take off in t-%.0f seconds.", m.Seconds())
Вывод:
Take off in t-90 seconds.
func (Duration) String
func (d Duration) String() string
String возвращает строковое представление длительности в формате "72h3m0.5s". Начальные нулевые единицы опускаются. В особом случае для длительностей меньше секунды используется меньшая единица (милли-, микро- или наносекунды), чтобы первая цифра была ненулевой. Нулевая длительность представляется как 0s.
Пример
Код:
fmt.Println(1*time.Hour + 2*time.Minute + 300*time.Millisecond) fmt.Println(300 * time.Millisecond)
Вывод:
1h2m0.3s 300ms
func (Duration) Truncate 1.9
func (d Duration) Truncate(m Duration) Duration
Truncate возвращает результат округления d к нулю до значения, кратного m. Если m <= 0, Truncate возвращает d без изменений.
Пример
Код:
d, err := time.ParseDuration("1h15m30.918273645s")
if err != nil {
panic(err)
}
trunc := []time.Duration{
time.Nanosecond,
time.Microsecond,
time.Millisecond,
time.Second,
2 * time.Second,
time.Minute,
10 * time.Minute,
time.Hour,
}
for _, t := range trunc {
fmt.Printf("d.Truncate(%6s) = %s\n", t, d.Truncate(t).String())
}
Вывод:
d.Truncate( 1ns) = 1h15m30.918273645s d.Truncate( 1µs) = 1h15m30.918273s d.Truncate( 1ms) = 1h15m30.918s d.Truncate( 1s) = 1h15m30s d.Truncate( 2s) = 1h15m30s d.Truncate( 1m0s) = 1h15m0s d.Truncate( 10m0s) = 1h10m0s d.Truncate(1h0m0s) = 1h0m0s
type Location
Location сопоставляет моменты времени часовому поясу, действующему в этот момент. Как правило, Location представляет набор смещений времени, используемых в географической области. Во многих объектах Location смещение времени зависит от того, действует ли в данный момент летнее время.
Location используется для указания часового пояса при выводе значения Time и для вычислений с интервалами, которые могут пересекать границы перехода на летнее время.
type Location struct {
// contains filtered or unexported fields
}
Local представляет местный часовой пояс системы. В Unix-системах Local обращается к переменной окружения TZ, чтобы определить используемый часовой пояс. Если TZ не задана, используется системное значение по умолчанию /etc/localtime. Если TZ="", используется UTC. Если TZ="foo", используется файл foo в системном каталоге часовых поясов.
var Local *Location = &localLoc
UTC представляет всемирное координированное время (UTC).
var UTC *Location = &utcLoc
Пример
Код:
// China doesn't have daylight saving. It uses a fixed 8 hour offset from UTC.
secondsEastOfUTC := int((8 * time.Hour).Seconds())
beijing := time.FixedZone("Beijing Time", secondsEastOfUTC)
// If the system has a timezone database present, it's possible to load a location
// from that, e.g.:
// newYork, err := time.LoadLocation("America/New_York")
// Creating a time requires a location. Common locations are time.Local and time.UTC.
timeInUTC := time.Date(2009, 1, 1, 12, 0, 0, 0, time.UTC)
sameTimeInBeijing := time.Date(2009, 1, 1, 20, 0, 0, 0, beijing)
// Although the UTC clock time is 1200 and the Beijing clock time is 2000, Beijing is
// 8 hours ahead so the two dates actually represent the same instant.
timesAreEqual := timeInUTC.Equal(sameTimeInBeijing)
fmt.Println(timesAreEqual)
Вывод:
true
func FixedZone
func FixedZone(name string, offset int) *Location
FixedZone возвращает Location, который всегда использует заданное имя часового пояса и смещение (в секундах к востоку от UTC).
Пример
Код:
loc := time.FixedZone("UTC-8", -8*60*60)
t := time.Date(2009, time.November, 10, 23, 0, 0, 0, loc)
fmt.Println("The time is:", t.Format(time.RFC822))
Вывод:
The time is: 10 Nov 09 23:00 UTC-8
func LoadLocation
func LoadLocation(name string) (*Location, error)
LoadLocation возвращает Location с заданным именем.
Если имя — "" или "UTC", LoadLocation возвращает UTC. Если имя — "Local", LoadLocation возвращает Local.
В противном случае создается новый объект Location, где имя соответствует названию местоположения из файла базы часовых поясов IANA, например "America/New_York".
LoadLocation ищет базу часовых поясов IANA в следующих местах в указанном порядке:
- каталог или несжатый ZIP-файл, заданный переменной окружения ZONEINFO
- в Unix-системе — стандартный системный каталог установки
- $GOROOT/lib/time/zoneinfo.zip
- пакет time/tzdata, если он был импортирован
Пример
Код:
location, err := time.LoadLocation("America/Los_Angeles")
if err != nil {
panic(err)
}
timeInUTC := time.Date(2018, 8, 30, 12, 0, 0, 0, time.UTC)
fmt.Println(timeInUTC.In(location))
Вывод:
2018-08-30 05:00:00 -0700 PDT
func LoadLocationFromTZData 1.10
func LoadLocationFromTZData(name string, data []byte) (*Location, error)
LoadLocationFromTZData возвращает новый объект Location с заданным именем, инициализированный данными в формате базы часовых поясов IANA. Данные должны быть представлены в формате стандартного файла часового пояса IANA (например, содержимого /etc/localtime в Unix-системах).
func (*Location) String
func (l *Location) String() string
String возвращает описательное имя сведений о часовом поясе, соответствующее аргументу name функций LoadLocation или FixedZone.
type Month
Month задает месяц года (January = 1, ...).
type Month int
const (
January Month = 1 + iota
February
March
April
May
June
July
August
September
October
November
December
) Пример
Код:
_, month, day := time.Now().Date()
if month == time.November && day == 10 {
fmt.Println("Happy Go day!")
}
func (Month) String
func (m Month) String() string
String возвращает английское название месяца ("January", "February", ...).
type ParseError
ParseError описывает проблему при разборе строки времени.
type ParseError struct {
Layout string
Value string
LayoutElem string
ValueElem string
Message string
}
func (*ParseError) Error
func (e *ParseError) Error() string
Error возвращает строковое представление ParseError.
type Ticker
Тикер содержит канал, который через заданные интервалы передаёт «тики» часов.
type Ticker struct {
C <-chan Time // The channel on which the ticks are delivered.
// contains filtered or unexported fields
}
func NewTicker
func NewTicker(d Duration) *Ticker
NewTicker возвращает новый Ticker, содержащий канал, который после каждого тика отправляет в канал текущее время. Период тиков задаётся аргументом duration. Тикер корректирует интервал времени или пропускает тики, чтобы компенсировать медленную работу получателей. Значение duration d должно быть больше нуля; в противном случае NewTicker вызовет панику.
До Go 1.23 сборщик мусора не освобождал тикеры, которые ещё не сработали или не были остановлены, поэтому код часто сразу после вызова NewTicker откладывал вызов t.Stop, чтобы тикер можно было освободить, когда он больше не нужен. Начиная с Go 1.23 сборщик мусора может освобождать тикеры, на которые больше нет ссылок, даже если они не были остановлены. Метод Stop больше не нужен для помощи сборщику мусора. (Разумеется, код всё ещё может вызывать Stop, чтобы остановить тикер по другим причинам.)
Пример
Код:
ticker := time.NewTicker(time.Second)
defer ticker.Stop()
done := make(chan bool)
go func() {
time.Sleep(10 * time.Second)
done <- true
}()
for {
select {
case <-done:
fmt.Println("Done!")
return
case t := <-ticker.C:
fmt.Println("Current time: ", t)
}
}
func (*Ticker) Reset 1.15
func (t *Ticker) Reset(d Duration)
Reset останавливает тикер и устанавливает для него указанный период. Следующий тик произойдёт по истечении нового периода. Значение duration d должно быть больше нуля; в противном случае Reset вызовет панику.
func (*Ticker) Stop
func (t *Ticker) Stop()
Stop отключает тикер. После вызова Stop новые тики отправляться не будут. Stop не закрывает канал, чтобы можно было вызывать Ticker.Reset и чтобы горутина, одновременно читающая данные из канала, не получила ошибочный «тик».
type Time
Time представляет момент времени с наносекундной точностью.
Программы обычно должны хранить и передавать значения времени как значения, а не как указатели. То есть переменные времени и поля структур должны иметь тип time.Time, а не *time.Time.
Одно значение Time могут одновременно использовать несколько горутин, за исключением методов Time.GobDecode, Time.UnmarshalBinary, Time.UnmarshalJSON и Time.UnmarshalText, которые не являются безопасными для конкурентного использования.
Моменты времени можно сравнивать с помощью методов Time.Before, Time.After и Time.Equal. Метод Time.Sub вычитает один момент времени из другого и возвращает значение типа Duration. Метод Time.Add складывает значения Time и Duration и возвращает значение Time.
Нулевое значение типа Time — это 1 января 1 года, 00:00:00.000000000 UTC. Поскольку такое время вряд ли встретится на практике, метод Time.IsZero позволяет просто определить, было ли время явно инициализировано.
С каждым временем связана Location. Методы Time.Local, Time.UTC и Time.In возвращают Time с заданной Location. Изменение Location значения Time с помощью этих методов не меняет представляемый им фактический момент времени, а лишь часовой пояс, в котором его следует интерпретировать.
Представления значения Time, сохраняемые методами Time.GobEncode, Time.MarshalBinary, Time.AppendBinary, Time.MarshalJSON, Time.MarshalText и Time.AppendText, содержат смещение Time.Location, но не название местоположения. Поэтому при сериализации теряется информация о переходе на летнее время.
Помимо обязательного показания «настенных часов», Time может содержать необязательное показание монотонных часов текущего процесса, позволяющее повысить точность сравнения или вычитания. Подробности см. в разделе «Монотонные часы» документации пакета.
Обратите внимание, что оператор Go == сравнивает не только момент времени, но также Location и показание монотонных часов. Поэтому значения Time не следует использовать в качестве ключей карт или баз данных, не убедившись предварительно, что для всех значений установлена одна и та же Location (этого можно добиться с помощью метода UTC или Local) и что показание монотонных часов удалено присваиванием t = t.Round(0). В общем случае предпочтительнее использовать t.Equal(u), а не t == u, поскольку t.Equal применяет наиболее точное из доступных сравнений и корректно обрабатывает ситуацию, когда показание монотонных часов есть только у одного из аргументов.
type Time struct {
// contains filtered or unexported fields
}
func Date
func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time
Date возвращает Time, соответствующее
yyyy-mm-dd hh:mm:ss + nsec nanoseconds
в подходящем часовом поясе для этого времени в указанном местоположении.
Значения month, day, hour, min, sec и nsec могут выходить за свои обычные диапазоны и будут нормализованы при преобразовании. Например, 32 октября преобразуется в 1 ноября.
При переходе на летнее время некоторые моменты пропускаются или повторяются. Например, в США 13 марта 2011 года 2:15 ночи не наступало, а 6 ноября 2011 года 1:15 ночи наступало дважды. В таких случаях выбор часового пояса и, следовательно, времени не определён однозначно. Date возвращает время, корректное в одном из двух часовых поясов, участвующих в переходе, но не гарантирует, в каком именно.
Date вызывает панику, если loc равен nil.
Пример
Код:
t := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)
fmt.Printf("Go launched at %s\n", t.Local())
Вывод:
Go launched at 2009-11-10 15:00:00 -0800 PST
func Now
func Now() Time
Now возвращает текущее местное время.
func Parse
func Parse(layout, value string) (Time, error)
Parse разбирает строку в заданном формате и возвращает представляемое ею значение времени. Описание того, как задать формат, см. в документации константы Layout. Второй аргумент должен поддаваться разбору с использованием строки формата (шаблона), переданной первым аргументом.
Пример для Time.Format подробно демонстрирует работу строки шаблона и служит хорошим справочным материалом.
Только при разборе входные данные могут содержать поле дробной части секунды непосредственно после поля секунд, даже если шаблон не указывает на его наличие. В этом случае запятая или десятичная точка, за которой следует максимально длинная последовательность цифр, разбирается как дробная часть секунды. Дробная часть секунды усекается до наносекундной точности.
Элементы, пропущенные в шаблоне, считаются равными нулю или, если ноль невозможен, единице, поэтому разбор строки "3:04pm" возвращает время, соответствующее 1 января 0 года, 15:04:00 UTC (обратите внимание, что из-за года 0 это время предшествует нулевому значению Time). Год должен находиться в диапазоне 0000..9999. День недели проверяется на соответствие синтаксису, но в остальном игнорируется.
Для шаблонов, задающих двузначный год 06, значение NN >= 69 трактуется как 19NN, а значение NN < 69 — как 20NN.
Метки времени, представляющие високосные секунды (секунда 60), разобрать нельзя. Они не представимы типом Time.
Далее в этом комментарии описывается обработка часовых поясов.
Если индикатор часового пояса отсутствует, Parse возвращает время в UTC.
При разборе времени с указанием смещения часового пояса, например -0700, если это смещение соответствует часовому поясу, используемому текущим местоположением (Local), Parse использует это местоположение и часовой пояс в возвращаемом времени. В противном случае время сохраняется в искусственно созданном местоположении с часовым поясом, фиксированным на указанном смещении.
При разборе времени с аббревиатурой часового пояса, например MST, используется смещение, заданное для этой аббревиатуры в текущем местоположении, если оно определено. Аббревиатура часового пояса "UTC" распознаётся как UTC независимо от местоположения. Если аббревиатура часового пояса неизвестна, Parse сохраняет время в искусственно созданном местоположении с указанной аббревиатурой часового пояса и нулевым смещением. Благодаря этому такое время можно разобрать и повторно отформатировать с тем же шаблоном без потери данных, но точный момент времени в представлении будет отличаться на фактическое смещение часового пояса. Чтобы избежать подобных проблем, предпочтительно использовать шаблоны времени с числовым смещением часового пояса или применять ParseInLocation.
Пример
Код:
// See the example for Time.Format for a thorough description of how
// to define the layout string to parse a time.Time value; Parse and
// Format use the same model to describe their input and output.
// longForm shows by example how the reference time would be represented in
// the desired layout.
const longForm = "Jan 2, 2006 at 3:04pm (MST)"
t, _ := time.Parse(longForm, "Feb 3, 2013 at 7:54pm (PST)")
fmt.Println(t)
// shortForm is another way the reference time would be represented
// in the desired layout; it has no time zone present.
// Note: without explicit zone, returns time in UTC.
const shortForm = "2006-Jan-02"
t, _ = time.Parse(shortForm, "2013-Feb-03")
fmt.Println(t)
// Some valid layouts are invalid time values, due to format specifiers
// such as _ for space padding and Z for zone information.
// For example the RFC3339 layout 2006-01-02T15:04:05Z07:00
// contains both Z and a time zone offset in order to handle both valid options:
// 2006-01-02T15:04:05Z
// 2006-01-02T15:04:05+07:00
t, _ = time.Parse(time.RFC3339, "2006-01-02T15:04:05Z")
fmt.Println(t)
t, _ = time.Parse(time.RFC3339, "2006-01-02T15:04:05+07:00")
fmt.Println(t)
_, err := time.Parse(time.RFC3339, time.RFC3339)
fmt.Println("error", err) // Returns an error as the layout is not a valid time value
Вывод:
2013-02-03 19:54:00 -0800 PST 2013-02-03 00:00:00 +0000 UTC 2006-01-02 15:04:05 +0000 UTC 2006-01-02 15:04:05 +0700 +0700 error parsing time "2006-01-02T15:04:05Z07:00": extra text: "07:00"
func ParseInLocation 1.1
func ParseInLocation(layout, value string, loc *Location) (Time, error)
ParseInLocation похож на Parse, но отличается двумя важными особенностями. Во-первых, если информация о часовом поясе отсутствует, Parse трактует время как UTC, а ParseInLocation — как время в указанном местоположении. Во-вторых, если задано смещение или аббревиатура часового пояса, Parse пытается сопоставить их с местоположением Local, а ParseInLocation использует заданное местоположение.
Пример
Код:
loc, _ := time.LoadLocation("Europe/Berlin")
// This will look for the name CEST in the Europe/Berlin time zone.
const longForm = "Jan 2, 2006 at 3:04pm (MST)"
t, _ := time.ParseInLocation(longForm, "Jul 9, 2012 at 5:02am (CEST)", loc)
fmt.Println(t)
// Note: without explicit zone, returns time in given location.
const shortForm = "2006-Jan-02"
t, _ = time.ParseInLocation(shortForm, "2012-Jul-09", loc)
fmt.Println(t)
Вывод:
2012-07-09 05:02:00 +0200 CEST 2012-07-09 00:00:00 +0200 CEST
func Unix
func Unix(sec int64, nsec int64) Time
Unix возвращает местное время, соответствующее заданному времени Unix: sec секунд и nsec наносекунд, прошедших с 1 января 1970 года UTC. Значение nsec может выходить за пределы диапазона [0, 999999999]. Не каждому значению sec соответствует значение времени. Одно из таких значений — 1<<63-1 (наибольшее значение int64).
Пример
Код:
unixTime := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC) fmt.Println(unixTime.Unix()) t := time.Unix(unixTime.Unix(), 0).UTC() fmt.Println(t)
Вывод:
1257894000 2009-11-10 23:00:00 +0000 UTC
func UnixMicro 1.17
func UnixMicro(usec int64) Time
UnixMicro возвращает местное время, соответствующее заданному времени Unix: usec микросекунд, прошедших с 1 января 1970 года UTC.
Пример
Код:
umt := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC) fmt.Println(umt.UnixMicro()) t := time.UnixMicro(umt.UnixMicro()).UTC() fmt.Println(t)
Вывод:
1257894000000000 2009-11-10 23:00:00 +0000 UTC
func UnixMilli 1.17
func UnixMilli(msec int64) Time
UnixMilli возвращает местное время, соответствующее заданному времени Unix: msec миллисекунд, прошедших с 1 января 1970 года UTC.
Пример
Код:
umt := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC) fmt.Println(umt.UnixMilli()) t := time.UnixMilli(umt.UnixMilli()).UTC() fmt.Println(t)
Вывод:
1257894000000 2009-11-10 23:00:00 +0000 UTC
func (Time) Add
func (t Time) Add(d Duration) Time
Add возвращает время t+d.
Пример
Код:
start := time.Date(2009, 1, 1, 12, 0, 0, 0, time.UTC)
afterTenSeconds := start.Add(time.Second * 10)
afterTenMinutes := start.Add(time.Minute * 10)
afterTenHours := start.Add(time.Hour * 10)
afterTenDays := start.Add(time.Hour * 24 * 10)
fmt.Printf("start = %v\n", start)
fmt.Printf("start.Add(time.Second * 10) = %v\n", afterTenSeconds)
fmt.Printf("start.Add(time.Minute * 10) = %v\n", afterTenMinutes)
fmt.Printf("start.Add(time.Hour * 10) = %v\n", afterTenHours)
fmt.Printf("start.Add(time.Hour * 24 * 10) = %v\n", afterTenDays)
Вывод:
start = 2009-01-01 12:00:00 +0000 UTC start.Add(time.Second * 10) = 2009-01-01 12:00:10 +0000 UTC start.Add(time.Minute * 10) = 2009-01-01 12:10:00 +0000 UTC start.Add(time.Hour * 10) = 2009-01-01 22:00:00 +0000 UTC start.Add(time.Hour * 24 * 10) = 2009-01-11 12:00:00 +0000 UTC
func (Time) AddDate
func (t Time) AddDate(years int, months int, days int) Time
AddDate возвращает время, полученное прибавлением к t указанного числа лет, месяцев и дней. Например, применение AddDate(-1, 2, 3) к 1 января 2011 года возвращает 4 марта 2010 года.
Обратите внимание, что даты неразрывно связаны с часовыми поясами, а календарные периоды, например дни, не имеют фиксированной длительности. AddDate использует Location значения Time для определения этой длительности. Это означает, что одинаковые аргументы AddDate могут привести к разному сдвигу абсолютного времени в зависимости от исходного значения Time и его Location. Например, применение AddDate(0, 0, 1) к 12:00 27 марта всегда возвращает 12:00 28 марта. В некоторых местоположениях и годах сдвиг составит 24 часа. В других он составит 23 часа из-за перехода на летнее время.
AddDate нормализует результат так же, как Date: например, прибавление одного месяца к 31 октября даёт 1 декабря — нормализованное представление 31 ноября.
Пример
Код:
start := time.Date(2023, 03, 25, 12, 0, 0, 0, time.UTC)
oneDayLater := start.AddDate(0, 0, 1)
dayDuration := oneDayLater.Sub(start)
oneMonthLater := start.AddDate(0, 1, 0)
oneYearLater := start.AddDate(1, 0, 0)
zurich, err := time.LoadLocation("Europe/Zurich")
if err != nil {
panic(err)
}
// This was the day before a daylight saving time transition in Zürich.
startZurich := time.Date(2023, 03, 25, 12, 0, 0, 0, zurich)
oneDayLaterZurich := startZurich.AddDate(0, 0, 1)
dayDurationZurich := oneDayLaterZurich.Sub(startZurich)
fmt.Printf("oneDayLater: start.AddDate(0, 0, 1) = %v\n", oneDayLater)
fmt.Printf("oneMonthLater: start.AddDate(0, 1, 0) = %v\n", oneMonthLater)
fmt.Printf("oneYearLater: start.AddDate(1, 0, 0) = %v\n", oneYearLater)
fmt.Printf("oneDayLaterZurich: startZurich.AddDate(0, 0, 1) = %v\n", oneDayLaterZurich)
fmt.Printf("Day duration in UTC: %v | Day duration in Zürich: %v\n", dayDuration, dayDurationZurich)
Вывод:
oneDayLater: start.AddDate(0, 0, 1) = 2023-03-26 12:00:00 +0000 UTC oneMonthLater: start.AddDate(0, 1, 0) = 2023-04-25 12:00:00 +0000 UTC oneYearLater: start.AddDate(1, 0, 0) = 2024-03-25 12:00:00 +0000 UTC oneDayLaterZurich: startZurich.AddDate(0, 0, 1) = 2023-03-26 12:00:00 +0200 CEST Day duration in UTC: 24h0m0s | Day duration in Zürich: 23h0m0s
func (Time) After
func (t Time) After(u Time) bool
After сообщает, наступает ли момент времени t после u.
Пример
Код:
year2000 := time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC)
year3000 := time.Date(3000, 1, 1, 0, 0, 0, 0, time.UTC)
isYear3000AfterYear2000 := year3000.After(year2000) // True
isYear2000AfterYear3000 := year2000.After(year3000) // False
fmt.Printf("year3000.After(year2000) = %v\n", isYear3000AfterYear2000)
fmt.Printf("year2000.After(year3000) = %v\n", isYear2000AfterYear3000)
Вывод:
year3000.After(year2000) = true year2000.After(year3000) = false
func (Time) AppendBinary 1.24
func (t Time) AppendBinary(b []byte) ([]byte, error)
AppendBinary реализует интерфейс encoding.BinaryAppender.
Пример
Код:
t := time.Date(2025, 4, 1, 15, 30, 45, 123456789, time.UTC)
var buffer []byte
buffer, err := t.AppendBinary(buffer)
if err != nil {
panic(err)
}
var parseTime time.Time
err = parseTime.UnmarshalBinary(buffer[:])
if err != nil {
panic(err)
}
fmt.Printf("t: %v\n", t)
fmt.Printf("parseTime: %v\n", parseTime)
fmt.Printf("equal: %v\n", parseTime.Equal(t))
Вывод:
t: 2025-04-01 15:30:45.123456789 +0000 UTC parseTime: 2025-04-01 15:30:45.123456789 +0000 UTC equal: true
func (Time) AppendFormat 1.5
func (t Time) AppendFormat(b []byte, layout string) []byte
AppendFormat похож на Time.Format, но добавляет текстовое представление в b и возвращает расширенный буфер.
Пример
Код:
t := time.Date(2017, time.November, 4, 11, 0, 0, 0, time.UTC)
text := []byte("Time: ")
text = t.AppendFormat(text, time.Kitchen)
fmt.Println(string(text))
Вывод:
Time: 11:00AM
func (Time) AppendText 1.24
func (t Time) AppendText(b []byte) ([]byte, error)
AppendText реализует интерфейс encoding.TextAppender. Время форматируется в формате RFC 3339 с точностью до долей секунды. Если метку времени нельзя представить в корректном формате RFC 3339 (например, год выходит за допустимый диапазон), возвращается ошибка.
Пример
Код:
t := time.Date(2025, 4, 1, 15, 30, 45, 123456789, time.UTC)
buffer := []byte("t: ")
buffer, err := t.AppendText(buffer)
if err != nil {
panic(err)
}
fmt.Printf("%s\n", buffer)
Вывод:
t: 2025-04-01T15:30:45.123456789Z
func (Time) Before
func (t Time) Before(u Time) bool
Before сообщает, наступает ли момент времени t раньше u.
Пример
Код:
year2000 := time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC)
year3000 := time.Date(3000, 1, 1, 0, 0, 0, 0, time.UTC)
isYear2000BeforeYear3000 := year2000.Before(year3000) // True
isYear3000BeforeYear2000 := year3000.Before(year2000) // False
fmt.Printf("year2000.Before(year3000) = %v\n", isYear2000BeforeYear3000)
fmt.Printf("year3000.Before(year2000) = %v\n", isYear3000BeforeYear2000)
Вывод:
year2000.Before(year3000) = true year3000.Before(year2000) = false
func (Time) Clock
func (t Time) Clock() (hour, min, sec int)
Clock возвращает час, минуту и секунду в пределах дня, заданного значением t.
func (Time) Compare 1.20
func (t Time) Compare(u Time) int
Compare сравнивает момент времени t с u. Если t предшествует u, возвращается -1; если t следует за u, возвращается +1; если они совпадают, возвращается 0.
func (Time) Date
func (t Time) Date() (year int, month Month, day int)
Date возвращает год, месяц и день, на которые приходится t.
Пример
Код:
d := time.Date(2000, 2, 1, 12, 30, 0, 0, time.UTC)
year, month, day := d.Date()
fmt.Printf("year = %v\n", year)
fmt.Printf("month = %v\n", month)
fmt.Printf("day = %v\n", day)
Вывод:
year = 2000 month = February day = 1
func (Time) Day
func (t Time) Day() int
Day возвращает день месяца, заданный значением t.
Пример
Код:
d := time.Date(2000, 2, 1, 12, 30, 0, 0, time.UTC)
day := d.Day()
fmt.Printf("day = %v\n", day)
Вывод:
day = 1
func (Time) Equal
func (t Time) Equal(u Time) bool
Equal сообщает, представляют ли t и u один и тот же момент времени. Два времени могут быть равны, даже если они относятся к разным местоположениям. Например, 6:00 +0200 и 4:00 UTC равны. О проблемах использования == со значениями Time см. документацию типа Time; в большинстве случаев следует использовать Equal.
Пример
Код:
secondsEastOfUTC := int((8 * time.Hour).Seconds())
beijing := time.FixedZone("Beijing Time", secondsEastOfUTC)
// Unlike the equal operator, Equal is aware that d1 and d2 are the
// same instant but in different time zones.
d1 := time.Date(2000, 2, 1, 12, 30, 0, 0, time.UTC)
d2 := time.Date(2000, 2, 1, 20, 30, 0, 0, beijing)
datesEqualUsingEqualOperator := d1 == d2
datesEqualUsingFunction := d1.Equal(d2)
fmt.Printf("datesEqualUsingEqualOperator = %v\n", datesEqualUsingEqualOperator)
fmt.Printf("datesEqualUsingFunction = %v\n", datesEqualUsingFunction)
Вывод:
datesEqualUsingEqualOperator = false datesEqualUsingFunction = true
func (Time) Format
func (t Time) Format(layout string) string
Format возвращает текстовое представление значения времени, отформатированное согласно шаблону, заданному аргументом. Описание формата шаблона см. в документации константы Layout.
Исполняемый пример для Time.Format подробно демонстрирует работу строки шаблона и служит хорошим справочным материалом.
Пример
Код:
// Parse a time value from a string in the standard Unix format.
t, err := time.Parse(time.UnixDate, "Wed Feb 25 11:06:39 PST 2015")
if err != nil { // Always check errors even if they should not happen.
panic(err)
}
tz, err := time.LoadLocation("Asia/Shanghai")
if err != nil { // Always check errors even if they should not happen.
panic(err)
}
// time.Time's Stringer method is useful without any format.
fmt.Println("default format:", t)
// Predefined constants in the package implement common layouts.
fmt.Println("Unix format:", t.Format(time.UnixDate))
// The time zone attached to the time value affects its output.
fmt.Println("Same, in UTC:", t.UTC().Format(time.UnixDate))
fmt.Println("in Shanghai with seconds:", t.In(tz).Format("2006-01-02T15:04:05 -070000"))
fmt.Println("in Shanghai with colon seconds:", t.In(tz).Format("2006-01-02T15:04:05 -07:00:00"))
// The rest of this function demonstrates the properties of the
// layout string used in the format.
// The layout string used by the Parse function and Format method
// shows by example how the reference time should be represented.
// We stress that one must show how the reference time is formatted,
// not a time of the user's choosing. Thus each layout string is a
// representation of the time stamp,
// Jan 2 15:04:05 2006 MST
// An easy way to remember this value is that it holds, when presented
// in this order, the values (lined up with the elements above):
// 1 2 3 4 5 6 -7
// There are some wrinkles illustrated below.
// Most uses of Format and Parse use constant layout strings such as
// the ones defined in this package, but the interface is flexible,
// as these examples show.
// Define a helper function to make the examples' output look nice.
do := func(name, layout, want string) {
got := t.Format(layout)
if want != got {
fmt.Printf("error: for %q got %q; expected %q\n", layout, got, want)
return
}
fmt.Printf("%-16s %q gives %q\n", name, layout, got)
}
// Print a header in our output.
fmt.Printf("\nFormats:\n\n")
// Simple starter examples.
do("Basic full date", "Mon Jan 2 15:04:05 MST 2006", "Wed Feb 25 11:06:39 PST 2015")
do("Basic short date", "2006/01/02", "2015/02/25")
// The hour of the reference time is 15, or 3PM. The layout can express
// it either way, and since our value is the morning we should see it as
// an AM time. We show both in one format string. Lower case too.
do("AM/PM", "3PM==3pm==15h", "11AM==11am==11h")
// When parsing, if the seconds value is followed by a decimal point
// and some digits, that is taken as a fraction of a second even if
// the layout string does not represent the fractional second.
// Here we add a fractional second to our time value used above.
t, err = time.Parse(time.UnixDate, "Wed Feb 25 11:06:39.1234 PST 2015")
if err != nil {
panic(err)
}
// It does not appear in the output if the layout string does not contain
// a representation of the fractional second.
do("No fraction", time.UnixDate, "Wed Feb 25 11:06:39 PST 2015")
// Fractional seconds can be printed by adding a run of 0s or 9s after
// a decimal point in the seconds value in the layout string.
// If the layout digits are 0s, the fractional second is of the specified
// width. Note that the output has a trailing zero.
do("0s for fraction", "15:04:05.00000", "11:06:39.12340")
// If the fraction in the layout is 9s, trailing zeros are dropped.
do("9s for fraction", "15:04:05.99999999", "11:06:39.1234")
Вывод:
default format: 2015-02-25 11:06:39 -0800 PST Unix format: Wed Feb 25 11:06:39 PST 2015 Same, in UTC: Wed Feb 25 19:06:39 UTC 2015 in Shanghai with seconds: 2015-02-26T03:06:39 +080000 in Shanghai with colon seconds: 2015-02-26T03:06:39 +08:00:00 Formats: Basic full date "Mon Jan 2 15:04:05 MST 2006" gives "Wed Feb 25 11:06:39 PST 2015" Basic short date "2006/01/02" gives "2015/02/25" AM/PM "3PM==3pm==15h" gives "11AM==11am==11h" No fraction "Mon Jan _2 15:04:05 MST 2006" gives "Wed Feb 25 11:06:39 PST 2015" 0s for fraction "15:04:05.00000" gives "11:06:39.12340" 9s for fraction "15:04:05.99999999" gives "11:06:39.1234"
Пример (выравнивание)
Код:
// Parse a time value from a string in the standard Unix format.
t, err := time.Parse(time.UnixDate, "Sat Mar 7 11:06:39 PST 2015")
if err != nil { // Always check errors even if they should not happen.
panic(err)
}
// Define a helper function to make the examples' output look nice.
do := func(name, layout, want string) {
got := t.Format(layout)
if want != got {
fmt.Printf("error: for %q got %q; expected %q\n", layout, got, want)
return
}
fmt.Printf("%-16s %q gives %q\n", name, layout, got)
}
// The predefined constant Unix uses an underscore to pad the day.
do("Unix", time.UnixDate, "Sat Mar 7 11:06:39 PST 2015")
// For fixed-width printing of values, such as the date, that may be one or
// two characters (7 vs. 07), use an _ instead of a space in the layout string.
// Here we print just the day, which is 2 in our layout string and 7 in our
// value.
do("No pad", "<2>", "<7>")
// An underscore represents a space pad, if the date only has one digit.
do("Spaces", "<_2>", "< 7>")
// A "0" indicates zero padding for single-digit values.
do("Zeros", "<02>", "<07>")
// If the value is already the right width, padding is not used.
// For instance, the second (05 in the reference time) in our value is 39,
// so it doesn't need padding, but the minutes (04, 06) does.
do("Suppressed pad", "04:05", "06:39")
Вывод:
Unix "Mon Jan _2 15:04:05 MST 2006" gives "Sat Mar 7 11:06:39 PST 2015" No pad "<2>" gives "<7>" Spaces "<_2>" gives "< 7>" Zeros "<02>" gives "<07>" Suppressed pad "04:05" gives "06:39"
func (Time) GoString 1.17
func (t Time) GoString() string
GoString реализует интерфейс fmt.GoStringer и форматирует t для вывода в исходном коде Go.
Пример
Код:
t := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)
fmt.Println(t.GoString())
t = t.Add(1 * time.Minute)
fmt.Println(t.GoString())
t = t.AddDate(0, 1, 0)
fmt.Println(t.GoString())
t, _ = time.Parse("Jan 2, 2006 at 3:04pm (MST)", "Feb 3, 2013 at 7:54pm (UTC)")
fmt.Println(t.GoString())
Вывод:
time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC) time.Date(2009, time.November, 10, 23, 1, 0, 0, time.UTC) time.Date(2009, time.December, 10, 23, 1, 0, 0, time.UTC) time.Date(2013, time.February, 3, 19, 54, 0, 0, time.UTC)
func (*Time) GobDecode
func (t *Time) GobDecode(data []byte) error
GobDecode реализует интерфейс gob.GobDecoder.
func (Time) GobEncode
func (t Time) GobEncode() ([]byte, error)
GobEncode реализует интерфейс gob.GobEncoder.
func (Time) Hour
func (t Time) Hour() int
Hour возвращает час в пределах дня, заданного значением t, в диапазоне [0, 23].
func (Time) ISOWeek
func (t Time) ISOWeek() (year, week int)
ISOWeek возвращает год и номер недели по ISO 8601, на которые приходится t. Номер недели находится в диапазоне от 1 до 53. Даты с 1 по 3 января года n могут относиться к 52-й или 53-й неделе года n-1, а даты с 29 по 31 декабря — к 1-й неделе года n+1.
func (Time) In
func (t Time) In(loc *Location) Time
In возвращает копию t, представляющую тот же момент времени, но с информацией о местоположении loc, заданной для отображения.
In вызывает панику, если loc равен nil.
func (Time) IsDST 1.17
func (t Time) IsDST() bool
IsDST сообщает, действует ли в настроенном местоположении летнее время.
func (Time) IsZero
func (t Time) IsZero() bool
IsZero сообщает, представляет ли t нулевой момент времени: 1 января 1 года, 00:00:00 UTC.
func (Time) Local
func (t Time) Local() Time
Local возвращает t с местным часовым поясом.
func (Time) Location
func (t Time) Location() *Location
Location возвращает информацию о часовом поясе, связанную с t.
func (Time) MarshalBinary 1.2
func (t Time) MarshalBinary() ([]byte, error)
MarshalBinary реализует интерфейс encoding.BinaryMarshaler.
func (Time) MarshalJSON
func (t Time) MarshalJSON() ([]byte, error)
MarshalJSON реализует интерфейс encoding/json.Marshaler. Время представляется строкой в кавычках в формате RFC 3339 с точностью до долей секунды. Если метку времени нельзя представить в корректном формате RFC 3339 (например, год выходит за допустимый диапазон), возвращается ошибка.
func (Time) MarshalText 1.2
func (t Time) MarshalText() ([]byte, error)
MarshalText реализует интерфейс encoding.TextMarshaler. Результат совпадает с результатом вызова метода Time.AppendText.
Дополнительную информацию см. в описании Time.AppendText.
func (Time) Minute
func (t Time) Minute() int
Minute возвращает минуту в пределах часа, заданного значением t, в диапазоне [0, 59].
func (Time) Month
func (t Time) Month() Month
Month возвращает месяц года, заданный значением t.
func (Time) Nanosecond
func (t Time) Nanosecond() int
Nanosecond возвращает наносекунды в пределах секунды, заданной значением t, в диапазоне [0, 999999999].
func (Time) Round 1.1
func (t Time) Round(d Duration) Time
Round возвращает результат округления t до ближайшего кратного d (отсчитывая от нулевого времени). При округлении значений, находящихся ровно посередине, результат округляется вверх. Если d <= 0, Round возвращает t без показания монотонных часов, не изменяя его в остальном.
Round оперирует абсолютной длительностью времени, прошедшей с нулевого времени, а не отображаемым представлением времени. Поэтому Round(Hour) может вернуть время с ненулевым значением минут в зависимости от Location времени.
Пример
Код:
t := time.Date(0, 0, 0, 12, 15, 30, 918273645, time.UTC)
round := []time.Duration{
time.Nanosecond,
time.Microsecond,
time.Millisecond,
time.Second,
2 * time.Second,
time.Minute,
10 * time.Minute,
time.Hour,
}
for _, d := range round {
fmt.Printf("t.Round(%6s) = %s\n", d, t.Round(d).Format("15:04:05.999999999"))
}
Вывод:
t.Round( 1ns) = 12:15:30.918273645 t.Round( 1µs) = 12:15:30.918274 t.Round( 1ms) = 12:15:30.918 t.Round( 1s) = 12:15:31 t.Round( 2s) = 12:15:30 t.Round( 1m0s) = 12:16:00 t.Round( 10m0s) = 12:20:00 t.Round(1h0m0s) = 12:00:00
func (Time) Second
func (t Time) Second() int
Second возвращает секунды в пределах минуты, заданной значением t, в диапазоне [0, 59].
func (Time) String
func (t Time) String() string
String возвращает время, отформатированное с помощью строки формата
"2006-01-02 15:04:05.999999999 -0700 MST"
Если время содержит показание монотонных часов, возвращаемая строка включает последнее поле "m=±<value>", где value — показание монотонных часов, отформатированное как десятичное число секунд.
Возвращаемая строка предназначена для отладки; для стабильного сериализованного представления используйте t.MarshalText, t.MarshalBinary или t.Format с явно заданной строкой формата.
Пример
Код:
timeWithNanoseconds := time.Date(2000, 2, 1, 12, 13, 14, 15, time.UTC)
withNanoseconds := timeWithNanoseconds.String()
timeWithoutNanoseconds := time.Date(2000, 2, 1, 12, 13, 14, 0, time.UTC)
withoutNanoseconds := timeWithoutNanoseconds.String()
fmt.Printf("withNanoseconds = %v\n", withNanoseconds)
fmt.Printf("withoutNanoseconds = %v\n", withoutNanoseconds)
Вывод:
withNanoseconds = 2000-02-01 12:13:14.000000015 +0000 UTC withoutNanoseconds = 2000-02-01 12:13:14 +0000 UTC
func (Time) Sub
func (t Time) Sub(u Time) Duration
Sub возвращает длительность t-u. Если результат превышает максимальное (или минимальное) значение, которое можно сохранить в Duration, возвращается максимальная (или минимальная) длительность. Чтобы вычислить t-d для длительности d, используйте t.Add(-d).
Пример
Код:
start := time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC)
end := time.Date(2000, 1, 1, 12, 0, 0, 0, time.UTC)
difference := end.Sub(start)
fmt.Printf("difference = %v\n", difference)
Вывод:
difference = 12h0m0s
func (Time) Truncate 1.1
func (t Time) Truncate(d Duration) Time
Truncate возвращает результат округления t вниз до кратного d (отсчитывая от нулевого времени). Если d <= 0, Truncate возвращает t без показания монотонных часов, не изменяя его в остальном.
Truncate оперирует абсолютной длительностью времени, прошедшей с нулевого времени, а не отображаемым представлением времени. Поэтому Truncate(Hour) может вернуть время с ненулевым значением минут в зависимости от Location времени.
Пример
Код:
t, _ := time.Parse("2006 Jan 02 15:04:05", "2012 Dec 07 12:15:30.918273645")
trunc := []time.Duration{
time.Nanosecond,
time.Microsecond,
time.Millisecond,
time.Second,
2 * time.Second,
time.Minute,
10 * time.Minute,
}
for _, d := range trunc {
fmt.Printf("t.Truncate(%5s) = %s\n", d, t.Truncate(d).Format("15:04:05.999999999"))
}
// To round to the last midnight in the local timezone, create a new Date.
midnight := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, time.Local)
_ = midnight
Вывод:
t.Truncate( 1ns) = 12:15:30.918273645 t.Truncate( 1µs) = 12:15:30.918273 t.Truncate( 1ms) = 12:15:30.918 t.Truncate( 1s) = 12:15:30 t.Truncate( 2s) = 12:15:30 t.Truncate( 1m0s) = 12:15:00 t.Truncate(10m0s) = 12:10:00
func (Time) UTC
func (t Time) UTC() Time
UTC возвращает t с часовым поясом UTC.
func (Time) Unix
func (t Time) Unix() int64
Unix возвращает t как время Unix — число секунд, прошедших с 1 января 1970 года UTC. Результат не зависит от местоположения, связанного с t. В Unix-подобных операционных системах время часто записывается как 32-разрядное число секунд, однако этот метод возвращает 64-разрядное значение, поэтому оно подходит для дат за миллиарды лет до или после текущего момента.
Пример
Код:
// 1 billion seconds of Unix, three ways. fmt.Println(time.Unix(1e9, 0).UTC()) // 1e9 seconds fmt.Println(time.Unix(0, 1e18).UTC()) // 1e18 nanoseconds fmt.Println(time.Unix(2e9, -1e18).UTC()) // 2e9 seconds - 1e18 nanoseconds t := time.Date(2001, time.September, 9, 1, 46, 40, 0, time.UTC) fmt.Println(t.Unix()) // seconds since 1970 fmt.Println(t.UnixNano()) // nanoseconds since 1970
Вывод:
2001-09-09 01:46:40 +0000 UTC 2001-09-09 01:46:40 +0000 UTC 2001-09-09 01:46:40 +0000 UTC 1000000000 1000000000000000000
func (Time) UnixMicro 1.17
func (t Time) UnixMicro() int64
UnixMicro возвращает t как время Unix — число микросекунд, прошедших с 1 января 1970 года UTC. Результат не определён, если время Unix в микросекундах нельзя представить значением int64 (дата до 290307 года до н. э. или после 294246 года). Результат не зависит от местоположения, связанного с t.
func (Time) UnixMilli 1.17
func (t Time) UnixMilli() int64
UnixMilli возвращает t как время Unix — число миллисекунд, прошедших с 1 января 1970 года UTC. Результат не определён, если время Unix в миллисекундах нельзя представить значением int64 (дата более чем на 292 миллиона лет раньше или позже 1970 года). Результат не зависит от местоположения, связанного с t.
func (Time) UnixNano
func (t Time) UnixNano() int64
UnixNano возвращает t как время Unix — число наносекунд, прошедших с 1 января 1970 года UTC. Результат не определён, если время Unix в наносекундах нельзя представить значением int64 (дата до 1678 года или после 2262 года). Обратите внимание: это означает, что результат вызова UnixNano для нулевого значения Time не определён. Результат не зависит от местоположения, связанного с t.
func (*Time) UnmarshalBinary 1.2
func (t *Time) UnmarshalBinary(data []byte) error
UnmarshalBinary реализует интерфейс encoding.BinaryUnmarshaler.
func (*Time) UnmarshalJSON
func (t *Time) UnmarshalJSON(data []byte) error
UnmarshalJSON реализует интерфейс encoding/json.Unmarshaler. Время должно быть строкой в кавычках в формате RFC 3339.
func (*Time) UnmarshalText 1.2
func (t *Time) UnmarshalText(data []byte) error
UnmarshalText реализует интерфейс encoding.TextUnmarshaler. Время должно быть задано в формате RFC 3339.
func (Time) Weekday
func (t Time) Weekday() Weekday
Weekday возвращает день недели, заданный значением t.
func (Time) Year
func (t Time) Year() int
Year возвращает год, на который приходится t.
func (Time) YearDay 1.1
func (t Time) YearDay() int
YearDay возвращает день года, заданный значением t: в диапазоне [1,365] для невисокосных лет и [1,366] для високосных.
func (Time) Zone
func (t Time) Zone() (name string, offset int)
Zone определяет часовой пояс, действующий в момент времени t, и возвращает сокращённое название пояса (например, "CET") и его смещение в секундах к востоку от UTC.
func (Time) ZoneBounds 1.19
func (t Time) ZoneBounds() (start, end Time)
ZoneBounds возвращает границы часового пояса, действующего в момент времени t. Часовой пояс начинается в момент start, а следующий часовой пояс начинается в момент end. Если часовой пояс действует с начала отсчёта времени, в качестве start возвращается нулевое значение Time. Если часовой пояс действует бесконечно, в качестве end возвращается нулевое значение Time. Location возвращаемых значений времени совпадает с Location значения t.
type Timer
Тип Timer представляет одно событие. По истечении времени Timer текущее время отправляется в C, если только Timer не был создан с помощью AfterFunc. Timer необходимо создавать с помощью NewTimer или AfterFunc.
type Timer struct {
C <-chan Time
// contains filtered or unexported fields
}
func AfterFunc
func AfterFunc(d Duration, f func()) *Timer
AfterFunc ожидает истечения заданной длительности, а затем вызывает f в отдельной горутине. Метод возвращает Timer, с помощью которого можно отменить вызов методом Stop. Поле C возвращаемого Timer не используется и будет равно nil.
func NewTimer
func NewTimer(d Duration) *Timer
NewTimer создаёт новый Timer, который отправит текущее время в свой канал по истечении как минимум длительности d.
До Go 1.23 сборщик мусора не освобождал таймеры, которые ещё не сработали или не были остановлены, поэтому код часто сразу после вызова NewTimer откладывал вызов t.Stop, чтобы таймер можно было освободить, когда он больше не нужен. Начиная с Go 1.23 сборщик мусора может освобождать таймеры, на которые больше нет ссылок, даже если они не сработали или не были остановлены. Метод Stop больше не нужен для помощи сборщику мусора. (Разумеется, код всё ещё может вызывать Stop, чтобы остановить таймер по другим причинам.)
До Go 1.23 связанный с Timer канал был асинхронным (буферизованным, ёмкостью 1), поэтому даже после возврата Timer.Stop или Timer.Reset можно было получить устаревшие значения времени. Начиная с Go 1.23 канал является синхронным (небуферизованным, ёмкостью 0), что исключает возможность получения таких устаревших значений.
func (*Timer) Reset 1.1
func (t *Timer) Reset(d Duration) bool
Reset изменяет таймер так, чтобы он сработал через длительность d. Метод возвращает true, если таймер был активен, и false, если он уже сработал или был остановлен.
Для таймера на основе функции, созданного с помощью AfterFunc(d, f), Reset либо переносит время вызова f — в этом случае Reset возвращает true, — либо планирует повторный вызов f и возвращает false. Если Reset возвращает false, он не дожидается завершения предыдущего вызова f и не гарантирует, что последующая горутина, вызывающая f, не будет выполняться одновременно с предыдущей. Если вызывающему коду необходимо знать, завершилось ли предыдущее выполнение f, он должен явно синхронизироваться с f.
Для таймера на основе канала, созданного с помощью NewTimer, начиная с Go 1.23 любая операция чтения из t.C после возврата Reset гарантированно не получит значение времени, соответствующее предыдущим настройкам таймера; если программа ещё не прочитала данные из t.C и таймер запущен, Reset гарантированно вернёт true. До Go 1.23 единственным безопасным способом использовать Reset был вызов Timer.Stop с последующим явным чтением из канала таймера для очистки. Подробнее см. документацию NewTimer.
func (*Timer) Stop
func (t *Timer) Stop() bool
Stop предотвращает срабатывание Timer. Метод возвращает true, если вызов остановил таймер, и false, если таймер уже сработал или был остановлен.
Для таймера на основе функции, созданного с помощью AfterFunc(d, f), если t.Stop возвращает false, таймер уже сработал и функция f запущена в отдельной горутине; Stop не дожидается завершения f. Если вызывающему коду необходимо знать, завершилась ли f, он должен явно синхронизироваться с f.
Для таймера на основе канала, созданного с помощью NewTimer(d), начиная с Go 1.23 любая операция чтения из t.C после возврата Stop гарантированно будет заблокирована, а не получит устаревшее значение времени, появившееся до вызова Stop; если программа ещё не прочитала данные из t.C и таймер запущен, Stop гарантированно вернёт true. До Go 1.23 единственным безопасным способом использовать Stop было дополнительное чтение <-t.C, если Stop возвращал false, чтобы очистить возможное устаревшее значение. Подробнее см. документацию NewTimer.
type Weekday
Weekday обозначает день недели (воскресенье = 0, ...).
type Weekday int
const (
Sunday Weekday = iota
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
) func (Weekday) String
func (d Weekday) String() string
String возвращает английское название дня ("Sunday", "Monday", ...).
Подкаталоги
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/time/
