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