Merge pull request #1140 from influxdata/flux/timeable

Update 'date' package with support for duration values

content/v2.0/reference/flux/stdlib/built-in/misc/now.md

@@ -12,7 +12,7 @@ related:
   - /v2.0/reference/flux/stdlib/system/time/
 ---
 
-The `now()` function returns the current time (UTC).
+The `now()` function returns the current time (UTC) or the time defined in the `now` option.
 
 _**Function type:** Date/Time_  
 _**Output data type:** Time_
@@ -22,11 +22,21 @@ now()
 ```
 
 ## Examples
+
+##### Use the current UTC time as a query boundary
 ```js
 data
   |> range(start: -10h, stop: now())
 ```
 
+##### Return the now option time
+```js
+option now = () => 2020-01-01T00:00:00Z
+
+now()
+// Returns 2020-01-01T00:00:00.000000000Z
+```
+
 {{% note %}}
 #### now() vs system.time()
 `now()` returns the current UTC time.

content/v2.0/reference/flux/stdlib/date/hour.md

@@ -29,5 +29,29 @@ date.hour(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the hour of a time value
+```js
+import "date"
+
+date.hour(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 12
+```
+
+##### Return the hour of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.hour(t: -8h)
+
+// Returns 4
+```

content/v2.0/reference/flux/stdlib/date/microsecond.md

@@ -29,5 +29,29 @@ date.microsecond(t: 2019-07-17T12:05:21.012934584Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the microsecond of a time value
+```js
+import "date"
+
+date.microsecond(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 293534
+```
+
+##### Return the microsecond of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.microsecond(t: -1890us)
+
+// Returns 291644
+```

content/v2.0/reference/flux/stdlib/date/millisecond.md

@@ -29,5 +29,29 @@ date.millisecond(t: 2019-07-17T12:05:21.012934584Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the millisecond of a time value
+```js
+import "date"
+
+date.millisecond(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 293
+```
+
+##### Return the millisecond of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.millisecond(t: -150ms)
+
+// Returns 143
+```

content/v2.0/reference/flux/stdlib/date/minute.md

@@ -29,5 +29,29 @@ date.minute(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the minute of a time value
+```js
+import "date"
+
+date.minute(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 21
+```
+
+##### Return the minute of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.minute(t: -45m)
+
+// Returns 36
+```

content/v2.0/reference/flux/stdlib/date/month.md

@@ -29,5 +29,29 @@ date.month(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the month of a time value
+```js
+import "date"
+
+date.month(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 2
+```
+
+##### Return the month of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.month(t: -3mo)
+
+// Returns 11
+```

content/v2.0/reference/flux/stdlib/date/monthday.md

@@ -29,5 +29,29 @@ date.monthDay(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the day of the month for a time value
+```js
+import "date"
+
+date.monthDay(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 11
+```
+
+##### Return the day of the month for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.monthDay(t: -8d)
+
+// Returns 3
+```

content/v2.0/reference/flux/stdlib/date/nanosecond.md

@@ -29,5 +29,29 @@ date.nanosecond(t: 2019-07-17T12:05:21.012934584Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the nanosecond for a time value
+```js
+import "date"
+
+date.nanosecond(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 293534940Z
+```
+
+##### Return the nanosecond for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.nanosecond(t: -2111984ns)
+
+// Returns 291422956
+```

content/v2.0/reference/flux/stdlib/date/quarter.md

@@ -29,5 +29,29 @@ date.quarter(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the quarter for a time value
+```js
+import "date"
+
+date.quarter(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 1
+```
+
+##### Return the quarter for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.quarter(t: -7mo)
+
+// Returns 3
+```

content/v2.0/reference/flux/stdlib/date/second.md

@@ -29,5 +29,29 @@ date.second(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the second of a time value
+```js
+import "date"
+
+date.second(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 3
+```
+
+##### Return the second of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.second(t: -50s)
+
+// Returns 13
+```

content/v2.0/reference/flux/stdlib/date/truncate.md

@@ -30,8 +30,10 @@ date.truncate(
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
 
 ### unit
 The unit of time to truncate to.
@@ -44,16 +46,33 @@ For example: `1s`, `1m`, `1h`.
 {{% /note %}}
 
 ## Examples
+
+##### Truncate time values
 ```js
 import "date"
 
-date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1s)
-// Returns  2019-06-03T13:59:01.000000000Z
+date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1s)
+// Returns 2019-06-03T13:59:01.000000000Z
 
-date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1m)
-// Returns  2019-06-03T13:59:00.000000000Z
-
-date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1h)
-// Returns  2019-06-03T13:00:00.000000000Z
+date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1m)
+// Returns 2019-06-03T13:59:00.000000000Z
 
+date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1h)
+// Returns 2019-06-03T13:00:00.000000000Z
+```
+
+##### Truncate time values using durations
+```js
+import "date"
+
+option now = () => 2020-01-01T00:00:30.500000000Z
+
+date.truncate(t: -30s, unit: 1s)
+// Returns 2019-12-31T23:59:30.000000000Z
+
+date.truncate(t: -1m, unit: 1m)
+// Returns 2019-12-31T23:59:00.000000000Z
+
+date.truncate(t: -1h, unit: 1h)
+// Returns 2019-12-31T23:00:00.000000000Z
 ```

content/v2.0/reference/flux/stdlib/date/week.md

@@ -29,5 +29,29 @@ date.week(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the week of the year
+```js
+import "date"
+
+date.week(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 7
+```
+
+##### Return the week of the year using a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.week(t: -12d)
+
+// Returns 5
+```

content/v2.0/reference/flux/stdlib/date/weekday.md

@@ -29,5 +29,29 @@ date.weekDay(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the day of the week for a time value
+```js
+import "date"
+
+date.weekDay(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 2
+```
+
+##### Return the day of the week for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.weekDay(t: -84h)
+
+// Returns 6
+```

content/v2.0/reference/flux/stdlib/date/year.md

@@ -27,5 +27,29 @@ date.year(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the year for a time value
+```js
+import "date"
+
+date.year(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 2020
+```
+
+##### Return the year for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.year(t: -14y)
+
+// Returns 2006
+```

content/v2.0/reference/flux/stdlib/date/yearday.md

@@ -29,5 +29,29 @@ date.yearDay(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the day of the year for a time value
+```js
+import "date"
+
+date.yearDay(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 42
+```
+
+##### Return the day of the year for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.yearDay(t: -1mo)
+
+// Returns 11
+```