...

パッケージ time

import "time"
概要
目次

概要 ▾

time パッケージは,時間の測定と表示機能を提供します。

カレンダ計算は常にグレゴリオ暦を想定しており,うるう秒はありません。

モノトニッククロック

オペレーティングシステムは,クロック同期の変更を受ける "ウォールクロック" とそうでない "モノトニッククロック" の両方を提供します。 原則として,ウォールクロックは時間を伝えるためのもので,モノトニッククロックは時間を測定するためのものです。 このパッケージでは, API を分割するのではなく, time によって返される Time にウォールクロック読み取り値とモノトニッククロック読み取り値の両方が含まれています。 時間を伝える操作にはウォールクロックを使い,時間測定動作,特に比較や差分計算はモノトニッククロックを使用します。

たとえば,次のコードでは,計時中にウォールクロックが変更された場合でも,常に約 20 ミリ秒の経過時間が計算されます。

start := time.Now()
... operation that takes 20 milliseconds ...
t := time.Now()
elapsed := t.Sub(start)

time.Since(開始), time.Until(期限), time.Now() などの他の表現も同様に,ウォールクロックのリセットの影響を受けません。

このセクションの残りの部分では,モノトニッククロックを使用する方法の詳細を説明しますが,これらの詳細を理解することはこのパッケージを使用するために必要ではありません。

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.Sub(u) の操作はウォールクロックの読みを無視して,モノトニッククロック読み取り値のみを使用して実行されます。 t または u のいずれかにモノトニッククロック読み取り値が含まれていない場合,これらの操作はフォールバックして,ウォールクロック読み取り値を使用します。

システムによっては,コンピュータがスリープ状態になるとモノトニッククロックが停止します。そのようなシステムでは, t.Sub(u) は, t と u の間に経過した実際の時間を正確に反映していない可能性があります。

モノトニッククロックの読み取りは現在のプロセス以外では意味がないため,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 は常にモノトニッククロック読み取りなしで時間を作成します。

Go の == 演算子は,時刻だけでなく Location とモノトニッククロックの読み取りも比較することに注意してください。 Time 値の等価性テストについては, Time 型のドキュメントを参照してください。

デバッグの場合, t.String の結果にはモノトニッククロックの読み取り値が含まれます (存在する場合)。モノトニッククロックの読み値が異なるために t != u の場合, t.String() と u.String() の出力時にその違いがわかります。

目次 ▾

定数
func After(d Duration) <-chan Time
func Sleep(d Duration)
func Tick(d Duration) <-chan Time
type Duration
    func ParseDuration(s string) (Duration, error)
    func Since(t Time) Duration
    func Until(t Time) Duration
    func (d Duration) Hours() float64
    func (d Duration) Microseconds() int64
    func (d Duration) Milliseconds() int64
    func (d Duration) Minutes() float64
    func (d Duration) Nanoseconds() int64
    func (d Duration) Round(m Duration) Duration
    func (d Duration) Seconds() float64
    func (d Duration) String() string
    func (d Duration) Truncate(m Duration) Duration
type Location
    func FixedZone(name string, offset int) *Location
    func LoadLocation(name string) (*Location, error)
    func LoadLocationFromTZData(name string, data []byte) (*Location, error)
    func (l *Location) String() string
type Month
    func (m Month) String() string
type ParseError
    func (e *ParseError) Error() string
type Ticker
    func NewTicker(d Duration) *Ticker
    func (t *Ticker) Stop()
type Time
    func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time
    func Now() Time
    func Parse(layout, value string) (Time, error)
    func ParseInLocation(layout, value string, loc *Location) (Time, error)
    func Unix(sec int64, nsec int64) Time
    func (t Time) Add(d Duration) Time
    func (t Time) AddDate(years int, months int, days int) Time
    func (t Time) After(u Time) bool
    func (t Time) AppendFormat(b []byte, layout string) []byte
    func (t Time) Before(u Time) bool
    func (t Time) Clock() (hour, min, sec int)
    func (t Time) Date() (year int, month Month, day int)
    func (t Time) Day() int
    func (t Time) Equal(u Time) bool
    func (t Time) Format(layout string) string
    func (t *Time) GobDecode(data []byte) error
    func (t Time) GobEncode() ([]byte, error)
    func (t Time) Hour() int
    func (t Time) ISOWeek() (year, week int)
    func (t Time) In(loc *Location) Time
    func (t Time) IsZero() bool
    func (t Time) Local() Time
    func (t Time) Location() *Location
    func (t Time) MarshalBinary() ([]byte, error)
    func (t Time) MarshalJSON() ([]byte, error)
    func (t Time) MarshalText() ([]byte, error)
    func (t Time) Minute() int
    func (t Time) Month() Month
    func (t Time) Nanosecond() int
    func (t Time) Round(d Duration) Time
    func (t Time) Second() int
    func (t Time) String() string
    func (t Time) Sub(u Time) Duration
    func (t Time) Truncate(d Duration) Time
    func (t Time) UTC() Time
    func (t Time) Unix() int64
    func (t Time) UnixNano() int64
    func (t *Time) UnmarshalBinary(data []byte) error
    func (t *Time) UnmarshalJSON(data []byte) error
    func (t *Time) UnmarshalText(data []byte) error
    func (t Time) Weekday() Weekday
    func (t Time) Year() int
    func (t Time) YearDay() int
    func (t Time) Zone() (name string, offset int)
