From fc456adc6a62d09b755243b8c8f190934b9965d6 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 13 Nov 2021 14:48:57 -0600 Subject: Enhanced RDoc for Integer (#5099) Treats: #allbits? #anybits? #nobits? #succ #pred #chr` #to_s #+ #- --- numeric.c | 207 +++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 138 insertions(+), 69 deletions(-) (limited to 'numeric.c') diff --git a/numeric.c b/numeric.c index 7a28e32b27..224232f603 100644 --- a/numeric.c +++ b/numeric.c @@ -3338,9 +3338,25 @@ rb_int_even_p(VALUE num) /* * call-seq: - * int.allbits?(mask) -> true or false + * allbits?(mask) -> true or false + * + * Returns +true+ if all bits that are set (=1) in +mask+ + * are also set in +self+; returns +false+ otherwise. + * + * Example values: + * + * 0b1010101 self + * 0b1010100 mask + * 0b1010100 self & mask + * true self.allbits?(mask) + * + * 0b1010100 self + * 0b1010101 mask + * 0b1010100 self & mask + * false self.allbits?(mask) + * + * Related: Integer#anybits?, Integer#nobits?. * - * Returns +true+ if all bits of +int+ & +mask+ are 1. */ static VALUE @@ -3352,9 +3368,25 @@ int_allbits_p(VALUE num, VALUE mask) /* * call-seq: - * int.anybits?(mask) -> true or false + * anybits?(mask) -> true or false + * + * Returns +true+ if any bit that is set (=1) in +mask+ + * is also set in +self+; returns +false+ otherwise. + * + * Example values: + * + * 0b10000010 self + * 0b11111111 mask + * 0b10000010 self & mask + * true self.anybits?(mask) + * + * 0b00000000 self + * 0b11111111 mask + * 0b00000000 self & mask + * false self.anybits?(mask) + * + * Related: Integer#allbits?, Integer#nobits?. * - * Returns +true+ if any bits of +int+ & +mask+ are 1. */ static VALUE @@ -3366,9 +3398,25 @@ int_anybits_p(VALUE num, VALUE mask) /* * call-seq: - * int.nobits?(mask) -> true or false + * nobits?(mask) -> true or false + * + * Returns +true+ if no bit that is set (=1) in +mask+ + * is also set in +self+; returns +false+ otherwise. + * + * Example values: + * + * 0b11110000 self + * 0b00001111 mask + * 0b00000000 self & mask + * true self.nobits?(mask) + * + * 0b00000001 self + * 0b11111111 mask + * 0b00000001 self & mask + * false self.nobits?(mask) + * + * Related: Integer#allbits?, Integer#anybits?. * - * Returns +true+ if no bits of +int+ & +mask+ are 1. */ static VALUE @@ -3379,19 +3427,17 @@ int_nobits_p(VALUE num, VALUE mask) } /* - * Document-method: Integer#succ - * Document-method: Integer#next * call-seq: - * int.next -> integer - * int.succ -> integer + * succ -> next_integer * - * Returns the successor of +int+, - * i.e. the Integer equal to int+1. + * Returns the successor integer of +self+ (equivalent to self + 1): * - * 1.next #=> 2 - * (-1).next #=> 0 - * 1.succ #=> 2 - * (-1).succ #=> 0 + * 1.succ #=> 2 + * -1.succ #=> 0 + * + * Integer#next is an alias for Integer#succ. + * + * Related: Integer#pred (predecessor value). */ VALUE @@ -3411,13 +3457,15 @@ rb_int_succ(VALUE num) /* * call-seq: - * int.pred -> integer + * pred -> next_integer + * + * Returns the predecessor of +self+ (equivalent to self - 1): + * + * 1.pred #=> 0 + * -1.pred #=> -2 * - * Returns the predecessor of +int+, - * i.e. the Integer equal to int-1. + * Related: Integer#succ (successor value). * - * 1.pred #=> 0 - * (-1).pred #=> -2 */ static VALUE @@ -3435,19 +3483,6 @@ rb_int_pred(VALUE num) #define int_pred rb_int_pred -/* - * Document-method: Integer#chr - * call-seq: - * int.chr([encoding]) -> string - * - * Returns a string containing the character represented by the +int+'s value - * according to +encoding+. - * - * 65.chr #=> "A" - * 230.chr #=> "\xE6" - * 255.chr(Encoding::UTF_8) #=> "\u00FF" - */ - VALUE rb_enc_uint_chr(unsigned int code, rb_encoding *enc) { @@ -3470,6 +3505,24 @@ rb_enc_uint_chr(unsigned int code, rb_encoding *enc) return str; } +/* + * call-seq: + * chr(encoding = Encoding.default_internal) -> string + * + * Returns a 1-character string containing the character + * represented by the value of +self+, according to the given +encoding+. + * + * 65.chr # => "A" + * 0..chr # => "\x00" + * 255.chr # => "\xFF" + * 255.chr(Encoding::UTF_8) # => "ΓΏ" + * + * Raises an exception if +self+ is negative. + * + * Related: Integer#ord. + * + */ + static VALUE int_chr(int argc, VALUE *argv, VALUE num) { @@ -3535,23 +3588,6 @@ rb_int_uminus(VALUE num) } } -/* - * Document-method: Integer#to_s - * call-seq: - * int.to_s(base=10) -> string - * - * Returns a string containing the place-value representation of +int+ - * with radix +base+ (between 2 and 36). - * - * 12345.to_s #=> "12345" - * 12345.to_s(2) #=> "11000000111001" - * 12345.to_s(8) #=> "30071" - * 12345.to_s(10) #=> "12345" - * 12345.to_s(16) #=> "3039" - * 12345.to_s(36) #=> "9ix" - * 78546939656932.to_s(36) #=> "rubyrules" - */ - VALUE rb_fix2str(VALUE x, int base) { @@ -3594,6 +3630,27 @@ rb_fix2str(VALUE x, int base) return rb_usascii_str_new(b, e - b); } +/* + * call-seq: + * to_s(base = 10) -> string + * + * Returns a string containing the place-value representation of +self+ + * in radix +base+ (in 2..36). + * + * 12345.to_s # => "12345" + * 12345.to_s(2) # => "11000000111001" + * 12345.to_s(8) # => "30071" + * 12345.to_s(10) # => "12345" + * 12345.to_s(16) # => "3039" + * 12345.to_s(36) # => "9ix" + * 78546939656932.to_s(36) # => "rubyrules" + * + * Raises an exception if +base+ is out of range. + * + * Integer#inspect is an alias for Integer#to_s. + * + */ + static VALUE int_to_s(int argc, VALUE *argv, VALUE x) { @@ -3619,15 +3676,6 @@ rb_int2str(VALUE x, int base) return rb_any_to_s(x); } -/* - * Document-method: Integer#+ - * call-seq: - * int + numeric -> numeric_result - * - * Performs addition: the class of the resulting object depends on - * the class of +numeric+. - */ - static VALUE fix_plus(VALUE x, VALUE y) { @@ -3654,6 +3702,21 @@ rb_fix_plus(VALUE x, VALUE y) return fix_plus(x, y); } +/* + * call-seq: + * self + numeric -> numeric + * + * Performs addition: + * + * 2 + 2 # => 4 + * -2 + 2 # => 0 + * -2 + -2 # => -4 + * 2 + 2.0 # => 4.0 + * 2 + Rational(2, 1) # => (4/1) + * 2 + Complex(2, 0) # => (4+0i) + * + */ + VALUE rb_int_plus(VALUE x, VALUE y) { @@ -3666,15 +3729,6 @@ rb_int_plus(VALUE x, VALUE y) return rb_num_coerce_bin(x, y, '+'); } -/* - * Document-method: Integer#- - * call-seq: - * int - numeric -> numeric_result - * - * Performs subtraction: the class of the resulting object depends on - * the class of +numeric+. - */ - static VALUE fix_minus(VALUE x, VALUE y) { @@ -3693,6 +3747,21 @@ fix_minus(VALUE x, VALUE y) } } +/* + * call-seq: + * int - numeric -> numeric + * + * Performs subtraction: + * + * 4 - 2 # => 2 + * -4 - 2 # => -6 + * -4 - -2 # => -2 + * 4 - 2.0 # => 2.0 + * 4 - Rational(2, 1) # => (2/1) + * 4 - Complex(2, 0) # => (2+0i) + * + */ + VALUE rb_int_minus(VALUE x, VALUE y) { -- cgit v1.2.1