Class: String

Inherits:
Object show all
Includes:
Comparable
Defined in:
string.c

Overview

A String object holds and manipulates an arbitrary sequence of bytes, typically representing characters. String objects may be created using String::new or as literals.

Because of aliasing issues, users of strings should be aware of the methods that modify the contents of a String object. Typically, methods with names ending in “!'' modify their receiver, while those without a “!'' return a new String. However, there are exceptions, such as String#[]=.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Comparable

#<, #<=, #>, #>=, #between?

Constructor Details

#new(str = "") ⇒ String #new(str = "", encoding: enc) ⇒ String

Returns a new string object containing a copy of str. The optional enc argument specifies the encoding of the new string. If not specified, the encoding of str (or ASCII-8BIT, if str is not specified) is used.

Overloads:

  • #new(str = "") ⇒ String
  • #new(str = "", encoding: enc) ⇒ String


1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
# File 'string.c', line 1342

static VALUE
rb_str_init(int argc, VALUE *argv, VALUE str)
{
    static ID keyword_ids[1];
    VALUE orig, opt, enc;
    int n;

    if (!keyword_ids[0])
  keyword_ids[0] = rb_id_encoding();

    n = rb_scan_args(argc, argv, "01:", &orig, &opt);
    if (argc > 0 && n == 1)
  rb_str_replace(str, orig);
    if (!NIL_P(opt)) {
  rb_get_kwargs(opt, keyword_ids, 0, 1, &enc);
  if (enc != Qundef && !NIL_P(enc)) {
      rb_enc_associate(str, rb_to_encoding(enc));
      ENC_CODERANGE_CLEAR(str);
  }
    }
    return str;
}

Class Method Details

.try_convert(obj) ⇒ String?

Try to convert obj into a String, using to_str method. Returns converted string or nil if obj cannot be converted for any reason.

String.try_convert("str")     #=> "str"
String.try_convert(/re/)      #=> nil

Returns:



1972
1973
1974
1975
1976
# File 'string.c', line 1972

static VALUE
rb_str_s_try_convert(VALUE dummy, VALUE str)
{
    return rb_check_string_type(str);
}

Instance Method Details

#%(arg) ⇒ String

Format—Uses str as a format specification, and returns the result of applying it to arg. If the format specification contains more than one substitution, then arg must be an Array or Hash containing the values to be substituted. See Kernel::sprintf for details of the format string.

"%05d" % 123                              #=> "00123"
"%-5s: %08x" % [ "ID", self.object_id ]   #=> "ID   : 200e14d6"
"foo = %{foo}" % { :foo => 'bar' }        #=> "foo = bar"

Returns:



1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
# File 'string.c', line 1723

static VALUE
rb_str_format_m(VALUE str, VALUE arg)
{
    VALUE tmp = rb_check_array_type(arg);

    if (!NIL_P(tmp)) {
  VALUE rv = rb_str_format(RARRAY_LENINT(tmp), RARRAY_CONST_PTR(tmp), str);
  RB_GC_GUARD(tmp);
  return rv;
    }
    return rb_str_format(1, &arg, str);
}

#*(integer) ⇒ String

Copy — Returns a new String containing integer copies of the receiver. integer must be greater than or equal to 0.

"Ho! " * 3   #=> "Ho! Ho! Ho! "
"Ho! " * 0   #=> ""

Returns:



1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
# File 'string.c', line 1662

VALUE
rb_str_times(VALUE str, VALUE times)
{
    VALUE str2;
    long n, len;
    char *ptr2;
    int termlen;

    if (times == INT2FIX(1)) {
  return rb_str_dup(str);
    }
    if (times == INT2FIX(0)) {
  str2 = str_alloc(rb_obj_class(str));
  rb_enc_copy(str2, str);
  OBJ_INFECT(str2, str);
  return str2;
    }
    len = NUM2LONG(times);
    if (len < 0) {
  rb_raise(rb_eArgError, "negative argument");
    }
    if (len && LONG_MAX/len <  RSTRING_LEN(str)) {
  rb_raise(rb_eArgError, "argument too big");
    }

    len *= RSTRING_LEN(str);
    termlen = TERM_LEN(str);
    str2 = rb_str_new_with_class(str, 0, (len + termlen - 1));
    ptr2 = RSTRING_PTR(str2);
    if (len) {
        n = RSTRING_LEN(str);
        memcpy(ptr2, RSTRING_PTR(str), n);
        while (n <= len/2) {
            memcpy(ptr2 + n, ptr2, n);
            n *= 2;
        }
        memcpy(ptr2 + n, ptr2, len-n);
    }
    STR_SET_LEN(str2, len);
    TERM_FILL(&ptr2[len], termlen);
    OBJ_INFECT(str2, str);
    rb_enc_cr_str_copy_for_substr(str2, str);

    return str2;
}

#+(other_str) ⇒ String

Concatenation—Returns a new String containing other_str concatenated to str.

"Hello from " + self.to_s   #=> "Hello from main"

Returns:



1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
# File 'string.c', line 1625

VALUE
rb_str_plus(VALUE str1, VALUE str2)
{
    VALUE str3;
    rb_encoding *enc;
    char *ptr1, *ptr2, *ptr3;
    long len1, len2;

    StringValue(str2);
    enc = rb_enc_check_str(str1, str2);
    RSTRING_GETMEM(str1, ptr1, len1);
    RSTRING_GETMEM(str2, ptr2, len2);
    str3 = rb_str_new(0, len1+len2);
    ptr3 = RSTRING_PTR(str3);
    memcpy(ptr3, ptr1, len1);
    memcpy(ptr3+len1, ptr2, len2);
    TERM_FILL(&ptr3[len1+len2], rb_enc_mbminlen(enc));

    FL_SET_RAW(str3, OBJ_TAINTED_RAW(str1) | OBJ_TAINTED_RAW(str2));
    ENCODING_CODERANGE_SET(str3, rb_enc_to_index(enc),
         ENC_CODERANGE_AND(ENC_CODERANGE(str1), ENC_CODERANGE(str2)));
    RB_GC_GUARD(str1);
    RB_GC_GUARD(str2);
    return str3;
}

#+Object

If the string is frozen, then return duplicated mutable string.

If the string is not frozen, then return the string itself.



2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
# File 'string.c', line 2263

static VALUE
str_uplus(VALUE str)
{
    if (OBJ_FROZEN(str)) {
  return rb_str_dup(str);
    }
    else {
  return str;
    }
}

#-Object

If the string is frozen, then return the string itself.

If the string is not frozen, then duplicate the string freeze it and return it.



2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
# File 'string.c', line 2283

static VALUE
str_uminus(VALUE str)
{
    if (OBJ_FROZEN(str)) {
  return str;
    }
    else {
  return rb_str_freeze(rb_str_dup(str));
    }
}

#<<(integer) ⇒ String #concat(integer) ⇒ String #<<(obj) ⇒ String #concat(obj) ⇒ String

Append—Concatenates the given object to str. If the object is a Integer, it is considered as a codepoint, and is converted to a character before concatenation.

a = "hello "
a << "world"   #=> "hello world"
a.concat(33)   #=> "hello world!"

Overloads:



2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
# File 'string.c', line 2637

VALUE
rb_str_concat(VALUE str1, VALUE str2)
{
    unsigned int code;
    rb_encoding *enc = STR_ENC_GET(str1);

    if (FIXNUM_P(str2) || RB_TYPE_P(str2, T_BIGNUM)) {
  if (rb_num_to_uint(str2, &code) == 0) {
  }
  else if (FIXNUM_P(str2)) {
      rb_raise(rb_eRangeError, "%ld out of char range", FIX2LONG(str2));
  }
  else {
      rb_raise(rb_eRangeError, "bignum out of char range");
  }
    }
    else {
  return rb_str_append(str1, str2);
    }

    if (enc == rb_usascii_encoding()) {
  /* US-ASCII automatically extended to ASCII-8BIT */
  char buf[1];
  buf[0] = (char)code;
  if (code > 0xFF) {
      rb_raise(rb_eRangeError, "%u out of char range", code);
  }
  rb_str_cat(str1, buf, 1);
  if (code > 127) {
      rb_enc_associate(str1, rb_ascii8bit_encoding());
      ENC_CODERANGE_SET(str1, ENC_CODERANGE_VALID);
  }
    }
    else {
  long pos = RSTRING_LEN(str1);
  int cr = ENC_CODERANGE(str1);
  int len;
  char *buf;

  switch (len = rb_enc_codelen(code, enc)) {
    case ONIGERR_INVALID_CODE_POINT_VALUE:
      rb_raise(rb_eRangeError, "invalid codepoint 0x%X in %s", code, rb_enc_name(enc));
      break;
    case ONIGERR_TOO_BIG_WIDE_CHAR_VALUE:
    case 0:
      rb_raise(rb_eRangeError, "%u out of char range", code);
      break;
  }
  buf = ALLOCA_N(char, len + 1);
  rb_enc_mbcput(code, buf, enc);
  if (rb_enc_precise_mbclen(buf, buf + len + 1, enc) != len) {
      rb_raise(rb_eRangeError, "invalid codepoint 0x%X in %s", code, rb_enc_name(enc));
  }
  rb_str_resize(str1, pos+len);
  memcpy(RSTRING_PTR(str1) + pos, buf, len);
  if (cr == ENC_CODERANGE_7BIT && code > 127)
      cr = ENC_CODERANGE_VALID;
  ENC_CODERANGE_SET(str1, cr);
    }
    return str1;
}

#<=>(other_string) ⇒ -1, ...

Comparison—Returns -1, 0, +1 or nil depending on whether string is less than, equal to, or greater than other_string.

nil is returned if the two values are incomparable.

If the strings are of different lengths, and the strings are equal when compared up to the shortest length, then the longer string is considered greater than the shorter one.

<=> is the basis for the methods <, <=, >, >=, and between?, included from module Comparable. The method String#== does not use Comparable#==.

"abcdef" <=> "abcde"     #=> 1
"abcdef" <=> "abcdef"    #=> 0
"abcdef" <=> "abcdefg"   #=> -1
"abcdef" <=> "ABCDEF"    #=> 1
"abcdef" <=> 1           #=> nil

Returns:

  • (-1, 0, +1, nil)


2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
# File 'string.c', line 2895

static VALUE
rb_str_cmp_m(VALUE str1, VALUE str2)
{
    int result;

    if (!RB_TYPE_P(str2, T_STRING)) {
  VALUE tmp = rb_check_funcall(str2, idTo_str, 0, 0);
  if (RB_TYPE_P(tmp, T_STRING)) {
      result = rb_str_cmp(str1, tmp);
  }
  else {
      return rb_invcmp(str1, str2);
  }
    }
    else {
  result = rb_str_cmp(str1, str2);
    }
    return INT2FIX(result);
}

#==(obj) ⇒ Boolean #===(obj) ⇒ Boolean

Equality

Returns whether str == obj, similar to Object#==.

If obj is not an instance of String but responds to to_str, then the two strings are compared using case equality Object#===.

Otherwise, returns similarly to String#eql?, comparing length and content.

Overloads:

  • #==(obj) ⇒ Boolean

    Returns:

    • (Boolean)
  • #===(obj) ⇒ Boolean

    Returns:

    • (Boolean)


2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
# File 'string.c', line 2841

VALUE
rb_str_equal(VALUE str1, VALUE str2)
{
    if (str1 == str2) return Qtrue;
    if (!RB_TYPE_P(str2, T_STRING)) {
  if (!rb_respond_to(str2, idTo_str)) {
      return Qfalse;
  }
  return rb_equal(str2, str1);
    }
    return str_eql(str1, str2);
}

#==(obj) ⇒ Boolean #===(obj) ⇒ Boolean

Equality

Returns whether str == obj, similar to Object#==.

If obj is not an instance of String but responds to to_str, then the two strings are compared using case equality Object#===.

Otherwise, returns similarly to String#eql?, comparing length and content.

Overloads:

  • #==(obj) ⇒ Boolean

    Returns:

    • (Boolean)
  • #===(obj) ⇒ Boolean

    Returns:

    • (Boolean)


2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
# File 'string.c', line 2841

VALUE
rb_str_equal(VALUE str1, VALUE str2)
{
    if (str1 == str2) return Qtrue;
    if (!RB_TYPE_P(str2, T_STRING)) {
  if (!rb_respond_to(str2, idTo_str)) {
      return Qfalse;
  }
  return rb_equal(str2, str1);
    }
    return str_eql(str1, str2);
}

#=~(obj) ⇒ Fixnum?

Match—If obj is a Regexp, use it as a pattern to match against str,and returns the position the match starts, or nil if there is no match. Otherwise, invokes obj.=~, passing str as an argument. The default =~ in Object returns nil.

Note: str =~ regexp is not the same as regexp =~ str. Strings captured from named capture groups are assigned to local variables only in the second case.

"cat o' 9 tails" =~ /\d/   #=> 7
"cat o' 9 tails" =~ 9      #=> nil

Returns:



3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
# File 'string.c', line 3291

static VALUE
rb_str_match(VALUE x, VALUE y)
{
    if (SPECIAL_CONST_P(y)) goto generic;
    switch (BUILTIN_TYPE(y)) {
      case T_STRING:
  rb_raise(rb_eTypeError, "type mismatch: String given");

      case T_REGEXP:
  return rb_reg_match(y, x);

      generic:
      default:
  return rb_funcall(y, idEqTilde, 1, x);
    }
}

#[](index) ⇒ String? #[](start, length) ⇒ String? #[](range) ⇒ String? #[](regexp) ⇒ String? #[](regexp, capture) ⇒ String? #[](match_str) ⇒ String? #slice(index) ⇒ String? #slice(start, length) ⇒ String? #slice(range) ⇒ String? #slice(regexp) ⇒ String? #slice(regexp, capture) ⇒ String? #slice(match_str) ⇒ String?

Element Reference — If passed a single index, returns a substring of one character at that index. If passed a start index and a length, returns a substring containing length characters starting at the start index. If passed a range, its beginning and end are interpreted as offsets delimiting the substring to be returned.

In these three cases, if an index is negative, it is counted from the end of the string. For the start and range cases the starting index is just before a character and an index matching the string's size. Additionally, an empty string is returned when the starting index for a character range is at the end of the string.

Returns nil if the initial index falls outside the string or the length is negative.

If a Regexp is supplied, the matching portion of the string is returned. If a capture follows the regular expression, which may be a capture group index or name, follows the regular expression that component of the MatchData is returned instead.

If a match_str is given, that string is returned if it occurs in the string.

Returns nil if the regular expression does not match or the match string cannot be found.

a = "hello there"

a[1]                   #=> "e"
a[2, 3]                #=> "llo"
a[2..3]                #=> "ll"

a[-3, 2]               #=> "er"
a[7..-2]               #=> "her"
a[-4..-2]              #=> "her"
a[-2..-4]              #=> ""

a[11, 0]               #=> ""
a[11]                  #=> nil
a[12, 0]               #=> nil
a[12..-1]              #=> nil

a[/[aeiou](.)\1/]      #=> "ell"
a[/[aeiou](.)\1/, 0]   #=> "ell"
a[/[aeiou](.)\1/, 1]   #=> "l"
a[/[aeiou](.)\1/, 2]   #=> nil

a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "non_vowel"] #=> "l"
a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "vowel"]     #=> "e"

a["lo"]                #=> "lo"
a["bye"]               #=> nil

Overloads:



4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
# File 'string.c', line 4007

static VALUE
rb_str_aref_m(int argc, VALUE *argv, VALUE str)
{
    if (argc == 2) {
  if (RB_TYPE_P(argv[0], T_REGEXP)) {
      return rb_str_subpat(str, argv[0], argv[1]);
  }
  return rb_str_substr(str, NUM2LONG(argv[0]), NUM2LONG(argv[1]));
    }
    rb_check_arity(argc, 1, 2);
    return rb_str_aref(str, argv[0]);
}

#[]=(fixnum) ⇒ Object #[]=(fixnum, fixnum) ⇒ Object #[]=(range) ⇒ Object #[]=(regexp) ⇒ Object #[]=(regexp, fixnum) ⇒ Object #[]=(regexp, name) ⇒ Object #[]=(other_str) ⇒ Object

Element Assignment—Replaces some or all of the content of str. The portion of the string affected is determined using the same criteria as String#[]. If the replacement string is not the same length as the text it is replacing, the string will be adjusted accordingly. If the regular expression or string is used as the index doesn't match a position in the string, IndexError is raised. If the regular expression form is used, the optional second Fixnum allows you to specify which portion of the match to replace (effectively using the MatchData indexing rules. The forms that take a Fixnum will raise an IndexError if the value is out of range; the Range form will raise a RangeError, and the Regexp and String will raise an IndexError on negative match.



4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
# File 'string.c', line 4235

static VALUE
rb_str_aset_m(int argc, VALUE *argv, VALUE str)
{
    if (argc == 3) {
  if (RB_TYPE_P(argv[0], T_REGEXP)) {
      rb_str_subpat_set(str, argv[0], argv[1], argv[2]);
  }
  else {
      rb_str_splice(str, NUM2LONG(argv[0]), NUM2LONG(argv[1]), argv[2]);
  }
  return argv[2];
    }
    rb_check_arity(argc, 2, 3);
    return rb_str_aset(str, argv[0], argv[1]);
}

