natural_time 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f93b0e487a332d71b0a5751d366950478e56275476f405a3747e8fdcfbbb7deb
-  data.tar.gz: 2031102f88c016a6503c41dcc8f5908f18fbe016952df23c7dfa5102150a17b4
+  metadata.gz: c4b40e761d45e9aa1632c1e6569005bf60c1ce6ba4fea1f897740238f70ddf6d
+  data.tar.gz: 42b36e25bcb2392cf293dcb2bdd7d3f77cfcd2cdc8aad56e2718e7187baed5c5
 SHA512:
-  metadata.gz: 79a73e4faab5d6931451851d26d3e82385807c6a0b10632bea5f6f85a6fc3113c5238c3c468575efde37319e9ec22370dda4bdcf015aa980a63bba13b78171b9
-  data.tar.gz: 202a0fd2e3bd54ba7cb2ab6bb51b2fa2025e816bd75ba9e6cafb174620c494b34fd9c56b4fbc60120ae282f1487e078fd1a21d9a599851d9ffa5baba56ec1c20
+  metadata.gz: 5c432a254a76167015c30cf860152e56dc22c077c00b0306749622aabc0001f6721988fa36e51054654b2af7dffc418f4402f6be02cea8d47d954ceaef08c775
+  data.tar.gz: 4ce289e049c3bb9aaf96f19bfc8fc1eaf28ef0ad3417cf7bea9fc813710013370c464f1ec55abae1515ded8faca212e5993756160625f527a12715d10ed776e7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    natural_time (0.3.0)
+    natural_time (0.4.0)
       activesupport (~> 5.1.4)
 
 GEM

data/README.md

@@ -6,59 +6,61 @@ NaturalTime outputs a duration in natural language.
 
 ### Sentence
 
-The <tt>to_sentence</tt> method will output the duration in time in natural language
+The `to_sentence` method will output the duration in time in natural language
 and formatted like a sentence.
 
-    NaturalTime.new(65).to_sentence         #> "1 minute and 5 seconds"
+    NaturalTime.to_sentence(65)         #=> "1 minute and 5 seconds"
 
-    NaturalTime.new(120).to_sentence        #> "2 minutes"
+    NaturalTime.to_sentence(120)        #=> "2 minutes"
 
-    NaturalTime.new(10000).to_sentence      #> "2 hours, 46 minutes, and 40 seconds"
+    NaturalTime.to_sentence(10000)      #=> "2 hours, 46 minutes, and 40 seconds"
 
 ### String
 
-The <tt>to_s</tt> command will separate the units with commas but with no "and":
+The `to_s` command will separate the units with commas but with no "and":
 
-    NaturalTime.new(65).to_s                #> "1 minute, 5 seconds"
+    NaturalTime.to_s(65)                #=> "1 minute, 5 seconds"
 
-    NaturalTime.new(10000).to_s             #> "2 hours, 46 minutes, 40 seconds"
+    NaturalTime.to_s(10000)             #=> "2 hours, 46 minutes, 40 seconds"
 
 ### Array
 
-NaturalTime instances can also be output to an array with <tt>to_a</tt>:
+NaturalTime instances can also be output to an array with `to_array`:
 
-    NaturalTime.new(65).to_a                #> ["1 minutes", "5 seconds"]
+    NaturalTime.to_array(65)                #=> ["1 minutes", "5 seconds"]
 
-    NaturalTime.new(120).to_a               #> ["2 minutes"]
+    NaturalTime.to_array(120)               #=> ["2 minutes"]
 
 ### Precision
 
-NaturalTime can return the amount of time to a specific precision.  If all you want is the greatest unit:
+NaturalTime can return the amount of time to a specific precision. If all you
+want is the greatest unit:
 
