Module: NaturalTime

Defined in:
lib/natural_time.rb,
lib/natural_time/version.rb

Overview

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"

Constant Summary collapse

VERSION = 
"0.4.1"

Class Method Summary collapse

Class Method Details

.distance(duration, precision: nil) ⇒ String

Return a natural-language representation of a distance in time, relative to now.

Examples:

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"

Parameters:

  • duration (Integer) —

    a duration in time

  • precision (Integer) (defaults to: nil) —

    level of precision for the natural-language representation

Returns:

  • (String) 


112
113
114
115
116
117
118
119
 
# File 'lib/natural_time.rb', line 112

def distance(duration, precision: nil)
  if duration < 1
    modifier = "ago"
  else
    modifier = "from now"
  end
  "#{to_sentence(duration, precision: precision)} #{modifier}"
end

.natural_time(duration, precision: nil) ⇒ String

Return a natural-language representation of a duration in time.

Examples:

NaturalTime.natural_time(65)         #=> "1 minute, 5 seconds"

NaturalTime.natural_time(120)        #=> "2 minutes"

NaturalTime.natural_time(10000)      #=> "2 hours, 46 minutes, 40 seconds"

Parameters:

  • duration (Integer) —

    a duration in time

  • precision (Integer) (defaults to: nil) —

    level of precision for the natural-language representation

Returns:

  • (String) 


84
85
86
 
# File 'lib/natural_time.rb', line 84

def natural_time(duration, precision: nil)
  to_array(duration, precision: precision).join(", ")
end

.to_array(duration, precision: nil) ⇒ Array<String>

Return the natural-language elements of a duration in an array.

Examples:

NaturalTime.to_array(65)                #=> ["1 minutes", "5 seconds"]

NaturalTime.to_array(120)               #=> ["2 minutes"]

Parameters:

  • duration (Integer) —

    a duration in time

  • precision (Integer) (defaults to: nil) —

    level of precision for the natural-language representation

Returns:

  • (Array<String>) 


171
172
173
 
# File 'lib/natural_time.rb', line 171

def to_array(duration, precision: nil)
  [elapsed_time(duration, precision: precision)].flatten
end

.to_sentence(duration, precision: nil) ⇒ String

Return the duration in time in natural-language and formatted like a sentence.

Examples:

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"

Parameters:

  • duration (Integer) —

    a duration in time

  • precision (Integer) (defaults to: nil) —

    level of precision for the natural-language representation

Returns:

  • (String) 


154
155
156
 
# File 'lib/natural_time.rb', line 154

def to_sentence(duration, precision: nil)
  to_array(duration, precision: precision).to_sentence
end

.to_string(duration, precision: nil) ⇒ String

Return a natural-language representation of a duration in time, separating the units with commas but with no "and".

Examples:

NaturalTime.to_s(65)                #=> "1 minute, 5 seconds"

NaturalTime.to_s(10000)             #=> "2 hours, 46 minutes, 40 seconds"

Parameters:

  • duration (Integer) —

    a duration in time

  • precision (Integer) (defaults to: nil) —

    level of precision for the natural-language representation

Returns:

  • (String) 


135
136
137
 
# File 'lib/natural_time.rb', line 135

def to_string(duration, precision: nil)
  natural_time(duration, precision: precision)
end