#ascii_only?Boolean

Returns true for a string which has only ASCII characters.

"abc".force_encoding("UTF-8").ascii_only?          #=> true
"abc\u{6666}".force_encoding("UTF-8").ascii_only?  #=> false

Returns:

  • (Boolean)

Returns:

  • (Boolean)


8587
8588
8589
8590
8591
8592
8593
# File 'string.c', line 8587

static VALUE
rb_str_is_ascii_only_p(VALUE str)
{
    int cr = rb_enc_str_coderange(str);

    return cr == ENC_CODERANGE_7BIT ? Qtrue : Qfalse;
}

#bString

Returns a copied string whose encoding is ASCII-8BIT.

Returns:



8548
8549
8550
8551
8552
8553
8554
8555
8556
# File 'string.c', line 8548

static VALUE
rb_str_b(VALUE str)
{
    VALUE str2 = str_alloc(rb_cString);
    str_replace_shared_without_enc(str2, str);
    OBJ_INFECT_RAW(str2, str);
    ENC_CODERANGE_CLEAR(str2);
    return str2;
}

#bytesArray

Returns an array of bytes in str. This is a shorthand for str.each_byte.to_a.

If a block is given, which is a deprecated form, works the same as each_byte.

Returns:



7226
7227
7228
7229
7230
# File 'string.c', line 7226

static VALUE
rb_str_bytes(VALUE str)
{
    return rb_str_enumerate_bytes(str, 1);
}

#bytesizeInteger

Returns the length of str in bytes.

"\x80\u3042".bytesize  #=> 4
"hello".bytesize       #=> 5

Returns:



1590
1591
1592
1593
1594
# File 'string.c', line 1590

static VALUE
rb_str_bytesize(VALUE str)
{
    return LONG2NUM(RSTRING_LEN(str));
}

#byteslice(fixnum) ⇒ String? #byteslice(fixnum, fixnum) ⇒ String? #byteslice(range) ⇒ String?

Byte Reference—If passed a single Fixnum, returns a substring of one byte at that position. If passed two Fixnum 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 str. Returns nil 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.

"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"

Overloads:



5024
5025
5026
5027
5028
5029
5030
5031
5032
# File 'string.c', line 5024

static VALUE
rb_str_byteslice(int argc, VALUE *argv, VALUE str)
{
    if (argc == 2) {
  return str_byte_substr(str, NUM2LONG(argv[0]), NUM2LONG(argv[1]));
    }
    rb_check_arity(argc, 1, 2);
    return str_byte_aref(str, argv[0]);
}

#capitalizeString

Returns a copy of str with the first character converted to uppercase and the remainder to lowercase. Note: case conversion is effective only in ASCII region.

"hello".capitalize    #=> "Hello"
"HELLO".capitalize    #=> "Hello"
"123ABC".capitalize   #=> "123abc"

Returns:



5833
5834
5835
5836
5837
5838
5839
# File 'string.c', line 5833

static VALUE
rb_str_capitalize(VALUE str)
{
    str = rb_str_dup(str);
    rb_str_capitalize_bang(str);
    return str;
}

#capitalize!String?

Modifies str by converting the first character to uppercase and the remainder to lowercase. Returns nil if no changes are made. Note: case conversion is effective only in ASCII region.

a = "hello"
a.capitalize!   #=> "Hello"
a               #=> "Hello"
a.capitalize!   #=> nil

Returns:



5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
5809
5810
5811
5812
5813
5814
5815
5816
5817
# File 'string.c', line 5785

static VALUE
rb_str_capitalize_bang(VALUE str)
{
    rb_encoding *enc;
    char *s, *send;
    int modify = 0;
    unsigned int c;
    int n;

    str_modify_keep_cr(str);
    enc = STR_ENC_GET(str);
    rb_str_check_dummy_enc(enc);
    if (RSTRING_LEN(str) == 0 || !RSTRING_PTR(str)) return Qnil;
    s = RSTRING_PTR(str); send = RSTRING_END(str);

    c = rb_enc_codepoint_len(s, send, &n, enc);
    if (rb_enc_islower(c, enc)) {
  rb_enc_mbcput(rb_enc_toupper(c, enc), s, enc);
  modify = 1;
    }
    s += n;
    while (s < send) {
  c = rb_enc_codepoint_len(s, send, &n, enc);
  if (rb_enc_isupper(c, enc)) {
      rb_enc_mbcput(rb_enc_tolower(c, enc), s, enc);
      modify = 1;
  }
  s += n;
    }

    if (modify) return str;
    return Qnil;
}

#casecmp(other_str) ⇒ -1, ...

Case-insensitive version of String#<=>.

"abcdef".casecmp("abcde")     #=> 1
"aBcDeF".casecmp("abcdef")    #=> 0
"abcdef".casecmp("abcdefg")   #=> -1
"abcdef".casecmp("ABCDEF")    #=> 0

Returns:

  • (-1, 0, +1, nil)


2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
# File 'string.c', line 2927

static VALUE
rb_str_casecmp(VALUE str1, VALUE str2)
{
    long len;
    rb_encoding *enc;
    char *p1, *p1end, *p2, *p2end;

    StringValue(str2);
    enc = rb_enc_compatible(str1, str2);
    if (!enc) {
  return Qnil;
    }

    p1 = RSTRING_PTR(str1); p1end = RSTRING_END(str1);
    p2 = RSTRING_PTR(str2); p2end = RSTRING_END(str2);
    if (single_byte_optimizable(str1) && single_byte_optimizable(str2)) {
  while (p1 < p1end && p2 < p2end) {
      if (*p1 != *p2) {
    unsigned int c1 = TOUPPER(*p1 & 0xff);
    unsigned int c2 = TOUPPER(*p2 & 0xff);
                if (c1 != c2)
                    return INT2FIX(c1 < c2 ? -1 : 1);
      }
      p1++;
      p2++;
  }
    }
    else {
  while (p1 < p1end && p2 < p2end) {
            int l1, c1 = rb_enc_ascget(p1, p1end, &l1, enc);
            int l2, c2 = rb_enc_ascget(p2, p2end, &l2, enc);

            if (0 <= c1 && 0 <= c2) {
                c1 = TOUPPER(c1);
                c2 = TOUPPER(c2);
                if (c1 != c2)
                    return INT2FIX(c1 < c2 ? -1 : 1);
            }
            else {
                int r;
                l1 = rb_enc_mbclen(p1, p1end, enc);
                l2 = rb_enc_mbclen(p2, p2end, enc);
                len = l1 < l2 ? l1 : l2;
                r = memcmp(p1, p2, len);
                if (r != 0)
                    return INT2FIX(r < 0 ? -1 : 1);
                if (l1 != l2)
                    return INT2FIX(l1 < l2 ? -1 : 1);
            }
      p1 += l1;
      p2 += l2;
  }
    }
    if (RSTRING_LEN(str1) == RSTRING_LEN(str2)) return INT2FIX(0);
    if (RSTRING_LEN(str1) > RSTRING_LEN(str2)) return INT2FIX(1);
    return INT2FIX(-1);
}

#center(width, padstr = ' ') ⇒ 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.

"hello".center(4)         #=> "hello"
"hello".center(20)        #=> "       hello        "
"hello".center(20, '123') #=> "1231231hello12312312"

Returns:



8352
8353
8354
8355
8356
# File 'string.c', line 8352

static VALUE
rb_str_center(int argc, VALUE *argv, VALUE str)
{
    return rb_str_justify(argc, argv, str, 'c');
}

#charsArray

Returns an array of characters in str. This is a shorthand for str.each_char.to_a.

If a block is given, which is a deprecated form, works the same as each_char.

Returns:



7330
7331
7332
7333
7334
# File 'string.c', line 7330

static VALUE
rb_str_chars(VALUE str)
{
    return rb_str_enumerate_chars(str, 1);
}

#chomp(separator = $/) ⇒ String

Returns a new String with the given record separator removed from the end of str (if present). If $/ has not been changed from the default Ruby record separator, then chomp also removes carriage return characters (that is it will remove \n, \r, and \r\n). If $/ is an empty string, it will remove all trailing newlines from the string.

"hello".chomp                #=> "hello"
"hello\n".chomp              #=> "hello"
"hello\r\n".chomp            #=> "hello"
"hello\n\r".chomp            #=> "hello\n"
"hello\r".chomp              #=> "hello"
"hello \n there".chomp       #=> "hello \n there"
"hello".chomp("llo")         #=> "he"
"hello\r\n\r\n".chomp('')    #=> "hello"
"hello\r\n\r\r\n".chomp('')  #=> "hello\r\n\r"

Returns:



7665
7666
7667
7668
7669
7670
7671
# File 'string.c', line 7665

static VALUE
rb_str_chomp(int argc, VALUE *argv, VALUE str)
{
    VALUE rs = chomp_rs(argc, argv);
    if (NIL_P(rs)) return rb_str_dup(str);
    return rb_str_subseq(str, 0, chompped_length(str, rs));
}

#chomp!(separator = $/) ⇒ String?

Modifies str in place as described for String#chomp, returning str, or nil if no modifications were made.

Returns:



7621
7622
7623
7624
7625
7626
7627
7628
7629
7630
7631
7632
7633
7634
7635
7636
7637
7638
7639
7640
# File 'string.c', line 7621

static VALUE
rb_str_chomp_bang(int argc, VALUE *argv, VALUE str)
{
    VALUE rs;
    long olen;
    str_modify_keep_cr(str);
    if ((olen = RSTRING_LEN(str)) > 0 && !NIL_P(rs = chomp_rs(argc, argv))) {
  long len;
  len = chompped_length(str, rs);
  if (len < olen) {
      STR_SET_LEN(str, len);
      TERM_FILL(&RSTRING_PTR(str)[len], TERM_LEN(str));
      if (ENC_CODERANGE(str) != ENC_CODERANGE_7BIT) {
    ENC_CODERANGE_CLEAR(str);
      }
      return str;
  }
    }
    return Qnil;
}

#chopString

Returns a new String with the last character removed. If the string ends with \r\n, both characters are removed. Applying chop to an empty string returns an empty string. String#chomp is often a safer alternative, as it leaves the string unchanged if it doesn't end in a record separator.

"string\r\n".chop   #=> "string"
"string\n\r".chop   #=> "string\n"
"string\n".chop     #=> "string"
"string".chop       #=> "strin"
"x".chop.chop       #=> ""

Returns:



7493
7494
7495
7496
7497
# File 'string.c', line 7493

static VALUE
rb_str_chop(VALUE str)
{
    return rb_str_subseq(str, 0, chopped_length(str));
}

#chop!String?

Processes str as for String#chop, returning str, or nil if str is the empty string. See also String#chomp!.

Returns:



7458
7459
7460
7461
7462
7463
7464
7465
7466
7467
7468
7469
7470
7471
7472
7473
# File 'string.c', line 7458

static VALUE
rb_str_chop_bang(VALUE str)
{
    str_modify_keep_cr(str);
    if (RSTRING_LEN(str) > 0) {
  long len;
  len = chopped_length(str);
  STR_SET_LEN(str, len);
  TERM_FILL(&RSTRING_PTR(str)[len], TERM_LEN(str));
  if (ENC_CODERANGE(str) != ENC_CODERANGE_7BIT) {
      ENC_CODERANGE_CLEAR(str);
  }
  return str;
    }
    return Qnil;
}

#chrString

Returns a one-character string at the beginning of the string.

a = "abcde"
a.chr    #=> "a"

Returns:



4829
4830
4831
4832
4833
# File 'string.c', line 4829

static VALUE
rb_str_chr(VALUE str)
{
    return rb_str_substr(str, 0, 1);
}

#clearString

Makes string empty.

a = "abcde"
a.clear    #=> ""

Returns:



4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
# File 'string.c', line 4805

static VALUE
rb_str_clear(VALUE str)
{
    str_discard(str);
    STR_SET_EMBED(str);
    STR_SET_EMBED_LEN(str, 0);
    RSTRING_PTR(str)[0] = 0;
    if (rb_enc_asciicompat(STR_ENC_GET(str)))
  ENC_CODERANGE_SET(str, ENC_CODERANGE_7BIT);
    else
  ENC_CODERANGE_SET(str, ENC_CODERANGE_VALID);
    return str;
}

#codepointsArray

Returns an array of the Integer ordinals of the characters in str. This is a shorthand for str.each_codepoint.to_a.

If a block is given, which is a deprecated form, works the same as each_codepoint.

Returns:



7424
7425
7426
7427
7428
# File 'string.c', line 7424

static VALUE
rb_str_codepoints(VALUE str)
{
    return rb_str_enumerate_codepoints(str, 1);
}

#<<(integer) ⇒ String #concat(integer) ⇒ String #<<(obj) ⇒ String #concat(obj) ⇒ String

Append—Concatenates the given object to str. If the object is a Integer, it is considered as a codepoint, and is converted to a character before concatenation.

a = "hello "
a << "world"   #=> "hello world"
a.concat(33)   #=> "hello world!"

Overloads:



2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
# File 'string.c', line 2637

VALUE
rb_str_concat(VALUE str1, VALUE str2)
{
    unsigned int code;
    rb_encoding *enc = STR_ENC_GET(str1);

    if (FIXNUM_P(str2) || RB_TYPE_P(str2, T_BIGNUM)) {
  if (rb_num_to_uint(str2, &code) == 0) {
  }
  else if (FIXNUM_P(str2)) {
      rb_raise(rb_eRangeError, "%ld out of char range", FIX2LONG(str2));
  }
  else {
      rb_raise(rb_eRangeError, "bignum out of char range");
  }
    }
    else {
  return rb_str_append(str1, str2);
    }

    if (enc == rb_usascii_encoding()) {
  /* US-ASCII automatically extended to ASCII-8BIT */
  char buf[1];
  buf[0] = (char)code;
  if (code > 0xFF) {
      rb_raise(rb_eRangeError, "%u out of char range", code);
  }
  rb_str_cat(str1, buf, 1);
  if (code > 127) {
      rb_enc_associate(str1, rb_ascii8bit_encoding());
      ENC_CODERANGE_SET(str1, ENC_CODERANGE_VALID);
  }
    }
    else {
  long pos = RSTRING_LEN(str1);
  int cr = ENC_CODERANGE(str1);
  int len;
  char *buf;

  switch (len = rb_enc_codelen(code, enc)) {
    case ONIGERR_INVALID_CODE_POINT_VALUE:
      rb_raise(rb_eRangeError, "invalid codepoint 0x%X in %s", code, rb_enc_name(enc));
      break;
    case ONIGERR_TOO_BIG_WIDE_CHAR_VALUE:
    case 0:
      rb_raise(rb_eRangeError, "%u out of char range", code);
      break;
  }
  buf = ALLOCA_N(char, len + 1);
  rb_enc_mbcput(code, buf, enc);
  if (rb_enc_precise_mbclen(buf, buf + len + 1, enc) != len) {
      rb_raise(rb_eRangeError, "invalid codepoint 0x%X in %s", code, rb_enc_name(enc));
  }
  rb_str_resize(str1, pos+len);
  memcpy(RSTRING_PTR(str1) + pos, buf, len);
  if (cr == ENC_CODERANGE_7BIT && code > 127)
      cr = ENC_CODERANGE_VALID;
  ENC_CODERANGE_SET(str1, cr);
    }
    return str1;
}

#count([other_str]) ⇒ Fixnum

Each other_str parameter defines a set of characters to count. The intersection of these sets defines the characters to count in str. Any other_str that starts with a caret ^ is negated. The sequence c1-c2 means all characters between c1 and c2. The backslash character \</code> can be used to escape <code>^ or - and is otherwise ignored unless it appears at the end of a sequence or the end of a other_str.

a = "hello world"
a.count "lo"                   #=> 5
a.count "lo", "o"              #=> 2
a.count "hello", "^l"          #=> 4
a.count "ej-m"                 #=> 4

"hello^world".count "\\^aeiou" #=> 4
"hello-world".count "a\\-eo"   #=> 4

c = "hello world\\r\\n"
c.count "\\"                   #=> 2
c.count "\\A"                  #=> 0
c.count "X-\\w"                #=> 3

Returns:



6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
# File 'string.c', line 6624