type Timer
    func AfterFunc(d Duration, f func()) *Timer
    func NewTimer(d Duration) *Timer
    func (t *Timer) Reset(d Duration) bool
    func (t *Timer) Stop() bool
type Weekday
    func (d Weekday) String() string

パッケージファイル

format.go sleep.go sys_unix.go tick.go time.go zoneinfo.go zoneinfo_read.go zoneinfo_unix.go

定数

これらは Time.Format および time.Parse で使用するための事前定義レイアウトです。 レイアウトで使用される基準時間はこの特定の時間です。

Mon Jan 2 15:04:05 MST 2006

これは,Unix 時間 1136239445 です。 MST は GMT-0700 であるため,基準時刻は次のように考えることができます。

01/02 03:04:05PM '06 -0700

独自のフォーマットを定義するためには,基準時間がその独自の方法でフォーマットされたように見えるものを書き留めてください。 例として, ANSIC , StampMicro , Kitchen などの定数を参照してください。 基準時間がどのように見えるかを示せば, Format メソッドと Parse メソッドがその変換を一般的な時間値に適用できます。

スペースの埋め込みには _ ,ゾーン情報には Z などの形式があるため,有効なレイアウトの中には, time.Parse には無効な時間値とあるものがあります。

フォーマット文字列内で,アンダースコア (_) は, 次の数字 (日) が 2 桁の場合に,数字に置き換えられるスペースを表します。 これは,固定幅の Unix 時間フォーマットとの互換性のためにあります。

小数点の後に 1 つ以上の 0 が続くと,指定された桁数で小数秒を表示します。 小数点の後に 1 つ以上の 9 が続くと,指定された桁数で小数秒を表示しますが,末尾のゼロは削除されます。 パース時 (のみ) には,レイアウトにその存在が示されていなくても,入力の秒フィールドの直後に小数秒のフィールドが含まれることがあります。 その場合,小数点の後に続く最大の一連の数字が小数秒としてパースされます。

数値のタイムゾーンオフセットの形式は次のとおりです。

-0700  ±hhmm
-07:00 ±hh:mm
-07    ±hh

フォーマットの符号を Z に置き換えると, UTC ゾーンのオフセットではなく, Z を表示するという ISO 8601 の動作となります。したがって:

Z0700  Z or ±hhmm
Z07:00 Z or ±hh:mm
Z07    Z or ±hh

認識される曜日の形式は "Mon" と "Monday" です。認識される月の形式は "Jan" と "January" です。

The formats 2, _2, and 02 are unpadded, space-padded, and zero-padded day of month. The formats __2 and 002 are space-padded and zero-padded three-character day of year; there is no unpadded day of year format.

基準時刻の一部として認識されていないフォーマット文字列内のテキストは,Format では逐語的にエコーされ, Parse では入力に逐語的に現れると期待されます。

Time.Format の例は,レイアウト文字列の動作を詳細に説明しており,参考になります。

RFC822, RFC850, および RFC1123 フォーマットは現地時間にのみ適用されるべきであることに注意してください。 これらを UTC 時間に適用し,タイムゾーンの省略形として "UTC" を使用したいかもしれませんが, RFC に厳密に従えば,その場合 "GMT" を使用すべきです。 一般にそのフォーマットを使うサーバには RFC1123 の代わりに RFC1123Z を使用すべきであり, 新しいプロトコルでは RFC3339 が推奨されます。 RFC3339, RFC822, RFC822Z, RFC1123, および RFC1123Z はフォーマットに役立ちますが, RFC で許可されているすべての時刻形式を time.Parse でパースすることはできません。 RFC3339Nano 形式では,秒フィールドの末尾のゼロが削除されるため,フォーマット後に正しくソートされない可能性があります。

