Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOC] Enhanced RDoc #63

Merged
merged 4 commits into from
Jul 12, 2022
Merged

[DOC] Enhanced RDoc #63

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
705de15
Enhanced RDoc
BurdetteLamar Jul 11, 2022
5d1750e
Enhanced RDoc
BurdetteLamar Jul 11, 2022
a4360b5
Update ext/date/date_core.c
BurdetteLamar Jul 11, 2022
a5306b3
Update ext/date/date_core.c
BurdetteLamar Jul 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 77 additions & 63 deletions ext/date/date_core.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6311,10 +6311,15 @@ d_lite_prev_day(int argc, VALUE *argv, VALUE self)

/*
* call-seq:
* d.succ -> date
* d.next -> date
* d.next -> new_date
*
* Returns a date object denoting the following day.
* Returns a new \Date object representing the following day:
*
* d = Date.today
* d.to_s # => "2022-07-11"
* d.next.to_s # => "2022-07-12"
*
* Date#succ is an alias for Date#next.
*/
static VALUE
d_lite_next(VALUE self)
Expand All @@ -6324,26 +6329,30 @@ d_lite_next(VALUE self)

/*
* call-seq:
* d >> n -> date
* d >> n -> new_date
*
* Returns a date object pointing +n+ months after self.
* The argument +n+ should be a numeric value.
* Returns a new \Date object representing the date
* +n+ months later; +n+ should be numeric:
peterzhu2118 marked this conversation as resolved.
Show resolved Hide resolved
*
* Date.new(2001,2,3) >> 1 #=> #<Date: 2001-03-03 ...>
* Date.new(2001,2,3) >> -2 #=> #<Date: 2000-12-03 ...>
* (Date.new(2001, 2, 3) >> 1).to_s # => "2001-03-03"
* (Date.new(2001, 2, 3) >> -2).to_s # => "2000-12-03"
*
* When the same day does not exist for the corresponding month,
* the last day of the month is used instead:
* When the same day does not exist for the new month,
* the last day of that month is used instead:
*
* Date.new(2001,1,28) >> 1 #=> #<Date: 2001-02-28 ...>
* Date.new(2001,1,31) >> 1 #=> #<Date: 2001-02-28 ...>
* (Date.new(2001, 1, 31) >> 1).to_s # => "2001-02-28"
* (Date.new(2001, 1, 31) >> -4).to_s # => "2000-09-30"
*
* This also results in the following, possibly unexpected, behavior:
* This results in the following, possibly unexpected, behaviors:
*
* Date.new(2001,1,31) >> 2 #=> #<Date: 2001-03-31 ...>
* Date.new(2001,1,31) >> 1 >> 1 #=> #<Date: 2001-03-28 ...>
* d0 = Date.new(2001, 1, 31)
* d1 = d0 >> 1 # => #<Date: 2001-02-28)>
peterzhu2118 marked this conversation as resolved.
Show resolved Hide resolved
* d2 = d1 >> 1 # => #<Date: 2001-03-28>
*
* d0 = Date.new(2001, 1, 31)
* d1 = d0 >> 1 # => #<Date: 2001-02-28>
* d2 = d1 >> -1 # => #<Date: 2001-01-28>
*
* Date.new(2001,1,31) >> 1 >> -1 #=> #<Date: 2001-01-28 ...>
*/
static VALUE
d_lite_rshift(VALUE self, VALUE other)
Expand Down Expand Up @@ -6388,24 +6397,28 @@ d_lite_rshift(VALUE self, VALUE other)
* call-seq:
* d << n -> date
*
* Returns a date object pointing +n+ months before self.
* The argument +n+ should be a numeric value.
* Returns a new \Date object representing the date
* +n+ months earlier; +n+ should be numeric:
BurdetteLamar marked this conversation as resolved.
Show resolved Hide resolved
*
* (Date.new(2001 ,2, 3) << 1).to_s # => "2001-01-03"
* (Date.new(2001 ,2, 3) << -2).to_s # => "2001-04-03"
peterzhu2118 marked this conversation as resolved.
Show resolved Hide resolved
*
* Date.new(2001,2,3) << 1 #=> #<Date: 2001-01-03 ...>
* Date.new(2001,2,3) << -2 #=> #<Date: 2001-04-03 ...>
* When the same day does not exist for the new month,
* the last day of that month is used instead:
*
* When the same day does not exist for the corresponding month,
* the last day of the month is used instead:
* (Date.new(2001, 3, 31) << 1).to_s # => "2001-02-28"
* (Date.new(2001, 3, 31) << -6).to_s # => "2001-09-30"
*
* Date.new(2001,3,28) << 1 #=> #<Date: 2001-02-28 ...>
* Date.new(2001,3,31) << 1 #=> #<Date: 2001-02-28 ...>
* This results in the following, possibly unexpected, behaviors:
*
* This also results in the following, possibly unexpected, behavior:
* d0 = Date.new(2001, 3, 31)
* d1 = d0 << 2 # => #<Date: 2001-01-31>
* d2 = d0 << 1 << 1 # => #<Date: 2001-01-28>
peterzhu2118 marked this conversation as resolved.
Show resolved Hide resolved
*
* Date.new(2001,3,31) << 2 #=> #<Date: 2001-01-31 ...>
* Date.new(2001,3,31) << 1 << 1 #=> #<Date: 2001-01-28 ...>
* d0 = Date.new(2001, 3, 31)
* d1 = d0 << 1 # => #<Date: 2001-02-28 (>
peterzhu2118 marked this conversation as resolved.
Show resolved Hide resolved
* d2 = d1 << -1 # => #<Date: 2001-03-28>
*
* Date.new(2001,3,31) << 1 << -1 #=> #<Date: 2001-03-28 ...>
*/
static VALUE
d_lite_lshift(VALUE self, VALUE other)
Expand All @@ -6416,11 +6429,9 @@ d_lite_lshift(VALUE self, VALUE other)

