summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBurdette Lamar <BurdetteLamar@Yahoo.com>2020-09-21 11:27:54 -0500
committerGitHub <noreply@github.com>2020-09-21 11:27:54 -0500
commitc6c5d4b3fac00e21122c554a6cd1ccf7be84376d (patch)
tree0f55018dcc2c3a197e91e56783d857f5a87ae3e9
parent82998918efa3a637c80e135198b573cfcb31acd9 (diff)
Comply with guide for method doc: string.c (#3528)
Methods: ::new #length #bytesize #empty? #+ #* #%
Notes
Notes: Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
-rw-r--r--string.c112
1 files changed, 42 insertions, 70 deletions
diff --git a/string.c b/string.c
index 1377ea3..a751aad 100644
--- a/string.c
+++ b/string.c
@@ -1566,31 +1566,19 @@ rb_str_resurrect(VALUE str)
/*
* call-seq:
- * String.new(str='') -> new_str
- * String.new(str='', encoding: enc) -> new_str
- * String.new(str='', capacity: size) -> new_str
+ * String.new(string = '') -> new_string
+ * String.new(string = '', encoding: encoding _name) -> new_string
+ * String.new(string = '', capacity: size) -> new_string
*
- * Argument +str+, if given, it must be a \String.
- *
- * Argument +encoding+, if given, must be the \String name of an encoding
- * that is compatible with +str+.
- *
- * Argument +capacity+, if given, must be an \Integer.
- *
- * The +str+, +encoding+, and +capacity+ arguments may all be used together:
- * String.new('hello', encoding: 'UTF-8', capacity: 25)
- *
- * Returns a new \String that is a copy of <i>str</i>.
- *
- * ---
+ * Returns a new \String that is a copy of +string+.
*
* With no arguments, returns the empty string with the Encoding <tt>ASCII-8BIT</tt>:
* s = String.new
* s # => ""
* s.encoding # => #<Encoding:ASCII-8BIT>
*
- * With the single argument +str+, returns a copy of +str+
- * with the same encoding as +str+:
+ * With the single \String argument +string+, returns a copy of +string+
+ * with the same encoding as +string+:
* s = String.new("Que veut dire \u{e7}a?")
* s # => "Que veut dire \u{e7}a?"
* s.encoding # => #<Encoding:UTF-8>
@@ -1598,8 +1586,6 @@ rb_str_resurrect(VALUE str)
* Literal strings like <tt>""</tt> or here-documents always use
* {script encoding}[Encoding.html#class-Encoding-label-Script+encoding], unlike String.new.
*
- * ---
- *
* With keyword +encoding+, returns a copy of +str+
* with the specified encoding:
* s = String.new(encoding: 'ASCII')
@@ -1612,29 +1598,14 @@ rb_str_resurrect(VALUE str)
* s1 = 'foo'.force_encoding('ASCII')
* s0.encoding == s1.encoding # => true
*
- * ---
- *
* With keyword +capacity+, returns a copy of +str+;
* the given +capacity+ may set the size of the internal buffer,
* which may affect performance:
* String.new(capacity: 1) # => ""
* String.new(capacity: 4096) # => ""
*
- * No exception is raised for zero or negative values:
- * String.new(capacity: 0) # => ""
- * String.new(capacity: -1) # => ""
- *
- * ---
- *
- * Raises an exception if the given +encoding+ is not a valid encoding name:
- * # Raises ArgumentError (unknown encoding name - FOO)
- * String.new(encoding: 'FOO')
- *
- * Raises an exception if the given +encoding+ is incompatible with +str+:
- * utf8 = "Que veut dire \u{e7}a?"
- * ascii = "Que veut dire \u{e7}a?".force_encoding('ASCII')
- * # Raises Encoding::CompatibilityError (incompatible character encodings: UTF-8 and US-ASCII)
- * utf8.include? ascii
+ * The +string+, +encoding+, and +capacity+ arguments may all be used together:
+ * String.new('hello', encoding: 'UTF-8', capacity: 25)
*/
static VALUE
@@ -1926,10 +1897,15 @@ rb_str_strlen(VALUE str)
/*
* call-seq:
- * str.length -> integer
- * str.size -> integer
+ * string.length -> integer
+ *
+ * Returns the count of characters (not bytes) in +self+:
+ * "\x80\u3042".length # => 2
+ * "hello".length # => 5
*
- * Returns the character length of <i>str</i>.
+ * String#size is an alias for String#length.
+ *
+ * Related: String#bytesize.
*/
VALUE
@@ -1940,12 +1916,13 @@ rb_str_length(VALUE str)
/*
* call-seq:
- * str.bytesize -> integer
+ * string.bytesize -> integer
*
- * Returns the length of +str+ in bytes.
+ * Returns the count of bytes in +self+:
+ * "\x80\u3042".bytesize # => 4
+ * "hello".bytesize # => 5
*
- * "\x80\u3042".bytesize #=> 4
- * "hello".bytesize #=> 5
+ * Related: String#length.
*/
static VALUE
@@ -1956,13 +1933,12 @@ rb_str_bytesize(VALUE str)
/*
* call-seq:
- * str.empty? -> true or false
- *
- * Returns <code>true</code> if <i>str</i> has a length of zero.
+ * string.empty? -> true or false
*
- * "hello".empty? #=> false
- * " ".empty? #=> false
- * "".empty? #=> true
+ * Returns +true+ if the length of +self+ is zero, +false+ otherwise:
+ * "hello".empty? # => false
+ * " ".empty? # => false
+ * "".empty? # => true
*/
static VALUE
@@ -1975,12 +1951,10 @@ rb_str_empty(VALUE str)
/*
* call-seq:
- * str + other_str -> new_str
+ * string + other_string -> new_string
*
- * Concatenation---Returns a new String containing
- * <i>other_str</i> concatenated to <i>str</i>.
- *
- * "Hello from " + self.to_s #=> "Hello from main"
+ * Returns a new \String containing +other_string+ concatenated to +self+:
+ * "Hello from " + self.to_s #=> "Hello from main"
*/
VALUE
@@ -2046,13 +2020,11 @@ rb_str_opt_plus(VALUE str1, VALUE str2)
/*
* call-seq:
- * str * integer -> new_str
- *
- * Copy --- Returns a new String containing +integer+ copies of the receiver.
- * +integer+ must be greater than or equal to 0.
+ * string * integer -> new_string
*
- * "Ho! " * 3 #=> "Ho! Ho! Ho! "
- * "Ho! " * 0 #=> ""
+ * Returns a new \String containing +integer+ copies of +self+:
+ * "Ho! " * 3 # => "Ho! Ho! Ho! "
+ * "Ho! " * 0 # => ""
*/
VALUE
@@ -2112,17 +2084,17 @@ rb_str_times(VALUE str, VALUE times)
/*
* call-seq:
- * str % arg -> new_str
+ * string % object -> new_string
*
- * Format---Uses <i>str</i> as a format specification, and returns
- * the result of applying it to <i>arg</i>. If the format
- * specification contains more than one substitution, then <i>arg</i>
- * must be an Array or Hash containing the values to be
- * substituted. See Kernel#sprintf for details of the format string.
+ * Returns the result of formatting +object+ into the format specification +self+
+ * (see Kernel#sprintf for formatting details):
+ * "%05d" % 123 # => "00123"
*
- * "%05d" % 123 #=> "00123"
- * "%-5s: %016x" % [ "ID", self.object_id ] #=> "ID : 00002b054ec93168"
- * "foo = %{foo}" % { :foo => 'bar' } #=> "foo = bar"
+ * If +self+ contains multiple substitutions, +object+ must be
+ * an \Array or \Hash containing the values to be substituted:
+ * "%-5s: %016x" % [ "ID", self.object_id ] # => "ID : 00002b054ec93168"
+ * "foo = %{foo}" % {foo: 'bar'} # => "foo = bar"
+ * "foo = %{foo}, baz = %{baz}" % {foo: 'bar', baz: 'bat'} # => "foo = bar, baz = bat"
*/
static VALUE