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

Jump to bottom

Enhanced RDoc for String #5227

Merged
merged 2 commits into from Dec 8, 2021
Merged

Enhanced RDoc for String #5227

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
22c04e0
Enhanced RDoc for String
BurdetteLamar Dec 7, 2021
8df4e1f
Enhanced RDoc for String
BurdetteLamar Dec 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
141 changes: 91 additions & 50 deletions string.c
View file
Open in desktop
Expand Up @@ -3480,7 +3480,7 @@ rb_str_concat(VALUE str1, VALUE str2)

/*
* call-seq:
* string.prepend(*other_strings) -> string
* prepend(*other_strings) -> string
*
* Prepends each string in +other_strings+ to +self+ and returns +self+:
*
Expand Down Expand Up @@ -3536,7 +3536,7 @@ rb_str_hash_cmp(VALUE str1, VALUE str2)

/*
* call-seq:
* string.hash -> integer
* hash -> integer
*
* Returns the integer hash value for +self+.
* The value is based on the length, content and encoding of +self+.
Expand Down Expand Up @@ -5756,9 +5756,9 @@ str_gsub(int argc, VALUE *argv, VALUE str, int bang)

/*
* call-seq:
* str.gsub!(pattern, replacement) -> self or nil
* str.gsub!(pattern) {|match| ... } -> self or nil
* str.gsub!(pattern) -> an_enumerator
* gsub!(pattern, replacement) -> self or nil
* gsub!(pattern) {|match| ... } -> self or nil
* gsub!(pattern) -> an_enumerator
*
* Performs the specified substring replacement(s) on +self+;
* returns +self+ if any replacement occurred, +nil+ otherwise.
Expand Down Expand Up @@ -5804,13 +5804,13 @@ rb_str_gsub(int argc, VALUE *argv, VALUE str)

/*
* call-seq:
* str.replace(other_str) -> str
* replace(other_string) -> self
*
* Replaces the contents of <i>str</i> with the corresponding
* values in <i>other_str</i>.
* Replaces the contents of +self+ with the contents of +other_string+:
*
* s = 'foo' # => "foo"
* s.replace('bar') # => "bar"
*
* s = "hello" #=> "hello"
* s.replace "world" #=> "world"
*/

VALUE
Expand All @@ -5826,12 +5826,13 @@ rb_str_replace(VALUE str, VALUE str2)

/*
* call-seq:
* string.clear -> string
* clear -> self
*
* Removes the contents of +self+:
*
* Makes string empty.
* s = 'foo' # => "foo"
* s.clear # => ""
*
* a = "abcde"
* a.clear #=> ""
*/

static VALUE
Expand All @@ -5850,12 +5851,13 @@ rb_str_clear(VALUE str)

/*
* call-seq:
* string.chr -> string
* chr -> string
*
* Returns a string containing the first character of +self+:
*
* Returns a one-character string at the beginning of the string.
* s = 'foo' # => "foo"
* s.chr # => "f"
*
* a = "abcde"
* a.chr #=> "a"
*/

static VALUE
Expand All @@ -5866,9 +5868,15 @@ rb_str_chr(VALUE str)

/*
* call-seq:
* str.getbyte(index) -> 0 .. 255
* getbyte(index) -> integer
*
* Returns the byte at zero-based +index+ as an integer:
*
* s = 'abcde' # => "abcde"
* s.getbyte(0) # => 97
* s.getbyte(1) # => 98
*
* returns the <i>index</i>th byte as an integer.
* Related: String#setbyte.
*/
static VALUE
rb_str_getbyte(VALUE str, VALUE index)
Expand All @@ -5885,9 +5893,15 @@ rb_str_getbyte(VALUE str, VALUE index)

/*
* call-seq:
* str.setbyte(index, integer) -> integer
* setbyte(index, integer) -> integer
*
* modifies the <i>index</i>th byte as <i>integer</i>.
* Sets the byte at zero-based +index+ to +integer+; returns +integer+:
*
* s = 'abcde' # => "abcde"
* s.setbyte(0, 98) # => 98
* s # => "bbcde"
*
* Related: String#getbyte.
*/
static VALUE
rb_str_setbyte(VALUE str, VALUE index, VALUE value)
Expand Down Expand Up @@ -6025,25 +6039,45 @@ str_byte_aref(VALUE str, VALUE indx)