static VALUE
rb_str_count(int argc, VALUE *argv, VALUE str)
{
    char table[TR_TABLE_SIZE];
    rb_encoding *enc = 0;
    VALUE del = 0, nodel = 0, tstr;
    char *s, *send;
    int i;
    int ascompat;

    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);

    tstr = argv[0];
    StringValue(tstr);
    enc = rb_enc_check(str, tstr);
    if (argc == 1) {
  const char *ptstr;
  if (RSTRING_LEN(tstr) == 1 && rb_enc_asciicompat(enc) &&
      (ptstr = RSTRING_PTR(tstr),
       ONIGENC_IS_ALLOWED_REVERSE_MATCH(enc, (const unsigned char *)ptstr, (const unsigned char *)ptstr+1)) &&
      !is_broken_string(str)) {
      int n = 0;
      int clen;
      unsigned char c = rb_enc_codepoint_len(ptstr, ptstr+1, &clen, enc);

      s = RSTRING_PTR(str);
      if (!s || RSTRING_LEN(str) == 0) return INT2FIX(0);
      send = RSTRING_END(str);
      while (s < send) {
    if (*(unsigned char*)s++ == c) n++;
      }
      return INT2NUM(n);
  }
    }

    tr_setup_table(tstr, table, TRUE, &del, &nodel, enc);
    for (i=1; i<argc; i++) {
  tstr = argv[i];
  StringValue(tstr);
  enc = rb_enc_check(str, tstr);
  tr_setup_table(tstr, table, FALSE, &del, &nodel, enc);
    }

    s = RSTRING_PTR(str);
    if (!s || RSTRING_LEN(str) == 0) return INT2FIX(0);
    send = RSTRING_END(str);
    ascompat = rb_enc_asciicompat(enc);
    i = 0;
    while (s < send) {
  unsigned int c;

  if (ascompat && (c = *(unsigned char*)s) < 0x80) {
      if (table[c]) {
    i++;
      }
      s++;
  }
  else {
      int clen;
      c = rb_enc_codepoint_len(s, send, &clen, enc);
      if (tr_find(c, table, del, nodel)) {
    i++;
      }
      s += clen;
  }
    }

    return INT2NUM(i);
}

#crypt(salt_str) ⇒ String

Applies a one-way cryptographic hash to str by invoking the standard library function crypt(3) with the given salt string. While the format and the result are system and implementation dependent, using a salt matching the regular expression \A[a-zA-Z0-9./]{2} should be valid and safe on any platform, in which only the first two characters are significant.

This method is for use in system specific scripts, so if you want a cross-platform hash function consider using Digest or OpenSSL instead.

Returns:



8078
8079
8080
8081
8082
8083
8084
8085
8086
8087
8088
8089
8090
8091
8092
8093
8094
8095
8096
8097
8098
8099
8100
8101
8102
8103
8104
8105
8106
8107
8108
8109
8110
8111
8112
8113
8114
8115
# File 'string.c', line 8078

static VALUE
rb_str_crypt(VALUE str, VALUE salt)
{
    extern char *crypt(const char *, const char *);
    VALUE result;
    const char *s, *saltp;
    char *res;
#ifdef BROKEN_CRYPT
    char salt_8bit_clean[3];
#endif

    StringValue(salt);
    mustnot_wchar(str);
    mustnot_wchar(salt);
    if (RSTRING_LEN(salt) < 2) {
      short_salt:
  rb_raise(rb_eArgError, "salt too short (need >=2 bytes)");
    }

    s = StringValueCStr(str);
    saltp = RSTRING_PTR(salt);
    if (!saltp[0] || !saltp[1]) goto short_salt;
#ifdef BROKEN_CRYPT
    if (!ISASCII((unsigned char)saltp[0]) || !ISASCII((unsigned char)saltp[1])) {
  salt_8bit_clean[0] = saltp[0] & 0x7f;
  salt_8bit_clean[1] = saltp[1] & 0x7f;
  salt_8bit_clean[2] = '\0';
  saltp = salt_8bit_clean;
    }
#endif
    res = crypt(s, saltp);
    if (!res) {
  rb_sys_fail("crypt");
    }
    result = rb_str_new_cstr(res);
    FL_SET_RAW(result, OBJ_TAINTED_RAW(str) | OBJ_TAINTED_RAW(salt));
    return result;
}

#delete([other_str]) ⇒ String

Returns a copy of str with all characters in the intersection of its arguments deleted. Uses the same rules for building the set of characters as String#count.

"hello".delete "l","lo"        #=> "heo"
"hello".delete "lo"            #=> "he"
"hello".delete "aeiou", "^e"   #=> "hell"
"hello".delete "ej-m"          #=> "ho"

Returns:



6443
6444
6445
6446
6447
6448
6449
# File 'string.c', line 6443

static VALUE
rb_str_delete(int argc, VALUE *argv, VALUE str)
{
    str = rb_str_dup(str);
    rb_str_delete_bang(argc, argv, str);
    return str;
}

#delete!([other_str]) ⇒ String?

Performs a delete operation in place, returning str, or nil if str was not modified.

Returns:



6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
# File 'string.c', line 6367

static VALUE
rb_str_delete_bang(int argc, VALUE *argv, VALUE str)
{
    char squeez[TR_TABLE_SIZE];
    rb_encoding *enc = 0;
    char *s, *send, *t;
    VALUE del = 0, nodel = 0;
    int modify = 0;
    int i, ascompat, cr;

    if (RSTRING_LEN(str) == 0 || !RSTRING_PTR(str)) return Qnil;
    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    for (i=0; i<argc; i++) {
  VALUE s = argv[i];

  StringValue(s);
  enc = rb_enc_check(str, s);
  tr_setup_table(s, squeez, i==0, &del, &nodel, enc);
    }

    str_modify_keep_cr(str);
    ascompat = rb_enc_asciicompat(enc);
    s = t = RSTRING_PTR(str);
    send = RSTRING_END(str);
    cr = ascompat ? ENC_CODERANGE_7BIT : ENC_CODERANGE_VALID;
    while (s < send) {
  unsigned int c;
  int clen;

  if (ascompat && (c = *(unsigned char*)s) < 0x80) {
      if (squeez[c]) {
    modify = 1;
      }
      else {
    if (t != s) *t = c;
    t++;
      }
      s++;
  }
  else {
      c = rb_enc_codepoint_len(s, send, &clen, enc);

      if (tr_find(c, squeez, del, nodel)) {
    modify = 1;
      }
      else {
    if (t != s) rb_enc_mbcput(c, t, enc);
    t += clen;
    if (cr == ENC_CODERANGE_7BIT) cr = ENC_CODERANGE_VALID;
      }
      s += clen;
  }
    }
    TERM_FILL(t, TERM_LEN(str));
    STR_SET_LEN(str, t - RSTRING_PTR(str));
    ENC_CODERANGE_SET(str, cr);

    if (modify) return str;
    return Qnil;
}

#downcaseString

Returns a copy of str with all uppercase letters replaced with their lowercase counterparts. The operation is locale insensitive—only characters “A'' to “Z'' are affected. Note: case replacement is effective only in ASCII region.

"hEllO".downcase   #=> "hello"

Returns:



5762
5763
5764
5765
5766
5767
5768
# File 'string.c', line 5762

static VALUE
rb_str_downcase(VALUE str)
{
    str = rb_str_dup(str);
    rb_str_downcase_bang(str);
    return str;
}

#downcase!String?

Downcases the contents of str, returning nil if no changes were made. Note: case replacement is effective only in ASCII region.

Returns:



5697
5698
5699
5700
5701
5702
5703
5704
5705
5706
5707
5708
5709
5710
5711
5712
5713
5714
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
5742
5743
5744
5745
5746
5747
# File 'string.c', line 5697

static VALUE
rb_str_downcase_bang(VALUE str)
{
    rb_encoding *enc;
    char *s, *send;
    int modify = 0;

    str_modify_keep_cr(str);
    enc = STR_ENC_GET(str);
    rb_str_check_dummy_enc(enc);
    s = RSTRING_PTR(str); send = RSTRING_END(str);
    if (single_byte_optimizable(str)) {
  while (s < send) {
      unsigned int c = *(unsigned char*)s;

      if (rb_enc_isascii(c, enc) && 'A' <= c && c <= 'Z') {
    *s = 'a' + (c - 'A');
    modify = 1;
      }
      s++;
  }
    }
    else {
  int ascompat = rb_enc_asciicompat(enc);

  while (s < send) {
      unsigned int c;
      int n;

      if (ascompat && (c = *(unsigned char*)s) < 0x80) {
    if (rb_enc_isascii(c, enc) && 'A' <= c && c <= 'Z') {
        *s = 'a' + (c - 'A');
        modify = 1;
    }
    s++;
      }
      else {
    c = rb_enc_codepoint_len(s, send, &n, enc);
    if (rb_enc_isupper(c, enc)) {
        /* assuming toupper returns codepoint with same size */
        rb_enc_mbcput(rb_enc_tolower(c, enc), s, enc);
        modify = 1;
    }
    s += n;
      }
  }
    }

    if (modify) return str;
    return Qnil;
}

#dumpString

Produces a version of str with all non-printing characters replaced by \nnn notation and all special characters escaped.

"hello \n ''".dump  #=> "\"hello \\n ''\"

Returns:



5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
# File 'string.c', line 5464

VALUE
rb_str_dump(VALUE str)
{
    rb_encoding *enc = rb_enc_get(str);
    long len;
    const char *p, *pend;
    char *q, *qend;
    VALUE result;
    int u8 = (enc == rb_utf8_encoding());

    len = 2;      /* "" */
    p = RSTRING_PTR(str); pend = p + RSTRING_LEN(str);
    while (p < pend) {
  unsigned char c = *p++;
  switch (c) {
    case '"':  case '\\':
    case '\n': case '\r':
    case '\t': case '\f':
    case '\013': case '\010': case '\007': case '\033':
      len += 2;
      break;

    case '#':
      len += IS_EVSTR(p, pend) ? 2 : 1;
      break;

    default:
      if (ISPRINT(c)) {
    len++;
      }
      else {
    if (u8 && c > 0x7F) { /* \u{NN} */
        int n = rb_enc_precise_mbclen(p-1, pend, enc);
        if (MBCLEN_CHARFOUND_P(n)) {
      unsigned int cc = rb_enc_mbc_to_codepoint(p-1, pend, enc);
      while (cc >>= 4) len++;
      len += 5;
      p += MBCLEN_CHARFOUND_LEN(n)-1;
      break;
        }
    }
    len += 4; /* \xNN */
      }
      break;
  }
    }
    if (!rb_enc_asciicompat(enc)) {
  len += 19;   /* ".force_encoding('')" */
  len += strlen(enc->name);
    }

    result = rb_str_new_with_class(str, 0, len);
    p = RSTRING_PTR(str); pend = p + RSTRING_LEN(str);
    q = RSTRING_PTR(result); qend = q + len + 1;

    *q++ = '"';
    while (p < pend) {
  unsigned char c = *p++;

  if (c == '"' || c == '\\') {
      *q++ = '\\';
      *q++ = c;
  }
  else if (c == '#') {
      if (IS_EVSTR(p, pend)) *q++ = '\\';
      *q++ = '#';
  }
  else if (c == '\n') {
      *q++ = '\\';
      *q++ = 'n';
  }
  else if (c == '\r') {
      *q++ = '\\';
      *q++ = 'r';
  }
  else if (c == '\t') {
      *q++ = '\\';
      *q++ = 't';
  }
  else if (c == '\f') {
      *q++ = '\\';
      *q++ = 'f';
  }
  else if (c == '\013') {
      *q++ = '\\';
      *q++ = 'v';
  }
  else if (c == '\010') {
      *q++ = '\\';
      *q++ = 'b';
  }
  else if (c == '\007') {
      *q++ = '\\';
      *q++ = 'a';
  }
  else if (c == '\033') {
      *q++ = '\\';
      *q++ = 'e';
  }
  else if (ISPRINT(c)) {
      *q++ = c;
  }
  else {
      *q++ = '\\';
      if (u8) {
    int n = rb_enc_precise_mbclen(p-1, pend, enc) - 1;
    if (MBCLEN_CHARFOUND_P(n)) {
        int cc = rb_enc_mbc_to_codepoint(p-1, pend, enc);
        p += n;
        snprintf(q, qend-q, "u{%x}", cc);
        q += strlen(q);
        continue;
    }
      }
      snprintf(q, qend-q, "x%02X", c);
      q += 3;
  }
    }
    *q++ = '"';
    *q = '\0';
    if (!rb_enc_asciicompat(enc)) {
  snprintf(q, qend-q, ".force_encoding(\"%s\")", enc->name);
  enc = rb_ascii8bit_encoding();
    }
    OBJ_INFECT_RAW(result, str);
    /* result from dump is ASCII */
    rb_enc_associate(result, enc);
    ENC_CODERANGE_SET(result, ENC_CODERANGE_7BIT);
    return result;
}

#each_byte {|fixnum| ... } ⇒ String #each_byteObject

Passes each byte in str to the given block, or returns an enumerator if no block is given.

"hello".each_byte {|c| print c, ' ' }

produces:

104 101 108 108 111

Overloads:

  • #each_byte {|fixnum| ... } ⇒ String

    Yields:

    • (fixnum)

    Returns:



7209
7210
7211
7212
7213
# File 'string.c', line 7209

static VALUE
rb_str_each_byte(VALUE str)
{
    return rb_str_enumerate_bytes(str, 0);
}

#each_char {|cstr| ... } ⇒ String #each_charObject

Passes each character in str to the given block, or returns an enumerator if no block is given.

"hello".each_char {|c| print c, ' ' }

produces:

h e l l o

Overloads:

  • #each_char {|cstr| ... } ⇒ String

    Yields:

    • (cstr)

    Returns:



7313
7314
7315
7316
7317
# File 'string.c', line 7313

static VALUE
rb_str_each_char(VALUE str)
{
    return rb_str_enumerate_chars(str, 0);
}

#each_codepoint {|integer| ... } ⇒ String #each_codepointObject

Passes the Integer ordinal of each character in str, also known as a codepoint when applied to Unicode strings to the given block.

If no block is given, an enumerator is returned instead.

"hello\u0639".each_codepoint {|c| print c, ' ' }

produces:

104 101 108 108 111 1593

Overloads:

  • #each_codepoint {|integer| ... } ⇒ String

    Yields:

    • (integer)

    Returns:



7406
7407
7408
7409
7410
# File 'string.c', line 7406

static VALUE
rb_str_each_codepoint(VALUE str)
{
    return rb_str_enumerate_codepoints(str, 0);
}

#each_line(separator = $/) {|substr| ... } ⇒ String #each_line(separator = $/) ⇒ Object

Splits str using the supplied parameter as the record separator ($/ by default), passing each substring in turn to the supplied block. If a zero-length record separator is supplied, the string is split into paragraphs delimited by multiple successive newlines.

If no block is given, an enumerator is returned instead.

print "Example one\n"
"hello\nworld".each_line {|s| p s}
print "Example two\n"
"hello\nworld".each_line('l') {|s| p s}
print "Example three\n"
"hello\n\n\nworld".each_line('') {|s| p s}

produces:

Example one
"hello\n"
"world"
Example two
"hel"
"l"
"o\nworl"
"d"
Example three
"hello\n\n\n"
"world"

Overloads:

  • #each_line(separator = $/) {|substr| ... } ⇒ String

    Yields:

    • (substr)

    Returns:



7128
7129
7130
7131
7132
# File 'string.c', line 7128

static VALUE
rb_str_each_line(int argc, VALUE *argv, VALUE str)
{
    return rb_str_enumerate_lines(argc, argv, str, 0);
}

#empty?Boolean

Returns true if str has a length of zero.

"hello".empty?   #=> false
" ".empty?       #=> false
"".empty?        #=> true

Returns:

  • (Boolean)

Returns:

  • (Boolean)


1607
1608
1609
1610
1611
1612
1613
# File 'string.c', line 1607

static VALUE
rb_str_empty(VALUE str)
{
    if (RSTRING_LEN(str) == 0)
  return Qtrue;
    return Qfalse;
}

#encode(encoding[, options]) ⇒ String #encode(dst_encoding, src_encoding[, options]) ⇒ String #encode([options]) ⇒ String

The first form returns a copy of str transcoded to encoding encoding. The second form returns a copy of str transcoded from src_encoding to dst_encoding. The last form returns a copy of str transcoded to Encoding.default_internal.

By default, the first and second form raise Encoding::UndefinedConversionError for characters that are undefined in the destination encoding, and Encoding::InvalidByteSequenceError for invalid byte sequences in the source encoding. The last form by default does not raise exceptions but uses replacement strings.

The options Hash gives details for conversion and can have the following keys:

:invalid

If the value is :replace, #encode replaces invalid byte sequences in str with the replacement character. The default is to raise the Encoding::InvalidByteSequenceError exception

:undef

If the value is :replace, #encode replaces characters which are undefined in the destination encoding with the replacement character. The default is to raise the Encoding::UndefinedConversionError.

:replace

Sets the replacement string to the given value. The default replacement string is “uFFFD” for Unicode encoding forms, and “?” otherwise.

:fallback

Sets the replacement string by the given object for undefined character. The object should be a Hash, a Proc, a Method, or an object which has [] method. Its key is an undefined character encoded in the source encoding of current transcoder. Its value can be any encoding until it can be converted into the destination encoding of the transcoder.

:xml

The value must be :text or :attr. If the value is :text #encode replaces undefined characters with their (upper-case hexadecimal) numeric character references. '&', '<', and '>' are converted to “&amp;”, “&lt;”, and “&gt;”, respectively. If the value is :attr, #encode also quotes the replacement result (using '“'), and replaces '”' with “&quot;”.

:cr_newline

Replaces LF (“n”) with CR (“r”) if value is true.

:crlf_newline

