1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
# Duration
> Durations are a component of time intervals and define the amount of
> intervening time in a time interval. Source: [Wikipedia ISO8601](https://en.wikipedia.org/wiki/ISO_8601#Durations)
See [Time Interval](time-interval.md) for working with specific intervals of
time.
## Supported patterns
```
PnYnMnDTnHnMnS
PnW
```
`P<date>T<time>` will not be implemented.
## Usage
Some times using durations might be more convenient than using time intervals:
```ruby
duration = ISO8601::Duration.new('PT10H')
duration.to_seconds # => 36000.0
```
You can reuse the duration with a time interval:
```ruby
start_time = ISO8601::DateTime.new('2015-01-01T10:11:12Z')
time_interval = ISO8601::TimeInterval.from_duration(start_time, duration)
time_interval.size # => 36000.0
end_time = ISO8601::DateTime.new('2015-01-01T10:11:12Z')
time_interval = ISO8601::TimeInterval.from_duration(duration, end_time)
```
Or use an ad-hoc base:
```ruby
base = ISO8601::DateTime.new('2015-01-01T10:11:12Z')
duration = ISO8601::Duration.new('PT10H')
duration.to_seconds(base) # => 36000.0
```
**Warning**: When using durations without base, the result of `#to_seconds` is
an _average_. See the atoms' implementation for details.
# Operate with durations
The `ISO8601::Duration` has the concept of sign to be able to represent negative
values:
```ruby
(ISO8601::Duration.new('PT10S') - ISO8601::Duration.new('PT12S')).to_s #=> '-PT2S'
(ISO8601::Duration.new('-PT10S') + ISO8601::Duration.new('PT12S')).to_s #=> 'PT2S'
```
You can also inspect a duration by atom:
```
duration = ISO8601::Duration.new('P2Y1MT2H')
duration.years # => #<ISO8601::Years ... @atom=2.0>
duration.months # => #<ISO8601::Months ... @atom=1.0>
duration.days # => #<ISO8601::Days ... @atom=0>
duration.hours # => #<ISO8601::Hours ... @atom=2.0>
duration.minutes # => #<ISO8601::Hours ... @atom=0.0>
duration.seconds # => #<ISO8601::Hours ... @atom=0.0>
```
Or get back the pattern:
```ruby
duration.to_s # => 'P2Y1MT2H'
```
|