const (
    ANSIC       = "Mon Jan _2 15:04:05 2006"
    UnixDate    = "Mon Jan _2 15:04:05 MST 2006"
    RubyDate    = "Mon Jan 02 15:04:05 -0700 2006"
    RFC822      = "02 Jan 06 15:04 MST"
    RFC822Z     = "02 Jan 06 15:04 -0700" // 数値ゾーンを持つ RFC822
    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
    RFC3339     = "2006-01-02T15:04:05Z07:00"
    RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"
    Kitchen     = "3:04PM"
    // 便利なタイムスタンプ。
    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"
)

一般的な期間夏時間のタイムゾーンの移行にまたがる混乱を避けるために, Day 以上の単位の定義はありません。

Duration の単位数を数えるには,次のように分割します。

second := time.Second
fmt.Print(int64(second/time.Millisecond)) // 1000 を表示します

整数の単位を Duration に変換するには,次の式を掛けます。

seconds := 10
fmt.Print(time.Duration(seconds)*time.Second) // 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 と同じです。 内部の Timer は,タイマーが起動するまでガベージコレクタによって回復されません。 効率が問題になる場合は,代わりに NewTimer を使用し,タイマーが不要になった場合は Timer.Stop を呼び出します。

コード:

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 用の便利なラッパーです。 Tick は Ticker を停止する必要がないクライアントには便利ですが, 停止する方法がないと,基になる Ticker をガベージコレクタで回復することはできず,"リーク" することになります。 NewTicker とは異なり, d <= 0 の場合, Tick は nil を返します。

コード:

c := time.Tick(5 * time.Second)
for now := range c {
    fmt.Printf("%v %s\n", now, statusUpdate())
}

type Duration

Duration (期間) は, 2 つの時刻間の経過時間を 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 (期間をパース) は期間文字列をパースします。期間文字列は,符号付き 10 進数のシーケンスで,それぞれ "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(), micro)

出力:

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) の省略形です。

func Until 1.8

func Until(t Time) Duration

Until は,現在から t までの期間を返します。 t.Sub(time.Now()) の省略形です。

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

func (d Duration) Microseconds() int64

Microseconds returns the duration as an integer microsecond count.

func (Duration) Milliseconds

func (d Duration) Milliseconds() int64

Milliseconds returns the duration as an integer millisecond count.

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" の形式で返します。 先頭のゼロは省略されます。 特別な場合として, 1 秒未満のフォーマットでは,先頭の桁がゼロ以外であることを保証するために,より小さい単位 (ミリ,マイクロ,またはナノ秒) が使用されます。 ゼロ Duration は 0s とフォーマットされます。

コード:

t1 := time.Date(2016, time.August, 15, 0, 0, 0, 0, time.UTC)
t2 := time.Date(2017, time.February, 16, 0, 0, 0, 0, time.UTC)
fmt.Println(t2.Sub(t1).String())

出力:

4440h0m0s

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 は,中央ヨーロッパの CEST や CET などの地理的領域で使用されている時間オフセットの集合を表します。

type Location struct {
    // エクスポートされていないフィールドがあります
}

Local はシステムのローカルタイムゾーンを表します。

var Local *Location = &localLoc

UTC は世界協定時刻 (UTC) を表します。

var UTC *Location = &utcLoc

コード:

// 中国には夏時間がありません。 UTC からの固定 8 時間オフセットを使用します。
secondsEastOfUTC := int((8 * time.Hour).Seconds())
beijing := time.FixedZone("Beijing Time", secondsEastOfUTC)

// システムにタイムゾーンデータベースが存在する場合は,そこからロケーションをロードすることができます。例:
//    newYork, err := time.LoadLocation("America/New_York")

// 時間を作成するにはロケーションが必要です。一般的なロケーションは time.Local と 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)

// UTC の時刻は 1200 ,北京の時刻は 2000 ですが,北京は 8 時間先であるため, 2 つの日付は実際には同じ時刻を表します。
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 を返します。

それ以外の場合,名前は, "America/New_York" のように, IANA タイムゾーンデータベース内のファイルに対応するロケーションの名前と見なされます。

LoadLocation に必要なタイムゾーンデータベースは,すべてのシステム, 特に Unix 以外のシステムには存在しないかもしれません。 LoadLocation は, ZONEINFO 環境変数で指定されたディレクトリまたは圧縮されていない zip ファイルがある場合はそれを調べ, 次に Unix システム上の既知のインストール場所を調べ, 最後に $GOROOT/lib/time/zoneinfo.zip を調べます。

コード:

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 は, IANA タイムゾーンのデータベース形式のデータから初期化された, 指定された名前の Location を返します。 データは標準の IANA タイムゾーンファイルの形式でなければなりません (たとえば, Unix システムの /etc/localtime の内容)。

