Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 16213] ファイルの概要

このコミットは、Go言語の標準ライブラリtimeパッケージにおけるFormatおよびParse関数のドキュメントを改善することを目的としています。具体的には、日付と時刻のフォーマット指定に使用される「標準時 (standard time)」という用語を「参照時 (reference time)」に変更し、その動作に関する説明をより明確にしています。これにより、既存の「標準時」という用語が持つ他の意味との混同を避け、Goのtimeパッケージのユニークなフォーマットメカニズムを正確に伝えることを意図しています。

コミット

commit c2857890591eb1cd2b0fbd54deabd109330674c8
Author: Rob Pike <r@golang.org>
Date:   Mon Apr 22 11:36:17 2013 -0700

    time: improve the explanation of the working of Format and Parse
    Change the term 'standard time', which already means something,
    to 'reference time', and add a couple of sentences and clarifications.
    
    R=golang-dev, bradfitz
    CC=golang-dev
    https://golang.org/cl/8799047

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/c2857890591eb1cd2b0fbd54deabd109330674c8

元コミット内容

timeパッケージ: FormatとParseの動作説明を改善。 「標準時 (standard time)」という、すでに意味を持つ用語を「参照時 (reference time)」に変更し、いくつかの文と説明を追加して明確化。

変更の背景

Go言語のtimeパッケージにおけるFormatおよびParse関数は、日付と時刻のフォーマット指定に独特なアプローチを採用しています。多くのプログラミング言語がstrftimeのような記号ベースのフォーマット文字列（例: %Y-%m-%d）を使用するのに対し、Goは特定の参照時刻（Mon Jan 2 15:04:05 MST 2006）をテンプレートとして使用します。この参照時刻をユーザーが望むフォーマットで記述することで、Format関数はそのテンプレートに従ってtime.Timeオブジェクトを文字列に変換し、Parse関数はそのテンプレートに従って文字列をtime.Timeオブジェクトに変換します。

このコミット以前は、この参照時刻を「標準時 (standard time)」と呼んでいました。しかし、「標準時」という用語は、タイムゾーンや協定世界時 (UTC) など、時間に関する他の確立された概念を指すことが一般的です。このため、Goのtimeパッケージのドキュメントを読んだ際に、読者がこのGo独自のフォーマットメカニズムと、一般的な「標準時」の概念を混同する可能性がありました。

この混同を避け、Goのtimeパッケージのフォーマット方法をより正確に、かつ誤解なく伝えるために、Rob Pike氏はこの用語を「参照時 (reference time)」に変更することを提案しました。これにより、Goのtimeパッケージが「この特定の時刻をこのように表現すると、他の時刻も同様に表現できる」という「参照」の概念に基づいていることを明確にしています。

前提知識の解説

Go言語のtimeパッケージ

Go言語のtimeパッケージは、日付と時刻を扱うための機能を提供します。主な型はtime.Timeで、特定の時点を表します。このパッケージには、時刻の取得、加算、減算、比較、そして文字列との相互変換のためのメソッドが豊富に用意されています。

time.Formatとtime.Parseの独特なフォーマット方法

GoのtimeパッケージのFormatおよびParseメソッドは、他の多くの言語とは異なるフォーマット指定方法を採用しています。

  • 参照時刻 (Reference Time): Goでは、Mon Jan 2 15:04:05 MST 2006という特定の時刻を「参照時刻」として使用します。この時刻は、Unixエポック（1970年1月1日00:00:00 UTC）から数えて1136239445秒後の時刻であり、各要素（月、日、時、分、秒、タイムゾーン、年）がユニークな値を持つように選ばれています。
  • テンプレートとしての参照時刻:
    • Format(layout string): time.Timeオブジェクトを文字列に変換する際に、layout引数に「参照時刻がどのように表示されるか」を記述します。例えば、"2006-01-02"と指定すると、Goは参照時刻の年（2006）、月（01）、日（02）を抽出し、それをテンプレートとして実際のtime.Timeオブジェクトの年、月、日をフォーマットします。
    • Parse(layout, value string): 文字列をtime.Timeオブジェクトに変換する際に、layout引数に「参照時刻がどのように入力文字列に現れるか」を記述します。例えば、Parse("2006-01-02", "2023-10-26")とすると、Goはlayoutから参照時刻の各要素の位置を学習し、value文字列の対応する位置から実際の年、月、日を抽出してtime.Timeオブジェクトを構築します。

この方法は、フォーマット文字列の記号を覚える必要がなく、具体的な例を示すことで直感的に理解しやすいという利点があります。

「標準時 (Standard Time)」という用語の多義性