Replaces LF (“n”) with CRLF (“rn”) if value is true.

:universal_newline

Replaces CRLF (“rn”) and CR (“r”) with LF (“n”) if value is true.

Overloads:

  • #encode(encoding[, options]) ⇒ String

    Returns:

  • #encode(dst_encoding, src_encoding[, options]) ⇒ String

    Returns:

  • #encode([options]) ⇒ String

    Returns:



2873
2874
2875
2876
2877
2878
2879
# File 'transcode.c', line 2873

static VALUE
str_encode(int argc, VALUE *argv, VALUE str)
{
    VALUE newstr = str;
    int encidx = str_transcode(argc, argv, &newstr);
    return encoded_dup(newstr, str, encidx);
}

#encode!(encoding[, options]) ⇒ String #encode!(dst_encoding, src_encoding[, options]) ⇒ String

The first form transcodes the contents of str from str.encoding to encoding. The second form transcodes the contents of str from src_encoding to dst_encoding. The options Hash gives details for conversion. See String#encode for details. Returns the string even if no changes were made.

Overloads:

  • #encode!(encoding[, options]) ⇒ String

    Returns:

  • #encode!(dst_encoding, src_encoding[, options]) ⇒ String

    Returns:



2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
# File 'transcode.c', line 2795

static VALUE
str_encode_bang(int argc, VALUE *argv, VALUE str)
{
    VALUE newstr;
    int encidx;

    rb_check_frozen(str);

    newstr = str;
    encidx = str_transcode(argc, argv, &newstr);

    if (encidx < 0) return str;
    if (newstr == str) {
  rb_enc_associate_index(str, encidx);
  return str;
    }
    rb_str_shared_replace(str, newstr);
    return str_encode_associate(str, encidx);
}

#encodingEncoding

Returns the Encoding object that represents the encoding of obj.

Returns:



991
992
993
994
995
996
997
998
999
# File 'encoding.c', line 991

VALUE
rb_obj_encoding(VALUE obj)
{
    int idx = rb_enc_get_index(obj);
    if (idx < 0) {
  rb_raise(rb_eTypeError, "unknown encoding");
    }
    return rb_enc_from_encoding_index(idx & ENC_INDEX_MASK);
}

#end_with?([suffixes]) ⇒ Boolean

Returns true if str ends with one of the suffixes given.

"hello".end_with?("ello")               #=> true

# returns true if one of the +suffixes+ matches.
"hello".end_with?("heaven", "ello")     #=> true
"hello".end_with?("heaven", "paradise") #=> false

Returns:

  • (Boolean)

Returns:

  • (Boolean)


8492
8493
8494
8495
8496
8497
8498
8499
8500
8501
8502
8503
8504
8505
8506
8507
8508
8509
8510
8511
8512
8513
# File 'string.c', line 8492

static VALUE
rb_str_end_with(int argc, VALUE *argv, VALUE str)
{
    int i;
    char *p, *s, *e;
    rb_encoding *enc;

    for (i=0; i<argc; i++) {
  VALUE tmp = argv[i];
  StringValue(tmp);
  enc = rb_enc_check(str, tmp);
  if (RSTRING_LEN(str) < RSTRING_LEN(tmp)) continue;
  p = RSTRING_PTR(str);
        e = p + RSTRING_LEN(str);
  s = e - RSTRING_LEN(tmp);
  if (rb_enc_left_char_head(p, s, e, enc) != s)
      continue;
  if (memcmp(s, RSTRING_PTR(tmp), RSTRING_LEN(tmp)) == 0)
      return Qtrue;
    }
    return Qfalse;
}

#eql?(other) ⇒ Boolean

Two strings are equal if they have the same length and content.

Returns:

  • (Boolean)

Returns:

  • (Boolean)


2861
2862
2863
2864
2865
2866
2867
# File 'string.c', line 2861

static VALUE
rb_str_eql(VALUE str1, VALUE str2)
{
    if (str1 == str2) return Qtrue;
    if (!RB_TYPE_P(str2, T_STRING)) return Qfalse;
    return str_eql(str1, str2);
}

#force_encoding(encoding) ⇒ String

Changes the encoding to encoding and returns self.

Returns:



8532
8533
8534
8535
8536
8537
8538
8539
# File 'string.c', line 8532

static VALUE
rb_str_force_encoding(VALUE str, VALUE enc)
{
    str_modifiable(str);
    rb_enc_associate(str, rb_to_encoding(enc));
    ENC_CODERANGE_CLEAR(str);
    return str;
}

#freezeObject



2246
2247
2248
2249
2250
2251
2252
# File 'string.c', line 2246

VALUE
rb_str_freeze(VALUE str)
{
    if (OBJ_FROZEN(str)) return str;
    rb_str_resize(str, RSTRING_LEN(str));
    return rb_obj_freeze(str);
}

#getbyte(index) ⇒ 0 .. 255

returns the indexth byte as an integer.

Returns:

  • (0 .. 255)


4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
# File 'string.c', line 4841

static VALUE
rb_str_getbyte(VALUE str, VALUE index)
{
    long pos = NUM2LONG(index);

    if (pos < 0)
        pos += RSTRING_LEN(str);
    if (pos < 0 ||  RSTRING_LEN(str) <= pos)
        return Qnil;

    return INT2FIX((unsigned char)RSTRING_PTR(str)[pos]);
}

#gsub(pattern, replacement) ⇒ String #gsub(pattern, hash) ⇒ String #gsub(pattern) {|match| ... } ⇒ String #gsub(pattern) ⇒ Object

Returns a copy of str with the all occurrences of pattern substituted for the second argument. The pattern is typically a Regexp; if given as a String, any regular expression metacharacters it contains will be interpreted literally, e.g. '\\d' will match a backlash followed by 'd', instead of a digit.

If replacement is a String it will be substituted for the matched text. It may contain back-references to the pattern's capture groups of the form \\d, where d is a group number, or \\k<n>, where n is a group name. If it is a double-quoted string, both back-references must be preceded by an additional backslash. However, within replacement the special match variables, such as $&, will not refer to the current match.

If the second argument is a Hash, and the matched text is one of its keys, the corresponding value is the replacement string.