func (*Location) String

func (l *Location) String() string

String は, LoadLocation または FixedZone の name 引数に対応する, タイムゾーン情報の説明的な名前を返します。

type Month

Month は,月を表します (1 月 = 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

Ticker (ティッカー) は,一定間隔でクロックの "時刻刻み" を配信するチャンネルを保持します。

type Ticker struct {
    C <-chan Time // 時刻刻みが配信されるチャンネル。
    // エクスポートされていないフィールドがあります
}

func NewTicker

func NewTicker(d Duration) *Ticker

NewTicker は, duration 引数で指定された期間で時間を送信するチャンネルを含む新しい Ticker を返します。 受信が遅い場合,これは間隔を調整するか,時間刻みを省略します。 期間 d はゼロより大きくなければなりません。 そうでなければ, NewTicker はパニックします。 関連リソースを解放するにはティッカーを 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) Stop

func (t *Ticker) Stop()

Stop (停止) はティッカーを停止します。 Stop 後,これ以上時間刻みは送信されません。 平行ゴルーチンのチャンネル読み取りが誤った "時間刻み" を受け取らないようにするため,Stop はチャンネルを閉じません。

type Time

Time は,ナノ秒の精度で時刻を表します。

Time を使用するプログラムは通常,ポインタではなく値としてそれらを格納して渡す必要があります。つまり,時間変数と構造体フィールドは *time.Time ではなく time.Time 型であるべきです。

Time 値は, GobDecode, UnmarshalBinary, UnmarshalJSON, UnmarshalText の各メソッドが平行実行に対して安全ではないことを除いて, 複数のゴルーチンで平行に使用できます。

Time 同士は, Before, After, Equal メソッドを使用して比較できます。 Sub メソッドは 2 つの時点を減算して Duration を生成します。 Add メソッドは Time と Duration を加算して Time を生成します。

Time 型のゼロ値は, January 1, year 1, 00:00:00.000000000 UTC です。 この時間は実際には起こりそうにないので, IsZero メソッドで明示的に初期化されていない時間を検出できます。

各 Time は,Format, Hour, Year メソッドで用いる Location(ロケーション) に関連づけられています。 Local, UTC, In の各メソッドは,特定のロケーションの Time を返します。 ロケーションを変更すると,表示だけが変わります。 時刻は変更されないため,前の段落で説明した計算には影響しません。

GobEncode, MarshalBinary, MarshalJSON, MarshalText メソッドによって生成された Time 値の表現は, Time.Location のオフセットを格納しますが,ロケーション名は格納しません。 そのため,彼らは夏時間についての情報は失われます。

必要な "ウォールクロック" の読み取りに加えて, Time には,比較や減算の精度を高めるために,現在のプロセスのモノトニッククロックの読み取り値が含まれることがあります。詳細については,パッケージドキュメントの "モノトニッククロック" のセクションを参照してください。

Go の == 演算子は,時刻だけでなく Location とモノトニッククロックの読み取りも比較することに注意してください。 それで,Time 値をマップまたはデータベースキーとして使用しないでください。 もし使用するのであれば,UTC または Local メソッドを使用してすべての値に同じ Location が設定されていることと,t = t.Round(0) でモノトニッククロックの読み取りが削除されていることを確認してください。 一般に,t == u よりも t.Equal(u) を使うとよいでしょう。 なぜなら,t.Equal は,利用可能な最も正確な比較を使用し, 1 つのみがモノトニッククロック読み取り値を持つ場合を正しく処理するからです。

type Time struct {
    // エクスポートされていないフィールドがあります
}

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 ナノ秒

月,日,時,分,秒,および n 秒の値は通常の範囲外である可能性があり,変換中に正規化されます。たとえば, 10 月 32 日は 11 月 1 日に変換されます。

夏時間への移行では,時間がスキップまたは繰り返されます。 たとえば,米国では, 2011 年 3 月 13 日午前 2 時 15 分は発生しませんでしたが, 2011 年 11 月 6 日午前 1 時 15 分は 2 回発生しました。 そのような場合,タイムゾーンの選択と時間は明確に定義されていません。 Date は,移行に関与する 2 つのゾーンのうちの 1 つを使って正しい時刻を返しますが,どちらが返るかを保証するものではありません。

loc が nil の場合,Date はパニックします。

コード:

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 (レイアウト) は,以下の基準時間が value (値) であったならどのように表示されるかを示すことによってフォーマットを定義します。

Mon Jan 2 15:04:05 -0700 MST 2006

これは入力フォーマットの例として機能します。 同じ解釈が入力文字列についても行われます。

