Пакет time
Обзор
Пакет time предоставляет функциональность для измерения и отображения времени.
Календарные вычисления всегда предполагают григорианский календарь без високосных секунд.
Монотонные часы
Операционные системы предоставляют как «часы реального времени», которые могут изменяться при синхронизации часов, так и «монотонные часы», которые не изменяются. Общее правило таково: часы реального времени используются для определения времени, а монотонные часы — для измерения времени. Для того, чтобы не разделять API, в этом пакете возвращаемое значение time.Now содержит как показания часов реального времени, так и показания монотонных часов; последующие операции определения времени используют показания часов реального времени, но последующие операции измерения времени, в частности сравнения и вычитания, используют показания монотонных часов.
Например, этот код всегда вычисляет положительное время выполнения примерно 20 миллисекунд, даже если часы реального времени изменяются во время операции измерения времени:
start := time.Now() ... operation that takes 20 milliseconds ... t := time.Now() elapsed := t.Sub(start)
Другие конструкции, такие как time.Since(начало), time.Until(срок), и time.Now().Before(срок), аналогично устойчивы к сбросу часов реального времени.
Остальная часть этого раздела содержит точные подробности о том, как операции используют монотонные часы, но понимание этих деталей не требуется для использования этого пакета.
Возвращаемое значение time.Now содержит показания монотонных часов. Если Time t имеет показания монотонных часов, t.Add добавляет ту же продолжительность как к показаниям часов реального времени, так и к показаниям монотонных часов для вычисления результата. Поскольку t.AddDate(год, месяц, день), 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().
Разрешение таймера
Разрешение таймера зависит от среды выполнения Go, операционной системы и базового оборудования. В Unix разрешение составляет ~1 мс. В Windows версии 1803 и более поздних разрешение составляет ~0,5 мс. В более старых версиях Windows стандартное разрешение составляет ~16 мс, но более высокое разрешение может быть запрошено с помощью golang.org/x/sys/windows.TimeBeginPeriod.
Индекс
Примеры
- После
- Дата
- Продолжительность
- Duration.Abs
- Duration.Hours
- Duration.Микросекунды
- Duration.Миллисекунды
- Duration.Минуты
- Duration.Наносекунды
- Duration.Округлять
- Duration.Секунды
- Duration.Строка
- Duration.Обрезать
- FixedZone
- LoadLocation
- Местоположение
- Месяц
- NewTicker
- Разбор
- РазборПродолжительности
- РазборВМестоположении
- С_момента
- Sleep
- Tick
- Time.Добавить
- Time.Добавить_Дату
- Time.После
- Time.Добавить_Формат
- Time.До
- Time.Дата
- Time.День
- Time.Равно
- Time.Формат
- Time.Формат (Заполнение)
- Time.GoСтрока
- Time.Округлять
- Time.Строка
- Time.Разность
- Time.Обрезать
- Time.Unix
- Unix
- UnixМикро
- UnixМилли
- До
Файлы пакета
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.Формат и time.Разбор. Время отсчета, используемое в этих макетах, — это конкретная метка времени:
01/02 03:04:05PM '06 -0700
(2 января, 15:04:05, 2006, в часовом поясе на семь часов западнее Гринвича). Это значение записывается как константа с именем Макет, перечисленная ниже. В качестве 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 днях данного месяца. В общем случае следует использовать RFC1123Z вместо RFC1123 для серверов, которые настаивают на этом формате, а RFC3339 следует предпочитать для новых протоколов. RFC3339, RFC822, RFC822Z, RFC1123 и RFC1123Z полезны для форматирования; при использовании с time.Parse они не принимают все форматы времени, разрешенные RFC, и они принимают форматы времени, не формально определенные. Формат RFC3339Nano удаляет конечные нули из поля секунд и, таким образом, может не сортироваться правильно после форматирования.
Большинство программ могут использовать одну из определенных констант в качестве макета, передаваемого в Format или Parse. Остальную часть этого комментария можно пропустить, если вы не создаете пользовательский макет строки.
Чтобы определить свой собственный формат, запишите, как бы выглядело эталонное время в вашем формате; см. значения констант, таких как ANSIC, StampMicro или Kitchen, для примеров. Модель демонстрирует, как выглядит эталонное время, чтобы методы Format и Parse могли применить то же преобразование к общему значению времени.
Вот краткое описание компонентов строки макета. Каждый элемент демонстрирует на примере форматирование элемента эталонного времени. Только эти значения распознаются. Текст в строке макета, который не распознается как часть эталонного времени, дублируется дословно во время Format и ожидается, что он будет появляться дословно в вводе 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, печатая Z вместо смещения для часового пояса UTC. Таким образом:
"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"
) Общие продолжительности. Нет определения для единиц Дня или большего, чтобы избежать путаницы при переходе через смещение летнего времени.
Чтобы подсчитать количество единиц в Продолжительности, разделите:
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 После
func After(d Duration) <-chan Time
После ожидает истечения продолжительности, а затем отправляет текущее время по возвращаемому каналу. Это эквивалентно NewTimer(d).C.
До Go 1.23 в этом документе предупреждалось, что базовый Таймер не будет восстановлен сборщиком мусора до срабатывания таймера, и что если производительность была проблемой, код должен использовать NewTimer вместо этого и вызвать Timer.Stop, если таймер больше не нужен. Начиная с Go 1.23, сборщик мусора может восстанавливать неиспользуемые, не остановленные таймеры. Нет необходимости предпочитать 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 в этом документе предупреждалось, что базовый Измеритель никогда не будет восстановлен сборщиком мусора, и что если производительность была проблемой, код должен использовать NewTicker вместо этого и вызвать Ticker.Stop, когда измеритель больше не нужен. Начиная с Go 1.23, сборщик мусора может восстанавливать неиспользуемые измерители, даже если они не были остановлены. Метод Stop больше не нужен для помощи сборщику мусора. Больше нет причин предпочитать NewTicker, когда Tick подойдёт.
Пример
Код:
c := time.Tick(5 * time.Second)
for next := range c {
fmt.Printf("%v %s\n", next, statusUpdate())
}
тип Продолжительность
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 РазборПродолжительности
func ParseDuration(s string) (Duration, error)
ParseDuration разбирает строку продолжительности. Строка продолжительности — это возможно знакопоследовательность десятичных чисел, каждое из которых может содержать дробную часть и суффикс единицы измерения, например, «300мс», «-1,5ч» или «2ч45м». Допустимые единицы времени — «нс», «мкс» (или «µс»), «мс», «с», «м», «ч».
Пример
Код:
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 С_момента
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 До 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 возвращает строковое представление продолжительности в формате "72ч3м0,5с". Ведущие нулевые единицы опускаются. В качестве специального случая, продолжительности меньше одной секунды используют более мелкие единицы (милли-, микро- или наносекунды), чтобы гарантировать, что ведущая цифра отлична от нуля. Нулевая продолжительность форматируется как 0с.
Пример
Код:
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
A 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.
В противном случае имя рассматривается как имя расположения, соответствующее файлу в базе данных часовых поясов 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 указывает месяц года (январь = 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 возвращает английское название месяца ("январь", "февраль", ...).
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
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. Ticker будет регулировать интервал времени или пропускать тики, чтобы компенсировать медленных получателей. Duration d должен быть больше нуля; в противном случае NewTicker вызовет панику.
До Go 1.23 сборщик мусора не восстанавливал тимеры, которые еще не истекли или не были остановлены, поэтому код часто сразу же откладывал t.Stop после вызова NewTicker, чтобы сделать тимер восстанавливаемым, когда он больше не был нужен. С 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 не закрывает канал, чтобы предотвратить ситуацию, когда конкурирующая горутина, читающая из канала, увидит ошибочный «тик».
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 может содержать дополнительное значение монотонных часов процесса для дополнительной точности при сравнении или вычитании. Подробности см. в разделе «Монотонные часы» в документации пакета.
END_OF_DOCUMENT_MARKERОбратите внимание, что оператор 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
в соответствующей зоне для этого времени в заданной области.
Значения месяца, дня, часа, мин, сек и нсек могут выходить за обычные пределы и будут нормализованы во время преобразования. Например, 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.
Остальная часть этого комментария описывает обработку часовых поясов.
В отсутствие индикатора часового пояса 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 пытается сопоставить его с локальной областью; 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 возвращает локальное значение Time, соответствующее заданному времени 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 возвращает локальное значение Time, соответствующее заданному времени 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 возвращает локальное значение Time, соответствующее заданному времени 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 и его области. Например, 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.
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 (например, год вне диапазона), то возвращается ошибка.
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) может вернуть время с ненулевой минутой, в зависимости от часового пояса времени.
Пример
Код:
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=±<значение>", где значение — значение метки монотонного времени, отформатированное в виде десятичного числа секунд.
Возвращаемая строка предназначена для отладки; для стабильного сериализованного представления используйте 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", string(withNanoseconds))
fmt.Printf("withoutNanoseconds = %v\n", string(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) может вернуть время с ненулевой минутой, в зависимости от часового пояса времени.
Пример
Код:
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 для нулевого времени не определен. Результат не зависит от местоположения, связанного с 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 будет возвращено как нулевое время. Если пояс продолжается вечно, end будет возвращено как нулевое время. Часовой пояс возвращаемых времен будет таким же, как у t.
type Timer
Тип Timer представляет собой отдельное событие. При истечении срока действия таймера текущее время будет отправлено в C, если только таймер не был создан с помощью AfterFunc. Таймер должен быть создан с помощью 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 сборщик мусора не восстанавливал таймеры, которые еще не истекли или не были остановлены, поэтому код часто сразу же откладывал t.Stop после вызова NewTimer, чтобы сделать таймер восстанавливаемым, когда он больше не нужен. Начиная с Go 1.23, сборщик мусора может восстанавливать неиспользуемые таймеры, даже если они не истекли или не были остановлены. Метод Stop больше не нужен для помощи сборщику мусора. (Код, конечно, может по-прежнему захотеть вызвать Stop, чтобы остановить таймер по другим причинам.)
До Go 1.23 канал, связанный с таймером, был асинхронным (буферизованным, ёмкость 1), что означало, что устаревшие значения времени могли быть получены даже после того, как Timer.Stop или Timer.Reset вернули значение. Начиная с Go 1.23, канал является синхронным (небуферизованным, ёмкость 0), устраняя возможность получения таких устаревших значений.
Настройка GODEBUG как asynctimerchan=1 восстанавливает поведение, характерное для версий Go до 1.23: при установке она предотвращает сборку мусора для неистекших таймеров и каналы будут иметь буферизованную ёмкость. Данная настройка может быть удалена в Go 1.27 или более поздних версиях.
func (*Timer) Reset 1.1
func (t *Timer) Reset(d Duration) bool
Reset изменяет таймер, чтобы он истек через промежуток времени d. Возвращает true, если таймер был активным, и false, если таймер истек или был остановлен.
Для таймера, созданного с помощью func-based таймера с AfterFunc(d, f), Reset либо перепланирует выполнение f, в этом случае Reset возвращает true, либо планирует повторное выполнение f, в этом случае возвращается false. Когда Reset возвращает false, Reset не ожидает завершения предыдущего f перед возвратом, и не гарантирует, что последующая горутина, выполняющая f, не запустится параллельно с предыдущей. Если вызывающему коду необходимо узнать, завершилось ли предыдущее выполнение f, он должен явно координироваться с f.
Для таймера, созданного с помощью chan-based таймера с 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, если таймер уже истек или был остановлен.
Для таймера, созданного с помощью func-based таймера с AfterFunc(d, f), если t.Stop возвращает false, то таймер уже истек, и функция f была запущена в своей собственной горутине; Stop не ожидает завершения f перед возвратом. Если вызывающему коду необходимо узнать, завершилась ли f, он должен явно координироваться с f.
Для таймера, созданного с помощью chan-based таймера с 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", ...).
Подкаталоги
| Название | Краткое описание |
|---|---|
| .. | |
| tzdata | Пакет tzdata предоставляет встроенную копию базы данных часовых поясов. |
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/time/
