iso8601 0.8.7 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: da8595f5fe628655a291148485dbd7d24f65688c
-  data.tar.gz: 02f8ad412ea8b17eacbf4b0e9a3758c8f4bdc2c2
+  metadata.gz: 7ddae589523a353d89540217174b6d9ee8806be0
+  data.tar.gz: e0194acdcdc97a76bfa05ef1cf0389e01ab39d10
 SHA512:
-  metadata.gz: e33d0e1b9016a1d5c41bf2b4c582ccbff2fb030e8d373151ac9f2e6fa09aaabb2126c160253c1e126a1ce4a4ffdfa4e607c61b74d09dc926cbabb880c9ddf47b
-  data.tar.gz: 96d0336d8add6e8a91e82ef6d27fa1cfaf9cc1d0b54a010123d9b01d2b161135135a7b03c5d8e74422edb785a0948401a702e82c8c303a93713653dbce87506a
+  metadata.gz: d013dd70e31518034388484c891a4b407d475bafb178b762fc997a9927ac43a90cde015ac0cf308a1d713d3dc4a1cb1ee0d333e8f0e31cf93e2c0c75a859ec81
+  data.tar.gz: 6144023256e448874c926377449230a059145996d48ab355d04acba4f22d2bd497a8a11892a43bf46c76d10cd3775d9661ce41f6aa101d19938216d307ce54bb

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 0.9.0
+
+This version is **not compatible** with previous versions.  Atoms and Durations
+changed their interface when treating base dates so it is only applied when
+computing the Atom length (e.g. `#to_seconds`).  As a consequence, it is no
+longer possible to do operations like `DateTime + Duration`.
+
+* Add time intervals (thanks @Angelmmiguel).
+* Remove `Duration#to_i`.
+* Change `Duration#to_seconds` to accept a base `DateTime`.
+* Remove duration dependency on a base date on the instance level.
+* Change `Years#to_seconds` and `Months#to_seconds` to accept a base `DateTime`.
+* Remove atom dependency on a base date on the instance level.
+* Add `Atomic` mixin.
+* Remove `Atom` abstract class.
+* Allow `ISO8601::Duration` to perform operations with `Numeric` (thanks @Angelmmiguel).
+
 ## 0.8.7
 
 * Make `Atom` comparable with the same kind (thanks @glassbead0).

