From 056b7a86335f38618c1749674a11e838de7c3c12 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 31 Mar 2022 15:09:25 -0500 Subject: [DOC] Enhanced RDoc for String (#5742) Treats: #force_encoding #b #valid_encoding? #ascii_only? #scrub #scrub! #unicode_normalized? Plus a couple of minor tweaks. --- string.c | 111 ++++++++++++++++++++++++--------------------------------------- 1 file changed, 42 insertions(+), 69 deletions(-) (limited to 'string.c') diff --git a/string.c b/string.c index 640b5b6c73..401fcca2fc 100644 --- a/string.c +++ b/string.c @@ -8416,7 +8416,7 @@ rb_str_squeeze_bang(int argc, VALUE *argv, VALUE str) /* * call-seq: - * str.squeeze(*selectors) -> new_string + * squeeze(*selectors) -> new_string * * Returns a copy of +self+ with characters specified by +selectors+ "squeezed" * (see {Multiple Character Selectors}[rdoc-ref:character_selectors.rdoc@Multiple+Character+Selectors]): @@ -10707,7 +10707,7 @@ rb_str_delete_suffix_bang(VALUE str, VALUE suffix) /* * call-seq: - * str.delete_suffix(suffix) -> new_string + * delete_suffix(suffix) -> new_string * * :include: doc/string/delete_suffix.rdoc * @@ -10751,9 +10751,10 @@ rb_fs_setter(VALUE val, ID id, VALUE *var) /* * call-seq: - * str.force_encoding(encoding) -> str + * force_encoding(encoding) -> self + * + * :include: doc/string/force_encoding.rdoc * - * Changes the encoding to +encoding+ and returns self. */ static VALUE @@ -10769,19 +10770,7 @@ rb_str_force_encoding(VALUE str, VALUE enc) * call-seq: * b -> string * - * Returns a copy of +self+ with that has ASCII-8BIT encoding; - * the contents (bytes) of +self+ are not modified: - * - * s = "\x99" - * s.encoding # => # - * t = s.b # => "\x99" - * t.encoding # => # - * - * s = "\u4095" - * s.encoding # => # - * s.bytes # => [228, 130, 149] - * t = s.b # => "\xE4\x82\x95" - * t.encoding # => # + * :include: doc/string/b.rdoc * */ @@ -10802,13 +10791,13 @@ rb_str_b(VALUE str) /* * call-seq: - * str.valid_encoding? -> true or false + * valid_encoding? -> true or false * - * Returns true for a string which is encoded correctly. + * Returns +true+ if +self+ is encoded correctly, +false+ otherwise: * - * "\xc2\xa1".force_encoding("UTF-8").valid_encoding? #=> true - * "\xc2".force_encoding("UTF-8").valid_encoding? #=> false - * "\x80".force_encoding("UTF-8").valid_encoding? #=> false + * "\xc2\xa1".force_encoding("UTF-8").valid_encoding? # => true + * "\xc2".force_encoding("UTF-8").valid_encoding? # => false + * "\x80".force_encoding("UTF-8").valid_encoding? # => false */ static VALUE @@ -10821,12 +10810,14 @@ rb_str_valid_encoding_p(VALUE str) /* * call-seq: - * str.ascii_only? -> true or false + * ascii_only? -> true or false * - * Returns true for a string which has only ASCII characters. + * Returns +true+ if +self+ contains only ASCII characters, + * +false+ otherwise: + * + * 'abc'.ascii_only? # => true + * "abc\u{6666}".ascii_only? # => false * - * "abc".force_encoding("UTF-8").ascii_only? #=> true - * "abc\u{6666}".force_encoding("UTF-8").ascii_only? #=> false */ static VALUE @@ -11158,37 +11149,10 @@ enc_str_scrub(rb_encoding *enc, VALUE str, VALUE repl, int cr) /* * call-seq: - * scrub(replacement_string = default_replacement) -> string - * scrub{|bytes| ... } -> string - * - * Returns a copy of self with each invalid byte sequence replaced - * by a replacement string. - * - * With no block given and no argument, replaces each invalid sequence - * with the default replacement string - * ("\uFFFD" for a Unicode encoding, '?' otherwise): - * - * "\uFFFD".bytes # => [239, 191, 189] - * s = "foo\x81\x81bar" - * s.bytes - * # => [102, 111, 111, 129, 129, 98, 97, 114] - * s.scrub.bytes - * # => [102, 111, 111, 239, 191, 189, 239, 191, 189, 98, 97, 114] - * - * With no block given and argument +replacement_string+ given, - * replaces each invalid sequence with that string: - * - * "foo\x81\x81bar".scrub('xyzzy') # => "fooxyzzyxyzzybar" - * - * With a block given, replaces each invalid sequence with the value - * of the block: + * scrub(replacement_string = default_replacement) -> new_string + * scrub{|bytes| ... } -> new_string * - * "foo\x81\x81bar".scrub {|bytes| p bytes; 'XYZZY' } # => "fooXYZZYXYZZYbar" - * - * Output: - * - * "\x81" - * "\x81" + * :include: doc/string/scrub.rdoc * */ static VALUE @@ -11203,7 +11167,7 @@ str_scrub(int argc, VALUE *argv, VALUE str) * call-seq: * scrub! -> self * scrub!(replacement_string = default_replacement) -> self - * scrub!{|bytes|} -> self + * scrub!{|bytes| ... } -> self * * Like String#scrub, except that any replacements are made in +self+. * @@ -11267,6 +11231,7 @@ unicode_normalize_common(int argc, VALUE *argv, VALUE str, ID id) * "a\u0300".unicode_normalize # => "a" * "\u00E0".unicode_normalize(:nfd) # => "a " * + * Related: String#unicode_normalize!, String#unicode_normalized?. */ static VALUE rb_str_unicode_normalize(int argc, VALUE *argv, VALUE str) @@ -11281,6 +11246,8 @@ rb_str_unicode_normalize(int argc, VALUE *argv, VALUE str) * Like String#unicode_normalize, except that the normalization * is performed on +self+. * + * Related String#unicode_normalized?. + * */ static VALUE rb_str_unicode_normalize_bang(int argc, VALUE *argv, VALUE str) @@ -11289,21 +11256,27 @@ rb_str_unicode_normalize_bang(int argc, VALUE *argv, VALUE str) } /* call-seq: - * str.unicode_normalized?(form=:nfc) + * unicode_normalized?(form = :nfc) -> true or false + * + * Returns +true+ if +self+ is in the given +form+ of Unicode normalization, + * +false+ otherwise. + * The +form+ must be one of +:nfc+, +:nfd+, +:nfkc+, or +:nfkd+. + * + * Examples: + * + * "a\u0300".unicode_normalized? # => false + * "a\u0300".unicode_normalized?(:nfd) # => true + * "\u00E0".unicode_normalized? # => true + * "\u00E0".unicode_normalized?(:nfd) # => false + * + * + * Raises an exception if +self+ is not in a Unicode encoding: * - * Checks whether +str+ is in Unicode normalization form +form+, - * which can be any of the four values +:nfc+, +:nfd+, +:nfkc+, or +:nfkd+. - * The default is +:nfc+. + * s = "\xE0".force_encoding('ISO-8859-1') + * s.unicode_normalized? # Raises Encoding::CompatibilityError. * - * If the string is not in a Unicode Encoding, then an Exception is raised. - * For details, see String#unicode_normalize. + * Related: String#unicode_normalize, String#unicode_normalize!. * - * "a\u0300".unicode_normalized? #=> false - * "a\u0300".unicode_normalized?(:nfd) #=> true - * "\u00E0".unicode_normalized? #=> true - * "\u00E0".unicode_normalized?(:nfd) #=> false - * "\xE0".force_encoding('ISO-8859-1').unicode_normalized? - * #=> Encoding::CompatibilityError raised */ static VALUE rb_str_unicode_normalized_p(int argc, VALUE *argv, VALUE str) -- cgit v1.2.1