「標準時」という用語は、一般的に以下のような意味で使われます。

  • タイムゾーンの基準: 特定の地域で採用されている公式な時刻。例えば、日本標準時 (JST)、グリニッジ標準時 (GMT) など。
  • 協定世界時 (UTC): 国際的な時刻の基準。
  • 夏時間 (Daylight Saving Time) との対比: 夏時間ではない通常の時刻。

これらの意味合いから、Goのtimeパッケージのフォーマットにおける「標準時」という表現は、読者に混乱を招く可能性がありました。

技術的詳細

このコミットの技術的な変更は、主にドキュメントとコメントの用語の置き換えと、説明の追加に集約されます。

  1. 用語の変更:

    • src/pkg/time/format.go内のコメントで、「The standard time used in the layouts is:」という記述が「The reference time used in the layouts is:」に変更されました。
    • 同様に、「the standard time can be thought of as」が「the reference time can be thought of as」に、「To define your own format, write down what the standard time would look」が「To define your own format, write down what the reference time would look」に変更されています。
    • Time.FormatおよびTime.Parseメソッドのドキュメント文字列内でも、「standard time」が「reference time」に置き換えられています。

  2. 説明の追加と明確化:

    • src/pkg/time/format.goのFormatおよびParse関数の説明に、Goのフォーマット方法の「モデル」に関する記述が追加されました。
      • Formatの説明には、「The model is to demonstrate what the reference time looks like so that the Format and Parse methods can apply the same transformation to a general time value.」という文が追加され、参照時刻がどのようにテンプレートとして機能するかが強調されています。
      • Parseの説明には、「it serves as an example of the input format. The same interpretation will then be made to the input string.」という文が追加され、参照時刻が入力フォーマットの例としてどのように機能するかが明確化されています。
    • src/pkg/time/example_test.goのExampleTime_FormatとExampleParseの例に、layoutやlongForm、shortFormといった変数名にコメントが追加され、これらが「参照時刻がどのように表現されるかを示す例」であることが明示されました。これにより、コード例の意図がより分かりやすくなっています。

これらの変更は、コードの動作自体には影響を与えませんが、Goのtimeパッケージの最も特徴的な機能の一つであるフォーマット方法に関するドキュメントの品質を大幅に向上させ、新規ユーザーや他の言語からの移行者がGoのtimeパッケージをより迅速かつ正確に理解するのに役立ちます。

コアとなるコードの変更箇所

このコミットで変更されたファイルは以下の2つです。

  1. src/pkg/time/example_test.go
    • ExampleTime_Format関数とExampleParse関数内のコメントが追加・修正され、layout変数やlongForm/shortForm変数が「参照時刻の表現例」であることを明確にしています。
  2. src/pkg/time/format.go
    • ファイル冒頭のコメント、Time.Formatメソッドのドキュメント、Time.Parseメソッドのドキュメントにおいて、「standard time」という用語が「reference time」に一貫して置き換えられています。
    • Time.FormatとTime.Parseのドキュメントに、Goのフォーマットメカニズムの「モデル」を説明する追加の文が挿入されています。

コアとなるコードの解説

src/pkg/time/example_test.go