定義済みのレイアウト ANSIC, UnixDate, RFC3339 などは,基準時刻の標準的で便利な表現を記述しています。 フォーマットと基準時刻の定義についての詳細は, ANSIC の文書とこのパッケージで定義されているその他の定数を参照してください。 また, Time.Format の例は,レイアウト文字列の動作を詳細に示しており,参考になります。

value から省略された要素は 0,あるいは 0 が不可能な場合は 1 と見なされます。 したがって, "3:04pm" をパースすると,0 年 1 月 1 日 15:04:00 UTC に対応する時刻が返されます。 (0 年なので,この時間はゼロ時間よりも前であることに注意してください。) 年は 0000 から 9999 の範囲内でなければなりません。 曜日の構文はチェックされますが,それ以外の場合は無視されます。

タイムゾーンがない場合, Parse は UTC で時刻を返します。

-0700 のようなゾーンオフセット付きで時刻をパースするとき, オフセットが現在のロケーションで使用されているタイムゾーン (Local) に対応する場合, Parse は返り値の時間にそのロケーションとゾーンを設定します。 それ以外の場合は,指定されたゾーンオフセットに固定されたロケーションとして時間を記録します。

MST のようにゾーンの省略形で時刻をパースするときに,現在ロケーションにゾーンの省略形の定義済みオフセットがある場合は,そのオフセットが使用されます。 ゾーンの略語 "UTC" は,ロケーションに関係なく UTC として認識されます。 ゾーンの略語が不明な場合, Parse は,指定されたゾーンの略語とゼロオフセットを使用してロケーションを作成し,時間を記録します。 これは,そのような時間が同じレイアウトを用いて無損失でパースと再フォーマットできることを意味しますが,正確な時間と実際のゾーンオフセットのぶんだけずれることになります。 このような問題を回避するには,数値ゾーンオフセットを用いるタイムレイアウトを使用するか,ParseInLocation を使用してください。

コード:

// time.Time 値をパースするためのレイアウト文字列の定義方法の詳細については,
// Time.Format の例を参照してください。
// パースとフォーマットは,入力と出力を記述するために同じモデルを使用します。

// longForm は,例として,
// 標準時刻が希望のレイアウトでどのように表されるかを示します。
const longForm = "Jan 2, 2006 at 3:04pm (MST)"
t, _ := time.Parse(longForm, "Feb 3, 2013 at 7:54pm (PST)")
fmt.Println(t)

// shortForm は,標準時間を目的のレイアウトで表現するもう 1 つの方法です。
// タイムゾーンはありません。
// 注:明示的ゾーンなしでは, UTC で時間を返します。
const shortForm = "2006-Jan-02"
t, _ = time.Parse(shortForm, "2013-Feb-03")
fmt.Println(t)

// 有効なレイアウトの中には無効な時間値があるものがあります。
// なぜなら,スペースの埋め込みには _ ,ゾーン情報には Z などのフォーマット指定子があるためです。
// たとえば, RFC3339 のレイアウト 2006-01-02T15:04:05Z07:00 には,
// 次の 2 つの有効な文字列を処理するために Z とタイムゾーンオフセットの両方が含まれています。
// 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) // レイアウトが有効な時間値ではないため,エラーを返します

出力:

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 に似ていますが, 2 つの重要な点で異なります。 まず,タイムゾーン情報がない場合, Parse は時刻を UTC と解釈します。 ParseInLocation は,指定されたロケーションにあるものとして時刻を解釈します。 次に,ゾーンオフセットまたは略語が与えられた場合, Parse はそれを Local ロケーションと照合しようとします。 ParseInLocation は指定されたロケーションを使用します。

コード:

loc, _ := time.LoadLocation("Europe/Berlin")

const longForm = "Jan 2, 2006 at 3:04pm (MST)"
t, _ := time.ParseInLocation(longForm, "Jul 9, 2012 at 5:02am (CEST)", loc)
fmt.Println(t)

// 注:明示的なタイムゾーンなしで,与えられたロケーションで時間を返します。
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 は, 1970 年 1 月 1 日 UTC 以降の,指定された UNIX 時間 (sec 秒, nsec ナノ秒) に対応するローカル時間を返します。 [0, 999999999] の範囲外で nsec を渡しても構いません。 すべての sec 値に対応する時間値があるわけではありません。 そのような値の 1 つは 1<<63-1 (最大の int64 値) です。

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 に加算した時間を返します。 たとえば, 2011 年 1 月 1 日に適用された AddDate(-1, 2, 3) は, 2010 年 3 月 4 日を返します。