data/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Thanks for taking the time to submit a pull request!  These are the few
+guidelines to keep things coherent.
+
+[Fork the project](http://github.com/arnau/ISO8601/fork) and clone.
+
+Create your _feature_ branch:
+
+```sh
+git checkout -b features/xyz
+```
+
+Set up your machine.  I recommend using [Docker](https://docker.com):
+
+```sh
+make install
+```
+
+But of course you can go raw style
+
+```sh
+bundle install
+```
+
+Add your code and tests and check it passes:
+
+```sh
+make test  # mri, rbx, jruby
+# or
+make mri-test
+make rbx-test
+make jruby-test
+```
+
+Or raw style
+
+```sh
+bundle exec rspec
+```
+
+Although not required, try to adhere to Rubocop's checks:
+
+```sh
+make check
+```
+
+Or raw style
+
+```sh
+bundle exec rubocop
+```
+
+Push your branch and submit a [Pull Request](https://github.com/arnau/iso8601/compare/).
+
+Add a description of your proposed changes and why they are needed.
+
+I'll review it as soon as I can.

data/Gemfile

@@ -3,6 +3,6 @@ source 'http://rubygems.org'
 gemspec
 
 group :development do
-  gem 'pry'
-  gem 'pry-doc'
+  gem 'pry', '~> 0.10.3'
+  gem 'pry-doc', '~> 0.8.0'
 end

data/README.md

@@ -1,5 +1,14 @@
 # ISO8601
 
+Version 0.9.0 is **not compatible** with previous versions.  Atoms and Durations
+changed their interface when treating base dates so it is only applied when
+computing the Atom length (e.g. `#to_seconds`).  As a consequence, it is no
+longer possible to do operations like `DateTime + Duration`.
+
+Version 1.0.0 will lock public interfaces.
+
+Check the [changelog](https://github.com/arnau/ISO8601/blob/master/CHANGELOG.md) if you are upgrading from an older version.
+
 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/arnau/ISO8601?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 ISO8601 is a simple implementation of the ISO 8601 (Data elements and
@@ -14,132 +23,49 @@ times) standard.
 
 ## Supported versions
 
-* MRI 1.9.3, 2.0, 2.1, 2.2
+* MRI 2.x
 * RBX 2
-
-Check the [changelog](https://github.com/arnau/ISO8601/blob/master/CHANGELOG.md) if you are upgrading from an older version.
+* JRuby 9
 
 ## Documentation
 
-Check the [rubydoc documentation](http://www.rubydoc.info/gems/iso8601).
-
-## Comments about this implementation
-
-### Duration sign
-
-Because `Durations` and `DateTime` have a substraction method, `Durations` has
-sign to be able to represent negative values:
-
-    (ISO8601::Duration.new('PT10S') - ISO8601::Duration.new('PT12S')).to_s  #=> '-PT2S'
-    (ISO8601::Duration.new('-PT10S') + ISO8601::Duration.new('PT12S')).to_s #=> 'PT2S'
-
-### Fractional seconds precision
-
-Fractional seconds for `ISO8601::DateTime` and `ISO8601::Time` are rounded to
-one decimal.
-
-    ISO8601::DateTime.new('2015-02-03T10:11:12.12').second #=> 12.1
-    ISO8601::Time.new('T10:11:12.16').second #=> 12.2
-
-
-## Differences with core Date, Time and DateTime
-
-Core `Date.parse` and `DateTime.parse` doesn't allow reduced precision. For
-example:
-
-    DateTime.parse('2014-05') # => ArgumentError: invalid date
-
-But the standard covers this situation assuming any missing piece as its lower
-value:
-
-    ISO8601::DateTime.new('2014-05').to_s # => "2014-05-01T00:00:00+00:00"
-    ISO8601::DateTime.new('2014').to_s # => "2014-01-01T00:00:00+00:00"
-
-The same assumption happens in core classes with `.new`:
-
-    DateTime.new(2014,5) # => #<DateTime: 2014-05-01T00:00:00+00:00 ((2456779j,0s,0n),+0s,2299161j)>
-    DateTime.new(2014) # => #<DateTime: 2014-01-01T00:00:00+00:00 ((2456659j,0s,0n),+0s,2299161j)>
-
-
-The value of second in core classes are handled by two methods: `#second` and
-`#second_fraction`:
-
-    dt = DateTime.parse('2014-05-06T10:11:12.5')
-    dt.second # => 12
-    dt.second_fraction # => (1/2)
-
-This gem approaches second fraction using floats:
+Check the [rubydoc documentation](http://www.rubydoc.info/gems/iso8601). Or
+take a look to the implementation notes:
 
-    dt = ISO8601::DateTime.new('2014-05-06T10:11:12.5')
-    dt.second # => 12.5
+* [Date, Time, DateTime](docs/date-time.md)
+* [Duration](docs/duration.md)
+* [Time interval](docs/time-interval.md)
 
-Unmatching precison is handled strongly. Notice the time fragment is lost in
-`DateTime.parse` without warning only if the loose precision is in the time
-component.
 
-    ISO8601::DateTime.new('2014-05-06T101112')  # => ISO8601::Errors::UnknownPattern
-    DateTime.parse('2014-05-06T101112')  # => #<DateTime: 2014-05-06T00:00:00+00:00 ((2456784j,0s,0n),+0s,2299161j)>
-
-    ISO8601::DateTime.new('20140506T10:11:12')  # => ISO8601::Errors::UnknownPattern
-    DateTime.parse('20140506T10:11:12')  # => #<DateTime: 2014-05-06T10:11:12+00:00 ((2456784j,0s,0n),+0s,2299161j)>
-
-
-`DateTime#to_a` allow decomposing to an array of atoms:
-
-    atoms = ISO8601::DateTime.new('2014-05-31T10:11:12Z').to_a # => [2014, 5, 31, 10, 11, 12, '+00:00']
-    dt = DateTime.new(*atoms)
-
-Ordinal dates keep the sign. `2014-001` is not the same as `-2014-001`.
-
-Week dates raise an error when two digit days provied instead of return monday:
-
-    ISO8601::DateTime.new('2014-W15-02') # => ISO8601::Errors::UnknownPattern
-    DateTime.new('2014-W15-02')  # => #<Date: 2014-04-07 ((2456755j,0s,0n),+0s,2299161j)>
-
-
-## Compatibility with core classes
-
-Each ISO8601 class has a method `to_*` to convert to its core equivalent:
-
-`ISO8601::DateTime#to_datetime` -> `DateTime` (it actually delegates a couple of
-methods from `DateTime`).  Check `lib/iso8601/date_time.rb:13`.
+## Testing
 
-`ISO8601::Date#to_date` -> `Date` (it actually delegates to a couple of methods
-from `Date`).  Check `lib/iso8601/date.rb:18`
 
-`ISO8601::Time#to_time` -> `Time` (it actually delegates to a couple of methods
-from `Time`).  Check `lib/iso8601/time.rb:15`
+### Docker
 
-`ISO8601::Atom#to_f` -> `Float`, `ISO8601::Atom#to_i` -> `Integer`
+    # Install Docker
+    $ make install
+    $ make test
 
+You can alse target specific runtimes:
 
-## Testing
+    $ make mri-test
+    $ make rbx-test
+    $ make jruby-test
 
 ### Raw
 
+The old fashion way:
+
     # Install a Ruby flavour
     $ bundle install
     $ bundle exec rspec
 
-### Docker
-
-This way is in an early stage so for now it's only possible to test one Ruby
-version (currently Ruby 2.2.)
-
-    # Install Docker
-    $ make install
-    $ make test
 
 ## Contributing
 
 [Contributors](https://github.com/arnau/ISO8601/graphs/contributors)
 
-1. Fork it (http://github.com/arnau/ISO8601/fork)
-2. Create your feature branch (git checkout -b features/xyz)
-3. Commit your changes (git commit -am 'Add XYZ')
-4. Push to the branch (git push origin features/xyz)
-5. Create new Pull Request
-
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md)
 
 ## License
 

data/docs/date-time.md

@@ -0,0 +1,86 @@
+# Date Time, Date, Time
+
+
+## Interface with core classes
+
+ISO8601 classes provide a method `to_*` to convert to its core equivalent:
+
+```ruby
+ISO8601::DateTime#to_datetime # => #<DateTime: ...>
+ISO8601::Date#to_date # => #<Date: ...>
+ISO8601::Time#to_time # => #<Time: ...>
+```
+
+## Differences with core Date, Time and DateTime
+
+### Reduced precision
+
+Core `Date.parse` and `DateTime.parse` don't allow reduced precision. For
+example:
+
+```ruby
+DateTime.parse('2014-05') # => ArgumentError: invalid date
+```
+
+But the standard covers this situation assuming any missing token as its lower
+value:
+
+```ruby
+ISO8601::DateTime.new('2014-05').to_s # => "2014-05-01T00:00:00+00:00"
+ISO8601::DateTime.new('2014').to_s # => "2014-01-01T00:00:00+00:00"
+```
+
+The same assumption happens in core classes with `.new`:
+
+```ruby
+DateTime.new(2014,5) # => #<DateTime: 2014-05-01T00:00:00+00:00 ((2456779j,0s,0n),+0s,2299161j)>
+DateTime.new(2014) # => #<DateTime: 2014-01-01T00:00:00+00:00 ((2456659j,0s,0n),+0s,2299161j)>
+```
+
+### Unmatched precision
+
+Unmatched precison is handled strongly. Notice the time fragment is lost in
+`DateTime.parse` with no warning only if the loose precision is in the time
+component.
+
+```ruby
+ISO8601::DateTime.new('2014-05-06T101112')  # => ISO8601::Errors::UnknownPattern
+DateTime.parse('2014-05-06T101112')  # => #<DateTime: 2014-05-06T00:00:00+00:00 ((2456784j,0s,0n),+0s,2299161j)>
+
+ISO8601::DateTime.new('20140506T10:11:12')  # => ISO8601::Errors::UnknownPattern
+DateTime.parse('20140506T10:11:12')  # => #<DateTime: 2014-05-06T10:11:12+00:00 ((2456784j,0s,0n),+0s,2299161j)>
+```
+
+### Strong pattern matching
+
+Week dates raise an error when two digit days provied instead of return monday:
+
+```ruby
+ISO8601::DateTime.new('2014-W15-02') # => ISO8601::Errors::UnknownPattern
+DateTime.new('2014-W15-02')  # => #<Date: 2014-04-07 ((2456755j,0s,0n),+0s,2299161j)>
+```
+
+
+## Atomization
+
+`DateTime#to_a` allows decomposing to an array of atoms:
+
+```ruby
+atoms = ISO8601::DateTime.new('2014-05-31T10:11:12Z').to_a # => [2014, 5, 31, 10, 11, 12, '+00:00']
+dt = DateTime.new(*atoms)
+```
+
+## Sign
+
+Ordinal dates keep the sign. `2014-001` is not the same as `-2014-001`.
+
+
+## Fractional seconds precision
+
+Fractional seconds for `ISO8601::DateTime` and `ISO8601::Time` are rounded to
+one decimal.
+
+```ruby
+ISO8601::DateTime.new('2015-02-03T10:11:12.12').second #=> 12.1
+ISO8601::Time.new('T10:11:12.16').second #=> 12.2
+```

data/docs/duration.md

@@ -0,0 +1,77 @@
+# 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
+(e.g. you don't need or want a specific point in time).
+
+```ruby
+duration = ISO8601::Duration.new('PT10H')
+duration.to_seconds # => 36000.0
+```
+
+Although you 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 implementation of the atoms 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'
+```

data/docs/time-interval.md

@@ -0,0 +1,120 @@
+# Time Interval
+
+> A time interval is the intervening time between two time points.
+Source: [Wikipedia ISO8601](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals)
+
+This library implements the Time Interval type via [`ISO8601::TimeInterval`](../lib/iso8601/time_interval.rb)
+with the following constructors:
+
+* `TimeInterval.new(String)` (or `TimeInterval.parse(String)`)
+* `TimeInterval.from_duration(Duration, Hash<DateTime>)`
+* `TimeInterval.from_datetime(DateTime, DateTime)`
+
+
+## Supported patterns
+
+```
+<start>/<end>
+<start>/<duration>
+<duration>/<end>
+```
+
+Where `<start>` and `<end>` are points in time and `<duration>` is an amount of
+time.
+
+The pattern `<duration>` is not implemented; instead, you can use
+[`TimeInterval.from_duration`](../lib/iso8601/time_interval.rb#L70).
+
+
+## Usage
+
+### `<start>/<end>`
+
+The resulting time interval will have a starting point based on the provided
+`<start>` pattern and an ending point based on the provided `<end>` pattern.
+
+```ruby
+ti = ISO8601::TimeInterval.parse('2015-12-12T19:53:00Z/2015-12-13T19:53:00Z')
+ti.start_time.to_s  # => '2015-12-12T19:53:00Z'
+ti.end_time.to_s    # => '2015-12-13T19:53:00Z'
+ti.size             # => 86_400.0
+```
+
+### `<start>/<duration>`
+
+The resulting time interval will have a starting point based on the provided
+`<start>` pattern and an ending point result of `<start> + <duration>`.
+
+```ruby
+ti = ISO8601::TimeInterval.parse('2015-12-12T19:53:00Z/P1D')
+ti.start_time.to_s  # => '2015-12-12T19:53:00Z'
+ti.end_time.to_s    # => '2015-12-13T19:53:00Z'
+ti.size             # => 86_400.0
+```
+
+### `<duration>/<end>`
+
+The resulting time interval will have a starting point result of
+`<end> - <duration>` and an ending point based on the provided `<end>` pattern.
+
+```ruby
+ti = ISO8601::TimeInterval.parse('P1D/2015-12-13T19:53:00Z')
+ti.start_time.to_s  # => '2015-12-12T19:53:00Z'
+ti.end_time.to_s    # => '2015-12-13T19:53:00Z'
+ti.size             # => 86_400.0
+```
+
+
+### `TimeInterval.from_duration`
+
+```ruby
+duration = ISO8601::Duration.new('P1D`)
+start_time = ISO8601::DateTime.new('2015-12-12T19:53:00Z')
+ti = ISO8601::TimeInterval.from_duration(start_time, duration)
+ti.start_time.to_s  # => '2015-12-12T19:53:00Z'
+ti.end_time.to_s    # => '2015-12-13T19:53:00Z'
+ti.size             # => 86_400.0
+
+
+end_time = ISO8601::DateTime.new('2015-12-13T19:53:00Z')
+ti2 = ISO8601::TimeInterval.from_duration(duration, end_time)
+ti2.start_time.to_s  # => '2015-12-12T19:53:00Z'
+ti2.end_time.to_s    # => '2015-12-13T19:53:00Z'
+ti2.size             # => 86_400.0
+```
+
+### `TimeInterval.from_datetime`
+
+This constructor is an alternative way to `<start>/<end>` via Ruby objects.
+
+```ruby
+start_time = ISO8601::DateTime.new('2015-12-12T19:53:00Z')
+end_time = ISO8601::DateTime.new('2015-12-13T19:53:00Z')
+ti2 = ISO8601::TimeInterval.from_duration(start_time, end_time)
+ti2.start_time.to_s  # => '2015-12-12T19:53:00Z'
+ti2.end_time.to_s    # => '2015-12-13T19:53:00Z'
+ti2.size             # => 86_400.0
+```
+
+## Operate with time intervals
+
+`TimeInterval` is `Comparable`, so you can use the usual `<`, `>`, `<=`, `>=`,
+`==` to compare against another `TimeInterval`.  Is equivalent to get the
+amount of seconds via `#to_f` and compare the resulting numbers.
+
+A time interval can be viewed as an ordered set of datetime elements:
+
+* `#empty?` checks if an interval is empty.
+* `#include?` checks if a `DateTime` is part of the time interval.
+* `#intersect?` checks if two time intervals overlap.
+* `#intersection` returns the intersected time interval if the two intervals intersect.
+* `#disjoint?` checks if two time intervals don't intersect.
+* `#subset?` checks if a time interval is included in another one.
+* `#superset?` checks if a time interval is included in another one.
+* `#first` is the lower bound.
+* `#last` is the upper bound.
+* `#size` is the total amount of seconds.
+
+
+You can convert a time interval into a string with `#to_s` or into a float via
+`#to_f`.