/*
* call-seq:
* d.next_month([n=1]) -> date
* next_month(n = 1) -> new_date
*
* This method is equivalent to d >> n.
*
* See Date#>> for examples.
* Equivalent to #>> with argument +n+.
*/
static VALUE
d_lite_next_month(int argc, VALUE *argv, VALUE self)
Expand All @@ -6435,11 +6446,9 @@ d_lite_next_month(int argc, VALUE *argv, VALUE self)

/*
* call-seq:
* d.prev_month([n=1]) -> date
*
* This method is equivalent to d << n.
* prev_month(n = 1) -> new_date
*
* See Date#<< for examples.
* Equivalent to #<< with argument +n+.
*/
static VALUE
d_lite_prev_month(int argc, VALUE *argv, VALUE self)
Expand All @@ -6454,15 +6463,9 @@ d_lite_prev_month(int argc, VALUE *argv, VALUE self)

/*
* call-seq:
* d.next_year([n=1]) -> date
*
* This method is equivalent to d >> (n * 12).
*
* Date.new(2001,2,3).next_year #=> #<Date: 2002-02-03 ...>
* Date.new(2008,2,29).next_year #=> #<Date: 2009-02-28 ...>
* Date.new(2008,2,29).next_year(4) #=> #<Date: 2012-02-29 ...>
* next_year(n = 1) -> new_date
*
* See also Date#>>.
* Equivalent to #>> with argument <tt>n * 12</tt>.
*/
static VALUE
d_lite_next_year(int argc, VALUE *argv, VALUE self)
Expand All @@ -6477,15 +6480,9 @@ d_lite_next_year(int argc, VALUE *argv, VALUE self)

/*
* call-seq:
* d.prev_year([n=1]) -> date
* prev_year(n = 1) -> new_date
*
* This method is equivalent to d << (n * 12).
*
* Date.new(2001,2,3).prev_year #=> #<Date: 2000-02-03 ...>
* Date.new(2008,2,29).prev_year #=> #<Date: 2007-02-28 ...>
* Date.new(2008,2,29).prev_year(4) #=> #<Date: 2004-02-29 ...>
*
* See also Date#<<.
* Equivalent to #<< with argument <tt>n * 12</tt>.
*/
static VALUE
d_lite_prev_year(int argc, VALUE *argv, VALUE self)
Expand All @@ -6502,14 +6499,33 @@ static VALUE d_lite_cmp(VALUE, VALUE);

/*
* call-seq:
* d.step(limit[, step=1]) -> enumerator
* d.step(limit[, step=1]){|date| ...} -> self
* step(limit, step = 1){|date| ... } -> self
*
* Calls the block with specified dates;
* returns +self+.
*
* - The first +date+ is +self+.
* - Each successive +date+ is <tt>date + step</tt>,
* where +step+ is the numeric step size in days.
* - The last date is the last one that is before or equal to +limit+,
* which should be a \Date object.
*
* Example:
*
* limit = Date.new(2001, 12, 31)
* Date.new(2001).step(limit){|date| p date.to_s if date.mday == 31 }
*
* Output:
*
* Iterates evaluation of the given block, which takes a date object.
* The limit should be a date object.
* "2001-01-31"
* "2001-03-31"
* "2001-05-31"
* "2001-07-31"
* "2001-08-31"
* "2001-10-31"
* "2001-12-31"
*
* Date.new(2001).step(Date.new(2001,-1,-1)).select{|d| d.sunday?}.size
* #=> 52
* Returns an Enumerator if no block is given.
*/
static VALUE
d_lite_step(int argc, VALUE *argv, VALUE self)
Expand Down Expand Up @@ -6552,10 +6568,9 @@ d_lite_step(int argc, VALUE *argv, VALUE self)

/*
* call-seq:
* d.upto(max) -> enumerator
* d.upto(max){|date| ...} -> self
* upto(max){|date| ... } -> self
*
* This method is equivalent to step(max, 1){|date| ...}.
* Equivalent to #step with arguments +max+ and +1+.
*/
static VALUE
d_lite_upto(VALUE self, VALUE max)
Expand All @@ -6574,8 +6589,7 @@ d_lite_upto(VALUE self, VALUE max)

/*
* call-seq:
* d.downto(min) -> enumerator
* d.downto(min){|date| ...} -> self
* downto(min){|date| ... } -> self
*
* This method is equivalent to step(min, -1){|date| ...}.
peterzhu2118 marked this conversation as resolved.
Show resolved Hide resolved
*/
Expand Down