AddDate は, Date と同じ方法で結果を正規化します。たとえば, 10 月 31 日に 1 か月を追加すると, 11 月 31 日の正規化形式である 12 月 1 日になります。

コード:

start := time.Date(2009, 1, 1, 0, 0, 0, 0, time.UTC)
oneDayLater := start.AddDate(0, 0, 1)
oneMonthLater := start.AddDate(0, 1, 0)
oneYearLater := start.AddDate(1, 0, 0)

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)

出力:

oneDayLater: start.AddDate(0, 0, 1) = 2009-01-02 00:00:00 +0000 UTC
oneMonthLater: start.AddDate(0, 1, 0) = 2009-02-01 00:00:00 +0000 UTC
oneYearLater: start.AddDate(1, 0, 0) = 2010-01-01 00:00:00 +0000 UTC

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) AppendFormat 1.5

func (t Time) AppendFormat(b []byte, layout string) []byte

AppendFormat (フォーマットして追加) は 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) 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) 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 CEST と 4:00 UTC は等しいです。 Time 値に == を使用する際の落とし穴については, Time 型に関するドキュメントを参照してください。 ほとんどのコードでは代わりに Equal を使用してください。

コード:

secondsEastOfUTC := int((8 * time.Hour).Seconds())
beijing := time.FixedZone("Beijing Time", secondsEastOfUTC)

// == 演算子とは異なり, Equal は d1 と d2 が同じ時刻であるが異なる時間帯にあることを認識しています。
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 (レイアウト)に従ってフォーマットされた時間値のテキスト表現を返します。 これは,以下の基準時間が時間値であったならどのように表示されるかを示すことによって定義します。

Mon Jan 2 15:04:05 -0700 MST 2006

これは,出力例として機能します。 同じ表示規則が時間値にも適用されます。

小数秒は, "15:04:05.000" のように, レイアウト文字列の秒セクションの最後にピリオドとゼロを追加して, ミリ秒の精度でタイムスタンプをフォーマットします。

定義済みのレイアウト ANSIC, UnixDate, RFC3339 などは,基準時刻の標準的で便利な表現を記述しています。 フォーマットと基準時刻の定義についての詳細は, ANSIC の文書とこのパッケージで定義されているその他の定数を参照してください。

コード:

// 標準の Unix フォーマットの文字列からタイム値を解析します。
t, err := time.Parse(time.UnixDate, "Sat Mar  7 11:06:39 PST 2015")
if err != nil { // 発生しないはずの場合でも,エラーを必ず確認してください。
    panic(err)
}

// time.Time の Stringer メソッドはフォーマットなしで役に立ちます。
fmt.Println("default format:", t)

// パッケージ内の定義済み定数は共通のレイアウトを実装します。
fmt.Println("Unix format:", t.Format(time.UnixDate))

// タイム値に付加されたタイムゾーンはその出力に影響します。
fmt.Println("Same, in UTC:", t.UTC().Format(time.UnixDate))

// この関数の残りの部分は,フォーマットで使用されるレイアウト文字列のプロパティを示しています。

// Parse 関数と Format メソッドで使用されるレイアウト文字列は,
// 例を使って標準時刻を表しています。
// 任意の時間ではなく,標準時間がどのようにフォーマットされているかを
// 示す必要があります。
// それで,各レイアウト文字列はタイムスタンプの表現です。
//	Jan 2 15:04:05 2006 MST
// この値を簡単に覚えるには,数字が順序に並んでいることに着目します。
//	  1 2  3  4  5    6  -7
// 以下に,コツをいくつかお教えしましょう。

// Format と Parse のほとんどの使用法は,
// このパッケージで定義されているような定数のレイアウト文字列を使用しますが,
// 例が示すようにインターフェースは柔軟です。

// 例の出力を見栄えよくするために,ヘルパー関数を定義します。
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("%-15s %q gives %q\n", name, layout, got)
}

// 出力にヘッダを表示します。
fmt.Printf("\nFormats:\n\n")

// 簡単な例
do("Basic", "Mon Jan 2 15:04:05 MST 2006", "Sat Mar 7 11:06:39 PST 2015")

// 日付など, 1 文字または 2 文字 (7 と 07) の値を固定幅で表示するには,
// レイアウト文字列のスペースの代わりに _ を使用します。
// ここでは,日だけを表示します。
// これは,レイアウト文字列では 2 ,値では 7 です。
do("No pad", "<2>", "<7>")

// 日付が 1 桁の場合,アンダースコアはスペースパディングを表します。
do("Spaces", "<_2>", "< 7>")

// "0" は, 1 桁の値に対するゼロパディングを示します。
do("Zeros", "<02>", "<07>")

