From 5525e47a0b5e6b6c3e13ceec4b44535feba22631 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 28 Mar 2022 15:49:18 -0500 Subject: [PATCH] [DOC] Enhanced RDoc for String (#5726) Treats: #ljust #rjust #center #partition #rpartition --- doc/string/center.rdoc | 16 +++++++++ doc/string/ljust.rdoc | 16 +++++++++ doc/string/partition.rdoc | 24 +++++++++++++ doc/string/rjust.rdoc | 16 +++++++++ doc/string/rpartition.rdoc | 24 +++++++++++++ doc/string/split.rdoc | 2 ++ string.c | 70 +++++++++----------------------------- 7 files changed, 114 insertions(+), 54 deletions(-) create mode 100644 doc/string/center.rdoc create mode 100644 doc/string/ljust.rdoc create mode 100644 doc/string/partition.rdoc create mode 100644 doc/string/rjust.rdoc create mode 100644 doc/string/rpartition.rdoc diff --git a/doc/string/center.rdoc b/doc/string/center.rdoc new file mode 100644 index 0000000000..d53d921ad5 --- /dev/null +++ b/doc/string/center.rdoc @@ -0,0 +1,16 @@ +Returns a centered copy of +self+. + +If integer argument +size+ is greater than the size (in characters) of +self+, +returns a new string of length +size+ that is a copy of +self+, +centered and padded on both ends with +pad_string+: + + 'hello'.center(10) # => " hello " + ' hello'.center(10) # => " hello " + 'hello'.center(10, 'ab') # => "abhelloaba" + 'тест'.center(10) # => " тест " + 'こんにちは'.center(10) # => " こんにちは " + +If +size+ is not greater than the size of +self+, returns a copy of +self+: + + 'hello'.center(5) # => "hello" + 'hello'.center(1) # => "hello" diff --git a/doc/string/ljust.rdoc b/doc/string/ljust.rdoc new file mode 100644 index 0000000000..8e23c1fc8f --- /dev/null +++ b/doc/string/ljust.rdoc @@ -0,0 +1,16 @@ +Returns a left-justified copy of +self+. + +If integer argument +size+ is greater than the size (in characters) of +self+, +returns a new string of length +size+ that is a copy of +self+, +left justified and padded on the right with +pad_string+: + + 'hello'.ljust(10) # => "hello " + ' hello'.ljust(10) # => " hello " + 'hello'.ljust(10, 'ab') # => "helloababa" + 'тест'.ljust(10) # => "тест " + 'こんにちは'.ljust(10) # => "こんにちは " + +If +size+ is not greater than the size of +self+, returns a copy of +self+: + + 'hello'.ljust(5) # => "hello" + 'hello'.ljust(1) # => "hello" diff --git a/doc/string/partition.rdoc b/doc/string/partition.rdoc new file mode 100644 index 0000000000..ebe575e8eb --- /dev/null +++ b/doc/string/partition.rdoc @@ -0,0 +1,24 @@ +Returns a 3-element array of substrings of +self+. + +Matches a pattern against +self+, scanning from the beginning. +The pattern is: + +- +string_or_regexp+ itself, if it is a Regexp. +- Regexp.quote(string_or_regexp), if +string_or_regexp+ is a string. + +If the pattern is matched, returns pre-match, first-match, post-match: + + 'hello'.partition('l') # => ["he", "l", "lo"] + 'hello'.partition('ll') # => ["he", "ll", "o"] + 'hello'.partition('h') # => ["", "h", "ello"] + 'hello'.partition('o') # => ["hell", "o", ""] + 'hello'.partition(/l+/) #=> ["he", "ll", "o"] + 'hello'.partition('') # => ["", "", "hello"] + 'тест'.partition('т') # => ["", "т", "ест"] + 'こんにちは'.partition('に') # => ["こん", "に", "ちは"] + +If the pattern is not matched, returns a copy of +self+ and two empty strings: + + 'hello'.partition('x') # => ["hello", "", ""] + +Related: String#rpartition, String#split. diff --git a/doc/string/rjust.rdoc b/doc/string/rjust.rdoc new file mode 100644 index 0000000000..24e7bf3159 --- /dev/null +++ b/doc/string/rjust.rdoc @@ -0,0 +1,16 @@ +Returns a right-justified copy of +self+. + +If integer argument +size+ is greater than the size (in characters) of +self+, +returns a new string of length +size+ that is a copy of +self+, +right justified and padded on the left with +pad_string+: + + 'hello'.rjust(10) # => " hello" + 'hello '.rjust(10) # => " hello " + 'hello'.rjust(10, 'ab') # => "ababahello" + 'тест'.rjust(10) # => " тест" + 'こんにちは'.rjust(10) # => " こんにちは" + +If +size+ is not greater than the size of +self+, returns a copy of +self+: + + 'hello'.rjust(5, 'ab') # => "hello" + 'hello'.rjust(1, 'ab') # => "hello" diff --git a/doc/string/rpartition.rdoc b/doc/string/rpartition.rdoc new file mode 100644 index 0000000000..d24106fb9f --- /dev/null +++ b/doc/string/rpartition.rdoc @@ -0,0 +1,24 @@ +Returns a 3-element array of substrings of +self+. + +Matches a pattern against +self+, scanning backwards from the end. +The pattern is: + +- +string_or_regexp+ itself, if it is a Regexp. +- Regexp.quote(string_or_regexp), if +string_or_regexp+ is a string. + +If the pattern is matched, returns pre-match, last-match, post-match: + + 'hello'.rpartition('l') # => ["hel", "l", "o"] + 'hello'.rpartition('ll') # => ["he", "ll", "o"] + 'hello'.rpartition('h') # => ["", "h", "ello"] + 'hello'.rpartition('o') # => ["hell", "o", ""] + 'hello'.rpartition(/l+/) # => ["hel", "l", "o"] + 'hello'.rpartition('') # => ["hello", "", ""] + 'тест'.rpartition('т') # => ["тес", "т", ""] + 'こんにちは'.rpartition('に') # => ["こん", "に", "ちは"] + +If the pattern is not matched, returns two empty strings and a copy of +self+: + + 'hello'.rpartition('x') # => ["", "", "hello"] + +Related: String#partition, String#split. diff --git a/doc/string/split.rdoc b/doc/string/split.rdoc index d93b76d9b4..2b5e14ddb6 100644 --- a/doc/string/split.rdoc +++ b/doc/string/split.rdoc @@ -82,3 +82,5 @@ Output: "abc" "def" "ghi" + +Related: String#partition, String#rpartition. diff --git a/string.c b/string.c index 0917f56f35..56b2eca99b 100644 --- a/string.c +++ b/string.c @@ -10383,15 +10383,12 @@ rb_str_justify(int argc, VALUE *argv, VALUE str, char jflag) /* * call-seq: - * str.ljust(integer, padstr=' ') -> new_str + * ljust(size, pad_string = ' ') -> new_string * - * If integer is greater than the length of str, returns a new - * String of length integer with str left justified - * and padded with padstr; otherwise, returns str. + * :include: doc/string/ljust.rdoc + * + * Related: String#rjust, String#center. * - * "hello".ljust(4) #=> "hello" - * "hello".ljust(20) #=> "hello " - * "hello".ljust(20, '1234') #=> "hello123412341234123" */ static VALUE @@ -10400,18 +10397,14 @@ rb_str_ljust(int argc, VALUE *argv, VALUE str) return rb_str_justify(argc, argv, str, 'l'); } - /* * call-seq: - * str.rjust(integer, padstr=' ') -> new_str + * rjust(size, pad_string = ' ') -> new_string * - * If integer is greater than the length of str, returns a new - * String of length integer with str right justified - * and padded with padstr; otherwise, returns str. + * :include: doc/string/rjust.rdoc + * + * Related: String#ljust, String#center. * - * "hello".rjust(4) #=> "hello" - * "hello".rjust(20) #=> " hello" - * "hello".rjust(20, '1234') #=> "123412341234123hello" */ static VALUE @@ -10423,15 +10416,12 @@ rb_str_rjust(int argc, VALUE *argv, VALUE str) /* * call-seq: - * str.center(width, padstr=' ') -> new_str + * center(size, pad_string = ' ') -> new_string * - * Centers +str+ in +width+. If +width+ is greater than the length of +str+, - * returns a new String of length +width+ with +str+ centered and padded with - * +padstr+; otherwise, returns +str+. + * :include: doc/string/center.rdoc + * + * Related: String#ljust, String#rjust. * - * "hello".center(4) #=> "hello" - * "hello".center(20) #=> " hello " - * "hello".center(20, '123') #=> "1231231hello12312312" */ static VALUE @@ -10442,17 +10432,10 @@ rb_str_center(int argc, VALUE *argv, VALUE str) /* * call-seq: - * str.partition(sep) -> [head, sep, tail] - * str.partition(regexp) -> [head, match, tail] + * partition(string_or_regexp) -> [head, match, tail] * - * Searches sep or pattern (regexp) in the string - * and returns the part before it, the match, and the part - * after it. - * If it is not found, returns two empty strings and str. + * :include: doc/string/partition.rdoc * - * "hello".partition("l") #=> ["he", "l", "lo"] - * "hello".partition("x") #=> ["hello", "", ""] - * "hello".partition(/.l/) #=> ["h", "el", "lo"] */ static VALUE @@ -10486,31 +10469,10 @@ rb_str_partition(VALUE str, VALUE sep) /* * call-seq: - * str.rpartition(sep) -> [head, sep, tail] - * str.rpartition(regexp) -> [head, match, tail] + * rpartition(sep) -> [head, match, tail] * - * Searches sep or pattern (regexp) in the string from the end - * of the string, and returns the part before it, the match, and the part - * after it. - * If it is not found, returns two empty strings and str. + * :include: doc/string/rpartition.rdoc * - * "hello".rpartition("l") #=> ["hel", "l", "o"] - * "hello".rpartition("x") #=> ["", "", "hello"] - * "hello".rpartition(/.l/) #=> ["he", "ll", "o"] - * - * The match from the end means starting at the possible last position, not - * the last of longest matches. - * - * "hello".rpartition(/l+/) #=> ["hel", "l", "o"] - * - * To partition at the last longest match, needs to combine with - * negative lookbehind. - * - * "hello".rpartition(/(? ["he", "ll", "o"] - * - * Or String#partition with negative lookforward. - * - * "hello".partition(/l+(?!.*l)/) #=> ["he", "ll", "o"] */ static VALUE