In the block form, the current match string is passed in as a parameter, and variables such as $1, $2, $`, $&, and $' will be set appropriately. The value returned by the block will be substituted for the match on each call.

The result inherits any tainting in the original string or any supplied replacement string.

When neither a block nor a second argument is supplied, an Enumerator is returned.

"hello".gsub(/[aeiou]/, '*')                  #=> "h*ll*"
"hello".gsub(/([aeiou])/, '<\1>')             #=> "h<e>ll<o>"
"hello".gsub(/./) {|s| s.ord.to_s + ' '}      #=> "104 101 108 108 111 "
"hello".gsub(/(?<foo>[aeiou])/, '{\k<foo>}')  #=> "h{e}ll{o}"
'hello'.gsub(/[eo]/, 'e' => 3, 'o' => '*')    #=> "h3ll*"

Overloads:



4766
4767
4768
4769
4770
# File 'string.c', line 4766

static VALUE
rb_str_gsub(int argc, VALUE *argv, VALUE str)
{
    return str_gsub(argc, argv, str, 0);
}

#gsub!(pattern, replacement) ⇒ String? #gsub!(pattern, hash) ⇒ String? #gsub!(pattern) {|match| ... } ⇒ String? #gsub!(pattern) ⇒ Object

Performs the substitutions of String#gsub in place, returning str, or nil if no substitutions were performed. If no block and no replacement is given, an enumerator is returned instead.

Overloads:



4715
4716
4717
4718
4719
4720
# File 'string.c', line 4715

static VALUE
rb_str_gsub_bang(int argc, VALUE *argv, VALUE str)
{
    str_modify_keep_cr(str);
    return str_gsub(argc, argv, str, 1);
}

#hashFixnum

Return a hash based on the string's length, content and encoding.

See also Object#hash.

Returns:



2750
2751
2752
2753
2754
2755
# File 'string.c', line 2750

static VALUE
rb_str_hash_m(VALUE str)
{
    st_index_t hval = rb_str_hash(str);
    return INT2FIX(hval);
}

#hexInteger

Treats leading characters from str as a string of hexadecimal digits (with an optional sign and an optional 0x) and returns the corresponding number. Zero is returned on error.

"0x0a".hex     #=> 10
"-1234".hex    #=> -4660
"0".hex        #=> 0
"wombat".hex   #=> 0

Returns:



8030
8031
8032
8033
8034
# File 'string.c', line 8030

static VALUE
rb_str_hex(VALUE str)
{
    return rb_str_to_inum(str, 16, FALSE);
}

#include?(other_str) ⇒ Boolean

Returns true if str contains the given string or character.

"hello".include? "lo"   #=> true
"hello".include? "ol"   #=> false
"hello".include? ?h     #=> true

Returns:

  • (Boolean)

Returns:

  • (Boolean)


5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
# File 'string.c', line 5141

static VALUE
rb_str_include(VALUE str, VALUE arg)
{
    long i;

    StringValue(arg);
    i = rb_str_index(str, arg, 0);

    if (i == -1) return Qfalse;
    return Qtrue;
}

#index(substring[, offset]) ⇒ Fixnum? #index(regexp[, offset]) ⇒ Fixnum?

Returns the index of the first occurrence of the given substring or pattern (regexp) in str. Returns nil if not found. If the second parameter is present, it specifies the position in the string to begin the search.

"hello".index('e')             #=> 1
"hello".index('lo')            #=> 3
"hello".index('a')             #=> nil
"hello".index(?e)              #=> 1
"hello".index(/[aeiou]/, -3)   #=> 4

Overloads:

  • #index(substring[, offset]) ⇒ Fixnum?

    Returns:

  • #index(regexp[, offset]) ⇒ Fixnum?

    Returns:



3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
# File 'string.c', line 3049

static VALUE
rb_str_index_m(int argc, VALUE *argv, VALUE str)
{
    VALUE sub;
    VALUE initpos;
    long pos;

    if (rb_scan_args(argc, argv, "11", &sub, &initpos) == 2) {
  pos = NUM2LONG(initpos);
    }
    else {
  pos = 0;
    }
    if (pos < 0) {
  pos += str_strlen(str, NULL);
  if (pos < 0) {
      if (RB_TYPE_P(sub, T_REGEXP)) {
    rb_backref_set(Qnil);
      }
      return Qnil;
  }
    }

    if (SPECIAL_CONST_P(sub)) goto generic;
    switch (BUILTIN_TYPE(sub)) {
      case T_REGEXP:
  if (pos > str_strlen(str, NULL))
      return Qnil;
  pos = str_offset(RSTRING_PTR(str), RSTRING_END(str), pos,
       rb_enc_check(str, sub), single_byte_optimizable(str));

  pos = rb_reg_search(sub, str, pos, 0);
  pos = rb_str_sublen(str, pos);
  break;

      generic:
      default: {
  VALUE tmp;

  tmp = rb_check_string_type(sub);
  if (NIL_P(tmp)) {
      rb_raise(rb_eTypeError, "type mismatch: %s given",
         rb_obj_classname(sub));
  }
  sub = tmp;
      }
  /* fall through */
      case T_STRING:
  pos = rb_str_index(str, sub, pos);
  pos = rb_str_sublen(str, pos);
  break;
    }

    if (pos == -1) return Qnil;
    return LONG2NUM(pos);
}

#replace(other_str) ⇒ String

Replaces the contents and taintedness of str with the corresponding values in other_str.

s = "hello"         #=> "hello"
s.replace "world"   #=> "world"

Returns:



4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
# File 'string.c', line 4784

VALUE
rb_str_replace(VALUE str, VALUE str2)
{
    str_modifiable(str);
    if (str == str2) return str;

    StringValue(str2);
    str_discard(str);
    return str_replace(str, str2);
}

#insert(index, other_str) ⇒ String

Inserts other_str before the character at the given index, modifying str. Negative indices count from the end of the string, and insert after the given character. The intent is insert aString so that it starts at the given index.

"abcd".insert(0, 'X')    #=> "Xabcd"
"abcd".insert(3, 'X')    #=> "abcXd"
"abcd".insert(4, 'X')    #=> "abcdX"
"abcd".insert(-3, 'X')   #=> "abXcd"
"abcd".insert(-1, 'X')   #=> "abcdX"

Returns:



4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
# File 'string.c', line 4268

static VALUE
rb_str_insert(VALUE str, VALUE idx, VALUE str2)
{
    long pos = NUM2LONG(idx);

    if (pos == -1) {
  return rb_str_append(str, str2);
    }
    else if (pos < 0) {
  pos++;
    }
    rb_str_splice(str, pos, 0, str2);
    return str;
}

#inspectString

Returns a printable version of str, surrounded by quote marks, with special characters escaped.

str = "hello"
str[3] = "\b"
str.inspect       #=> "\"hel\\bo\""

Returns:



5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
# File 'string.c', line 5357

VALUE
rb_str_inspect(VALUE str)
{
    int encidx = ENCODING_GET(str);
    rb_encoding *enc = rb_enc_from_index(encidx), *actenc;
    const char *p, *pend, *prev;
    char buf[CHAR_ESC_LEN + 1];
    VALUE result = rb_str_buf_new(0);
    rb_encoding *resenc = rb_default_internal_encoding();
    int unicode_p = rb_enc_unicode_p(enc);
    int asciicompat = rb_enc_asciicompat(enc);

    if (resenc == NULL) resenc = rb_default_external_encoding();
    if (!rb_enc_asciicompat(resenc)) resenc = rb_usascii_encoding();
    rb_enc_associate(result, resenc);
    str_buf_cat2(result, "\"");

    p = RSTRING_PTR(str); pend = RSTRING_END(str);
    prev = p;
    actenc = get_actual_encoding(encidx, str);
    if (actenc != enc) {
  enc = actenc;
  if (unicode_p) unicode_p = rb_enc_unicode_p(enc);
    }
    while (p < pend) {
  unsigned int c, cc;
  int n;

        n = rb_enc_precise_mbclen(p, pend, enc);
        if (!MBCLEN_CHARFOUND_P(n)) {
      if (p > prev) str_buf_cat(result, prev, p - prev);
            n = rb_enc_mbminlen(enc);
            if (pend < p + n)
                n = (int)(pend - p);
            while (n--) {
                snprintf(buf, CHAR_ESC_LEN, "\\x%02X", *p & 0377);
                str_buf_cat(result, buf, strlen(buf));
                prev = ++p;
            }
      continue;
  }
        n = MBCLEN_CHARFOUND_LEN(n);
  c = rb_enc_mbc_to_codepoint(p, pend, enc);
  p += n;
  if ((asciicompat || unicode_p) &&
    (c == '"'|| c == '\\' ||
      (c == '#' &&
             p < pend &&
             MBCLEN_CHARFOUND_P(rb_enc_precise_mbclen(p,pend,enc)) &&
             (cc = rb_enc_codepoint(p,pend,enc),
              (cc == '$' || cc == '@' || cc == '{'))))) {
      if (p - n > prev) str_buf_cat(result, prev, p - n - prev);
      str_buf_cat2(result, "\\");
      if (asciicompat || enc == resenc) {
    prev = p - n;
    continue;
      }
  }
  switch (c) {
    case '\n': cc = 'n'; break;
    case '\r': cc = 'r'; break;
    case '\t': cc = 't'; break;
    case '\f': cc = 'f'; break;
    case '\013': cc = 'v'; break;
    case '\010': cc = 'b'; break;
    case '\007': cc = 'a'; break;
    case 033: cc = 'e'; break;
    default: cc = 0; break;
  }
  if (cc) {
      if (p - n > prev) str_buf_cat(result, prev, p - n - prev);
      buf[0] = '\\';
      buf[1] = (char)cc;
      str_buf_cat(result, buf, 2);
      prev = p;
      continue;
  }
  if ((enc == resenc && rb_enc_isprint(c, enc)) ||
      (asciicompat && rb_enc_isascii(c, enc) && ISPRINT(c))) {
      continue;
  }
  else {
      if (p - n > prev) str_buf_cat(result, prev, p - n - prev);
      rb_str_buf_cat_escaped_char(result, c, unicode_p);
      prev = p;
      continue;
  }
    }
    if (p > prev) str_buf_cat(result, prev, p - prev);
    str_buf_cat2(result, "\"");

    OBJ_INFECT_RAW(result, str);
    return result;
}

#internObject #to_symObject

Returns the Symbol corresponding to str, creating the symbol if it did not previously exist. See Symbol#id2name.

"Koala".intern         #=> :Koala
s = 'cat'.to_sym       #=> :cat
s == :cat              #=> true
s = '@cat'.to_sym      #=> :@cat
s == :@cat             #=> true

This can also be used to create symbols that cannot be represented using the :xxx notation.

'cat and dog'.to_sym   #=> :"cat and dog"


659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
# File 'symbol.c', line 659

VALUE
rb_str_intern(VALUE str)
{
#if USE_SYMBOL_GC
    rb_encoding *enc, *ascii;
    int type;
#else
    ID id;
#endif
    VALUE sym = lookup_str_sym(str);

    if (sym) {
  return sym;
    }

#if USE_SYMBOL_GC
    enc = rb_enc_get(str);
    ascii = rb_usascii_encoding();
    if (enc != ascii && sym_check_asciionly(str)) {
  str = rb_str_dup(str);
  rb_enc_associate(str, ascii);
  OBJ_FREEZE(str);
  enc = ascii;
    }
    else {
  str = rb_str_new_frozen(str);
    }
    str = rb_fstring(str);
    type = rb_str_symname_type(str, IDSET_ATTRSET_FOR_INTERN);
    if (type < 0) type = ID_JUNK;
    return dsymbol_alloc(rb_cSymbol, str, enc, type);
#else
    id = intern_str(str, 0);
    return ID2SYM(id);
#endif
}

#lengthInteger #sizeInteger

Returns the character length of str.

Overloads:



1574
1575
1576
1577
1578
# File 'string.c', line 1574

VALUE
rb_str_length(VALUE str)
{
    return LONG2NUM(str_strlen(str, NULL));
}

#lines(separator = $/) ⇒ Array

Returns an array of lines in str split using the supplied record separator ($/ by default). This is a shorthand for str.each_line(separator).to_a.

If a block is given, which is a deprecated form, works the same as each_line.

Returns:



7146
7147
7148
7149
7150
# File 'string.c', line 7146

static VALUE
rb_str_lines(int argc, VALUE *argv, VALUE str)
{
    return rb_str_enumerate_lines(argc, argv, str, 1);
}

#ljust(integer, padstr = ' ') ⇒ 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.

"hello".ljust(4)            #=> "hello"
"hello".ljust(20)           #=> "hello               "
"hello".ljust(20, '1234')   #=> "hello123412341234123"

Returns:



8312
8313
8314
8315
8316
# File 'string.c', line 8312

static VALUE
rb_str_ljust(int argc, VALUE *argv, VALUE str)
{
    return rb_str_justify(argc, argv, str, 'l');
}

#lstripString

Returns a copy of str with leading whitespace removed. See also String#rstrip and String#strip.

Refer to strip for the definition of whitespace.

"  hello  ".lstrip   #=> "hello  "
"hello".lstrip       #=> "hello"

Returns:



7742
7743
7744
7745
7746
7747
7748
7749
7750
7751
# File 'string.c', line 7742

static VALUE
rb_str_lstrip(VALUE str)
{
    char *start;
    long len, loffset;
    RSTRING_GETMEM(str, start, len);
    loffset = lstrip_offset(str, start, start+len, STR_ENC_GET(str));
    if (loffset <= 0) return rb_str_dup(str);
    return rb_str_subseq(str, loffset, len - loffset);
}

#lstrip!self?

Removes leading whitespace from str, returning nil if no change was made. See also String#rstrip! and String#strip!.

Refer to strip for the definition of whitespace.

"  hello  ".lstrip   #=> "hello  "
"hello".lstrip!      #=> nil

Returns:

  • (self, nil)


7704
7705
7706
7707
7708
7709
7710
7711
7712
7713
7714
7715
7716
7717
7718
7719
7720
7721
7722
7723
7724
7725
7726
# File 'string.c', line 7704

static VALUE
rb_str_lstrip_bang(VALUE str)
{
    rb_encoding *enc;
    char *start, *s;
    long olen, loffset;

    str_modify_keep_cr(str);
    enc = STR_ENC_GET(str);
    RSTRING_GETMEM(str, start, olen);
    loffset = lstrip_offset(str, start, start+olen, enc);
    if (loffset > 0) {
  long len = olen-loffset;
  s = start + loffset;
  memmove(start, s, len);
  STR_SET_LEN(str, len);
#if !SHARABLE_MIDDLE_SUBSTRING
  TERM_FILL(start+len, rb_enc_mbminlen(enc));
#endif
  return str;
    }
    return Qnil;
}

#match(pattern) ⇒ MatchData? #match(pattern, pos) ⇒ MatchData?

Converts pattern to a Regexp (if it isn't already one), then invokes its match method on str. If the second parameter is present, it specifies the position in the string to begin the search.

'hello'.match('(.)\1')      #=> #<MatchData "ll" 1:"l">
'hello'.match('(.)\1')[0]   #=> "ll"
'hello'.match(/(.)\1/)[0]   #=> "ll"
'hello'.match('xx')         #=> nil

If a block is given, invoke the block with MatchData if match succeed, so that you can write

str.match(pat) {|m| ...}

instead of

if m = str.match(pat)
  ...
end

The return value is a value from block execution in this case.

Overloads:



3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
# File 'string.c', line 3341

static VALUE
rb_str_match_m(int argc, VALUE *argv, VALUE str)
{
    VALUE re, result;
    if (argc < 1)
  rb_check_arity(argc, 1, 2);
    re = argv[0];
    argv[0] = str;
    result = rb_funcall2(get_pat(re), rb_intern("match"), argc, argv);
    if (!NIL_P(result) && rb_block_given_p()) {
  return rb_yield(result);
    }
    return result;
}

#succString #nextString

Returns the successor to str. The successor is calculated by incrementing characters starting from the rightmost alphanumeric (or the rightmost character if there are no alphanumerics) in the string. Incrementing a digit always results in another digit, and incrementing a letter results in another letter of the same case. Incrementing nonalphanumerics uses the underlying character set's collating sequence.

If the increment generates a “carry,'' the character to the left of it is incremented. This process repeats until there is no carry, adding an additional character if necessary.

"abcd".succ        #=> "abce"
"THX1138".succ     #=> "THX1139"
"<<koala>>".succ   #=> "<<koalb>>"
"1999zzz".succ     #=> "2000aaa"
"ZZZ9999".succ     #=> "AAAA0000"
"***".succ         #=> "**+"

Overloads:



3566
3567
3568
3569
3570
3571
3572
3573
3574
# File 'string.c', line 3566

VALUE
rb_str_succ(VALUE orig)
{
    VALUE str;
    str = rb_str_new_with_class(orig, RSTRING_PTR(orig), RSTRING_LEN(orig));
    rb_enc_cr_str_copy_for_substr(str, orig);
    OBJ_INFECT(str, orig);
    return str_succ(str);
}

#succ!String #next!String

Equivalent to String#succ, but modifies the receiver in place.

Overloads:



3673
3674
3675
3676
3677
3678
3679
# File 'string.c', line 3673

static VALUE
rb_str_succ_bang(VALUE str)
{
    rb_str_modify(str);
    str_succ(str);
    return str;
}

#octInteger

Treats leading characters of str as a string of octal digits (with an optional sign) and returns the corresponding number. Returns 0 if the conversion fails.

"123".oct       #=> 83
"-377".oct      #=> -255
"bad".oct       #=> 0
"0377bad".oct   #=> 255

If str starts with 0, radix indicators are hornored. See Kernel#Integer.

Returns:



8054
8055
8056
8057
8058
# File 'string.c', line 8054

static VALUE
rb_str_oct(VALUE str)
{
    return rb_str_to_inum(str, -8, FALSE);
}

#ordInteger

Return the Integer ordinal of a one-character string.

"a".ord         #=> 97

Returns:



8127
8128
8129
8130
8131
8132
8133
8134
# File 'string.c', line 8127

VALUE
rb_str_ord(VALUE s)
{
    unsigned int c;

    c = rb_enc_codepoint(RSTRING_PTR(s), RSTRING_END(s), STR_ENC_GET(s));
    return UINT2NUM(c);
}

#partition(sep) ⇒ Array #partition(regexp) ⇒ Array

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.

"hello".partition("l")         #=> ["he", "l", "lo"]
"hello".partition("x")         #=> ["hello", "", ""]
"hello".partition(/.l/)        #=> ["h", "el", "lo"]

Overloads:



8373
8374
8375
8376
8377
8378
8379
8380
8381
8382
8383
8384
8385
8386
8387
8388
8389
8390
8391
8392
8393
8394
8395
8396
# File 'string.c', line 8373

static VALUE
rb_str_partition(VALUE str, VALUE sep)
{
    long pos;

    sep = get_pat_quoted(sep, 0);
    if (RB_TYPE_P(sep, T_REGEXP)) {
  pos = rb_reg_search(sep, str, 0, 0);
  if (pos < 0) {
    failed:
      return rb_ary_new3(3, str, str_new_empty(str), str_new_empty(str));
  }
  sep = rb_str_subpat(str, sep, INT2FIX(0));
  if (pos == 0 && RSTRING_LEN(sep) == 0) goto failed;
    }
    else {
  pos = rb_str_index(str, sep, 0);
  if (pos < 0) goto failed;
    }
    return rb_ary_new3(3, rb_str_subseq(str, 0, pos),
              sep,
              rb_str_subseq(str, pos+RSTRING_LEN(sep),
               RSTRING_LEN(str)-pos-RSTRING_LEN(sep)));
}

#prepend(other_str) ⇒ String

Prepend—Prepend the given string to str.

a = "world"
a.prepend("hello ") #=> "hello world"
a                   #=> "hello world"

Returns:



2710
2711
2712
2713
2714
2715
2716
2717
# File 'string.c', line 2710

static VALUE
rb_str_prepend(VALUE str, VALUE str2)
{
    StringValue(str2);
    StringValue(str);
    rb_str_update(str, 0L, 0L, str2);
    return str;
}

#replace(other_str) ⇒ String

Replaces the contents and taintedness of str with the corresponding values in other_str.

s = "hello"         #=> "hello"
s.replace "world"   #=> "world"

Returns:



4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
# File 'string.c', line 4784

VALUE
rb_str_replace(VALUE str, VALUE str2)
{
    str_modifiable(str);
    if (str == str2) return str;

    StringValue(str2);
    str_discard(str);
    return str_replace(str, str2);
}

#reverseString

Returns a new string with the characters from str in reverse order.

"stressed".reverse   #=> "desserts"

Returns:



5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
# File 'string.c', line 5043

static VALUE
rb_str_reverse(VALUE str)
{
    rb_encoding *enc;
    VALUE rev;
    char *s, *e, *p;
    int cr;

    if (RSTRING_LEN(str) <= 1) return rb_str_dup(str);
    enc = STR_ENC_GET(str);
    rev = rb_str_new_with_class(str, 0, RSTRING_LEN(str));
    s = RSTRING_PTR(str); e = RSTRING_END(str);
    p = RSTRING_END(rev);
    cr = ENC_CODERANGE(str);

    if (RSTRING_LEN(str) > 1) {
  if (single_byte_optimizable(str)) {
      while (s < e) {
    *--p = *s++;
      }
  }
  else if (cr == ENC_CODERANGE_VALID) {
      while (s < e) {
    int clen = rb_enc_fast_mbclen(s, e, enc);

    p -= clen;
    memcpy(p, s, clen);
    s += clen;
      }
  }
  else {
      cr = rb_enc_asciicompat(enc) ?
    ENC_CODERANGE_7BIT : ENC_CODERANGE_VALID;
      while (s < e) {
    int clen = rb_enc_mbclen(s, e, enc);

    if (clen > 1 || (*s & 0x80)) cr = ENC_CODERANGE_UNKNOWN;
    p -= clen;
    memcpy(p, s, clen);
    s += clen;
      }
  }
    }
    STR_SET_LEN(rev, RSTRING_LEN(str));
    OBJ_INFECT_RAW(rev, str);
    str_enc_copy(rev, str);
    ENC_CODERANGE_SET(rev, cr);

    return rev;
}

#reverse!String

Reverses str in place.

Returns:



5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
# File 'string.c', line 5102

static VALUE
rb_str_reverse_bang(VALUE str)
{
    if (RSTRING_LEN(str) > 1) {
  if (single_byte_optimizable(str)) {
      char *s, *e, c;

      str_modify_keep_cr(str);
      s = RSTRING_PTR(str);
      e = RSTRING_END(str) - 1;
      while (s < e) {
    c = *s;
    *s++ = *e;
    *e-- = c;
      }
  }
  else {
      str_shared_replace(str, rb_str_reverse(str));
  }
    }
    else {
  str_modify_keep_cr(str);
    }
    return str;
}

#rindex(substring[, fixnum]) ⇒ Fixnum? #rindex(regexp[, fixnum]) ⇒ Fixnum?

Returns the index of the last occurrence of the given substring or pattern (regexp) in str. Returns nil if not found. If the second parameter is present, it specifies the position in the string to end the search—characters beyond this point will not be considered.

"hello".rindex('e')             #=> 1
"hello".rindex('l')             #=> 3
"hello".rindex('a')             #=> nil
"hello".rindex(?e)              #=> 1
"hello".rindex(/[aeiou]/, -2)   #=> 1

Overloads:

  • #rindex(substring[, fixnum]) ⇒ Fixnum?

    Returns:

  • #rindex(regexp[, fixnum]) ⇒ Fixnum?

    Returns:



3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
# File 'string.c', line 3214

static VALUE
rb_str_rindex_m(int argc, VALUE *argv, VALUE str)
{
    VALUE sub;
    VALUE vpos;
    rb_encoding *enc = STR_ENC_GET(str);
    long pos, len = str_strlen(str, enc); /* str's enc */

    if (rb_scan_args(argc, argv, "11", &sub, &vpos) == 2) {
  pos = NUM2LONG(vpos);
  if (pos < 0) {
      pos += len;
      if (pos < 0) {
    if (RB_TYPE_P(sub, T_REGEXP)) {
        rb_backref_set(Qnil);
    }
    return Qnil;
      }
  }
  if (pos > len) pos = len;
    }
    else {
  pos = len;
    }

    if (SPECIAL_CONST_P(sub)) goto generic;
    switch (BUILTIN_TYPE(sub)) {
      case T_REGEXP:
  /* enc = rb_get_check(str, sub); */
  pos = str_offset(RSTRING_PTR(str), RSTRING_END(str), pos,
       enc, single_byte_optimizable(str));

  if (!RREGEXP(sub)->ptr || RREGEXP_SRC_LEN(sub)) {
      pos = rb_reg_search(sub, str, pos, 1);
      pos = rb_str_sublen(str, pos);
  }
  if (pos >= 0) return LONG2NUM(pos);
  break;

      generic:
      default: {
  VALUE tmp;

  tmp = rb_check_string_type(sub);
  if (NIL_P(tmp)) {
      rb_raise(rb_eTypeError, "type mismatch: %s given",
         rb_obj_classname(sub));
  }
  sub = tmp;
      }
  /* fall through */
      case T_STRING:
  pos = rb_str_rindex(str, sub, pos);
  if (pos >= 0) return LONG2NUM(pos);
  break;
    }
    return Qnil;
}

#rjust(integer, padstr = ' ') ⇒ 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.

"hello".rjust(4)            #=> "hello"
"hello".rjust(20)           #=> "               hello"
"hello".rjust(20, '1234')   #=> "123412341234123hello"

Returns:



8332
8333
8334
8335
8336
# File 'string.c', line 8332

static VALUE
rb_str_rjust(int argc, VALUE *argv, VALUE str)
{
    return rb_str_justify(argc, argv, str, 'r');
}

#rpartition(sep) ⇒ Array #rpartition(regexp) ⇒ Array

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.

"hello".rpartition("l")         #=> ["hel", "l", "o"]
"hello".rpartition("x")         #=> ["", "", "hello"]
"hello".rpartition(/.l/)        #=> ["he", "ll", "o"]

Overloads:



8413
8414
8415
8416
8417
8418
8419
8420
8421
8422
8423
8424
8425
8426
8427
8428
8429
8430
8431
8432
8433
8434
8435
8436
8437
8438
8439
8440
8441
8442
8443
8444
8445
8446
8447
8448
# File 'string.c', line 8413

static VALUE
rb_str_rpartition(VALUE str, VALUE sep)
{
    long pos = RSTRING_LEN(str);
    int regex = FALSE;

    if (RB_TYPE_P(sep, T_REGEXP)) {
  pos = rb_reg_search(sep, str, pos, 1);
  regex = TRUE;
    }
    else {
  VALUE tmp;

  tmp = rb_check_string_type(sep);
  if (NIL_P(tmp)) {
      rb_raise(rb_eTypeError, "type mismatch: %s given",
         rb_obj_classname(sep));
  }
  sep = tmp;
  pos = rb_str_sublen(str, pos);
  pos = rb_str_rindex(str, sep, pos);
    }
    if (pos < 0) {
  return rb_ary_new3(3, str_new_empty(str), str_new_empty(str), str);
    }
    if (regex) {
  sep = rb_reg_nth_match(0, rb_backref_get());
    }
    else {
  pos = rb_str_offset(str, pos);
    }
    return rb_ary_new3(3, rb_str_subseq(str, 0, pos),
              sep,
              rb_str_subseq(str, pos+RSTRING_LEN(sep),
          RSTRING_LEN(str)-pos-RSTRING_LEN(sep)));
}

#rstripString

Returns a copy of str with trailing whitespace removed. See also String#lstrip and String#strip.

Refer to strip for the definition of whitespace.

"  hello  ".rstrip   #=> "  hello"
"hello".rstrip       #=> "hello"

Returns:



7830
7831
7832
7833
7834
7835
7836
7837
7838
7839
7840
7841
7842
7843
# File 'string.c', line 7830

static VALUE
rb_str_rstrip(VALUE str)
{
    rb_encoding *enc;
    char *start;
    long olen, roffset;

    enc = STR_ENC_GET(str);
    RSTRING_GETMEM(str, start, olen);
    roffset = rstrip_offset(str, start, start+olen, enc);

    if (roffset <= 0) return rb_str_dup(str);
    return rb_str_subseq(str, 0, olen-roffset);
}

#rstrip!self?

Removes trailing whitespace from str, returning nil if no change was made. See also String#lstrip! and String#strip!.

Refer to strip for the definition of whitespace.

"  hello  ".rstrip   #=> "  hello"
"hello".rstrip!      #=> nil

Returns:

  • (self, nil)


7793
7794
7795
7796
7797
7798
7799
7800
7801
7802
7803
7804
7805
7806
7807
7808
7809
7810
7811
7812
7813
7814
# File 'string.c', line 7793

static VALUE
rb_str_rstrip_bang(VALUE str)
{
    rb_encoding *enc;
    char *start;
    long olen, roffset;

    str_modify_keep_cr(str);
    enc = STR_ENC_GET(str);
    RSTRING_GETMEM(str, start, olen);
    roffset = rstrip_offset(str, start, start+olen, enc);
    if (roffset > 0) {
  long len = olen - roffset;

  STR_SET_LEN(str, len);
#if !SHARABLE_MIDDLE_SUBSTRING
  TERM_FILL(start+len, rb_enc_mbminlen(enc));
#endif
  return str;
    }
    return Qnil;
}

#scan(pattern) ⇒ Array #scan(pattern) {|match, ...| ... } ⇒ String

Both forms iterate through str, 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, $&. If the pattern contains groups, each individual result is itself an array containing one entry per group.

a = "cruel world"
a.scan(/\w+/)        #=> ["cruel", "world"]
a.scan(/.../)        #=> ["cru", "el ", "wor"]
a.scan(/(...)/)      #=> [["cru"], ["el "], ["wor"]]
a.scan(/(..)(..)/)   #=> [["cr", "ue"], ["l ", "wo"]]

And the block form:

a.scan(/\w+/) {|w| print "<<#{w}>> " }
print "\n"
a.scan(/(.)(.)/) {|x,y| print y, x }
print "\n"

produces:

"rceu lowlr\n">> "">>

Overloads:



7983
7984
7985
7986
7987
7988
7989
7990
7991
7992
7993
7994
7995
7996
7997
7998
7999
8000
8001
8002
8003
8004
8005
8006
8007
8008
8009
8010
8011
8012
8013
# File 'string.c', line 7983

static VALUE
rb_str_scan(VALUE str, VALUE pat)
{
    VALUE result;
    long start = 0;
    long last = -1, prev = 0;
    char *p = RSTRING_PTR(str); long len = RSTRING_LEN(str);

    pat = get_pat_quoted(pat, 1);
    mustnot_broken(str);
    if (!rb_block_given_p()) {
  VALUE ary = rb_ary_new();

  while (!NIL_P(result = scan_once(str, pat, &start))) {
      last = prev;
      prev = start;
      rb_ary_push(ary, result);
  }
  if (last >= 0) rb_pat_search(pat, str, last, 1);
  return ary;
    }

    while (!NIL_P(result = scan_once(str, pat, &start))) {
  last = prev;
  prev = start;
  rb_yield(result);
  str_mod_check(str, p, len);
    }
    if (last >= 0) rb_pat_search(pat, str, last, 1);
    return str;
}

#scrubString #scrub(repl) ⇒ String #scrub {|bytes| ... } ⇒ String

If the string is invalid byte sequence then replace invalid bytes with given replacement character, else returns self. If block is given, replace invalid bytes with returned value of the block.

"abc\u3042\x81".scrub #=> "abc\u3042\uFFFD"
"abc\u3042\x81".scrub("*") #=> "abc\u3042*"
"abc\u3042\xE3\x80".scrub{|bytes| '<'+bytes.unpack('H*')[0]+'>' } #=> "abc\u3042<e380>"

Overloads:



8923
8924
8925
8926
8927
8928
8929
# File 'string.c', line 8923

static VALUE
str_scrub(int argc, VALUE *argv, VALUE str)
{
    VALUE repl = argc ? (rb_check_arity(argc, 0, 1), argv[0]) : Qnil;
    VALUE new = rb_str_scrub(str, repl);
    return NIL_P(new) ? rb_str_dup(str): new;
}

#scrub!String #scrub!(repl) ⇒ String #scrub! {|bytes| ... } ⇒ String

If the string is invalid byte sequence then replace invalid bytes with given replacement character, else returns self. If block is given, replace invalid bytes with returned value of the block.

"abc\u3042\x81".scrub! #=> "abc\u3042\uFFFD"
"abc\u3042\x81".scrub!("*") #=> "abc\u3042*"
"abc\u3042\xE3\x80".scrub!{|bytes| '<'+bytes.unpack('H*')[0]+'>' } #=> "abc\u3042<e380>"

Overloads:



8945
8946
8947
8948
8949
8950
8951
8952
# File 'string.c', line 8945

static VALUE
str_scrub_bang(int argc, VALUE *argv, VALUE str)
{
    VALUE repl = argc ? (rb_check_arity(argc, 0, 1), argv[0]) : Qnil;
    VALUE new = rb_str_scrub(str, repl);
    if (!NIL_P(new)) rb_str_replace(str, new);
    return str;
}

#setbyte(index, integer) ⇒ Integer

modifies the indexth byte as integer.

Returns:



4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
# File 'string.c', line 4860

static VALUE
rb_str_setbyte(VALUE str, VALUE index, VALUE value)
{
    long pos = NUM2LONG(index);
    int byte = NUM2INT(value);
    long len = RSTRING_LEN(str);
    char *head, *ptr, *left = 0;
    rb_encoding *enc;
    int cr = ENC_CODERANGE_UNKNOWN, width, nlen;

    if (pos < -len || len <= pos)
        rb_raise(rb_eIndexError, "index %ld out of string", pos);
    if (pos < 0)
        pos += len;

    if (!str_independent(str))
  str_make_independent(str);
    enc = STR_ENC_GET(str);
    head = RSTRING_PTR(str);
    ptr = &head[pos];
    if (len > RSTRING_EMBED_LEN_MAX) {
  cr = ENC_CODERANGE(str);
  switch (cr) {
    case ENC_CODERANGE_7BIT:
      left = ptr;
      *ptr = byte;
      if (ISASCII(byte)) break;
      nlen = rb_enc_precise_mbclen(left, head+len, enc);
      if (!MBCLEN_CHARFOUND_P(nlen))
    ENC_CODERANGE_SET(str, ENC_CODERANGE_BROKEN);
      else
    ENC_CODERANGE_SET(str, ENC_CODERANGE_VALID);
      goto end;
    case ENC_CODERANGE_VALID:
      left = rb_enc_left_char_head(head, ptr, head+len, enc);
      width = rb_enc_precise_mbclen(left, head+len, enc);
      *ptr = byte;
      nlen = rb_enc_precise_mbclen(left, head+len, enc);
      if (!MBCLEN_CHARFOUND_P(nlen))
    ENC_CODERANGE_SET(str, ENC_CODERANGE_BROKEN);
      else if (MBCLEN_CHARFOUND_LEN(nlen) != width || ISASCII(byte))
    ENC_CODERANGE_CLEAR(str);
      goto end;
  }
    }
    ENC_CODERANGE_CLEAR(str);
    *ptr = byte;

  end:
    return value;
}

#lengthInteger #sizeInteger

Returns the character length of str.

Overloads:



1574
1575
1576
1577
1578
# File 'string.c', line 1574

VALUE
rb_str_length(VALUE str)
{
    return LONG2NUM(str_strlen(str, NULL));
}

#[](index) ⇒ String? #[](start, length) ⇒ String? #[](range) ⇒ String? #[](regexp) ⇒ String? #[](regexp, capture) ⇒ String? #[](match_str) ⇒ String? #slice(index) ⇒ String? #slice(start, length) ⇒ String? #slice(range) ⇒ String? #slice(regexp) ⇒ String? #slice(regexp, capture) ⇒ String? #slice(match_str) ⇒ String?

Element Reference — If passed a single index, returns a substring of one character at that index. If passed a start index and a length, returns a substring containing length characters starting at the start index. If passed a range, its beginning and end are interpreted as offsets delimiting the substring to be returned.

In these three cases, if an index is negative, it is counted from the end of the string. For the start and range cases the starting index is just before a character and an index matching the string's size. Additionally, an empty string is returned when the starting index for a character range is at the end of the string.

Returns nil if the initial index falls outside the string or the length is negative.

If a Regexp is supplied, the matching portion of the string is returned. If a capture follows the regular expression, which may be a capture group index or name, follows the regular expression that component of the MatchData is returned instead.

If a match_str is given, that string is returned if it occurs in the string.

Returns nil if the regular expression does not match or the match string cannot be found.

a = "hello there"

a[1]                   #=> "e"
a[2, 3]                #=> "llo"
a[2..3]                #=> "ll"

a[-3, 2]               #=> "er"
a[7..-2]               #=> "her"
a[-4..-2]              #=> "her"
a[-2..-4]              #=> ""

a[11, 0]               #=> ""
a[11]                  #=> nil
a[12, 0]               #=> nil
a[12..-1]              #=> nil

a[/[aeiou](.)\1/]      #=> "ell"
a[/[aeiou](.)\1/, 0]   #=> "ell"
a[/[aeiou](.)\1/, 1]   #=> "l"
a[/[aeiou](.)\1/, 2]   #=> nil

a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "non_vowel"] #=> "l"
a[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "vowel"]     #=> "e"

a["lo"]                #=> "lo"
a["bye"]               #=> nil

Overloads:



4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
# File 'string.c', line 4007

static VALUE
rb_str_aref_m(int argc, VALUE *argv, VALUE str)
{
    if (argc == 2) {
  if (RB_TYPE_P(argv[0], T_REGEXP)) {
      return rb_str_subpat(str, argv[0], argv[1]);
  }
  return rb_str_substr(str, NUM2LONG(argv[0]), NUM2LONG(argv[1]));
    }
    rb_check_arity(argc, 1, 2);
    return rb_str_aref(str, argv[0]);
}

#slice!(fixnum) ⇒ String? #slice!(fixnum, fixnum) ⇒ String? #slice!(range) ⇒ String? #slice!(regexp) ⇒ String? #slice!(other_str) ⇒ String?

Deletes the specified portion from str, and returns the portion deleted.

string = "this is a string"
string.slice!(2)        #=> "i"
string.slice!(3..6)     #=> " is "
string.slice!(/s.*t/)   #=> "sa st"
string.slice!("r")      #=> "r"
string                  #=> "thing"

Overloads:



4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
# File 'string.c', line 4303

static VALUE
rb_str_slice_bang(int argc, VALUE *argv, VALUE str)
{
    VALUE result;
    VALUE buf[3];
    int i;

    rb_check_arity(argc, 1, 2);
    for (i=0; i<argc; i++) {
  buf[i] = argv[i];
    }
    str_modify_keep_cr(str);
    result = rb_str_aref_m(argc, buf, str);
    if (!NIL_P(result)) {
  buf[i] = rb_str_new(0,0);
  rb_str_aset_m(argc+1, buf, str);
    }
    return result;
}

#split(pattern = nil, [limit]) ⇒ Array

Divides str into substrings based on a delimiter, returning an array of these substrings.

If pattern is a String, then its contents are used as the delimiter when splitting str. If pattern is a single space, str is split on whitespace, with leading whitespace and runs of contiguous whitespace characters ignored.

If pattern is a Regexp, str is divided where the pattern matches. Whenever the pattern matches a zero-length string, str is split into individual characters. If pattern contains groups, the respective matches will be returned in the array as well.

If pattern is nil, the value of $; is used. If $; is nil (which is the default), str is split on whitespace as if ` ' were specified.