// 値がすでに正しい幅の場合,パディングは使用されません。
// たとえば,2 番目 (標準時刻の 05) の値は 39 なので,
// パディングは不要です。ただし,分 (04, 06) はパディングされます。
do("Suppressed pad", "04:05", "06:39")

// あらかじめ定義された定数 Unix は日をパディングするためにアンダースコアを使います。簡単な例と比較してください。
do("Unix", time.UnixDate, "Sat Mar  7 11:06:39 PST 2015")

// 基準時間の時間は 15 ,または午後 3 時です。レイアウトはどちらの方法でも表現することができ,私たちの価値は朝なので,私たちはそれを AM 時間と見なすべきです。両方を 1 つのフォーマット文字列で表示します。小文字も。
do("AM/PM", "3PM==3pm==15h", "11AM==11am==11h")

// パース時に,秒の値の後に小数点と数桁が続く場合は,
// レイアウト文字列が小数秒を表していなくても,
// 1 秒の何分の 1 と見なされます。
// ここで,上で使用した時間値に小数秒を追加します。
t, err = time.Parse(time.UnixDate, "Sat Mar  7 11:06:39.1234 PST 2015")
if err != nil {
    panic(err)
}
// レイアウト文字列に小数秒の表現が含まれていない場合,
// 出力に表示されません。
do("No fraction", time.UnixDate, "Sat Mar  7 11:06:39 PST 2015")

// 小数秒は,レイアウト文字列の秒数の小数点の後に 0 または 9 の数字列を追加することによって表示できます。
// レイアウト桁が 0 の場合,小数秒は指定された幅になります。
// 出力の末尾にゼロがあることに注意してください。
do("0s for fraction", "15:04:05.00000", "11:06:39.12340")

// レイアウトの小数部が 9 の場合,末尾のゼロは削除されます。
do("9s for fraction", "15:04:05.99999999", "11:06:39.1234")

出力:

default format: 2015-03-07 11:06:39 -0800 PST
Unix format: Sat Mar  7 11:06:39 PST 2015
Same, in UTC: Sat Mar  7 19:06:39 UTC 2015

Formats:

Basic           "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"
Unix            "Mon Jan _2 15:04:05 MST 2006" gives "Sat Mar  7 11:06:39 PST 2015"
AM/PM           "3PM==3pm==15h" gives "11AM==11am==11h"
No fraction     "Mon Jan _2 15:04:05 MST 2006" gives "Sat Mar  7 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"

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 は, [0, 23] の範囲で, t で指定された日のうちの時間を返します。

func (Time) ISOWeek

func (t Time) ISOWeek() (year, week int)

ISOWeek は, t の ISO 8601 の年と週の番号を返します。週の範囲は 1 から 53 です。 n 年 1 月 1 日から 1 月 3 日までは n-1 年の 52 週または 53 週に属し, 12 月 29 日から 12 月 31 日までは n+1 年の 1 週に属するかもしれません。

func (Time) In

func (t Time) In(loc *Location) Time

In は,同じ時刻を表す t のコピーを返しますが, コピーのロケーションは表示用に loc に設定されます。

loc が nil の場合,パニックします。

func (Time) IsZero

func (t Time) IsZero() bool

IsZero は, t がゼロ時刻, 西暦 1 年 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 は json.Marshaler インターフェースを実装します。 時間は RFC 3339 形式の引用符で囲まれた文字列で,存在する場合は 1 秒未満の精度が追加されています。

func (Time) MarshalText 1.2

func (t Time) MarshalText() ([]byte, error)

MarshalText は encoding.TextMarshaler インターフェースを実装します。 時間は RFC 3339 フォーマットでフォーマットされ,存在する場合は 1 秒未満の精度が追加されます。

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 は, [0, 999999999] の範囲で, t で指定された秒内のナノ秒を返します。

func (Time) Round 1.1

func (t Time) Round(d Duration) Time

Round (丸め) は, (ゼロ時間以降) t を d の最も近い倍数に丸めた結果を返します。 中間値の丸め動作は切り上げです。 d <= 0 の場合, Round は t をモノトニッククロックの読み値から取り除きますが,それ以外は変わりません。

Round は,ゼロ時間からの絶対期間としての時間に作用します。 時間の表示形式に作用するのではありません。 したがって, Round(Hour) は,時間の Location に応じて, 0 以外の分で時間を返すことがあります。

コード:

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 は, [0, 59] の範囲で, t で指定された分内の秒を返します。

func (Time) String

func (t Time) String() string

String は以下のフォーマット文字列を使用してフォーマットされた時間を返します。

"2006-01-02 15:04:05.999999999 -0700 MST"

