4

I wanted to create a DateTime instance for the UTC time zone using the answer from this SOF post that uses the method DateTime#new_offset(0). However, I am not able to find its definition in either the DateTime rdoc or the rdoc of its parent class Date. Yet, DateTime indeed has the method defined:

DateTime.method_defined? :new_offset # => true

There must be a good reason why new_offset is not appearing in the rdoc.

Community
  • 1
  • 1
ecbrodie
  • 11,246
  • 21
  • 71
  • 120

2 Answers2

2

Why does DateTime#new_offset not appear in RDoc of DateTime?
Because it is defined in the parent class Date.

Why does Date#new_offset not appear in RDoc of Date?
Because it is a private method in class Date (for obvious reasons, as, a Date-object does not have a Time-portion and, thus, no Timezone) and private methods do not appear in RDoc.
Compare definition in Ruby/ext/date/date_core.c

Why is #new_offset defined in class Date instead of DateTime?
This is the actual question that can only be answered by a Ruby core developer.
I can only make an assumption here:
In the C-definition date_core.c that includes the definitions of both, class Date and class DateTime, two C-structs are defined, SimpleDateData and ComplexDateData, mirroring the Ruby-classes in question, where ComplexDateData contains all fields that SimpleDateData contains. The only reason for the two structs seems to be memory-usage in order to have a Date-object taking up less memory than a DateTime-object. Other then that, all functions are written to work with both structs and have not been duplicated, which makes sense for obvious reasons (eg. code-maintenance), especially as both structs are based on the same logic of how dates are represented internally.
Compare how most functions check the internal data-type with: if (simple_dat_p...
Particularly the function dup_obj_with_new_offset is a C-function that is also used by functions of the (later) Ruby-class Date, eg. method #httpdate, and (probably for this reason) is attributed to class Date.
Compare RDoc for Date#httpdate
Like other functions, d_lite_new_offset relies on duplicating the given object (struct) and, thus, on dup_obj_with_new_offset. For this reason, d_lite_new_offset is potentially also attributed to Date.
Surely, there would have been another way to outline the C file, but the outcome for the Ruby classes would not be different and, I assume, that is why nobody sees a reason to change the current outline.

Why does DateTime#new_offset not appear in RDoc of DateTime?
Returning to the original question, I summarize, that there are two things that I do not understand and, thus, cannot explain: I have no idea why...

  1. the script that creates RDoc for ruby-doc.org is written in a way that does not pick up all public methods of a class independently of how they have been defined. DateTime#new_offset is not the only example of forgotten methods; there a lots of others. In DateTime alone there are a few, eg. #hour, #min, #sec_fraction. All these methods are public methods for DateTime-objects but don't appear in any RDoc...
    Compare definition of DateTime methods
  2. for indexing, there are not at least some method stubs in these classes that help the RDoc script to pick up all public methods.
Andreas Rayo Kniep
  • 5,674
  • 2
  • 30
  • 30
0

It defined in Date class. Here is definition from the sources:

# d.new_offset([offset=0])  ->  date
#  
# Duplicates self and resets its offset.
# 
#    d = DateTime.new(2001,2,3,4,5,6,'-02:00')
#                              #=> #<DateTime: 2001-02-03T04:05:06-02:00 ...>
#    d.new_offset('+09:00')    #=> #<DateTime: 2001-02-03T15:05:06+09:00 ...>
def new_offset(p1 = v1)
    #This is a stub, used for indexing
end
Andrii Furmanets
  • 1,081
  • 2
  • 12
  • 29