If the limit parameter is omitted, trailing null fields are suppressed. If limit is a positive number, at most that number of fields will be returned (if limit is 1, the entire string is returned as the only entry in an array). If negative, there is no limit to the number of fields returned, and trailing null fields are not suppressed.

When the input str is empty an empty Array is returned as the string is considered to have no fields to split.

" now's  the time".split        #=> ["now's", "the", "time"]
" now's  the time".split(' ')   #=> ["now's", "the", "time"]
" now's  the time".split(/ /)   #=> ["", "now's", "", "the", "time"]
"1, 2.34,56, 7".split(%r{,\s*}) #=> ["1", "2.34", "56", "7"]
"hello".split(//)               #=> ["h", "e", "l", "l", "o"]
"hello".split(//, 3)            #=> ["h", "e", "llo"]
"hi mom".split(%r{\s*})         #=> ["h", "i", "m", "o", "m"]

"mellow yellow".split("ello")   #=> ["m", "w y", "w"]
"1,2,,3,4,,".split(',')         #=> ["1", "2", "", "3", "4"]
"1,2,,3,4,,".split(',', 4)      #=> ["1", "2", "", "3,4,,"]
"1,2,,3,4,,".split(',', -4)     #=> ["1", "2", "", "3", "4", "", ""]

"".split(',', -1)               #=> []

Returns:



6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
# File 'string.c', line 6762

static VALUE
rb_str_split_m(int argc, VALUE *argv, VALUE str)
{
    rb_encoding *enc;
    VALUE spat;
    VALUE limit;
    enum {awk, string, regexp} split_type;
    long beg, end, i = 0;
    int lim = 0;
    VALUE result, tmp;

    if (rb_scan_args(argc, argv, "02", &spat, &limit) == 2) {
  lim = NUM2INT(limit);
  if (lim <= 0) limit = Qnil;
  else if (lim == 1) {
      if (RSTRING_LEN(str) == 0)
    return rb_ary_new2(0);
      return rb_ary_new3(1, str);
  }
  i = 1;
    }

    enc = STR_ENC_GET(str);
    if (NIL_P(spat) && NIL_P(spat = rb_fs)) {
  split_type = awk;
    }
    else {
  spat = get_pat_quoted(spat, 0);
  if (BUILTIN_TYPE(spat) == T_STRING) {
      rb_encoding *enc2 = STR_ENC_GET(spat);

      mustnot_broken(spat);
      split_type = string;
      if (RSTRING_LEN(spat) == 0) {
    /* Special case - split into chars */
    spat = rb_reg_regcomp(spat);
    split_type = regexp;
      }
      else if (rb_enc_asciicompat(enc2) == 1) {
    if (RSTRING_LEN(spat) == 1 && RSTRING_PTR(spat)[0] == ' '){
        split_type = awk;
    }
      }
      else {
    int l;
    if (rb_enc_ascget(RSTRING_PTR(spat), RSTRING_END(spat), &l, enc2) == ' ' &&
        RSTRING_LEN(spat) == l) {
        split_type = awk;
    }
      }
  }
  else {
      split_type = regexp;
  }
    }

    result = rb_ary_new();
    beg = 0;
    if (split_type == awk) {
  char *ptr = RSTRING_PTR(str);
  char *eptr = RSTRING_END(str);
  char *bptr = ptr;
  int skip = 1;
  unsigned int c;

  end = beg;
  if (is_ascii_string(str)) {
      while (ptr < eptr) {
    c = (unsigned char)*ptr++;
    if (skip) {
        if (ascii_isspace(c)) {
      beg = ptr - bptr;
        }
        else {
      end = ptr - bptr;
      skip = 0;
      if (!NIL_P(limit) && lim <= i) break;
        }
    }
    else if (ascii_isspace(c)) {
        rb_ary_push(result, rb_str_subseq(str, beg, end-beg));
        skip = 1;
        beg = ptr - bptr;
        if (!NIL_P(limit)) ++i;
    }
    else {
        end = ptr - bptr;
    }
      }
  }
  else {
      while (ptr < eptr) {
    int n;

    c = rb_enc_codepoint_len(ptr, eptr, &n, enc);
    ptr += n;
    if (skip) {
        if (rb_isspace(c)) {
      beg = ptr - bptr;
        }
        else {
      end = ptr - bptr;
      skip = 0;
      if (!NIL_P(limit) && lim <= i) break;
        }
    }
    else if (rb_isspace(c)) {
        rb_ary_push(result, rb_str_subseq(str, beg, end-beg));
        skip = 1;
        beg = ptr - bptr;
        if (!NIL_P(limit)) ++i;
    }
    else {
        end = ptr - bptr;
    }
      }
  }
    }
    else if (split_type == string) {
  char *ptr = RSTRING_PTR(str);
  char *temp = ptr;
  char *eptr = RSTRING_END(str);
  char *sptr = RSTRING_PTR(spat);
  long slen = RSTRING_LEN(spat);

  mustnot_broken(str);
  enc = rb_enc_check(str, spat);
  while (ptr < eptr &&
         (end = rb_memsearch(sptr, slen, ptr, eptr - ptr, enc)) >= 0) {
      /* Check we are at the start of a char */
      char *t = rb_enc_right_char_head(ptr, ptr + end, eptr, enc);
      if (t != ptr + end) {
    ptr = t;
    continue;
      }
      rb_ary_push(result, rb_str_subseq(str, ptr - temp, end));
      ptr += end + slen;
      if (!NIL_P(limit) && lim <= ++i) break;
  }
  beg = ptr - temp;
    }
    else {
  char *ptr = RSTRING_PTR(str);
  long len = RSTRING_LEN(str);
  long start = beg;
  long idx;
  int last_null = 0;
  struct re_registers *regs;

  while ((end = rb_reg_search(spat, str, start, 0)) >= 0) {
      regs = RMATCH_REGS(rb_backref_get());
      if (start == end && BEG(0) == END(0)) {
    if (!ptr) {
        rb_ary_push(result, str_new_empty(str));
        break;
    }
    else if (last_null == 1) {
        rb_ary_push(result, rb_str_subseq(str, beg,
                  rb_enc_fast_mbclen(ptr+beg,
                   ptr+len,
                   enc)));
        beg = start;
    }
    else {
                    if (ptr+start == ptr+len)
                        start++;
                    else
                        start += rb_enc_fast_mbclen(ptr+start,ptr+len,enc);
        last_null = 1;
        continue;
    }
      }
      else {
    rb_ary_push(result, rb_str_subseq(str, beg, end-beg));
    beg = start = END(0);
      }
      last_null = 0;

      for (idx=1; idx < regs->num_regs; idx++) {
    if (BEG(idx) == -1) continue;
    if (BEG(idx) == END(idx))
        tmp = str_new_empty(str);
    else
        tmp = rb_str_subseq(str, BEG(idx), END(idx)-BEG(idx));
    rb_ary_push(result, tmp);
      }
      if (!NIL_P(limit) && lim <= ++i) break;
  }
    }
    if (RSTRING_LEN(str) > 0 && (!NIL_P(limit) || RSTRING_LEN(str) > beg || lim < 0)) {
  if (RSTRING_LEN(str) == beg)
      tmp = str_new_empty(str);
  else
      tmp = rb_str_subseq(str, beg, RSTRING_LEN(str)-beg);
  rb_ary_push(result, tmp);
    }
    if (NIL_P(limit) && lim == 0) {
  long len;
  while ((len = RARRAY_LEN(result)) > 0 &&
         (tmp = RARRAY_AREF(result, len-1), RSTRING_LEN(tmp) == 0))
      rb_ary_pop(result);
    }

    return result;
}

#squeeze([other_str]) ⇒ String

Builds a set of characters from the other_str parameter(s) using the procedure described for String#count. Returns a new string where runs of the same character that occur in this set are replaced by a single character. If no arguments are given, all runs of identical characters are replaced by a single character.

"yellow moon".squeeze                  #=> "yelow mon"
"  now   is  the".squeeze(" ")         #=> " now is the"
"putters shoot balls".squeeze("m-z")   #=> "puters shot balls"

Returns:



6551
6552
6553
6554
6555
6556
6557
# File 'string.c', line 6551

static VALUE
rb_str_squeeze(int argc, VALUE *argv, VALUE str)
{
    str = rb_str_dup(str);
    rb_str_squeeze_bang(argc, argv, str);
    return str;
}

#squeeze!([other_str]) ⇒ String?

Squeezes str in place, returning either str, or nil if no changes were made.

Returns:



6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
# File 'string.c', line 6460

static VALUE
rb_str_squeeze_bang(int argc, VALUE *argv, VALUE str)
{
    char squeez[TR_TABLE_SIZE];
    rb_encoding *enc = 0;
    VALUE del = 0, nodel = 0;
    char *s, *send, *t;
    int i, modify = 0;
    int ascompat, singlebyte = single_byte_optimizable(str);
    unsigned int save;

    if (argc == 0) {
  enc = STR_ENC_GET(str);
    }
    else {
  for (i=0; i<argc; i++) {
      VALUE s = argv[i];

      StringValue(s);
      enc = rb_enc_check(str, s);
      if (singlebyte && !single_byte_optimizable(s))
    singlebyte = 0;
      tr_setup_table(s, squeez, i==0, &del, &nodel, enc);
  }
    }

    str_modify_keep_cr(str);
    s = t = RSTRING_PTR(str);
    if (!s || RSTRING_LEN(str) == 0) return Qnil;
    send = RSTRING_END(str);
    save = -1;
    ascompat = rb_enc_asciicompat(enc);

    if (singlebyte) {
        while (s < send) {
      unsigned int c = *(unsigned char*)s++;
      if (c != save || (argc > 0 && !squeez[c])) {
          *t++ = save = c;
      }
  }
    }
    else {
  while (s < send) {
      unsigned int c;
      int clen;

      if (ascompat && (c = *(unsigned char*)s) < 0x80) {
    if (c != save || (argc > 0 && !squeez[c])) {
        *t++ = save = c;
    }
    s++;
      }
      else {
    c = rb_enc_codepoint_len(s, send, &clen, enc);

    if (c != save || (argc > 0 && !tr_find(c, squeez, del, nodel))) {
        if (t != s) rb_enc_mbcput(c, t, enc);
        save = c;
        t += clen;
    }
    s += clen;
      }
  }
    }

    TERM_FILL(t, TERM_LEN(str));
    if (t - RSTRING_PTR(str) != RSTRING_LEN(str)) {
  STR_SET_LEN(str, t - RSTRING_PTR(str));
  modify = 1;
    }

    if (modify) return str;
    return Qnil;
}

#start_with?([prefixes]) ⇒ Boolean

Returns true if str starts with one of the prefixes given.

"hello".start_with?("hell")               #=> true

# returns true if one of the prefixes matches.
"hello".start_with?("heaven", "hell")     #=> true
"hello".start_with?("heaven", "paradise") #=> false

Returns:

  • (Boolean)

Returns:

  • (Boolean)


8463
8464
8465
8466
8467
8468
8469
8470
8471
8472
8473
8474
8475
8476
8477
# File 'string.c', line 8463

static VALUE
rb_str_start_with(int argc, VALUE *argv, VALUE str)
{
    int i;

    for (i=0; i<argc; i++) {
  VALUE tmp = argv[i];
  StringValue(tmp);
  rb_enc_check(str, tmp);
  if (RSTRING_LEN(str) < RSTRING_LEN(tmp)) continue;
  if (memcmp(RSTRING_PTR(str), RSTRING_PTR(tmp), RSTRING_LEN(tmp)) == 0)
      return Qtrue;
    }
    return Qfalse;
}

#stripString

Returns a copy of str with leading and trailing whitespace removed.

Whitespace is defined as any of the following characters: null, horizontal tab, line feed, vertical tab, form feed, carriage return, space.

"    hello    ".strip   #=> "hello"
"\tgoodbye\r\n".strip   #=> "goodbye"
"\x00\t\n\v\f\r ".strip #=> ""

Returns:



7899
7900
7901
7902
7903
7904
7905
7906
7907
7908
7909
7910
7911
7912
# File 'string.c', line 7899

static VALUE
rb_str_strip(VALUE str)
{
    char *start;
    long olen, loffset, roffset;
    rb_encoding *enc = STR_ENC_GET(str);

    RSTRING_GETMEM(str, start, olen);
    loffset = lstrip_offset(str, start, start+olen, enc);
    roffset = rstrip_offset(str, start+loffset, start+olen, enc);

    if (loffset <= 0 && roffset <= 0) return rb_str_dup(str);
    return rb_str_subseq(str, loffset, olen-loffset-roffset);
}

#strip!String?

Removes leading and trailing whitespace from str. Returns nil if str was not altered.

Refer to strip for the definition of whitespace.

Returns:



7856
7857
7858
7859
7860
7861
7862
7863
7864
7865
7866
7867
7868
7869
7870
7871
7872
7873
7874
7875
7876
7877
7878
7879
7880
7881
7882
# File 'string.c', line 7856

static VALUE
rb_str_strip_bang(VALUE str)
{
    char *start;
    long olen, loffset, roffset;
    rb_encoding *enc;

    str_modify_keep_cr(str);
    enc = STR_ENC_GET(str);
    RSTRING_GETMEM(str, start, olen);
    loffset = lstrip_offset(str, start, start+olen, enc);
    roffset = rstrip_offset(str, start+loffset, start+olen, enc);

    if (loffset > 0 || roffset > 0) {
  long len = olen-roffset;
  if (loffset > 0) {
      len -= loffset;
      memmove(start, start + loffset, len);
  }
  STR_SET_LEN(str, len);
#if !SHARABLE_MIDDLE_SUBSTRING
  TERM_FILL(start+len, rb_enc_mbminlen(enc));
#endif
  return str;
    }
    return Qnil;
}

#sub(pattern, replacement) ⇒ String #sub(pattern, hash) ⇒ String #sub(pattern) {|match| ... } ⇒ String

Returns a copy of str with the first occurrence of pattern replaced by the second argument. The pattern is typically a Regexp; if given as a String, any regular expression metacharacters it contains will be interpreted literally, e.g. '\\d' will match a backlash followed by 'd', instead of a digit.

If replacement is a String it will be substituted for the matched text. It may contain back-references to the pattern's capture groups of the form "\d", where d is a group number, or "\k<n>", where n is a group name. If it is a double-quoted string, both back-references must be preceded by an additional backslash. However, within replacement the special match variables, such as &$, will not refer to the current match. If replacement is a String that looks like a pattern's capture group but is actually not a pattern capture group e.g. "\'", then it will have to be preceded by two backslashes like so "\\'".

If the second argument is a Hash, and the matched text is one of its keys, the corresponding value is the replacement string.

In the block form, the current match string is passed in as a parameter, and variables such as $1, $2, $`, $&, and $' will be set appropriately. The value returned by the block will be substituted for the match on each call.

The result inherits any tainting in the original string or any supplied replacement string.

"hello".sub(/[aeiou]/, '*')                  #=> "h*llo"
"hello".sub(/([aeiou])/, '<\1>')             #=> "h<e>llo"
"hello".sub(/./) {|s| s.ord.to_s + ' ' }     #=> "104 ello"
"hello".sub(/(?<foo>[aeiou])/, '*\k<foo>*')  #=> "h*e*llo"
'Is SHELL your preferred shell?'.sub(/[[:upper:]]{2,}/, ENV)
 #=> "Is /bin/bash your preferred shell?"

Overloads:



4565
4566
4567
4568
4569
4570
4571
# File 'string.c', line 4565

static VALUE
rb_str_sub(int argc, VALUE *argv, VALUE str)
{
    str = rb_str_dup(str);
    rb_str_sub_bang(argc, argv, str);
    return str;
}

#sub!(pattern, replacement) ⇒ String? #sub!(pattern) {|match| ... } ⇒ String?

Performs the same substitution as String#sub in-place.

Returns str if a substitution was performed or nil if no substitution was performed.

Overloads:

  • #sub!(pattern, replacement) ⇒ String?

    Returns:

  • #sub!(pattern) {|match| ... } ⇒ String?

    Yields:

    Returns:



4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
# File 'string.c', line 4411

static VALUE
rb_str_sub_bang(int argc, VALUE *argv, VALUE str)
{
    VALUE pat, repl, hash = Qnil;
    int iter = 0;
    int tainted = 0;
    long plen;
    int min_arity = rb_block_given_p() ? 1 : 2;
    long beg;

    rb_check_arity(argc, min_arity, 2);
    if (argc == 1) {
  iter = 1;
    }
    else {
  repl = argv[1];
  hash = rb_check_hash_type(argv[1]);
  if (NIL_P(hash)) {
      StringValue(repl);
  }
  tainted = OBJ_TAINTED_RAW(repl);
    }

    pat = get_pat_quoted(argv[0], 1);

    str_modifiable(str);
    beg = rb_pat_search(pat, str, 0, 1);
    if (beg >= 0) {
  rb_encoding *enc;
  int cr = ENC_CODERANGE(str);
  long beg0, end0;
  VALUE match, match0 = Qnil;
  struct re_registers *regs;
  char *p, *rp;
  long len, rlen;

  match = rb_backref_get();
  regs = RMATCH_REGS(match);
  if (RB_TYPE_P(pat, T_STRING)) {
      beg0 = beg;
      end0 = beg0 + RSTRING_LEN(pat);
      match0 = pat;
  }
  else {
      beg0 = BEG(0);
      end0 = END(0);
      if (iter) match0 = rb_reg_nth_match(0, match);
  }

  if (iter || !NIL_P(hash)) {
      p = RSTRING_PTR(str); len = RSTRING_LEN(str);

            if (iter) {
                repl = rb_obj_as_string(rb_yield(match0));
            }
            else {
                repl = rb_hash_aref(hash, rb_str_subseq(str, beg0, end0 - beg0));
                repl = rb_obj_as_string(repl);
            }
      str_mod_check(str, p, len);
      rb_check_frozen(str);
  }
  else {
      repl = rb_reg_regsub(repl, str, regs, RB_TYPE_P(pat, T_STRING) ? Qnil : pat);
  }

        enc = rb_enc_compatible(str, repl);
        if (!enc) {
            rb_encoding *str_enc = STR_ENC_GET(str);
      p = RSTRING_PTR(str); len = RSTRING_LEN(str);
      if (coderange_scan(p, beg0, str_enc) != ENC_CODERANGE_7BIT ||
    coderange_scan(p+end0, len-end0, str_enc) != ENC_CODERANGE_7BIT) {
                rb_raise(rb_eEncCompatError, "incompatible character encodings: %s and %s",
       rb_enc_name(str_enc),
       rb_enc_name(STR_ENC_GET(repl)));
            }
            enc = STR_ENC_GET(repl);
        }
  rb_str_modify(str);
  rb_enc_associate(str, enc);
  tainted |= OBJ_TAINTED_RAW(repl);
  if (ENC_CODERANGE_UNKNOWN < cr && cr < ENC_CODERANGE_BROKEN) {
      int cr2 = ENC_CODERANGE(repl);
            if (cr2 == ENC_CODERANGE_BROKEN ||
                (cr == ENC_CODERANGE_VALID && cr2 == ENC_CODERANGE_7BIT))
                cr = ENC_CODERANGE_UNKNOWN;
            else
                cr = cr2;
  }
  plen = end0 - beg0;
  rp = RSTRING_PTR(repl); rlen = RSTRING_LEN(repl);
  len = RSTRING_LEN(str);
  if (rlen > plen) {
      RESIZE_CAPA(str, len + rlen - plen);
  }
  p = RSTRING_PTR(str);
  if (rlen != plen) {
      memmove(p + beg0 + rlen, p + beg0 + plen, len - beg0 - plen);
  }
  memcpy(p + beg0, rp, rlen);
  len += rlen - plen;
  STR_SET_LEN(str, len);
  TERM_FILL(&RSTRING_PTR(str)[len], TERM_LEN(str));
  ENC_CODERANGE_SET(str, cr);
  FL_SET_RAW(str, tainted);

  return str;
    }
    return Qnil;
}

#succString #nextString

Returns the successor to str. The successor is calculated by incrementing characters starting from the rightmost alphanumeric (or the rightmost character if there are no alphanumerics) in the string. Incrementing a digit always results in another digit, and incrementing a letter results in another letter of the same case. Incrementing nonalphanumerics uses the underlying character set's collating sequence.

If the increment generates a “carry,'' the character to the left of it is incremented. This process repeats until there is no carry, adding an additional character if necessary.

"abcd".succ        #=> "abce"
"THX1138".succ     #=> "THX1139"
"<<koala>>".succ   #=> "<<koalb>>"
"1999zzz".succ     #=> "2000aaa"
"ZZZ9999".succ     #=> "AAAA0000"
"***".succ         #=> "**+"

Overloads:



3566
3567
3568
3569
3570
3571
3572
3573
3574
# File 'string.c', line 3566

VALUE
rb_str_succ(VALUE orig)
{
    VALUE str;
    str = rb_str_new_with_class(orig, RSTRING_PTR(orig), RSTRING_LEN(orig));
    rb_enc_cr_str_copy_for_substr(str, orig);
    OBJ_INFECT(str, orig);
    return str_succ(str);
}

#succ!String #next!String

Equivalent to String#succ, but modifies the receiver in place.

Overloads:



3673
3674
3675
3676
3677
3678
3679
# File 'string.c', line 3673

static VALUE
rb_str_succ_bang(VALUE str)
{
    rb_str_modify(str);
    str_succ(str);
    return str;
}

#sum(n = 16) ⇒ Integer

Returns a basic n-bit checksum of the characters in str, where n is the optional Fixnum parameter, defaulting to 16. The result is simply the sum of the binary value of each byte in str modulo 2**n - 1. This is not a particularly good checksum.

Returns:



8146
8147
8148
8149
8150
8151
8152
8153
8154
8155
8156
8157
8158
8159
8160
8161
8162
8163
8164
8165
8166
8167
8168
8169
8170
8171
8172
8173
8174
8175
8176
8177
8178
8179
8180
8181
8182
8183
8184
8185
8186
8187
8188
8189
8190
8191
8192
8193
8194
8195
8196
8197
8198
8199
8200
8201
8202
8203
8204
# File 'string.c', line 8146

static VALUE
rb_str_sum(int argc, VALUE *argv, VALUE str)
{
    VALUE vbits;
    int bits;
    char *ptr, *p, *pend;
    long len;
    VALUE sum = INT2FIX(0);
    unsigned long sum0 = 0;

    if (argc == 0) {
  bits = 16;
    }
    else {
  rb_scan_args(argc, argv, "01", &vbits);
  bits = NUM2INT(vbits);
        if (bits < 0)
            bits = 0;
    }
    ptr = p = RSTRING_PTR(str);
    len = RSTRING_LEN(str);
    pend = p + len;

    while (p < pend) {
        if (FIXNUM_MAX - UCHAR_MAX < sum0) {
            sum = rb_funcall(sum, '+', 1, LONG2FIX(sum0));
            str_mod_check(str, ptr, len);
            sum0 = 0;
        }
        sum0 += (unsigned char)*p;
        p++;
    }

    if (bits == 0) {
        if (sum0) {
            sum = rb_funcall(sum, '+', 1, LONG2FIX(sum0));
        }
    }
    else {
        if (sum == INT2FIX(0)) {
            if (bits < (int)sizeof(long)*CHAR_BIT) {
                sum0 &= (((unsigned long)1)<<bits)-1;
            }
            sum = LONG2FIX(sum0);
        }
        else {
            VALUE mod;

            if (sum0) {
                sum = rb_funcall(sum, '+', 1, LONG2FIX(sum0));
            }

            mod = rb_funcall(INT2FIX(1), idLTLT, 1, INT2FIX(bits));
            mod = rb_funcall(mod, '-', 1, INT2FIX(1));
            sum = rb_funcall(sum, '&', 1, mod);
        }
    }
    return sum;
}

#swapcaseString

Returns a copy of str with uppercase alphabetic characters converted to lowercase and lowercase characters converted to uppercase. Note: case conversion is effective only in ASCII region.

"Hello".swapcase          #=> "hELLO"
"cYbEr_PuNk11".swapcase   #=> "CyBeR_pUnK11"

Returns:



5896
5897
5898
5899
5900
5901
5902
# File 'string.c', line 5896

static VALUE
rb_str_swapcase(VALUE str)
{
    str = rb_str_dup(str);
    rb_str_swapcase_bang(str);
    return str;
}

#swapcase!String?

Equivalent to String#swapcase, but modifies the receiver in place, returning str, or nil if no changes were made. Note: case conversion is effective only in ASCII region.

Returns:



5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
# File 'string.c', line 5851

static VALUE
rb_str_swapcase_bang(VALUE str)
{
    rb_encoding *enc;
    char *s, *send;
    int modify = 0;
    int n;

    str_modify_keep_cr(str);
    enc = STR_ENC_GET(str);
    rb_str_check_dummy_enc(enc);
    s = RSTRING_PTR(str); send = RSTRING_END(str);
    while (s < send) {
  unsigned int c = rb_enc_codepoint_len(s, send, &n, enc);

  if (rb_enc_isupper(c, enc)) {
      /* assuming toupper returns codepoint with same size */
      rb_enc_mbcput(rb_enc_tolower(c, enc), s, enc);
      modify = 1;
  }
  else if (rb_enc_islower(c, enc)) {
      /* assuming tolower returns codepoint with same size */
      rb_enc_mbcput(rb_enc_toupper(c, enc), s, enc);
      modify = 1;
  }
  s += n;
    }

    if (modify) return str;
    return Qnil;
}

#to_cObject

Returns a complex which denotes the string form. The parser ignores leading whitespaces and trailing garbage. Any digit sequences can be separated by an underscore. Returns zero for null or garbage string.

'9'.to_c           #=> (9+0i)
'2.5'.to_c         #=> (2.5+0i)
'2.5/1'.to_c       #=> ((5/2)+0i)
'-3/2'.to_c        #=> ((-3/2)+0i)
'-i'.to_c          #=> (0-1i)
'45i'.to_c         #=> (0+45i)
'3-4i'.to_c        #=> (3-4i)
'-4e2-4e-2i'.to_c  #=> (-400.0-0.04i)
'-0.0-0.0i'.to_c   #=> (-0.0-0.0i)
'1/2+3/4i'.to_c    #=> ((1/2)+(3/4)*i)
'ruby'.to_c        #=> (0+0i)

See Kernel.Complex.



1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
# File 'complex.c', line 1878

static VALUE
string_to_c(VALUE self)
{
    char *s;
    VALUE num;

    rb_must_asciicompat(self);

    s = RSTRING_PTR(self);

    if (s && s[RSTRING_LEN(self)]) {
  rb_str_modify(self);
  s = RSTRING_PTR(self);
  s[RSTRING_LEN(self)] = '\0';
    }

    if (!s)
  s = (char *)"";

    (void)parse_comp(s, 0, &num);

    return num;
}

#to_fFloat

Returns the result of interpreting leading characters in str as a floating point number. Extraneous characters past the end of a valid number are ignored. If there is not a valid number at the start of str, 0.0 is returned. This method never raises an exception.

"123.45e1".to_f        #=> 1234.5
"45.67 degrees".to_f   #=> 45.67
"thx1138".to_f         #=> 0.0

Returns:



5208
5209
5210
5211
5212
# File 'string.c', line 5208

static VALUE
rb_str_to_f(VALUE str)
{
    return DBL2NUM(rb_str_to_dbl(str, FALSE));
}

#to_i(base = 10) ⇒ Integer

Returns the result of interpreting leading characters in str as an integer base base (between 2 and 36). Extraneous characters past the end of a valid number are ignored. If there is not a valid number at the start of str, 0 is returned. This method never raises an exception when base is valid.

"12345".to_i             #=> 12345
"99 red balloons".to_i   #=> 99
"0a".to_i                #=> 0
"0a".to_i(16)            #=> 10
"hello".to_i             #=> 0
"1100101".to_i(2)        #=> 101
"1100101".to_i(8)        #=> 294977
"1100101".to_i(10)       #=> 1100101
"1100101".to_i(16)       #=> 17826049

Returns:



5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
# File 'string.c', line 5175

static VALUE
rb_str_to_i(int argc, VALUE *argv, VALUE str)
{
    int base;

    if (argc == 0) base = 10;
    else {
  VALUE b;

  rb_scan_args(argc, argv, "01", &b);
  base = NUM2INT(b);
    }
    if (base < 0) {
  rb_raise(rb_eArgError, "invalid radix %d", base);
    }
    return rb_str_to_inum(str, base, FALSE);
}

#to_rObject

Returns a rational which denotes the string form. The parser ignores leading whitespaces and trailing garbage. Any digit sequences can be separated by an underscore. Returns zero for null or garbage string.

NOTE: '0.3'.to_r isn't the same as 0.3.to_r. The former is equivalent to '3/10'.to_r, but the latter isn't so.

'  2  '.to_r       #=> (2/1)
'300/2'.to_r       #=> (150/1)
'-9.2'.to_r        #=> (-46/5)
'-9.2e2'.to_r      #=> (-920/1)
'1_234_567'.to_r   #=> (1234567/1)
'21 june 09'.to_r  #=> (21/1)
'21/06/09'.to_r    #=> (7/2)
'bwv 1079'.to_r    #=> (0/1)

See Kernel.Rational.



2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
# File 'rational.c', line 2362

static VALUE
string_to_r(VALUE self)
{
    char *s;
    VALUE num;

    rb_must_asciicompat(self);

    s = RSTRING_PTR(self);

    if (s && s[RSTRING_LEN(self)]) {
  rb_str_modify(self);
  s = RSTRING_PTR(self);
  s[RSTRING_LEN(self)] = '\0';
    }

    if (!s)
  s = (char *)"";

    (void)parse_rat(s, 0, &num);

    if (RB_TYPE_P(num, T_FLOAT))
  rb_raise(rb_eFloatDomainError, "Infinity");
    return num;
}

#to_sString #to_strString

Returns self.

If called on a subclass of String, converts the receiver to a String object.

Overloads:



5225
5226
5227
5228
5229
5230
5231
5232
# File 'string.c', line 5225

static VALUE
rb_str_to_s(VALUE str)
{
    if (rb_obj_class(str) != rb_cString) {
  return str_duplicate(rb_cString, str);
    }
    return str;
}

#to_sString #to_strString

Returns self.

If called on a subclass of String, converts the receiver to a String object.

Overloads:



5225
5226
5227
5228
5229
5230
5231
5232
# File 'string.c', line 5225

static VALUE
rb_str_to_s(VALUE str)
{
    if (rb_obj_class(str) != rb_cString) {
  return str_duplicate(rb_cString, str);
    }
    return str;
}

#internObject #to_symObject

Returns the Symbol corresponding to str, creating the symbol if it did not previously exist. See Symbol#id2name.

"Koala".intern         #=> :Koala
s = 'cat'.to_sym       #=> :cat
s == :cat              #=> true
s = '@cat'.to_sym      #=> :@cat
s == :@cat             #=> true

This can also be used to create symbols that cannot be represented using the :xxx notation.

'cat and dog'.to_sym   #=> :"cat and dog"


659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
# File 'symbol.c', line 659

VALUE
rb_str_intern(VALUE str)
{
#if USE_SYMBOL_GC
    rb_encoding *enc, *ascii;
    int type;
#else
    ID id;
#endif
    VALUE sym = lookup_str_sym(str);

    if (sym) {
  return sym;
    }

#if USE_SYMBOL_GC
    enc = rb_enc_get(str);
    ascii = rb_usascii_encoding();
    if (enc != ascii && sym_check_asciionly(str)) {
  str = rb_str_dup(str);
  rb_enc_associate(str, ascii);
  OBJ_FREEZE(str);
  enc = ascii;
    }
    else {
  str = rb_str_new_frozen(str);
    }
    str = rb_fstring(str);
    type = rb_str_symname_type(str, IDSET_ATTRSET_FOR_INTERN);
    if (type < 0) type = ID_JUNK;
    return dsymbol_alloc(rb_cSymbol, str, enc, type);
#else
    id = intern_str(str, 0);
    return ID2SYM(id);
#endif
}

#tr(from_str, to_str) ⇒ String

Returns a copy of str with the characters in from_str replaced by the corresponding characters in to_str. If to_str is shorter than from_str, it is padded with its last character in order to maintain the correspondence.

"hello".tr('el', 'ip')      #=> "hippo"
"hello".tr('aeiou', '*')    #=> "h*ll*"
"hello".tr('aeiou', 'AA*')  #=> "hAll*"

Both strings may use the c1-c2 notation to denote ranges of characters, and from_str may start with a ^, which denotes all characters except those listed.

"hello".tr('a-y', 'b-z')    #=> "ifmmp"
"hello".tr('^aeiou', '*')   #=> "*e**o"

The backslash character \</code> can be used to escape <code>^ or - and is otherwise ignored unless it appears at the end of a range or the end of the from_str or to_str:

"hello^world".tr("\\^aeiou", "*") #=> "h*ll**w*rld"
"hello-world".tr("a\\-eo", "*")   #=> "h*ll**w*rld"

"hello\r\nworld".tr("\r", "")   #=> "hello\nworld"
"hello\r\nworld".tr("\\r", "")  #=> "hello\r\nwold"
"hello\r\nworld".tr("\\\r", "") #=> "hello\nworld"

"X['\\b']".tr("X\\", "")   #=> "['b']"
"X['\\b']".tr("X-\\]", "") #=> "'b'"

Returns:



6264
6265
6266
6267
6268
6269
6270
# File 'string.c', line 6264

static VALUE
rb_str_tr(VALUE str, VALUE src, VALUE repl)
{
    str = rb_str_dup(str);
    tr_trans(str, src, repl, 0);
    return str;
}

#tr!(from_str, to_str) ⇒ String?

Translates str in place, using the same rules as String#tr. Returns str, or nil if no changes were made.

Returns:



6222
6223
6224
6225
6226
# File 'string.c', line 6222

static VALUE
rb_str_tr_bang(VALUE str, VALUE src, VALUE repl)
{
    return tr_trans(str, src, repl, 0);
}

#tr_s(from_str, to_str) ⇒ String

Processes a copy of str as described under String#tr, then removes duplicate characters in regions that were affected by the translation.

"hello".tr_s('l', 'r')     #=> "hero"
"hello".tr_s('el', '*')    #=> "h*o"
"hello".tr_s('el', 'hx')   #=> "hhxo"

Returns:



6588
6589
6590
6591
6592
6593
6594
# File 'string.c', line 6588

static VALUE
rb_str_tr_s(VALUE str, VALUE src, VALUE repl)
{
    str = rb_str_dup(str);
    tr_trans(str, src, repl, 1);
    return str;
}

#tr_s!(from_str, to_str) ⇒ String?

Performs String#tr_s processing on str in place, returning str, or nil if no changes were made.

Returns:



6568
6569
6570
6571
6572
# File 'string.c', line 6568

static VALUE
rb_str_tr_s_bang(VALUE str, VALUE src, VALUE repl)
{
    return tr_trans(str, src, repl, 1);
}

#unpack(format) ⇒ Array

Decodes str (which may contain binary data) according to the format string, returning an array of each value extracted. The format string consists of a sequence of single-character directives, summarized in the table at the end of this entry. Each directive may be followed by a number, indicating the number of times to repeat with this directive. An asterisk (“*'') will use up all remaining elements. The directives sSiIlL may each be followed by an underscore (“_'') or exclamation mark (“!'') to use the underlying platform's native size for the specified type; otherwise, it uses a platform-independent consistent size. Spaces are ignored in the format string. See also Array#pack.

"abc \0\0abc \0\0".unpack('A6Z6')   #=> ["abc", "abc "]
"abc \0\0".unpack('a3a3')           #=> ["abc", " \000\000"]
"abc \0abc \0".unpack('Z*Z*')       #=> ["abc ", "abc "]
"aa".unpack('b8B8')                 #=> ["10000110", "01100001"]
"aaa".unpack('h2H2c')               #=> ["16", "61", 97]
"\xfe\xff\xfe\xff".unpack('sS')     #=> [-2, 65534]
"now=20is".unpack('M*')             #=> ["now is"]
"whole".unpack('xax2aX2aX1aX2a')    #=> ["h", "e", "l", "l", "o"]

This table summarizes the various formats and the Ruby classes returned by each.

Integer      |         |
Directive    | Returns | Meaning
-----------------------------------------------------------------
   C         | Integer | 8-bit unsigned (unsigned char)
   S         | Integer | 16-bit unsigned, native endian (uint16_t)
   L         | Integer | 32-bit unsigned, native endian (uint32_t)
   Q         | Integer | 64-bit unsigned, native endian (uint64_t)
             |         |
   c         | Integer | 8-bit signed (signed char)
   s         | Integer | 16-bit signed, native endian (int16_t)
   l         | Integer | 32-bit signed, native endian (int32_t)
   q         | Integer | 64-bit signed, native endian (int64_t)
             |         |
   S_, S!    | Integer | unsigned short, native endian
   I, I_, I! | Integer | unsigned int, native endian
   L_, L!    | Integer | unsigned long, native endian
   Q_, Q!    | Integer | unsigned long long, native endian (ArgumentError
             |         | if the platform has no long long type.)
             |         | (Q_ and Q! is available since Ruby 2.1.)
             |         |
   s_, s!    | Integer | signed short, native endian
   i, i_, i! | Integer | signed int, native endian
   l_, l!    | Integer | signed long, native endian
   q_, q!    | Integer | signed long long, native endian (ArgumentError
             |         | if the platform has no long long type.)
             |         | (q_ and q! is available since Ruby 2.1.)
             |         |
   S> L> Q>  | Integer | same as the directives without ">" except
   s> l> q>  |         | big endian
   S!> I!>   |         | (available since Ruby 1.9.3)
   L!> Q!>   |         | "S>" is same as "n"
   s!> i!>   |         | "L>" is same as "N"
   l!> q!>   |         |
             |         |
   S< L< Q<  | Integer | same as the directives without "<" except
   s< l< q<  |         | little endian
   S!< I!<   |         | (available since Ruby 1.9.3)
   L!< Q!<   |         | "S<" is same as "v"
   s!< i!<   |         | "L<" is same as "V"
   l!< q!<   |         |
             |         |
   n         | Integer | 16-bit unsigned, network (big-endian) byte order
   N         | Integer | 32-bit unsigned, network (big-endian) byte order
   v         | Integer | 16-bit unsigned, VAX (little-endian) byte order
   V         | Integer | 32-bit unsigned, VAX (little-endian) byte order
             |         |
   U         | Integer | UTF-8 character
   w         | Integer | BER-compressed integer (see Array.pack)

Float        |         |
Directive    | Returns | Meaning
-----------------------------------------------------------------
   D, d      | Float   | double-precision, native format
   F, f      | Float   | single-precision, native format
   E         | Float   | double-precision, little-endian byte order
   e         | Float   | single-precision, little-endian byte order
   G         | Float   | double-precision, network (big-endian) byte order
   g         | Float   | single-precision, network (big-endian) byte order

String       |         |
Directive    | Returns | Meaning
-----------------------------------------------------------------
   A         | String  | arbitrary binary string (remove trailing nulls and ASCII spaces)
   a         | String  | arbitrary binary string
   Z         | String  | null-