Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Smart enumeration of lengths of time in natural language
Branch: master
Failed to load latest commit information.
lib ensure array before joining to a string
.document Initial commit to naturaltime.
.ruby-version ruby-version
Gemfile add Gemfile
History.txt Precision and distance functions
LICENSE Initial commit to naturaltime.
README.rdoc Updated Readme
Rakefile Rebuild gemspec
natural_time.gemspec remove comment



NaturalTime outputs a duration in natural language.



The to_sentence method will output the duration in time in natural language and formatted like a sentence.         #=> "1 minute and 5 seconds"        #=> "2 minutes"      #=> "2 hours, 46 minutes, and 40 seconds"


The to_s command will separate the units with commas but with no “and”:                #=> "1 minute, 5 seconds"             #=> "2 hours, 46 minutes, 40 seconds"


NaturalTime instances can also be output to an array with to_a:                #=> ["1 minutes", "5 seconds"]               #=> ["2 minutes"]


NaturalTime can return the amount of time to a specific precision. If all you want is the greatest unit:, :precision => 1).to_sentence     #=> "1 minute", :precision => 1).to_sentence  #=> "2 hours", :precision => 2).to_sentence  #=> "2 hours and 46 minutes"


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 distance method will return a sentence indicating how long ago or in the future is your duration.                      #=> "1 minute and 5 seconds from now"                     #=> "1 minute and 5 seconds ago"

It works with :precision too:, :precision => 1).distance  #=> "2 hours from now", :precision => 2).distance #=> "2 hours and 46 minutes ago"

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2010 Jeff Coleman. See LICENSE for details.

Something went wrong with that request. Please try again.