[DOC] Enhanced RDoc for String (#5724)

Treats:

    #scan
    #hex
    #oct
    #crypt
    #ord
    #sum
This commit is contained in:
Burdette Lamar 2022-03-27 14:45:14 -05:00 коммит произвёл GitHub
Родитель ca85f16a7d
Коммит d52cf1013f
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
3 изменённых файлов: 74 добавлений и 46 удалений

6
doc/string/ord.rdoc Normal file
Просмотреть файл

@ -0,0 +1,6 @@
Returns the integer ordinal of the first character of +self+:
'h'.ord # => 104
'hello'.ord # => 104
'тест'.ord # => 1090
'こんにちは'.ord # => 12371

11
doc/string/sum.rdoc Normal file
Просмотреть файл

@ -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 <tt>2**n - 1</tt>:
'hello'.sum # => 532
'hello'.sum(4) # => 4
'hello'.sum(64) # => 532
'тест'.sum # => 1405
'こんにちは'.sum # => 2582
This is not a particularly strong checksum.

103
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 <i>str</i>, 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, <code>$&</code>. 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.
* - <tt>Regexp.quote(string_or_regexp)</tt>, 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, <code>$&</code>.
* - If the pattern contains groups, each result is an array
* containing one entry per group.
*
* <em>produces:</em>
* 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:
*
* <<cruel>> <<world>>
* 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 <i>str</i> 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 <code>0x</code>) 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 <i>str</i> 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 <tt>0</tt>, radix indicators are honored;
* see Kernel#Integer.
*
* Related: String#hex.
*
* If +str+ starts with <code>0</code>, 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 <code>crypt(3)</code>
* standard library function with <code>str</code> 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 <em>n</em>-bit checksum of the characters in <i>str</i>,
* where <em>n</em> is the optional Integer parameter, defaulting
* to 16. The result is simply the sum of the binary value of each byte in
* <i>str</i> modulo <code>2**n - 1</code>. This is not a particularly good
* checksum.
*/
static VALUE