From dfcc7a86c1971fad7778ed95af64e432c09dcb04 Mon Sep 17 00:00:00 2001 From: Kyoung-chan Lee Date: Sun, 2 Aug 2015 12:22:13 +0900 Subject: [PATCH] Improve some functions, add basic documents. --- README.md | 129 +++++++++++++++++++++++++++++++++++++++++++++- strftime_test.go | 9 ++-- timedelta.go | 54 ++++++++++--------- timedelta_test.go | 8 +-- 4 files changed, 167 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index db0f7e9..0d9bc3b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,127 @@ -# timeutil -timeutil - useful extensions to the golang's time package +# timeutil - useful extensions to the golang's time package +[![Build Status](https://travis-ci.org/leekchan/timeutil.svg?branch=master)](https://travis-ci.org/leekchan/timeutil) +[![Coverage Status](https://coveralls.io/repos/leekchan/timeutil/badge.svg?branch=master&service=github)](https://coveralls.io/github/leekchan/timeutil?branch=master) + +timeutil provides useful extensions (Timedelta, Strftime, ...) to the golang's time package. + +## Timedelta + +Timedelta represents a duration between two dates. (inspired by python's timedelta) + +### Timedelta struct + +```Go +type Timedelta struct { + days, seconds, microseconds, milliseconds, minutes, hours, weeks time.Duration +} +``` + +### Initialization + +All fields are optional and default to 0. You can initialize any type of timedelta by specifying field values which you want to use. + +**Examples:** + +```Go +td := Timedelta{days: 10} +td = Timedelta{minutes: 17} +td = Timedelta{seconds: 56} +td = Timedelta{days: 10, minutes: 17, seconds: 56} +td = Timedelta{days: 1, seconds: 1, microseconds: 1, milliseconds: 1, minutes: 1, hours: 1, weeks: 1} +``` + +### func (t *Timedelta) Duration() time.Duration + +Duration() returns time.Duration. time.Duration can be added to time.Date. + +**Exampels:** + +```Go +base := time.Date(2015, 2, 3, 0, 0, 0, 0, time.UTC) +td := Timedelta{days: 10, minutes: 17, seconds: 56} + +result := base.Add(td.Duration()) +fmt.Println(result) // "2015-02-28 00:31:38 +0000 UTC" +``` + +### Operations + +#### func (t *Timedelta) Add(t2 *Timedelta) + +Add returns the Timedelta t+t2. + +**Examples:** + +```Go +base = time.Date(2015, 2, 3, 0, 0, 0, 0, time.UTC) + +td := Timedelta{days: 10, minutes: 17, seconds: 56} +td2 := Timedelta{days: 15, minutes: 13, seconds: 42} +td = td.Add(&td2) + +result = base.Add(td.Duration()) +``` + +#### func (t *Timedelta) Subtract(t2 *Timedelta) Timedelta + +Subtract returns the Timedelta t-t2. + +```Go +base = time.Date(2015, 2, 3, 0, 0, 0, 0, time.UTC) + +td := Timedelta{days: 10, minutes: 17, seconds: 56} +td2 := Timedelta{days: 15, minutes: 13, seconds: 42} +td = td.Subtract(&td2) + +result = base.Add(td.Duration()) +``` + +#### func (t *Timedelta) Abs() Timedelta + +Abs returns the absolute value of t + +```Go +td := Timedelta{days: -10, minutes: -17, seconds: -56} +td = td.Abs(&td) +``` + + +## Strftime + +Strftime formats time.Date according to the directives in the given format string. The directives begins with a percent (%) character. + + +Directive | Meaning | Example +-- | ------------------------------------- | ------------ +%a | Weekday as locale’s abbreviated name. | Sun, Mon, ..., Sat +%A | Weekday as locale’s full name. | Sunday, Monday, ..., Saturday +%w | Weekday as a decimal number, where 0 is Sunday and 6 is Saturday | 0, 1, ..., 6 +%d | Day of the month as a zero-padded decimal number. | 01, 02, ..., 31 +%b | Month as locale’s abbreviated name. | Jan, Feb, ..., Dec +%B | Month as locale’s full name. | January, February, ..., December +%m | Month as a zero-padded decimal number. | 01, 02, ..., 12 +%y | Year without century as a zero-padded decimal number. | 00, 01, ..., 99 +%Y | Year with century as a decimal number. | 1970, 1988, 2001, 2013 +%H | Hour (24-hour clock) as a zero-padded decimal number. | 00, 01, ..., 23 +%I | Hour (12-hour clock) as a zero-padded decimal number. | 01, 02, ..., 12 +%p | Meridian indicator. (AM or PM.) | AM, PM +%M | Minute as a zero-padded decimal number. | 00, 01, ..., 59 +%S | Second as a zero-padded decimal number. | 00, 01, ..., 59 +%f | Microsecond as a decimal number, zero-padded on the left. | 000000, 000001, ..., 999999 +%z | UTC offset in the form +HHMM or -HHMM | +0000 +%Z | Time zone name | UTC +%j | Day of the year as a zero-padded decimal number | 001, 002, ..., 366 +%U | Week number of the year (Sunday as the first day of the week) as a zero padded decimal number. All days in a new year preceding the first Sunday are considered to be in week 0. | 00, 01, ..., 53 +%W | Week number of the year (Monday as the first day of the week) as a decimal number. All days in a new year preceding the first Monday are considered to be in week 0. | 00, 01, ..., 53 +%c | Date and time representation. | Tue Aug 16 21:30:00 1988 +%x | Date representation. | 08/16/88 +%X | Time representation. | 21:30:00 +%% | A literal '%' character. | % + + +## TODO + +* Locale support +* Strptime - a function which returns a Date parsed according to a format string +* Auto date parser - a generic string parser which is able to parse most known formats to represent a date +* And other useful features... \ No newline at end of file diff --git a/strftime_test.go b/strftime_test.go index ce6cc19..c4fdac1 100644 --- a/strftime_test.go +++ b/strftime_test.go @@ -13,14 +13,17 @@ func TestStrftime(t *testing.T) { date = time.Date(2015, 7, 2, 15, 24, 30, 35, time.UTC) AssertEqual(t, Strftime(&date, "%U %W"), "26 26") - + date = time.Date(1962, 3, 23, 15, 24, 30, 35, time.UTC) AssertEqual(t, Strftime(&date, "%U %W"), "11 12") - + date = time.Date(1989, 12, 31, 15, 24, 30, 35000, time.UTC) AssertEqual(t, Strftime(&date, "%U %W"), "53 52") - + AssertEqual(t, Strftime(&date, "%a %A %w %d %b %B %m %y %Y %H %I %p %M %S %f %z %Z %j %U %W %c %x %X %%"), "Sun Sunday 0 31 Dec December 12 89 1989 15 03 PM 24 30 000035 +0000 UTC 365 53 52 Sun Dec 31 15:24:30 1989 12/31/89 15:24:30 %") + + date = time.Date(1989, 12, 31, 0, 24, 30, 35000, time.UTC) + AssertEqual(t, Strftime(&date, "%I"), "12") } diff --git a/timedelta.go b/timedelta.go index 3b353ea..663a25a 100644 --- a/timedelta.go +++ b/timedelta.go @@ -15,34 +15,40 @@ type Timedelta struct { days, seconds, microseconds, milliseconds, minutes, hours, weeks time.Duration } -func (t *Timedelta) Add(t2 *Timedelta) { - t.days += t2.days - t.seconds += t2.seconds - t.microseconds += t2.microseconds - t.milliseconds += t2.milliseconds - t.minutes += t2.minutes - t.hours += t2.hours - t.weeks += t2.weeks +func (t *Timedelta) Add(t2 *Timedelta) Timedelta { + return Timedelta{ + days: t.days + t2.days, + seconds: t.seconds + t2.seconds, + microseconds: t.microseconds + t2.microseconds, + milliseconds: t.milliseconds + t2.milliseconds, + minutes: t.minutes + t2.minutes, + hours: t.hours + t2.hours, + weeks: t.weeks + t2.weeks, + } } -func (t *Timedelta) Subtract(t2 *Timedelta) { - t.days -= t2.days - t.seconds -= t2.seconds - t.microseconds -= t2.microseconds - t.milliseconds -= t2.milliseconds - t.minutes -= t2.minutes - t.hours -= t2.hours - t.weeks -= t2.weeks +func (t *Timedelta) Subtract(t2 *Timedelta) Timedelta { + return Timedelta{ + days: t.days - t2.days, + seconds: t.seconds - t2.seconds, + microseconds: t.microseconds - t2.microseconds, + milliseconds: t.milliseconds - t2.milliseconds, + minutes: t.minutes - t2.minutes, + hours: t.hours - t2.hours, + weeks: t.weeks - t2.weeks, + } } -func (t *Timedelta) Abs() { - t.days = abs(t.days) - t.seconds = abs(t.seconds) - t.microseconds = abs(t.microseconds) - t.milliseconds = abs(t.milliseconds) - t.minutes = abs(t.minutes) - t.hours = abs(t.hours) - t.weeks = abs(t.weeks) +func (t *Timedelta) Abs() Timedelta { + return Timedelta{ + days: abs(t.days), + seconds: abs(t.seconds), + microseconds: abs(t.microseconds), + milliseconds: abs(t.milliseconds), + minutes: abs(t.minutes), + hours: abs(t.hours), + weeks: abs(t.weeks), + } } func (t *Timedelta) Duration() time.Duration { diff --git a/timedelta_test.go b/timedelta_test.go index bb3f342..0497532 100644 --- a/timedelta_test.go +++ b/timedelta_test.go @@ -22,13 +22,13 @@ func TestTimedelta(t *testing.T) { td := Timedelta{days: 10, minutes: 17, seconds: 56} td2 := Timedelta{days: 15, minutes: 13, seconds: 42} - td.Add(&td2) + td = td.Add(&td2) base = time.Date(2015, 2, 3, 0, 0, 0, 0, time.UTC) result = base.Add(td.Duration()) AssertEqual(t, result.String(), "2015-02-28 00:31:38 +0000 UTC") - td.Subtract(&td2) + td = td.Subtract(&td2) result = base.Add(td.Duration()) AssertEqual(t, result.String(), "2015-02-13 00:17:56 +0000 UTC") @@ -37,7 +37,7 @@ func TestTimedelta(t *testing.T) { td = Timedelta{days: -1, seconds: -1, microseconds: -1, milliseconds: -1, minutes: -1, hours: -1, weeks: -1} td2 = td - td.Abs() - td.Add(&td2) + td = td.Abs() + td = td.Add(&td2) AssertEqual(t, td.String(), "0") }