/*
* call-seq:
* str.byteslice(integer) -> new_str or nil
* str.byteslice(integer, integer) -> new_str or nil
* str.byteslice(range) -> new_str or nil
* byteslice(index, length = 1) -> string or nil
* byteslice(range) -> string or nil
*
* Returns a substring of +self+, or +nil+ if the substring cannot be constructed.
*
* With integer arguments +index+ and +length+ given,
* returns the substring beginning at the given +index+
* of the given +length+ (if possible),
* or +nil+ if +length+ is negative or +index+ falls outside of +self+:
*
* s = '0123456789' # => "0123456789"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May want to align these vertically with the example lines below.

* s.byteslice(2) # => "2"
* s.byteslice(200) # => nil
* s.byteslice(4, 3) # => "456"
* s.byteslice(4, 30) # => "456789"
* s.byteslice(4, -1) # => nil
* s.byteslice(40, 2) # => nil
*
* Byte Reference---If passed a single Integer, returns a
* substring of one byte at that position. If passed two Integer
* objects, returns a substring starting at the offset given by the first, and
* a length given by the second. If given a Range, a substring containing
* bytes at offsets given by the range is returned. In all three cases, if
* an offset is negative, it is counted from the end of <i>str</i>. Returns
* <code>nil</code> if the initial offset falls outside the string, the length
* is negative, or the beginning of the range is greater than the end.
* The encoding of the resulted string keeps original encoding.
* In either case above, counts backwards from the end of +self+
* if +index+ is negative:
*
* s = '0123456789' # => "0123456789"
* s.byteslice(-4) # => "6"
* s.byteslice(-4, 3) # => "678"
*
* With Range argument +range+ given, returns
* <tt>byteslice(range.begin, range.size)</tt>:
*
* s = '0123456789' # => "0123456789"
* s.byteslice(4..6) # => "456"
* s.byteslice(-6..-4) # => "456"
* s.byteslice(5..2) # => "" # range.size is zero.
* s.byteslice(40..42) # => nil
*
* In all cases, a returned string has the same encoding as +self+:
*
* s.encoding # => #<Encoding:UTF-8>
* s.byteslice(4).encoding # => #<Encoding:UTF-8>
*
* "hello".byteslice(1) #=> "e"
* "hello".byteslice(-1) #=> "o"
* "hello".byteslice(1, 2) #=> "el"
* "\x80\u3042".byteslice(1, 3) #=> "\u3042"
* "\x03\u3042\xff".byteslice(1..3) #=> "\u3042"
*/

static VALUE
Expand All @@ -6060,11 +6094,12 @@ rb_str_byteslice(int argc, VALUE *argv, VALUE str)

/*
* call-seq:
* str.reverse -> new_str
* reverse -> string
*
* Returns a new string with the characters from <i>str</i> in reverse order.
* Returns a new string with the characters from +self+ in reverse order.
*
* 'stressed'.reverse # => "desserts"
*
* "stressed".reverse #=> "desserts"
*/

static VALUE
Expand Down Expand Up @@ -6120,9 +6155,14 @@ rb_str_reverse(VALUE str)

/*
* call-seq:
* str.reverse! -> str
* reverse! -> self
*
* Returns +self+ with its characters reversed:
*
* s = 'stressed'
* s.reverse! # => "desserts"
* s # => "desserts"
*
* Reverses <i>str</i> in place.
*/

static VALUE
Expand Down Expand Up @@ -6154,14 +6194,15 @@ rb_str_reverse_bang(VALUE str)

/*
* call-seq:
* str.include? other_str -> true or false
* include? other_string -> true or false
*
* Returns <code>true</code> if <i>str</i> contains the given string or
* character.
* Returns +true+ if +self+ contains +other_string+, +false+ otherwise:
*
* s = 'foo'
* s.include?('f') # => true
* s.include?('fo') # => true
* s.include?('food') # => false
*
* "hello".include? "lo" #=> true
* "hello".include? "ol" #=> false
* "hello".include? ?h #=> true
*/

static VALUE
Expand Down