From a8a9e74189b47db9c78557855a171f0c72c97544 Mon Sep 17 00:00:00 2001
From: Bart de Water <bartdewater@gmail.com>
Date: Wed, 21 Mar 2018 11:47:41 -0400
Subject: [PATCH] Add ISO8601 string parsing comparison for `Time` and `Date`

Unless you're dealing with historic times, you should avoid using `DateTime` as outlined in the Ruby docs:
https://ruby-doc.org/stdlib-2.3.0/libdoc/date/rdoc/DateTime.html#class-DateTime-label-When+should+you+use+DateTime+and+when+should+you+use+Time-3F
---
 README.md                     | 43 +++++++++++++++++++++++++++++++++++
 code/date/iso8601-vs-parse.rb | 18 +++++++++++++++
 code/time/iso8601-vs-parse.rb | 18 +++++++++++++++
 3 files changed, 79 insertions(+)
 create mode 100644 code/date/iso8601-vs-parse.rb
 create mode 100644 code/time/iso8601-vs-parse.rb

diff --git a/README.md b/README.md
index d659822..b2d7e47 100644
--- a/README.md
+++ b/README.md
@@ -46,10 +46,12 @@ Idioms
 
 - [General](#general)
 - [Array](#array)
+- [Date](#date)
 - [Enumerable](#enumerable)
 - [Hash](#hash)
 - [Proc & Block](#proc--block)
 - [String](#string)
+- [Time](#time)
 - [Range](#range)
 
 ### General
@@ -629,6 +631,27 @@ Comparison:
         inject block:    14063.1 i/s - 1.35x slower
 ```
 
+### Date
+
+##### `Date.iso8601` vs `Date.parse` [code](code/date/iso8601-vs-parse.rb)
+
+When expecting well-formatted data from e.g. an API, `iso8601` is faster and will raise an `ArgumentError` on malformed input.
+
+```
+$ ruby -v code/date/iso8601-vs-parse.rb
+ruby 2.4.3p205 (2017-12-14 revision 61247) [x86_64-darwin17]
+Warming up --------------------------------------
+        Date.iso8601    28.880k i/100ms
+          Date.parse    15.805k i/100ms
+Calculating -------------------------------------
+        Date.iso8601    328.035k (± 4.7%) i/s -      1.646M in   5.029287s
+          Date.parse    175.546k (± 3.8%) i/s -    885.080k in   5.049444s
+
+Comparison:
+        Date.iso8601:   328035.3 i/s
+          Date.parse:   175545.9 i/s - 1.87x  slower
+```
+
 ### Hash
 
 ##### `Hash#[]` vs `Hash#fetch` [code](code/hash/bracket-vs-fetch.rb)
@@ -1193,6 +1216,26 @@ Comparison:
  String#gsub/regex+/:    14668.1 i/s - 25.42x  slower
 ```
 
+### Time
+
+##### `Time.iso8601` vs `Time.parse` [code](code/time/iso8601-vs-parse.rb)
+
+When expecting well-formatted data from e.g. an API, `iso8601` is faster and will raise an `ArgumentError` on malformed input.
+
+```
+$ ruby -v code/time/iso8601-vs-parse.rb
+ruby 2.4.3p205 (2017-12-14 revision 61247) [x86_64-darwin17]
+Warming up --------------------------------------
+        Time.iso8601    10.234k i/100ms
+          Time.parse     4.228k i/100ms
+Calculating -------------------------------------
+        Time.iso8601    114.485k (± 3.5%) i/s -    573.104k in   5.012008s
+          Time.parse     43.711k (± 4.1%) i/s -    219.856k in   5.038349s
+
+Comparison:
+        Time.iso8601:   114485.1 i/s
+          Time.parse:    43710.9 i/s - 2.62x  slower
+```
 
 ### Range
 
diff --git a/code/date/iso8601-vs-parse.rb b/code/date/iso8601-vs-parse.rb
new file mode 100644
index 0000000..6d0bce4
--- /dev/null
+++ b/code/date/iso8601-vs-parse.rb
@@ -0,0 +1,18 @@
+require 'benchmark/ips'
+require 'date'
+
+STRING = '2018-03-21'.freeze
+
+def fast
+  Date.iso8601(STRING)
+end
+
+def slow
+  Date.parse(STRING)
+end
+
+Benchmark.ips do |x|
+  x.report('Date.iso8601') { fast }
+  x.report('Date.parse') { slow }
+  x.compare!
+end
diff --git a/code/time/iso8601-vs-parse.rb b/code/time/iso8601-vs-parse.rb
new file mode 100644
index 0000000..6cf7f9f
--- /dev/null
+++ b/code/time/iso8601-vs-parse.rb
@@ -0,0 +1,18 @@
+require 'benchmark/ips'
+require 'time'
+
+STRING = '2018-03-21T11:26:50Z'.freeze
+
+def fast
+  Time.iso8601(STRING)
+end
+
+def slow
+  Time.parse(STRING)
+end
+
+Benchmark.ips do |x|
+  x.report('Time.iso8601') { fast }
+  x.report('Time.parse') { slow }
+  x.compare!
+end