time: add a number of new examples

Change-Id: I14d19a3951fcae24e2c2ce2eb76312851e050fdd
Reviewed-on: https://go-review.googlesource.com/61033
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

src/time/example_test.go

@@ -394,3 +394,162 @@ func ExampleTime_Truncate() {
 	// t.Truncate( 1m0s) = 12:15:00
 	// t.Truncate(10m0s) = 12:10:00
 }
+
+func ExampleLocation() {
+	// 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)
+
+	// Output:
+	// true
+}
+
+func ExampleTime_Add() {
+	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)
+
+	// Output:
+	// 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 ExampleTime_AddDate() {
+	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)
+
+	// Output:
+	// 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 ExampleTime_After() {
+	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)
+
+	// Output:
+	// year3000.After(year2000) = true
+	// year2000.After(year3000) = false
+}
+
+func ExampleTime_Before() {
+	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)
+
+	// Output:
+	// year2000.Before(year3000) = true
+	// year3000.Before(year2000) = false
+}
+
+func ExampleTime_Date() {
+	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)
+
+	// Output:
+	// year = 2000
+	// month = February
+	// day = 1
+}
+
+func ExampleTime_Day() {
+	d := time.Date(2000, 2, 1, 12, 30, 0, 0, time.UTC)
+	day := d.Day()
+
+	fmt.Printf("day = %v\n", day)
+
+	// Output:
+	// day = 1
+}
+
+func ExampleTime_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)
+
+	// Output:
+	// datesEqualUsingEqualOperator = false
+	// datesEqualUsingFunction = true
+}
+
+func ExampleTime_String() {
+	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))
+
+	// Output:
+	// withNanoseconds = 2000-02-01 12:13:14.000000015 +0000 UTC
+	// withoutNanoseconds = 2000-02-01 12:13:14 +0000 UTC
+}
+
+func ExampleTime_Sub() {
+	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)
+
+	// Output:
+	// difference = 12h0m0s
+}