From d52cf1013f974ed00502caac624e8094b777385d Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sun, 27 Mar 2022 14:45:14 -0500 Subject: [PATCH] [DOC] Enhanced RDoc for String (#5724) Treats: #scan #hex #oct #crypt #ord #sum --- doc/string/ord.rdoc | 6 +++ doc/string/sum.rdoc | 11 +++++ string.c | 103 ++++++++++++++++++++++++-------------------- 3 files changed, 74 insertions(+), 46 deletions(-) create mode 100644 doc/string/ord.rdoc create mode 100644 doc/string/sum.rdoc diff --git a/doc/string/ord.rdoc b/doc/string/ord.rdoc new file mode 100644 index 0000000000..d586363d44 --- /dev/null +++ b/doc/string/ord.rdoc @@ -0,0 +1,6 @@ +Returns the integer ordinal of the first character of +self+: + + 'h'.ord # => 104 + 'hello'.ord # => 104 + 'тест'.ord # => 1090 + 'こんにちは'.ord # => 12371 diff --git a/doc/string/sum.rdoc b/doc/string/sum.rdoc new file mode 100644 index 0000000000..5de24e6402 --- /dev/null +++ b/doc/string/sum.rdoc @@ -0,0 +1,11 @@ +Returns a basic +n+-bit checksum of the characters in +self+; +the checksum is the sum of the binary value of each byte in +self+, +modulo 2**n - 1: + + 'hello'.sum # => 532 + 'hello'.sum(4) # => 4 + 'hello'.sum(64) # => 532 + 'тест'.sum # => 1405 + 'こんにちは'.sum # => 2582 + +This is not a particularly strong checksum. diff --git a/string.c b/string.c index 84a9d5f9ed..0917f56f35 100644 --- a/string.c +++ b/string.c @@ -9958,33 +9958,41 @@ scan_once(VALUE str, VALUE pat, long *start, int set_backref_str) /* * call-seq: - * str.scan(pattern) -> array - * str.scan(pattern) {|match, ...| block } -> str + * scan(string_or_regexp) -> array + * scan(string_or_regexp) {|matches| ... } -> self * - * Both forms iterate through str, matching the pattern (which may be a - * Regexp or a String). For each match, a result is - * generated and either added to the result array or passed to the block. If - * the pattern contains no groups, each individual result consists of the - * matched string, $&. If the pattern contains groups, each - * individual result is itself an array containing one entry per group. + * Matches a pattern against +self+; the pattern is: * - * a = "cruel world" - * a.scan(/\w+/) #=> ["cruel", "world"] - * a.scan(/.../) #=> ["cru", "el ", "wor"] - * a.scan(/(...)/) #=> [["cru"], ["el "], ["wor"]] - * a.scan(/(..)(..)/) #=> [["cr", "ue"], ["l ", "wo"]] + * - +string_or_regexp+ itself, if it is a Regexp. + * - Regexp.quote(string_or_regexp), if +string_or_regexp+ is a string. * - * And the block form: + * Iterates through +self+, generating a collection of matching results: * - * a.scan(/\w+/) {|w| print "<<#{w}>> " } - * print "\n" - * a.scan(/(.)(.)/) {|x,y| print y, x } - * print "\n" + * - If the pattern contains no groups, each result is the + * matched string, $&. + * - If the pattern contains groups, each result is an array + * containing one entry per group. * - * produces: + * With no block given, returns an array of the results: + * + * s = 'cruel world' + * s.scan(/\w+/) # => ["cruel", "world"] + * s.scan(/.../) # => ["cru", "el ", "wor"] + * s.scan(/(...)/) # => [["cru"], ["el "], ["wor"]] + * s.scan(/(..)(..)/) # => [["cr", "ue"], ["l ", "wo"]] + * + * With a block given, calls the block with each result; returns +self+: + * + * s.scan(/\w+/) {|w| print "<<#{w}>> " } + * print "\n" + * s.scan(/(.)(.)/) {|x,y| print y, x } + * print "\n" + * + * Output: * * <> <> * rceu lowlr + * */ static VALUE @@ -10023,16 +10031,20 @@ rb_str_scan(VALUE str, VALUE pat) /* * call-seq: - * str.hex -> integer + * hex -> integer * - * Treats leading characters from str as a string of hexadecimal digits + * Interprets the leading substring of +self+ as a string of hexadecimal digits * (with an optional sign and an optional 0x) and returns the - * corresponding number. Zero is returned on error. + * corresponding number; + * returns zero if there is no such leading substring: + * + * '0x0a'.hex # => 10 + * '-1234'.hex # => -4660 + * '0'.hex # => 0 + * 'non-numeric'.hex # => 0 + * + * Related: String#oct. * - * "0x0a".hex #=> 10 - * "-1234".hex #=> -4660 - * "0".hex #=> 0 - * "wombat".hex #=> 0 */ static VALUE @@ -10044,19 +10056,22 @@ rb_str_hex(VALUE str) /* * call-seq: - * str.oct -> integer + * oct -> integer * - * Treats leading characters of str as a string of octal digits (with an - * optional sign) and returns the corresponding number. Returns 0 if the - * conversion fails. + * Interprets the leading substring of +self+ as a string of octal digits + * (with an optional sign) and returns the corresponding number; + * returns zero if there is no such leading substring: * - * "123".oct #=> 83 - * "-377".oct #=> -255 - * "bad".oct #=> 0 - * "0377bad".oct #=> 255 + * '123'.oct # => 83 + '-377'.oct # => -255 + '0377non-numeric'.oct # => 255 + 'non-numeric'.oct # => 0 + * + * If +self+ starts with 0, radix indicators are honored; + * see Kernel#Integer. + * + * Related: String#hex. * - * If +str+ starts with 0, radix indicators are honored. - * See Kernel#Integer. */ static VALUE @@ -10081,7 +10096,7 @@ crypt_mutex_initialize(void) /* * call-seq: - * str.crypt(salt_str) -> new_str + * crypt(salt_str) -> new_string * * Returns the string generated by calling crypt(3) * standard library function with str and @@ -10198,11 +10213,10 @@ rb_str_crypt(VALUE str, VALUE salt) /* * call-seq: - * str.ord -> integer + * ord -> integer * - * Returns the Integer ordinal of a one-character string. + * :include: doc/string/ord.rdoc * - * "a".ord #=> 97 */ static VALUE @@ -10215,13 +10229,10 @@ rb_str_ord(VALUE s) } /* * call-seq: - * str.sum(n=16) -> integer + * sum(n = 16) -> integer + * + * :include: doc/string/sum.rdoc * - * Returns a basic n-bit checksum of the characters in str, - * where n is the optional Integer parameter, defaulting - * to 16. The result is simply the sum of the binary value of each byte in - * str modulo 2**n - 1. This is not a particularly good - * checksum. */ static VALUE