qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-22 22:40:02 -07:00
Code Releases Activity

time: improve Truncate and Round documentation

Browse Source 
Truncate and Round operate on absolute time, which means that
Truncate(Hour) may return a time with non-zero Minute(). Document that
more clearly, and remove the misleading example which suggests it is
safe.

Updates #16647

Change-Id: I930584ca030dd12849195d45e49ed2fb74e0c9ac
Reviewed-on: https://go-review.googlesource.com/28730
Reviewed-by: Ian Lance Taylor <iant@golang.org>
This commit is contained in:
Quentin Smith 2016-09-07 18:07:45 -04:00
parent 1ee5446414
commit e42ae65a85
2 changed files with 18 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/time/example_test.go
View File

@ -251,20 +251,18 @@ func ExampleTime_Truncate() {
2 * time.Second,
time.Minute,
10 * time.Minute,
time.Hour,
}
for _, d := range trunc {
fmt.Printf("t.Truncate(%6s) = %s\n", d, t.Truncate(d).Format("15:04:05.999999999"))
fmt.Printf("t.Truncate(%5s) = %s\n", d, t.Truncate(d).Format("15:04:05.999999999"))
}
// Output:
// 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
// t.Truncate(1h0m0s) = 12:00:00
// 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
}

10
src/time/time.go
View File

@ -1103,6 +1103,11 @@ func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) T
// Truncate returns the result of rounding t down to a multiple of d (since the zero time).
// If d <= 0, Truncate returns t unchanged.
//
// Truncate operates on the time as an absolute duration since the
// zero time; it does not operate on the presentation form of the
// time. Thus, Truncate(Hour) may return a time with a non-zero
// minute, depending on the time's Location.
func (t Time) Truncate(d Duration) Time {
if d <= 0 {
return t
@ -1114,6 +1119,11 @@ func (t Time) Truncate(d Duration) Time {
// Round returns the result of rounding t to the nearest multiple of d (since the zero time).
// The rounding behavior for halfway values is to round up.
// If d <= 0, Round returns t unchanged.
//
// Round operates on the time as an absolute duration since the
// zero time; it does not operate on the presentation form of the
// time. Thus, Round(Hour) may return a time with a non-zero
// minute, depending on the time's Location.
func (t Time) Round(d Duration) Time {
if d <= 0 {
return t