-    NaturalTime.new(65, :precision#> 1).to_sentence    #=> "1 minute"
+    NaturalTime.to_sentence(65, precision: 1)    #=> "1 minute"
 
-    NaturalTime.new(10000, :precision#> 1).to_sentence #=> "2 hours"
+    NaturalTime.to_sentence(10000, precision: 1) #=> "2 hours"
 
-    NaturalTime.new(10000, :precision#> 2).to_sentence #=> "2 hours and 46 minutes"
+    NaturalTime.to_sentence(10000, precision: 2) #=> "2 hours and 46 minutes"
 
 ### Distance
 
-If you want to use NaturalTime to show an elapsed time and you don't care if it's in the
-past or the future, use the <tt>natural_time</tt> or <tt>to_sentence</tt> methods, or the
-<tt>to_a</tt> method if you need the units in an array.
+If you want to use NaturalTime to show an elapsed time and you don't care if
+it's in the past or the future, use the `natural_time` or `to_sentence`
+methods, or the `to_a` method if you need the units in an array.
 
-If you're measuring distances that may be in the past or the future, the <tt>distance</tt>
-method will return a sentence indicating how long ago or in the future is your duration.
+If you're measuring distances that may be in the past or the future, the
+`distance` method will return a sentence indicating how long ago or in
+the future is your duration.
 
-    NaturalTime.new(65).distance                      #> "1 minute and 5 seconds from now"
+    NaturalTime.distance(65)                      #=> "1 minute and 5 seconds from now"
 
-    NaturalTime.new(-65).distance                     #> "1 minute and 5 seconds ago"
+    NaturalTime.distance(-65)                     #=> "1 minute and 5 seconds ago"
 
-It works with <tt>:precision</tt> too:
+It works with `:precision` too:
 
-    NaturalTime.new(10000, :precision#> 1).distance #=> "2 hours from now"
+    NaturalTime.distance(10000, precision: 1)     #=> "2 hours from now"
 
-    NaturalTime.new(-10000, :precision#> 2).distance#=> "2 hours and 46 minutes ago"
+    NaturalTime.distance(-10000, precision: 2)    #=> "2 hours and 46 minutes ago"
 
 
 ## Note on Patches/Pull Requests

data/lib/natural_time/version.rb

@@ -1,3 +1,3 @@
-class NaturalTime
-  VERSION = "0.3.0"
+module NaturalTime
+  VERSION = "0.4.0"
 end

data/lib/natural_time.rb

@@ -1,70 +1,206 @@
 require "natural_time/version"
 require 'active_support/core_ext/integer/time'
 
-class NaturalTime
-  attr_accessor :duration, :precision, :past
-
-  UNITS_OF_TIME = [["year", "years"], ["month", "months"], ["week", "weeks"], ["day", "days"], ["hour", "hours"], ["minute", "minutes"]]
+# # NaturalTime
+#
+# NaturalTime outputs a duration in natural language.
+#
+# ## Usage
+#
+# ### Sentence
+#
+# The `to_sentence` method will output the duration in time in natural language
+# and formatted like a sentence.
+#
+#     NaturalTime.to_sentence(65)         #=> "1 minute and 5 seconds"
+#
+#     NaturalTime.to_sentence(120)        #=> "2 minutes"
+#
+#     NaturalTime.to_sentence(10000)      #=> "2 hours, 46 minutes, and 40 seconds"
+#
+# ### String
+#
+# The `to_s` command will separate the units with commas but with no "and":
+#
+#     NaturalTime.to_s(65)                #=> "1 minute, 5 seconds"
+#
+#     NaturalTime.to_s(10000)             #=> "2 hours, 46 minutes, 40 seconds"
+#
+# ### Array
+#
+# NaturalTime instances can also be output to an array with `to_array`:
+#
+#     NaturalTime.to_array(65)                #=> ["1 minutes", "5 seconds"]
+#
+#     NaturalTime.to_array(120)               #=> ["2 minutes"]
+#
+# ### Precision
+#
+# NaturalTime can return the amount of time to a specific precision. If all
+# you want is the greatest unit:
+#
+#     NaturalTime.to_sentence(65, precision: 1)    #=> "1 minute"
+#
+#     NaturalTime.to_sentence(10000, precision: 1) #=> "2 hours"
+#
+#     NaturalTime.to_sentence(10000, precision: 2) #=> "2 hours and 46 minutes"
+#
+# ### Distance
+#
+# If you want to use NaturalTime to show an elapsed time and you don't care if it's in the
+# past or the future, use the `natural_time` or `to_sentence` methods, or the
+# `to_array` method if you need the units in an array.
+#
+# If you're measuring distances that may be in the past or the future, the `distance`
+# method will return a sentence indicating how long ago or in the future is your duration.
+#
+#     NaturalTime.distance(65)                      #=> "1 minute and 5 seconds from now"
+#
+#     NaturalTime.distance(-65)                     #=> "1 minute and 5 seconds ago"
+#
+# It works with `:precision` too:
+#
+#     NaturalTime.distance(10000, precision: 1)     #=> "2 hours from now"
+#
+#     NaturalTime.distance(-10000, precision: 2)    #=> "2 hours and 46 minutes ago"
+#
+module NaturalTime
+  class << self
+    # Return a natural-language representation of a duration in time.
+    #
+    # @param [Integer] duration a duration in time
+    # @param [Integer] precision level of precision for the
+    #   natural-language representation
+    #
+    # @return [String]
+    #
+    # @example
+    #   NaturalTime.to_sentence(65)         #=> "1 minute and 5 seconds"
+    #
+    #   NaturalTime.to_sentence(120)        #=> "2 minutes"
+    #
+    #   NaturalTime.to_sentence(10000)      #=> "2 hours, 46 minutes, and 40 seconds"
+    #
+    def natural_time(duration, precision: nil)
+      to_array(duration, precision: precision).join(", ")
+    end
 
-  def initialize(duration_in_seconds, options={})
-    @precision = options[:precision]
-    duration_in_seconds = duration_in_seconds.to_i
-    @past = duration_in_seconds < 1
-    @duration = duration_in_seconds.abs
-    elapsed_time = elapsed_time(duration_in_seconds)
-  end
+    # Return a natural-language representation of a distance in time, relative
+    # to now.
+    #
+    # @param [Integer] duration a duration in time
+    # @param [Integer] precision level of precision for the
+    #   natural-language representation
+    #
+    # @return [String]
+    #
+    # @example
+    #   If you're measuring distances that may be in the past or the future, the `distance`
+    #   method will return a sentence indicating how long ago or in the future is your duration.
+    #
+    #   NaturalTime.distance(65)                      #=> "1 minute and 5 seconds from now"
+    #
+    #   NaturalTime.distance(-65)                     #=> "1 minute and 5 seconds ago"
+    #
+    # @example
+    #   It works with `:precision` too:
+    #
+    #   NaturalTime.distance(10000, precision: 1)     #=> "2 hours from now"
+    #
+    #   NaturalTime.distance(-10000, precision: 2)    #=> "2 hours and 46 minutes ago"
+    #
+    def distance(duration, precision: nil)
+      if duration < 1
+        modifier = "ago"
+      else
+        modifier = "from now"
+      end
+      "#{to_sentence(duration, precision: precision)} #{modifier}"
+    end
 
-  def to_sentence
-    to_array.to_sentence
-  end
+    # Return a natural-language representation of a duration in time, separating the
+    # units with commas but with no "and".
+    #
+    # @param [Integer] duration a duration in time
+    # @param [Integer] precision level of precision for the
+    #   natural-language representation
+    #
+    # @return [String]
+    #
+    # @example
+    #   NaturalTime.to_s(65)                #=> "1 minute, 5 seconds"
+    #
+    #   NaturalTime.to_s(10000)             #=> "2 hours, 46 minutes, 40 seconds"
+    #
+    def to_string(duration, precision: nil)
+      natural_time(duration, precision: precision)
+    end
 
-  def natural_time
-    to_array.join(", ")
-  end
+    # Return the duration in time in natural-language and formatted like a sentence.
+    #
+    # @param [Integer] duration a duration in time
+    # @param [Integer] precision level of precision for the
+    #   natural-language representation
+    #
+    # @return [String]
+    #
+    # @example
+    #   NaturalTime.to_sentence(65)         #=> "1 minute and 5 seconds"
+    #
+    #   NaturalTime.to_sentence(120)        #=> "2 minutes"
+    #
+    #   NaturalTime.to_sentence(10000)      #=> "2 hours, 46 minutes, and 40 seconds"
+    #
+    def to_sentence(duration, precision: nil)
+      to_array(duration, precision: precision).to_sentence
+    end
 
-  def to_s
-    natural_time
-  end
+    # Return the natural-language elements of a duration in an array.
+    #
+    # @param [Integer] duration a duration in time
+    # @param [Integer] precision level of precision for the
+    #   natural-language representation
+    #
+    # @return [Array<String>]
+    #
+    # @example
+    #   NaturalTime.to_array(65)                #=> ["1 minutes", "5 seconds"]
+    #
+    #   NaturalTime.to_array(120)               #=> ["2 minutes"]
+    #
+    def to_array(duration, precision: nil)
+      [elapsed_time(duration, precision: precision)].flatten
+    end
 
-  def to_a
-    [elapsed_time(duration)].flatten
-  end
+    private
 
-  def to_array
-    to_a
-  end
+    UNITS_OF_TIME = [["year", "years"], ["month", "months"], ["week", "weeks"], ["day", "days"], ["hour", "hours"], ["minute", "minutes"]]
 
-  def distance
-    if past
-      modifier = "ago"
-    else
-      modifier = "from now"
-    end
-    "#{to_sentence} #{modifier}"
-  end
+    def elapsed_time(duration, precision: nil)
+      duration = duration.to_i.abs
 
-  def elapsed_time(duration_in_seconds)
-    return "0 seconds" if duration_in_seconds <= 0
+      return "0 seconds" if duration <= 0
 
-    elapsed_time = []
+      elapsed_time = []
 
-    seconds_left = duration_in_seconds
+      seconds_left = duration
 
-    UNITS_OF_TIME.each do |period|
-      amount = (seconds_left / 1.send(period.first)).to_i
-      str = amount == 1 ? period[0] : period[1]
-      elapsed_time << "#{amount} #{str}" if amount > 0
-      seconds_left = seconds_left % 1.send(period.first)
-    end
+      UNITS_OF_TIME.each do |period|
+        amount = (seconds_left / 1.send(period.first)).to_i
+        str = amount == 1 ? period[0] : period[1]
+        elapsed_time << "#{amount} #{str}" if amount > 0
+        seconds_left = seconds_left % 1.send(period.first)
+      end
 
-    seconds = seconds_left % 1.minute
-    str = seconds == 1 ? "second" : "seconds"
-    elapsed_time << "#{seconds.to_i} #{str}" unless (seconds == 0 && elapsed_time.compact.length > 0)
+      seconds = seconds_left % 1.minute
+      str = seconds == 1 ? "second" : "seconds"
+      elapsed_time << "#{seconds.to_i} #{str}" unless (seconds == 0 && elapsed_time.compact.length > 0)
 
-    if precision
-      elapsed_time.compact.first(precision)
-    else
-      elapsed_time.compact
+      if precision
+        elapsed_time.compact.first(precision)
+      else
+        elapsed_time.compact
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: natural_time
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Isaac Priestley