時間がモノトニッククロック読み取りの場合,返される文字列には最後のフィールド "m=±<value>" が含まれます。ここで, value は 10 進数の秒としてフォーマットされたモノトニッククロック読み取りです。

返された文字列はデバッグ用です。安定したシリアライゼーション表現のためには,明示的なフォーマット文字列を指定して 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 に格納できる最大 (または最小) 値を超えると,最大 (または最小) 期間が返されます。 期間 d について t-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 に応じて, 0 以外の分の時間を返します。

コード:

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"))
}
// 現地のタイムゾーンの最後の真夜中に丸めるため,新しい 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 は,位置を UTC に設定して t を返します。

func (Time) Unix

func (t Time) Unix() int64

UNIX は, t を Unix 時間として,1970 年 1 月 1 日 UTC から経過した秒数を返します。結果は, t に関連付けられたロケーションには依存しません。

コード:

// 10 億秒の Unix時間, 3 つの方法。
fmt.Println(time.Unix(1e9, 0).UTC())     // 1e9 秒
fmt.Println(time.Unix(0, 1e18).UTC())    // 1e18 ナノ秒
fmt.Println(time.Unix(2e9, -1e18).UTC()) // 2e9 秒 - 1e18 ナノ秒

t := time.Date(2001, time.September, 9, 1, 46, 40, 0, time.UTC)
fmt.Println(t.Unix())     // 1970 年からの秒数
fmt.Println(t.UnixNano()) // 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) UnixNano

func (t Time) UnixNano() int64

UnixNano は,t を Unix 時間として,UTC 1970 年 1 月 1 日から経過したナノ秒を返します。 UNIX のナノ秒単位の時間を int64 (1678 年より前または 2262 年より後) で表すことができない場合,結果は不定です。 これは,ゼロ Time に 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 は 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 の東側の秒数) を返します。

type Timer

Timer (タイマー) 型は 1 つのイベントを表します。 タイマーの期限が切れると,タイマーが AfterFunc によって作成されていない限り,現在時刻が C に送信されます。 Timer は NewTimer または AfterFunc で作成する必要があります。

type Timer struct {
    C <-chan Time
    // エクスポートされていないフィールドがあります
}

func AfterFunc

func AfterFunc(d Duration, f func()) *Timer

AfterFunc は期間が経過するのを待ってから自身のゴルーチンで f を呼び出します。 Stop メソッドを使用して呼び出しをキャンセルできる Timer を返します。

func NewTimer

func NewTimer(d Duration) *Timer

NewTimer は,少なくとも期間 d の経過後に現在の時刻をそのチャンネルに送信する新しい Timer を作成します。

func (*Timer) Reset 1.1

func (t *Timer) Reset(d Duration) bool

Reset (リセット) は,期間 d の経過後にタイマーが切れるように変更します。 タイマーがアクティブであった場合は true を返し,タイマーが期限切れまたは停止していた場合は false を返します。

Reset should be invoked only on stopped or expired timers with drained channels. If a program has already received a value from t.C, the timer is known to have expired and the channel drained, so t.Reset can be used directly. If a program has not yet received a value from t.C, however, the timer must be stopped and—if Stop reports that the timer expired before being stopped—the channel explicitly drained:

if !t.Stop() {
	<-t.C
}
t.Reset(d)

これはタイマーのチャンネルからの他の受信と平行に行われるべきではありません。

チャンネルの排出と新しいタイマーの期限切れとの間に競合状態があるため, Reset の戻り値を正しく使用することはできません。 上記のように,Reset は常に停止または期限切れのチャンネルで呼び出される必要があります。 戻り値は既存のプログラムとの互換性を保つために存在します。

func (*Timer) Stop

func (t *Timer) Stop() bool

Stop (停止) は,タイマーの作動を防ぎます。 呼び出しがタイマーを停止した場合は true, タイマーがすでに期限切れになっているか停止している場合は false を返します。 チャンネルからの読み取りが誤って成功するのを防ぐために, Stop はチャンネルを閉じません。

To ensure the channel is empty after a call to Stop, check the return value and drain the channel. For example, assuming the program has not received from t.C already:

if !t.Stop() {
	<-t.C
}

これはタイマーのチャンネルからの他の受信と平行に行うことはできません。

AfterFunc(d, f) で作成されたタイマーの場合, t.Stop が false を返すなら,そのタイマーはすでに期限切れになっており,関数 f は自身のゴルーチンで開始されています。 Stop は,戻る前に f が完了するのを待ちません。 呼び出し元が f が完了したかどうかを知る必要がある場合は,明示的に f と協調する必要があります。

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", ...) を返します。