Where is Time.advance documented?

Question

Looking around on the Web I found that the Ruby Time class has Time#advance. Where is this documented? I saw no mention of it in the Ruby API docs here.

The search function for the API docs indicated that there is no method called "advance" anywhere.

Nonetheless, in IRB...

>> t = Time.now
=> Thu Mar 05 16:08:57 -0800 2009
>> t.advance :months => 1
=> Sun Apr 05 16:08:57 -0700 2009

Another thing that puzzles me... In the docs for the time class, the first thing it says is "Implements the extensions to the Time class that are described in the documentation for the time.rb library."

Do they mean "the time.rb library implements extensions to this class?"

I thought maybe that's where Time#advance came from but all I found was this.

Answer 1

This, with a lot of other extensions to Time, is part of ActiveSupport, which you probably acquired as part of Rails, although the library is thoroughly useable in its own right.

See the documentation

Answer 2

Doesn't look like advance is a core part of the language, hence its lack of documentation. Looks to be a part of a package that's included with rails, the ActiveSupport module.

Documentation is here: http://rails.rubyonrails.org/classes/ActiveSupport/CoreExtensions/Time/Calculations.html#M001109

Answer 3

It's actually in the ActiveSupport::CoreExtensions::Numeric::Time module.

This is one of my gripes with Ruby - it's impossible to find comprehensive documentation for every method an object has, because the method list changes depending on the context. Powerful, yet irritating.

I'm working on a large Rails app that I did not write originally, and once in a while I google a method I don't recognize for a few minutes before realizing...yep, the previous developer defined it in /lib.

Answer 4

This is an answer your second question.

In the docs for the time class, the first thing it says is "Implements the extensions to the Time class that are described in the documentation for the time.rb library."

Do they mean "the time.rb library implements extensions to this class?"

The Time class is opened in many places:

• in Ruby:
  • time.c
  • lib/date.rb
  • lib/rss/rss.rb
  • lib/time.rb
  • lib/yaml/rubytypes.rb
• in Rails:
  • activesupport/lib/active-support/core-ext/numeric/time.rb

APIdock distinguishes between Ruby and Rails, but "combines" the RDocs of a single element when it's defined multiple times in one project. If there are multiple RDocs for a single element (like the Time class in this case), only one of them is shown, and the others are not. This can be confusing.

This text:

Implements the extensions to the Time class that are described in the documentation for the time.rb library.

... comes from lib/time.rb. It's from the standard library and extends the core library's Time class (that is defined in time.c). So, you need to call...

require 'time'

... to use the extensions defined in time.rb. Otherwise you can only use the methods defined in time.c.