--- a/src/pkg/time/example_test.go
+++ b/src/pkg/time/example_test.go
@@ -58,20 +58,25 @@ func ExampleDate() {
 }
 
 func ExampleTime_Format() {
-	const format = "Jan 2, 2006 at 3:04pm (MST)"
+	// layout shows by example how the reference time should be represented.
+	const layout = "Jan 2, 2006 at 3:04pm (MST)"
 	t := time.Date(2009, time.November, 10, 15, 0, 0, 0, time.Local)
-	fmt.Println(t.Format(format))
-	fmt.Println(t.UTC().Format(format))
+	fmt.Println(t.Format(layout))
+	fmt.Println(t.UTC().Format(layout))
 	// Output:
 	// Nov 10, 2009 at 3:00pm (PST)
 	// Nov 10, 2009 at 11:00pm (UTC)
 }
 
 func ExampleParse() {
+	// 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")

この変更では、ExampleTime_FormatとExampleParseの関数内で使用されているフォーマット文字列の定数（format, longForm, shortForm）に対して、その役割を説明するコメントが追加されました。特に、「layout shows by example how the reference time should be represented.」や「longForm shows by example how the reference time would be represented in the desired layout.」といったコメントは、Goのtimeパッケージのフォーマットが「参照時刻の例」に基づいているという核心的な概念を、コード例を通じて読者に伝えるのに役立ちます。

src/pkg/time/format.go

--- a/src/pkg/time/format.go
+++ b/src/pkg/time/format.go
@@ -6,15 +6,17 @@ package time
 
 import "errors"
 
-// These are predefined layouts for use in Time.Format.
-// The standard time used in the layouts is:
+// These are predefined layouts for use in Time.Format and Time.Parse.
+// The reference time used in the layouts is:
 //	Mon Jan 2 15:04:05 MST 2006
 // which is Unix time 1136239445. Since MST is GMT-0700,
-// the standard time can be thought of as
+// the reference time can be thought of as
 //	01/02 03:04:05PM '06 -0700
-// To define your own format, write down what the standard time would look
+// To define your own format, write down what the reference time would look
 // like formatted your way; see the values of constants like ANSIC,
-// StampMicro or Kitchen for examples.
+// StampMicro or Kitchen for examples. The model is to demonstrate what the
+// reference time looks like so that the Format and Parse methods can apply
+// the same transformation to a general time value.
 //
 // Within the format string, an underscore _ represents a space that may be
 // replaced by a digit if the following number (a day) has two digits; for
@@ -367,13 +369,16 @@ func (t Time) String() string {
 }
 
 // Format returns a textual representation of the time value formatted
-// according to layout.  The layout defines the format by showing the
-// representation of the standard time,
+// according to layout, which defines the format by showing how the reference
+// time,
 //	Mon Jan 2 15:04:05 -0700 MST 2006
-// which is then used to describe the time to be formatted. Predefined
-// layouts ANSIC, UnixDate, RFC3339 and others describe standard
-// representations. For more information about the formats and the
-// definition of the standard time, see the documentation for ANSIC.
+// would be displayed if it were the value; it serves as an example of the
+// desired output. The same display rules will then be aplied to the time
+// value.
+// Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
+// and convenient representations of the reference time. For more information
+// about the formats and the definition of the reference time, see the
+// documentation for ANSIC and the other constants defined by this package.
 func (t Time) Format(layout string) string {
 	var (
 		name, offset, abs = t.locabs()
@@ -627,13 +632,15 @@ func skip(value, prefix string) (string, error) {
 }
 
 // Parse parses a formatted string and returns the time value it represents.
-// The layout defines the format by showing the representation of the
-// standard time,
+// The layout  defines the format by showing how the reference time,
 //	Mon Jan 2 15:04:05 -0700 MST 2006
-// which is then used to describe the string to be parsed. Predefined layouts
-// ANSIC, UnixDate, RFC3339 and others describe standard representations. For
-// more information about the formats and the definition of the standard
-// time, see the documentation for ANSIC.
+// would be interepreted if it were the value; it serves as an example of
+// the input format. The same interpretation will then be made to the
+// input string.
+// Predefined layouts ANSIC, UnixDate, RFC3339 and others describe standard
+// and convenient representations of the reference time. For more information
+// about the formats and the definition of the reference time, see the
+// documentation for ANSIC and the other constants defined by this package.
 //
 // Elements omitted from the value are assumed to be zero or, when
 // zero is impossible, one, so parsing "3:04pm" returns the time

このファイルでは、主に以下の変更が行われました。

  1. ファイル冒頭のコメント: Time.FormatとTime.Parseで使用される事前定義されたレイアウトに関する説明で、「standard time」が「reference time」に置き換えられました。さらに、「The model is to demonstrate what the reference time looks like so that the Format and Parse methods can apply the same transformation to a general time value.」という重要な文が追加され、Goのフォーマットの「モデル」が明確に説明されています。これは、参照時刻が単なる例ではなく、変換ルールを定義するためのテンプレートとして機能するというGoの設計思想を強調しています。

  2. Formatメソッドのドキュメント: Formatメソッドのドキュメント文字列内で、「standard time」が「reference time」に置き換えられました。また、参照時刻が「desired outputの例として機能する」こと、そして「同じ表示ルールがtime値に適用される」ことが明確に記述されました。これにより、Formatの動作原理がより直感的に理解できるようになりました。

  3. Parseメソッドのドキュメント: Parseメソッドのドキュメント文字列内でも、「standard time」が「reference time」に置き換えられました。Formatと同様に、参照時刻が「input formatの例として機能する」こと、そして「同じ解釈が入力文字列に対して行われる」ことが強調されています。これにより、Parseの動作原理もより明確になりました。

これらの変更は、Goのtimeパッケージのドキュメントの正確性と明確性を大幅に向上させ、ユーザーがGoの独特な日付/時刻フォーマット方法をより深く理解するのに貢献しています。

関連リンク

参考にした情報源リンク