Ruby: include/ruby/internal/intern/string.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Macros | Functions | Variables
string.h File Reference

Public APIs related to rb_cString. More...

`#include "ruby/internal/config.h"`
`#include "ruby/internal/attr/deprecated.h"`
`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/constant_p.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/internal/variable.h"`
`#include "ruby/st.h"`

Go to the source code of this file.

## Macros
#define | rb_str_dup_frozen rb_str_new_frozen
| Just another name of rb_str_new_frozen.
#define | rb_hash_uint32(h, i)
| Just another name of st_hash_uint32.
#define | rb_hash_uint(h, i)
| Just another name of st_hash_uint.
#define | rb_hash_end(h)
| Just another name of st_hash_end.
#define | rb_str_new(str, len)
| Allocates an instance of rb_cString.
#define | rb_str_new_cstr(str)
| Identical to rb_str_new, except it assumes the passed pointer is a pointer to a C string.
#define | rb_usascii_str_new(str, len)
| Identical to rb_str_new, except it generates a string of "US ASCII" encoding.
#define | rb_utf8_str_new(str, len)
| Identical to rb_str_new, except it generates a string of "UTF-8" encoding.
#define | rb_usascii_str_new_cstr(str)
| Identical to rb_str_new_cstr, except it generates a string of "US ASCII" encoding.
#define | rb_utf8_str_new_cstr(str)
| Identical to rb_str_new_cstr, except it generates a string of "UTF-8" encoding.
#define | rb_external_str_new_cstr(str)
| Identical to rb_str_new_cstr, except it generates a string of "default external" encoding.
#define | rb_locale_str_new_cstr(str)
| Identical to rb_external_str_new_cstr, except it generates a string of "locale" encoding instead of "default external".
#define | rb_str_buf_new_cstr(str)
| Identical to rb_str_new_cstr, except done differently.
#define | rb_str_cat_cstr(buf, str)
| Identical to rb_str_cat(), except it assumes the passed pointer is a pointer to a C string.
#define | rb_exc_new_cstr(exc, str)
| Identical to rb_exc_new(), except it assumes the passed pointer is a pointer to a C string.
#define | rb_str_new2 rb_str_new_cstr
| Old name of rb_str_new_cstr.
#define | rb_str_new3 rb_str_new_shared
| Old name of rb_str_new_shared.
#define | rb_str_new4 rb_str_new_frozen
| Old name of rb_str_new_frozen.
#define | rb_str_new5 rb_str_new_with_class
| Old name of rb_str_new_with_class.
#define | rb_str_buf_new2 rb_str_buf_new_cstr
| Old name of rb_str_buf_new_cstr.
#define | rb_usascii_str_new2 rb_usascii_str_new_cstr
| Old name of rb_usascii_str_new_cstr.
#define | rb_str_buf_cat rb_str_cat
| Just another name of rb_str_cat.
#define | rb_str_buf_cat2 rb_str_cat_cstr
| Old name of rb_usascii_str_new_cstr.
#define | rb_str_cat2 rb_str_cat_cstr
| Old name of rb_str_cat_cstr.
#define | rb_strlen_lit(str)
| Length of a string literal.
#define | rb_str_new_lit(str)
| Identical to rb_str_new_static(), except it cannot take string variables.
#define | rb_usascii_str_new_lit(str)
| Identical to rb_usascii_str_new_static(), except it cannot take string variables.
#define | rb_utf8_str_new_lit(str)
| Identical to rb_utf8_str_new_static(), except it cannot take string variables.
#define | rb_enc_str_new_lit(str, enc)
| Identical to rb_enc_str_new_static(), except it cannot take string variables.
#define | rb_str_new_literal(str)
| Just another name of rb_str_new_lit.
#define | rb_usascii_str_new_literal(str)
| Just another name of rb_usascii_str_new_lit.
#define | rb_utf8_str_new_literal(str)
| Just another name of rb_utf8_str_new_lit.
#define | rb_enc_str_new_literal(str, enc)
| Just another name of rb_enc_str_new_lit.

## Functions
VALUE | rb_str_new (const char *ptr, long len)
| Allocates an instance of rb_cString.
VALUE | rb_str_new_cstr (const char *ptr)
| Identical to rb_str_new(), except it assumes the passed pointer is a pointer to a C string.
VALUE | rb_str_new_shared (VALUE str)
| Identical to rb_str_new_cstr(), except it takes a Ruby's string instead of C's.
VALUE | rb_str_new_frozen (VALUE str)
| Creates a frozen copy of the string, if necessary.
VALUE | rb_str_new_with_class (VALUE obj, const char *ptr, long len)
| Identical to rb_str_new(), except it takes the class of the allocating object.
VALUE | rb_external_str_new (const char *ptr, long len)
| Identical to rb_str_new(), except it generates a string of "default external" encoding.
VALUE | rb_external_str_new_cstr (const char *ptr)
| Identical to rb_external_str_new(), except it assumes the passed pointer is a pointer to a C string.
VALUE | rb_locale_str_new (const char *ptr, long len)
| Identical to rb_str_new(), except it generates a string of "locale" encoding.
VALUE | rb_locale_str_new_cstr (const char *ptr)
| Identical to rb_locale_str_new(), except it assumes the passed pointer is a pointer to a C string.
VALUE | rb_filesystem_str_new (const char *ptr, long len)
| Identical to rb_str_new(), except it generates a string of "filesystem" encoding.
VALUE | rb_filesystem_str_new_cstr (const char *ptr)
| Identical to rb_filesystem_str_new(), except it assumes the passed pointer is a pointer to a C string.
VALUE | rb_str_buf_new (long capa)
| Allocates a "string buffer".
VALUE | rb_str_buf_new_cstr (const char *ptr)
| This is a rb_str_buf_new() + rb_str_buf_cat() combo.
VALUE | rb_str_tmp_new (long len)
| Allocates a "temporary" string.
VALUE | rb_usascii_str_new (const char *ptr, long len)
| Identical to rb_str_new(), except it generates a string of "US ASCII" encoding.
VALUE | rb_usascii_str_new_cstr (const char *ptr)
| Identical to rb_str_new_cstr(), except it generates a string of "US ASCII" encoding.
VALUE | rb_utf8_str_new (const char *ptr, long len)
| Identical to rb_str_new(), except it generates a string of "UTF-8" encoding.
VALUE | rb_utf8_str_new_cstr (const char *ptr)
| Identical to rb_str_new_cstr(), except it generates a string of "UTF-8" encoding.
VALUE | rb_str_to_interned_str (VALUE str)
| Identical to rb_interned_str(), except it takes a Ruby's string instead of C's.
VALUE | rb_interned_str (const char *ptr, long len)
| Identical to rb_str_new(), except it returns an infamous "f"string.
VALUE | rb_interned_str_cstr (const char *ptr)
| Identical to rb_interned_str(), except it assumes the passed pointer is a pointer to a C's string.
void | rb_str_free (VALUE str)
| Destroys the given string for no reason.
void | rb_str_shared_replace (VALUE dst, VALUE src)
| Replaces the contents of the former with the latter.
VALUE | rb_str_buf_append (VALUE dst, VALUE src)
| Identical to rb_str_cat_cstr(), except it takes Ruby's string instead of C's.
VALUE | rb_str_buf_cat (VALUE, const char *, long)
| Just another name of rb_str_cat.
VALUE | rb_str_buf_cat2 (VALUE, const char *)
| Just another name of rb_str_cat_cstr.
VALUE | rb_str_buf_cat_ascii (VALUE dst, const char *src)
| Identical to rb_str_cat_cstr(), except it additionally assumes the source string be a NUL terminated ASCII string.
VALUE | rb_obj_as_string (VALUE obj)
| Try converting an object to its stringised representation using its `to_s` method, if any.
VALUE | rb_check_string_type (VALUE obj)
| Try converting an object to its stringised representation using its `to_str` method, if any.
void | rb_must_asciicompat (VALUE obj)
| Asserts that the given string's encoding is (Ruby's definition of) ASCII compatible.
VALUE | rb_str_dup (VALUE str)
| Duplicates a string.
VALUE | rb_str_resurrect (VALUE str)
| I guess there is no use case of this function in extension libraries, but this is a routine identical to rb_str_dup(), except it always creates an instance of rb_cString regardless of the given object's class.
VALUE | rb_str_locktmp (VALUE str)
| Obtains a "temporary lock" of the string.
VALUE | rb_str_unlocktmp (VALUE str)
| Releases a lock formerly obtained by rb_str_locktmp().
VALUE | rb_str_dup_frozen (VALUE)
| Just another name of rb_str_new_frozen.
VALUE | rb_str_plus (VALUE lhs, VALUE rhs)
| Generates a new string, concatenating the former to the latter.
VALUE | rb_str_times (VALUE str, VALUE num)
| Repetition of a string.
long | rb_str_sublen (VALUE str, long pos)
| Byte offset to character offset conversion.
VALUE | rb_str_substr (VALUE str, long beg, long len)
| This is the implementation of two-argumented `String#slice`.
VALUE | rb_str_subseq (VALUE str, long beg, long len)
| Identical to rb_str_substr(), except the numbers are interpreted as byte offsets instead of character offsets.
char * | rb_str_subpos (VALUE str, long beg, long *len)
| Identical to rb_str_substr(), except it returns a C's string instead of Ruby's.
void | rb_str_modify (VALUE str)
| Declares that the string is about to be modified.
void | rb_str_modify_expand (VALUE str, long capa)
| Identical to rb_str_modify(), except it additionally expands the capacity of the receiver.
VALUE | rb_str_freeze (VALUE str)
| This is the implementation of `String#freeze`.
void | rb_str_set_len (VALUE str, long len)
| Overwrites the length of the string.
VALUE | rb_str_resize (VALUE str, long len)
| Overwrites the length of the string.
VALUE | rb_str_cat (VALUE dst, const char *src, long srclen)
| Destructively appends the passed contents to the string.
VALUE | rb_str_cat_cstr (VALUE dst, const char *src)
| Identical to rb_str_cat(), except it assumes the passed pointer is a pointer to a C string.
VALUE | rb_str_cat2 (VALUE, const char *)
| Just another name of rb_str_cat_cstr.
VALUE | rb_str_append (VALUE dst, VALUE src)
| Identical to rb_str_buf_append(), except it converts the right hand side before concatenating.
VALUE | rb_str_concat (VALUE dst, VALUE src)
| Identical to rb_str_append(), except it also accepts an integer as a codepoint.
st_index_t | rb_memhash (const void *ptr, long len)
| This is a universal hash function.
st_index_t | rb_hash_start (st_index_t i)
| Starts a series of hashing.
st_index_t | rb_str_hash (VALUE str)
| Calculates a hash value of a string.
int | rb_str_hash_cmp (VALUE str1, VALUE str2)
| Compares two strings.
int | rb_str_comparable (VALUE str1, VALUE str2)
| Checks if two strings are comparable each other or not.
int | rb_str_cmp (VALUE lhs, VALUE rhs)
| Compares two strings, as in `strcmp(3)`.
VALUE | rb_str_equal (VALUE str1, VALUE str2)
| Equality of two strings.
VALUE | rb_str_drop_bytes (VALUE str, long len)
| Shrinks the given string for the given number of bytes.
void | rb_str_update (VALUE dst, long beg, long len, VALUE src)
| Replaces some (or all) of the contents of the given string.
VALUE | rb_str_replace (VALUE dst, VALUE src)
| Replaces the contents of the former object with the stringised contents of the latter.
VALUE | rb_str_inspect (VALUE str)
| Generates a "readable" version of the receiver.
VALUE | rb_str_dump (VALUE str)
| "Inverse" of rb_eval_string().
VALUE | rb_str_split (VALUE str, const char *delim)
| Divides the given string based on the given delimiter.
VALUE | rb_str_intern (VALUE str)
| Identical to rb_to_symbol(), except it assumes the receiver being an instance of RString.
VALUE | rb_sym_to_s (VALUE sym)
| This is an rb_sym2str() + rb_str_dup() combo.
long | rb_str_strlen (VALUE str)
| Counts the number of characters (not bytes) that are stored inside of the given string.
VALUE | rb_str_length (VALUE)
| Identical to rb_str_strlen(), except it returns the value in rb_cInteger.
long | rb_str_offset (VALUE str, long pos)
| "Inverse" of rb_str_sublen().
size_t | rb_str_capacity (VALUE str)
| Queries the capacity of the given string.
VALUE | rb_str_ellipsize (VALUE str, long len)
| Shortens `str` and adds three dots, an ellipsis, if it is longer than `len` characters.
VALUE | rb_str_scrub (VALUE str, VALUE repl)
| "Cleanses" the string.
VALUE | rb_str_succ (VALUE orig)
| Searches for the "successor" of a string.
Special strings that are backended by C string literals.
*_str_new_static functions are intended for C string literals. They require memory in the range [ptr, ptr+len] to always be readable. Note that this range covers a total of len + 1 bytes.
VALUE | rb_str_new_static (const char *ptr, long len)
| Identical to rb_str_new(), except it takes a C string literal.
VALUE | rb_usascii_str_new_static (const char *ptr, long len)
| Identical to rb_str_new_static(), except it generates a string of "US ASCII" encoding instead of "binary".
VALUE | rb_utf8_str_new_static (const char *ptr, long len)
| Identical to rb_str_new_static(), except it generates a string of "UTF-8" encoding instead of "binary".

## Variables
rb_gvar_setter_t | rb_str_setter
| This is a rb_gvar_setter_t that refutes non-string assignments.

## Detailed Description

Public APIs related to rb_cString.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file string.h.

## Macro Definition Documentation

## ◆ rb_enc_str_new_lit

#define rb_enc_str_new_lit | ( |  | str,
|  |  | enc )

Value:
rb_enc_str_new_static((str), rb_strlen_lit(str), (enc))
rb_enc_str_new_static
VALUE rb_enc_str_new_static(const char *ptr, long len, rb_encoding *enc)
Identical to rb_enc_str_new(), except it takes a C string literal.
Definition string.c:1074
rb_strlen_lit
#define rb_strlen_lit(str)
Length of a string literal.
Definition string.h:1692

Identical to rb_enc_str_new_static(), except it cannot take string variables.

Parameters

  [in] | str | A C string literal.
  [in] | enc | A pointer to an encoding.

Precondition
  `str` must not be a variable.

Returns
  An instance of rb_cString, of the passed encoding, whose backend storage is the passed C string literal.

Warning
  It is a very bad idea to write to a C string literal (often immediate SEGV shall occur). Consider return values of this function be read-only.

Definition at line 1748 of file string.h.

## ◆ rb_enc_str_new_literal

#define rb_enc_str_new_literal | ( |  | str,
|  |  | enc )

Value:
rb_enc_str_new_lit(str, enc)
rb_enc_str_new_lit
#define rb_enc_str_new_lit(str, enc)
Identical to rb_enc_str_new_static(), except it cannot take string variables.
Definition string.h:1748

Just another name of rb_enc_str_new_lit.

Definition at line 1753 of file string.h.

## ◆ rb_exc_new_cstr

#define rb_exc_new_cstr | ( |  | exc,
|  |  | str )

Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_exc_new_cstr : \
rb_exc_new_cstr) ((exc), (str)))
RBIMPL_CONSTANT_P
#define RBIMPL_CONSTANT_P(expr)
Wraps (or simulates) __builtin_constant_p
Definition constant_p.h:35
rb_exc_new_cstr
#define rb_exc_new_cstr(exc, str)
Identical to rb_exc_new(), except it assumes the passed pointer is a pointer to a C string.
Definition string.h:1670

Identical to rb_exc_new(), except it assumes the passed pointer is a pointer to a C string.

Parameters

  [out] | exc | A subclass of rb_eException.
  [in] | str | Message to raise.

Returns
  An instance of `exc` whose message is `str`.

Precondition
  `str` must not be a null pointer.

Definition at line 1670 of file string.h.

## ◆ rb_external_str_new_cstr

#define rb_external_str_new_cstr | ( |  | str | ) |

Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_external_str_new_cstr : \
rb_external_str_new_cstr) (str))
rb_external_str_new_cstr
#define rb_external_str_new_cstr(str)
Identical to rb_str_new_cstr, except it generates a string of "defaultexternal" encoding.
Definition string.h:1604

Identical to rb_str_new_cstr, except it generates a string of "default external" encoding.

Parameters

  [in] | str | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString. In case encoding conversion from "default internal" to "default external" is fully defined over the given contents, then the return value is a string of "default external" encoding, whose contents are the converted ones. Otherwise the string is a junk.

Warning
  It doesn't raise on a conversion failure and silently ends up in a corrupted output. You can know the failure by querying `valid_encoding?` of the result object.

Precondition
  `str` must not be a null pointer.

Definition at line 1604 of file string.h.

## ◆ rb_hash_end

#define rb_hash_end | ( |  | h | ) |

Value:
st_hash_end(h)

Just another name of st_hash_end.

Definition at line 945 of file string.h.

## ◆ rb_hash_uint

#define rb_hash_uint | ( |  | h,
|  |  | i )

Value:
st_hash_uint((h), (i))

Just another name of st_hash_uint.

Definition at line 942 of file string.h.

## ◆ rb_hash_uint32

#define rb_hash_uint32 | ( |  | h,
|  |  | i )

Value:
st_hash_uint32((h), (i))

Just another name of st_hash_uint32.

Definition at line 939 of file string.h.

## ◆ rb_locale_str_new_cstr

#define rb_locale_str_new_cstr | ( |  | str | ) |

Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_locale_str_new_cstr : \
rb_locale_str_new_cstr) (str))
rb_locale_str_new_cstr
#define rb_locale_str_new_cstr(str)
Identical to rb_external_str_new_cstr, except it generates a string of "locale" encoding instead of "...
Definition string.h:1625

Identical to rb_external_str_new_cstr, except it generates a string of "locale" encoding instead of "default external".

Parameters

  [in] | str | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString. In case encoding conversion from "default internal" to "locale" is fully defined over the given contents, then the return value is a string of "locale" encoding, whose contents are the converted ones. Otherwise the string is a junk.

Warning
  It doesn't raise on a conversion failure and silently ends up in a corrupted output. You can know the failure by querying `valid_encoding?` of the result object.

Precondition
  `str` must not be a null pointer.

Definition at line 1625 of file string.h.

## ◆ rb_str_buf_cat

#define rb_str_buf_cat rb_str_cat

Just another name of rb_str_cat.

Definition at line 1681 of file string.h.

Referenced by rb_str_buf_new_cstr(), and rb_str_cat_cstr().

## ◆ rb_str_buf_new_cstr

#define rb_str_buf_new_cstr | ( |  | str | ) |

Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_str_buf_new_cstr : \
rb_str_buf_new_cstr) (str))
rb_str_buf_new_cstr
#define rb_str_buf_new_cstr(str)
Identical to rb_str_new_cstr, except done differently.
Definition string.h:1639

Identical to rb_str_new_cstr, except done differently.

Parameters

  [in] | str | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString, of "binary" encoding, whose contents are verbatim copy of `str`.

Precondition
  `str` must not be a null pointer.

Definition at line 1639 of file string.h.

## ◆ rb_str_cat_cstr

#define rb_str_cat_cstr | ( |  | buf,
|  |  | str )

Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_str_cat_cstr : \
rb_str_cat_cstr) ((buf), (str)))
rb_str_cat_cstr
#define rb_str_cat_cstr(buf, str)
Identical to rb_str_cat(), except it assumes the passed pointer is a pointer to a C string.
Definition string.h:1656

Identical to rb_str_cat(), except it assumes the passed pointer is a pointer to a C string.

Parameters

  [out] | buf | Destination object.
  [in] | str | Contents to append.

Exceptions

  rb_eArgError | Result string too big.

Returns
  The passed `buf`.

Precondition
  `buf` must not be any arbitrary objects except RString.
  `str` must not be a null pointer.

Postcondition
  `buf` has the contents of `str` appended.

Definition at line 1656 of file string.h.

Referenced by ruby_init_loadpath().

## ◆ rb_str_dup_frozen

#define rb_str_dup_frozen rb_str_new_frozen

Just another name of rb_str_new_frozen.

Definition at line 631 of file string.h.

## ◆ rb_str_new

#define rb_str_new | ( |  | str,
|  |  | len )

Value:
((RBIMPL_CONSTANT_P(str) && \
RBIMPL_CONSTANT_P(len) ? \
rb_str_new_static : \
rb_str_new) ((str), (len)))
rb_str_new
#define rb_str_new(str, len)
Allocates an instance of rb_cString.
Definition string.h:1498
rb_str_new_static
VALUE rb_str_new_static(const char *ptr, long len)
Identical to rb_str_new(), except it takes a C string literal.
Definition string.c:1056

Allocates an instance of rb_cString.

Parameters

  [in] | str | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString, of `len` bytes length, of "binary" encoding, whose contents are verbatim copy of `str`.

Precondition
  At least `len` bytes of continuous memory region shall be accessible via `str`.

Definition at line 1498 of file string.h.

Referenced by rb_ary_join(), rb_enc_str_new(), rb_exc_new(), rb_external_str_new_with_enc(), rb_io_ungetbyte(), rb_path_check(), rb_reg_quote(), rb_str_dump(), rb_str_ellipsize(), rb_str_format(), rb_str_new_cstr(), rb_str_succ(), rb_usascii_str_new(), and rb_write_error2().

## ◆ rb_str_new_cstr

#define rb_str_new_cstr | ( |  | str | ) |

Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_str_new_cstr : \
rb_str_new_cstr) (str))
rb_str_new_cstr
#define rb_str_new_cstr(str)
Identical to rb_str_new, except it assumes the passed pointer is a pointer to a C string.
Definition string.h:1514

Identical to rb_str_new, except it assumes the passed pointer is a pointer to a C string.

Parameters

  [in] | str | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString, of "binary" encoding, whose contents are verbatim copy of `str`.

Precondition
  `str` must not be a null pointer.

Definition at line 1514 of file string.h.

Referenced by rb_check_typeddata(), rb_econv_open_exc(), rb_file_open(), rb_load_file(), rb_path2class(), rb_str_split(), rb_throw_obj(), rb_usascii_str_new_cstr(), and rb_utf8_str_new_cstr().

## ◆ rb_str_new_lit

#define rb_str_new_lit | ( |  | str | ) |

Value:
rb_str_new_static((str), rb_strlen_lit(str))

Identical to rb_str_new_static(), except it cannot take string variables.

Parameters

  [in] | str | A C string literal.

Precondition
  `str` must not be a variable.

Returns
  An instance of rb_cString, of "binary" encoding, whose backend storage is the passed C string literal.

Warning
  It is a very bad idea to write to a C string literal (often immediate SEGV shall occur). Consider return values of this function be read-only.

Definition at line 1705 of file string.h.

## ◆ rb_str_new_literal

#define rb_str_new_literal | ( |  | str | ) |

Value:
rb_str_new_lit(str)
rb_str_new_lit
#define rb_str_new_lit(str)
Identical to rb_str_new_static(), except it cannot take string variables.
Definition string.h:1705

Just another name of rb_str_new_lit.

Definition at line 1750 of file string.h.

Referenced by rb_profile_frame_absolute_path().

## ◆ rb_strlen_lit

#define rb_strlen_lit | ( |  | str | ) |

Value:
(sizeof(str "") - 1)

Length of a string literal.

Parameters

  [in] | str | A C String literal.

Returns
  An integer constant expression that represents `str`'s length, in bytes, not including the terminating NUL character.

Definition at line 1692 of file string.h.

Referenced by rb_str_dump(), and ruby_init_loadpath().

## ◆ rb_usascii_str_new

#define rb_usascii_str_new | ( |  | str,
|  |  | len )

Value:
((RBIMPL_CONSTANT_P(str) && \
RBIMPL_CONSTANT_P(len) ? \
rb_usascii_str_new_static : \
rb_usascii_str_new) ((str), (len)))
rb_usascii_str_new
#define rb_usascii_str_new(str, len)
Identical to rb_str_new, except it generates a string of "US ASCII" encoding.
Definition string.h:1532
rb_usascii_str_new_static
VALUE rb_usascii_str_new_static(const char *ptr, long len)
Identical to rb_str_new_static(), except it generates a string of "US ASCII" encoding instead of "bin...
Definition string.c:1062

Identical to rb_str_new, except it generates a string of "US ASCII" encoding.

This is different from rb_external_str_new(), not only for the output encoding, but also it doesn't convert the contents.

Parameters

  [in] | str | A memory region of `len` bytes length.
  [in] | len | Length of `str`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString, of `len` bytes length, of "US ASCII" encoding, whose contents are verbatim copy of `str`.

Definition at line 1532 of file string.h.

Referenced by rb_ary_join(), rb_fix2str(), and rb_str_ellipsize().

## ◆ rb_usascii_str_new_cstr

#define rb_usascii_str_new_cstr | ( |  | str | ) |

Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_usascii_str_new_cstr : \
rb_usascii_str_new_cstr) (str))
rb_usascii_str_new_cstr
#define rb_usascii_str_new_cstr(str)
Identical to rb_str_new_cstr, except it generates a string of "US ASCII" encoding.
Definition string.h:1567

Identical to rb_str_new_cstr, except it generates a string of "US ASCII" encoding.

It can also be seen as a routine Identical to rb_usascii_str_new, except it assumes the passed pointer is a pointer to a C string.

Parameters

  [in] | str | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString, of "US ASCII" encoding, whose contents are verbatim copy of `str`.

Precondition
  `str` must not be a null pointer.

Definition at line 1567 of file string.h.

Referenced by rb_locale_charmap().

## ◆ rb_usascii_str_new_lit

#define rb_usascii_str_new_lit | ( |  | str | ) |

Value:
rb_usascii_str_new_static((str), rb_strlen_lit(str))

Identical to rb_usascii_str_new_static(), except it cannot take string variables.

Parameters

  [in] | str | A C string literal.

Precondition
  `str` must not be a variable.

Returns
  An instance of rb_cString, of "US ASCII" encoding, whose backend storage is the passed C string literal.

Warning
  It is a very bad idea to write to a C string literal (often immediate SEGV shall occur). Consider return values of this function be read-only.

Definition at line 1719 of file string.h.

## ◆ rb_usascii_str_new_literal

#define rb_usascii_str_new_literal | ( |  | str | ) |

Value:
rb_usascii_str_new_lit(str)
rb_usascii_str_new_lit
#define rb_usascii_str_new_lit(str)
Identical to rb_usascii_str_new_static(), except it cannot take string variables.
Definition string.h:1719

Just another name of rb_usascii_str_new_lit.

Definition at line 1751 of file string.h.

## ◆ rb_utf8_str_new

#define rb_utf8_str_new | ( |  | str,
|  |  | len )

Value:
((RBIMPL_CONSTANT_P(str) && \
RBIMPL_CONSTANT_P(len) ? \
rb_utf8_str_new_static : \
rb_utf8_str_new) ((str), (len)))
rb_utf8_str_new_static
VALUE rb_utf8_str_new_static(const char *ptr, long len)
Identical to rb_str_new_static(), except it generates a string of "UTF-8" encoding instead of "binary...
Definition string.c:1068
rb_utf8_str_new
#define rb_utf8_str_new(str, len)
Identical to rb_str_new, except it generates a string of "UTF-8" encoding.
Definition string.h:1549

Identical to rb_str_new, except it generates a string of "UTF-8" encoding.

Parameters

  [in] | str | A memory region of `len` bytes length.
  [in] | len | Length of `str`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString, of `len` bytes length, of "UTF-8" encoding, whose contents are verbatim copy of `str`.

Definition at line 1549 of file string.h.

## ◆ rb_utf8_str_new_cstr

#define rb_utf8_str_new_cstr | ( |  | str | ) |

Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_utf8_str_new_cstr : \
rb_utf8_str_new_cstr) (str))
rb_utf8_str_new_cstr
#define rb_utf8_str_new_cstr(str)
Identical to rb_str_new_cstr, except it generates a string of "UTF-8" encoding.
Definition string.h:1583

Identical to rb_str_new_cstr, except it generates a string of "UTF-8" encoding.

It can also be seen as a routine Identical to rb_utf8_str_new, except it assumes the passed pointer is a pointer to a C string.

Parameters

  [in] | str | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString, of "UTF-8" encoding, whose contents are verbatim copy of `str`.

Precondition
  `str` must not be a null pointer.

Definition at line 1583 of file string.h.

## ◆ rb_utf8_str_new_lit

#define rb_utf8_str_new_lit | ( |  | str | ) |

Value:
rb_utf8_str_new_static((str), rb_strlen_lit(str))

Identical to rb_utf8_str_new_static(), except it cannot take string variables.

Parameters

  [in] | str | A C string literal.

Precondition
  `str` must not be a variable.

Returns
  An instance of rb_cString, of "UTF-8" encoding, whose backend storage is the passed C string literal.

Warning
  It is a very bad idea to write to a C string literal (often immediate SEGV shall occur). Consider return values of this function be read-only.

Definition at line 1733 of file string.h.

## ◆ rb_utf8_str_new_literal

#define rb_utf8_str_new_literal | ( |  | str | ) |

Value:
rb_utf8_str_new_lit(str)
rb_utf8_str_new_lit
#define rb_utf8_str_new_lit(str)
Identical to rb_utf8_str_new_static(), except it cannot take string variables.
Definition string.h:1733

Just another name of rb_utf8_str_new_lit.

Definition at line 1752 of file string.h.

## Function Documentation

## ◆ rb_check_string_type()

VALUE rb_check_string_type | ( | VALUE | obj | ) |

Try converting an object to its stringised representation using its `to_str` method, if any.

If there is no such thing, returns RUBY_Qnil.

Parameters

  [in] | obj | Arbitrary ruby object to stringise.

Exceptions

  rb_eTypeError | `obj.to_str` returned something non-String.

Return values

  RUBY_Qnil | No conversion from obj to String defined.

Returns
  otherwise Stringised representation of `obj`.

See also
  rb_io_check_io
  rb_check_array_type
  rb_check_hash_type

Definition at line 2640 of file string.c.

Referenced by rb_ary_join(), rb_check_id(), rb_check_symbol(), rb_io_extract_encoding_option(), rb_str_format(), rb_String(), and rb_to_encoding_index().

## ◆ rb_external_str_new()

VALUE rb_external_str_new | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new(), except it generates a string of "default external" encoding.

Parameters

  [in] | ptr | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString. In case encoding conversion from "default internal" to "default external" is fully defined over the given contents, then the return value is a string of "default external" encoding, whose contents are the converted ones. Otherwise the string is a junk.

Warning
  It doesn't raise on a conversion failure and silently ends up in a corrupted output. You can know the failure by querying `valid_encoding?` of the result object.

Definition at line 1265 of file string.c.

## ◆ rb_external_str_new_cstr()

VALUE rb_external_str_new_cstr | ( | const char * | ptr | ) |

Identical to rb_external_str_new(), except it assumes the passed pointer is a pointer to a C string.

It can also be seen as a routine identical to rb_str_new_cstr(), except it generates a string of "default external" encoding.

Parameters

  [in] | ptr | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString. In case encoding conversion from "default internal" to "default external" is fully defined over the given contents, then the return value is a string of "default external" encoding, whose contents are the converted ones. Otherwise the string is a junk.

Warning
  It doesn't raise on a conversion failure and silently ends up in a corrupted output. You can know the failure by querying `valid_encoding?` of the result object.

Precondition
  `ptr` must not be a null pointer.

Definition at line 1271 of file string.c.

## ◆ rb_filesystem_str_new()

VALUE rb_filesystem_str_new | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new(), except it generates a string of "filesystem" encoding.

It can also be seen as a routine identical to rb_external_str_new(), except it generates a string of "filesystem" encoding instead of "default external" encoding.

Parameters

  [in] | ptr | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString. In case encoding conversion from "default internal" to "filesystem" is fully defined over the given contents, then the return value is a string of "filesystem" encoding, whose contents are the converted ones. Otherwise the string is a junk.

Warning
  It doesn't raise on a conversion failure and silently ends up in a corrupted output. You can know the failure by querying `valid_encoding?` of the result object.

Definition at line 1289 of file string.c.

## ◆ rb_filesystem_str_new_cstr()

VALUE rb_filesystem_str_new_cstr | ( | const char * | ptr | ) |

Identical to rb_filesystem_str_new(), except it assumes the passed pointer is a pointer to a C string.

It can also be seen as a routine identical to rb_external_str_new_cstr(), except it generates a string of "filesystem" encoding instead of "default external".

Parameters

  [in] | ptr | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString. In case encoding conversion from "default internal" to "filesystem" is fully defined over the given contents, then the return value is a string of "filesystem" encoding, whose contents are the converted ones. Otherwise the string is a junk.

Warning
  It doesn't raise on a conversion failure and silently ends up in a corrupted output. You can know the failure by querying `valid_encoding?` of the result object.

Precondition
  `ptr` must not be a null pointer.

Definition at line 1295 of file string.c.

## ◆ rb_hash_start()

st_index_t rb_hash_start | ( | st_index_t | i | ) |

Starts a series of hashing.

Suppose you have a struct:

struct foo_tag {
unsigned char bar;
uint32_t baz;
};

It is not a wise idea to call rb_memhash() over it, because there could be padding bits. Instead you should explicitly iterate over each fields:

foo_tag foo = { 0, 0, };
st_index_t hash = 0;
hash = rb_hash_start(0);
hash = rb_hash_uint(hash, foo.bar);
hash = rb_hash_uint32(hash, foo.baz);
hash = rb_hash_end(hash);
rb_hash_uint
#define rb_hash_uint(h, i)
Just another name of st_hash_uint.
Definition string.h:942
rb_hash_end
#define rb_hash_end(h)
Just another name of st_hash_end.
Definition string.h:945
rb_hash_uint32
#define rb_hash_uint32(h, i)
Just another name of st_hash_uint32.
Definition string.h:939
rb_hash_start
st_index_t rb_hash_start(st_index_t i)
Starts a series of hashing.
Definition random.c:1735

Parameters

  [in] | i | Initial value.

Returns
  A hash value.

Definition at line 1735 of file random.c.

Referenced by rb_hash_start().

## ◆ rb_interned_str()

VALUE rb_interned_str | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new(), except it returns an infamous "f"string.

What is a fstring? Well it is a special subkind of strings that is immutable, deduped globally, and managed by our GC. It is much like a Symbol (in fact Symbols are dynamic these days and are backended using fstrings). This concept has been silently introduced at some point in 2.x era. Since then it gained wider acceptance in the core. Starting from 3.x extension libraries can also generate ones.

Parameters

  [in] | ptr | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eArgError | `len` is negative.

Returns
  A found or created instance of rb_cString, of `len` bytes length, of "binary" encoding, whose contents are identical to that of `ptr`.

Precondition
  At least `len` bytes of continuous memory region shall be accessible via `ptr`.

Definition at line 11957 of file string.c.

Referenced by rb_interned_str_cstr().

## ◆ rb_interned_str_cstr()

VALUE rb_interned_str_cstr | ( | const char * | ptr | ) |

Identical to rb_interned_str(), except it assumes the passed pointer is a pointer to a C's string.

It can also be seen as a routine identical to to rb_str_to_interned_str(), except it takes a C's string instead of Ruby's. Or it can also be seen as a routine identical to rb_str_new_cstr(), except it returns an infamous "f"string.

Parameters

  [in] | ptr | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString, of "binary" encoding, whose contents are verbatim copy of `ptr`.

Precondition
  `ptr` must not be a null pointer.

Definition at line 11964 of file string.c.

## ◆ rb_locale_str_new()

VALUE rb_locale_str_new | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new(), except it generates a string of "locale" encoding.

It can also be seen as a routine identical to rb_external_str_new(), except it generates a string of "locale" encoding instead of "default external" encoding.

Parameters

  [in] | ptr | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString. In case encoding conversion from "default internal" to "locale" is fully defined over the given contents, then the return value is a string of "locale" encoding, whose contents are the converted ones. Otherwise the string is a junk.

Warning
  It doesn't raise on a conversion failure and silently ends up in a corrupted output. You can know the failure by querying `valid_encoding?` of the result object.

Definition at line 1277 of file string.c.

## ◆ rb_locale_str_new_cstr()

VALUE rb_locale_str_new_cstr | ( | const char * | ptr | ) |

Identical to rb_locale_str_new(), except it assumes the passed pointer is a pointer to a C string.

It can also be seen as a routine identical to rb_external_str_new_cstr(), except it generates a string of "locale" encoding instead of "default external".

Parameters

  [in] | ptr | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString. In case encoding conversion from "default internal" to "locale" is fully defined over the given contents, then the return value is a string of "locale" encoding, whose contents are the converted ones. Otherwise the string is a junk.

Warning
  It doesn't raise on a conversion failure and silently ends up in a corrupted output. You can know the failure by querying `valid_encoding?` of the result object.

Precondition
  `ptr` must not be a null pointer.

Definition at line 1283 of file string.c.

## ◆ rb_memhash()

st_index_t rb_memhash | ( | const void * | ptr,
|  | long | len )

This is a universal hash function.

Warning
  This function changes its value per process.

Parameters

  [in] | ptr | Target message.
  [in] | len | Length of `ptr` in bytes.

Returns
  A pseudorandom number suitable for Hash's hash value.

See also
  Aumasson, JP., Bernstein, D.J., "SipHash: A Fast Short-Input PRF", In proceedings of 13th International Conference on Cryptology in India (INDOCRYPT 2012), LNCS 7668, pp. 489-508,
  1. http://doi.org/10.1007/978-3-642-34931-7_28

Definition at line 1741 of file random.c.

Referenced by rb_memhash(), and rb_str_hash().

## ◆ rb_must_asciicompat()

void rb_must_asciicompat | ( | VALUE | obj | ) |

Asserts that the given string's encoding is (Ruby's definition of) ASCII compatible.

Parameters

  [in] | obj | An instance of rb_cString.

Exceptions

  rb_eEncCompatError | `obj` is ASCII incompatible.

Definition at line 2489 of file string.c.

Referenced by rb_str_format().

## ◆ rb_obj_as_string()

VALUE rb_obj_as_string | ( | VALUE | obj | ) |

Try converting an object to its stringised representation using its `to_s` method, if any.

If there is no such thing, it resorts to rb_any_to_s() output.

Parameters

  [in] | obj | Arbitrary ruby object to stringise.

Returns
  An instance of rb_cString.

Definition at line 1682 of file string.c.

Referenced by rb_inspect(), rb_io_puts(), rb_p(), and rb_str_format().

## ◆ rb_str_append()

VALUE rb_str_append | ( | VALUE | dst,
|  | VALUE | src )

Identical to rb_str_buf_append(), except it converts the right hand side before concatenating.

Parameters

  [out] | dst | Destination object.
  [in] | src | Source object.

Exceptions

  rb_eEncCompatError | Can't mix the encodings.
  rb_eArgError | Result string too big.

Returns
  The passed `dst`.

Precondition
  `dst` must not be any arbitrary objects except RString.

Postcondition
  `dst` has the contents of `src` appended, with encoding converted into `dst`'s one, into the end of `dst`.

Definition at line 3353 of file string.c.

Referenced by rb_str_concat(), and rb_str_ellipsize().

## ◆ rb_str_buf_append()

VALUE rb_str_buf_append | ( | VALUE | dst,
|  | VALUE | src )

Identical to rb_str_cat_cstr(), except it takes Ruby's string instead of C's.

It can also be seen as a routine identical to rb_str_shared_replace(), except it appends instead of replaces.

Parameters

  [out] | dst | Destination object.
  [in] | src | Source object.

Exceptions

  rb_eEncCompatError | Can't mix the encodings.
  rb_eArgError | Result string too big.

Returns
  The passed `dst`.

Precondition
  Both objects must not be any arbitrary objects except RString.

Postcondition
  `dst` has the contents of `src` appended, with encoding converted into `dst`'s one, into the end of `dst`.

Definition at line 3319 of file string.c.

Referenced by rb_str_append().

## ◆ rb_str_buf_cat()

VALUE rb_str_buf_cat | ( | VALUE | ,
|  | const char * | ,
|  | long | )

Just another name of rb_str_cat.

## ◆ rb_str_buf_cat2()

VALUE rb_str_buf_cat2 | ( | VALUE | ,
|  | const char * | )

Just another name of rb_str_cat_cstr.

## ◆ rb_str_buf_cat_ascii()

VALUE rb_str_buf_cat_ascii | ( | VALUE | dst,
|  | const char * | src )

Identical to rb_str_cat_cstr(), except it additionally assumes the source string be a NUL terminated ASCII string.

Parameters

  [out] | dst | Destination object.
  [in] | src | Source string.

Exceptions

  rb_eArgError | Result string too big.

Returns
  The passed `dst`.

Precondition
  `dst` must not be any arbitrary object except RString.
  `src` must be a NUL terminated ASCII string.

Postcondition
  `dst` has the contents of `src` appended, with encoding converted into `dst`'s one, into the end of `dst`.

Definition at line 3295 of file string.c.

## ◆ rb_str_buf_new()

VALUE rb_str_buf_new | ( | long | capa | ) |

Allocates a "string buffer".

A string buffer here is an instance of rb_cString, whose capacity is bigger than the length of it. If you can say that a string grows to a specific amount of bytes, this could be effective than resizing a string over and over again and again.

Parameters

  [in] | capa | Designed capacity of the generating string.

Returns
  An empty string, of "binary" encoding, whose capacity is `capa`.

Definition at line 1532 of file string.c.

Referenced by rb_ary_join(), rb_econv_append(), rb_enc_vsprintf(), rb_reg_regsub(), rb_str_buf_new_cstr(), rb_str_conv_enc_opts(), rb_str_format(), and rb_str_inspect().

## ◆ rb_str_buf_new_cstr()

VALUE rb_str_buf_new_cstr | ( | const char * | ptr | ) |

This is a rb_str_buf_new() + rb_str_buf_cat() combo.

Parameters

  [in] | ptr | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.

Returns
  An instance of rb_cString, of "binary" encoding, whose contents are verbatim copy of `ptr`.

Precondition
  `ptr` must not be a null pointer.

Definition at line 1553 of file string.c.

## ◆ rb_str_capacity()

size_t rb_str_capacity | ( | VALUE | str | ) |

Queries the capacity of the given string.

See also
  RString::capa

Parameters

  [in] | str | String in question.

Returns
  Its capacity.

Definition at line 871 of file string.c.

Referenced by rb_econv_append(), and rb_str_format().

## ◆ rb_str_cat()

VALUE rb_str_cat | ( | VALUE | dst,
|  | const char * | src,
|  | long | srclen )

Destructively appends the passed contents to the string.

Parameters

  [out] | dst | Destination object.
  [in] | src | Contents to append.
  [in] | srclen | Length of `src`.

Exceptions

  rb_eArgError | `srclen` is negative.

Returns
  The passed `dst`.

Precondition
  `dst` must not be any arbitrary objects except RString.

Postcondition
  `dst` has the contents of `ptr` appended.

Definition at line 3177 of file string.c.

Referenced by rb_id_attrset(), rb_str_concat(), and rb_str_ellipsize().

## ◆ rb_str_cat2()

VALUE rb_str_cat2 | ( | VALUE | ,
|  | const char * | )

Just another name of rb_str_cat_cstr.

## ◆ rb_str_cat_cstr()

VALUE rb_str_cat_cstr | ( | VALUE | dst,
|  | const char * | src )

Identical to rb_str_cat(), except it assumes the passed pointer is a pointer to a C string.

Parameters

  [out] | dst | Destination object.
  [in] | src | Contents to append.

Exceptions

  rb_eArgError | Result string too big.
  rb_eArgError | `src` is a null pointer.

Returns
  The passed `dst`.

Precondition
  `dst` must not be any arbitrary objects except RString.
  `src` must not be a null pointer.

Postcondition
  `dst` has the contents of `src` appended.

Definition at line 3187 of file string.c.

## ◆ rb_str_cmp()

int rb_str_cmp | ( | VALUE | lhs,
|  | VALUE | rhs )

Compares two strings, as in `strcmp(3)`.

This does not consider the current locale, but considers the encodings of both sides instead.

Parameters

  [in] | lhs | A string.
  [in] | rhs | Another string.

Return values

  -1 | `lhs` is "bigger than" `rhs`.
  1 | `rhs` is "bigger than" `lhs`.
  0 | Otherwise, e.g. not comparable.

Precondition
  Both objects must not be any arbitrary objects except RString.

Definition at line 3637 of file string.c.

## ◆ rb_str_comparable()

int rb_str_comparable | ( | VALUE | str1,
|  | VALUE | str2 )

Checks if two strings are comparable each other or not.

Because rb_str_cmp() must return "lesser than" or "greater than" information, comparing two strings needs a stricter restriction. Both sides must be in a same set of strings which have total order. This is to check that property. Intuitive it sounds? But they can have different encodings. A character and another might or might not appear in the same order in their codepoints. It is complicated than you think.

Parameters

  [in] | str1 | A string.
  [in] | str2 | Another string.

Return values

  1 | They agree on a total order.
  0 | Otherwise.

Precondition
  Both objects must not be any arbitrary objects except RString.

Definition at line 3612 of file string.c.

Referenced by rb_str_cmp(), and rb_str_hash_cmp().

## ◆ rb_str_concat()

VALUE rb_str_concat | ( | VALUE | dst,
|  | VALUE | src )

Identical to rb_str_append(), except it also accepts an integer as a codepoint.

This resembles `String#<<`.

Parameters

  [out] | dst | Destination object.
  [in] | src | Source object, String or Numeric.

Exceptions

  rb_eRangeError | Source numeric is out of range.
  rb_eEncCompatError | Source string too long.
  rb_eArgError | Result string too big.

Returns
  The passed `dst`.

Precondition
  `dst` must not be any arbitrary objects except RString.

Postcondition
  `dst` has the contents of `src` appended, with encoding converted into `dst`'s one, into the end of `dst`.

Definition at line 3453 of file string.c.

## ◆ rb_str_drop_bytes()

VALUE rb_str_drop_bytes | ( | VALUE | str,
|  | long | len )

Shrinks the given string for the given number of bytes.

Parameters

  [out] | str | String to squash.
  [in] | len | Number of bytes to reduce.

Exceptions

  rb_eRuntimeError | `str` is `locktmp`-ed.
  rb_eFrozenError | `str` is frozen.

Returns
  The passed `str`.

Precondition
  `str` must not be any arbitrary objects except RString.

Postcondition
  `str` is shrunken.

Warning
  Can break a multibyte character in middle.

Definition at line 5258 of file string.c.

## ◆ rb_str_dump()

VALUE rb_str_dump | ( | VALUE | str | ) |

"Inverse" of rb_eval_string().

Returns a quoted version of the string. All non-printing characters are replaced by `\uNNNN` or `\xHH` notation and all special characters are escaped. The result string is guaranteed to render a string of the same contents when passed to `eval` and friends.

Parameters

  [in] | str | String to dump.

Exceptions

  rb_eRuntimeError | Too many escape sequences causes integer overflow on the length of the string.

Returns
  An US-ASCII string that includes all the necessary info to reconstruct the original string.

Definition at line 6826 of file string.c.

Referenced by rb_econv_prepare_options().

## ◆ rb_str_dup()

VALUE rb_str_dup | ( | VALUE | str | ) |

Duplicates a string.

Parameters

  [in] | str | String in question to duplicate.

Returns
  A duplicated new instance.

Precondition
  `str` must be of RString.

Definition at line 1834 of file string.c.

Referenced by rb_class_path(), rb_find_file_ext(), rb_id_attrset(), rb_str_conv_enc_opts(), rb_str_intern(), ruby_init_loadpath(), and ruby_set_script_name().

## ◆ rb_str_dup_frozen()

VALUE rb_str_dup_frozen | ( | VALUE |  | ) |

Just another name of rb_str_new_frozen.

## ◆ rb_str_ellipsize()

VALUE rb_str_ellipsize | ( | VALUE | str,
|  | long | len )

Shortens `str` and adds three dots, an ellipsis, if it is longer than `len` characters.

The length of the returned string in characters is less than or equal to `len`. If the length of `str` is less than or equal `len`, returns `str` itself. The encoding of returned string is equal to that of passed one. The class of returned string is equal to that of passed one.

Parameters

  [in] | str | The string to shorten.
  [in] | len | The maximum string length.

Exceptions

  rb_eIndexError | `len` is negative.

Return values

  str | No need to add ellipsis.
  otherwise | A new, shortened string.

Note
  The length is counted in characters.

Definition at line 10890 of file string.c.

## ◆ rb_str_equal()

VALUE rb_str_equal | ( | VALUE | str1,
|  | VALUE | str2 )

Equality of two strings.

If `str2` is not a String, it resorts to `str2 == str1`. Otherwise if they are not comparable, returns RUBY_Qfalse. Otherwise if they have the same contents and the length, returns RUBY_Qtrue. Otherwise, returns RUBY_Qfalse.

Parameters

  [in] | str1 | A string.
  [in] | str2 | Another string.

Return values

  RUBY_Qtrue | They are equal.
  RUBY_Qfalse | They are either different, or not comparable.

Definition at line 3683 of file string.c.

## ◆ rb_str_free()

void rb_str_free | ( | VALUE | str | ) |

Destroys the given string for no reason.

Warning
  DO NOT USE IT.
  Leave this task to our GC.
  It was a bad idea at the first place to let you know about it.

Parameters

  [out] | str | The string to be executed.

Postcondition
  The given string no longer exists.

Note
  Maybe `String#clear` could be what you want.

Definition at line 1571 of file string.c.

## ◆ rb_str_freeze()

VALUE rb_str_freeze | ( | VALUE | str | ) |

This is the implementation of `String#freeze`.

Parameters

  [out] | str | Target string to freeze.

Returns
  The passed string.

Postcondition
  Upon successful return the passed string is frozen.

Definition at line 2942 of file string.c.

## ◆ rb_str_hash()

st_index_t rb_str_hash | ( | VALUE | str | ) |

Calculates a hash value of a string.

This is one of the two functions that constructs struct st_hash_type.

Parameters

  [in] | str | An object of RString.

Returns
  A hash value.

Precondition
  `str` must not be any arbitrary object except RString.

Definition at line 3571 of file string.c.

## ◆ rb_str_hash_cmp()

int rb_str_hash_cmp | ( | VALUE | str1,
|  | VALUE | str2 )

Compares two strings.

This is one of the two functions that constructs struct st_hash_type.

Parameters

  [in] | str1 | A string.
  [in] | str2 | Another string.

Return values

  1 | They have identical contents, length, and encodings.
  0 | Otherwise.

Precondition
  Both objects must not be any arbitrary objects except RString.

Definition at line 3581 of file string.c.

## ◆ rb_str_inspect()

VALUE rb_str_inspect | ( | VALUE | str | ) |

Generates a "readable" version of the receiver.

Warning
  The output is insecure. Never feed one to `eval`.
  The output is not always in the same encoding as the given one.
  A character might or might not be escaped, depending on the result encoding.

Parameters

  [in] | str | String to inspect.

Returns
  Its inspection, either in default internal encoding if any, or in default external encoding otherwise.

See also
  rb_str_dump()

Definition at line 6712 of file string.c.

## ◆ rb_str_intern()

VALUE rb_str_intern | ( | VALUE | str | ) |

Identical to rb_to_symbol(), except it assumes the receiver being an instance of RString.

Parameters

  [in] | str | The name of the id.

Exceptions

  rb_eRuntimeError | Too many symbols.

Returns
  A (possibly new) id whose value is the given `str`.

Precondition
  `str` must not be any arbitrary object except RString.

Note
  These days Ruby internally has two kinds of symbols (static/dynamic). Symbols created using this function would become dynamic ones; i.e. would be garbage collected. It could be safer for you to use it than alternatives, when applicable.

Definition at line 851 of file symbol.c.

Referenced by rb_f_global_variables(), and rb_to_symbol().

## ◆ rb_str_length()

VALUE rb_str_length | ( | VALUE | str | ) |

Identical to rb_str_strlen(), except it returns the value in rb_cInteger.

Parameters

  [in] | str | Target string to query.

Returns
  Its number of characters.

Definition at line 2163 of file string.c.

## ◆ rb_str_locktmp()

VALUE rb_str_locktmp | ( | VALUE | str | ) |

Obtains a "temporary lock" of the string.

This advisory locking mechanism prevents other cooperating threads from tampering the receiver. The same thing could be done via freeze mechanism, but this one can also be unlocked using rb_str_unlocktmp().

Parameters

  [out] | str | String to lock.

Exceptions

  rb_eRuntimeError | `str` already locked.

Returns
  The given string.

Postcondition
  The string is locked.

## ◆ rb_str_modify()

void rb_str_modify | ( | VALUE | str | ) |

Declares that the string is about to be modified.

This for instance let the string have a dedicated backend storage.

Parameters

  [out] | str | String about to be modified.

Exceptions

  rb_eRuntimeError | `str` is `locktmp`-ed.
  rb_eFrozenError | `str` is frozen.

Precondition
  `str` must not be any arbitrary objects except RString.

Postcondition
  Upon successful return the passed string is eligible to be modified.

Definition at line 2437 of file string.c.

Referenced by rb_str_vcatf().

## ◆ rb_str_modify_expand()

void rb_str_modify_expand | ( | VALUE | str,
|  | long | capa )

Identical to rb_str_modify(), except it additionally expands the capacity of the receiver.

Parameters

  [out] | str | Target string to modify.
  [in] | capa | Additional capacity to add.

Exceptions

  rb_eArgError | `capa` is negative.
  rb_eRuntimeError | `str` is `locktmp`-ed.
  rb_eFrozenError | `str` is frozen.

Precondition
  `str` must not be any arbitrary objects except RString.

Postcondition
  Upon successful return the passed string is modified so that its capacity is increased for `capa` bytes.

Definition at line 2445 of file string.c.

Referenced by rb_econv_append().

## ◆ rb_str_new()

VALUE rb_str_new | ( | const char * | ptr,
|  | long | len )

Allocates an instance of rb_cString.

Parameters

  [in] | ptr | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString, of `len` bytes length, of "binary" encoding, whose contents are verbatim copy of `ptr`.

Precondition
  At least `len` bytes of continuous memory region shall be accessible via `ptr`.

Definition at line 959 of file string.c.

## ◆ rb_str_new_cstr()

VALUE rb_str_new_cstr | ( | const char * | ptr | ) |

Identical to rb_str_new(), except it assumes the passed pointer is a pointer to a C string.

Parameters

  [in] | ptr | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.
  rb_eArgError | `ptr` is a null pointer.

Returns
  An instance of rb_cString, of "binary" encoding, whose contents are verbatim copy of `ptr`.

Precondition
  `ptr` must not be a null pointer.

Definition at line 993 of file string.c.

## ◆ rb_str_new_frozen()

VALUE rb_str_new_frozen | ( | VALUE | str | ) |

Creates a frozen copy of the string, if necessary.

This function does nothing when the passed string is already frozen. Otherwise, it allocates a copy of it, which is frozen. The passed string is untouched either ways.

Parameters

  [in] | str | An object of RString.

Returns
  Something frozen.

Precondition
  `str` must not be any arbitrary object except RString.

Note
  Use StringValue to enforce the precondition.

Definition at line 1382 of file string.c.

Referenced by rb_econv_prepare_options(), rb_econv_substr_append(), and rb_set_class_path_string().

## ◆ rb_str_new_shared()

VALUE rb_str_new_shared | ( | VALUE | str | ) |

Identical to rb_str_new_cstr(), except it takes a Ruby's string instead of C's.

Implementation wise it creates a string that shares the backend memory region with the receiver. So the name. But there is no way for extension libraries to know if a string is of such variant.

Parameters

  [in] | str | An object of RString.

Returns
  An allocated instance of rb_cString, which shares the encoding, length, and contents with the passed string.

Precondition
  `str` must not be any arbitrary object except RString.

Note
  Use StringValue to enforce the precondition.

Definition at line 1376 of file string.c.

## ◆ rb_str_new_static()

VALUE rb_str_new_static | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new(), except it takes a C string literal.

Parameters

  [in] | ptr | A C string literal.
  [in] | len | `strlen(ptr)`.

Exceptions

  rb_eArgError | `len` out of range of `size_t`.

Precondition
  `ptr` must be a C string constant.

Returns
  An instance of rb_cString, of "binary" encoding, whose backend storage is the passed C string literal.

Warning
  It is a very bad idea to write to a C string literal (often immediate SEGV shall occur). Consider return values of this function be read-only.

Definition at line 1056 of file string.c.

## ◆ rb_str_new_with_class()

VALUE rb_str_new_with_class | ( | VALUE | obj,
|  | const char * | ptr,
|  | long | len )

Identical to rb_str_new(), except it takes the class of the allocating object.

Parameters

  [in] | obj | A string-ish object.
  [in] | ptr | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of the class of `obj`, of `len` bytes length, of "binary" encoding, whose contents are verbatim copy of `ptr`.

Precondition
  At least `len` bytes of continuous memory region shall be accessible via `ptr`.

Definition at line 1513 of file string.c.

## ◆ rb_str_offset()

long rb_str_offset | ( | VALUE | str,
|  | long | pos )

"Inverse" of rb_str_sublen().

This function scans the contents to find the byte index that matches the character index. Generally speaking this is an `O(n)` operation. Could be slow.

Parameters

  [in] | str | The string to scan.
  [in] | pos | Offset, in characters.

Returns
  Offset, in bytes.

Definition at line 2744 of file string.c.

## ◆ rb_str_plus()

VALUE rb_str_plus | ( | VALUE | lhs,
|  | VALUE | rhs )

Generates a new string, concatenating the former to the latter.

It can also be seen as a routine identical to rb_str_append(), except it doesn't tamper the passed strings to create a new one instead.

Parameters

  [in] | lhs | Source string #1.
  [in] | rhs | Source string #2.

Exceptions

  rb_eEncCompatError | Can't mix the encodings.
  rb_eArgError | Result string too big.

Returns
  A new string containing `rhs` concatenated to `lhs`.

Precondition
  Both objects must not be any arbitrary objects except RString.

Note
  This operation doesn't commute. Don't get confused by the "plus" terminology. For historical reasons there are some noncommutative `+`s in Ruby. This is one of such things. There has been a long discussion around `+`s in programming languages.

Definition at line 2211 of file string.c.

## ◆ rb_str_replace()

VALUE rb_str_replace | ( | VALUE | dst,
|  | VALUE | src )

Replaces the contents of the former object with the stringised contents of the latter.

Parameters

  [out] | dst | Destination object.
  [in] | src | Source object.

Exceptions

  rb_eTypeError | `src` has no implicit conversion to String.
  rb_eRuntimeError | `dst` is `locktmp`-ed.
  rb_eFrozenError | `dst` is frozen.

Returns
  The passed `dst`.

Precondition
  `dst` must not be any arbitrary object except RString.

Postcondition
  `dst`'s former components are abandoned. It now has the identical encoding, length, and contents to `src`.

Definition at line 6030 of file string.c.

## ◆ rb_str_resize()

VALUE rb_str_resize | ( | VALUE | str,
|  | long | len )

Overwrites the length of the string.

In contrast to rb_str_set_len(), this function can also expand a string.

Parameters

  [out] | str | String to shrink.
  [in] | len | New length of the string.

Exceptions

  rb_eArgError | `len` is negative.
  rb_eRuntimeError | `str` is `locktmp`-ed.
  rb_eFrozenError | `str` is frozen.

Returns
  The passed `str`.

Precondition
  `str` must not be any arbitrary objects except RString.

Postcondition
  Upon successful return `str` is either expanded or shrunken to have its length be `len`.

Definition at line 3064 of file string.c.

Referenced by rb_find_file(), rb_find_file_ext(), rb_reg_quote(), rb_str_concat(), rb_str_format(), rb_str_freeze(), and ruby_init_loadpath().

## ◆ rb_str_resurrect()

VALUE rb_str_resurrect | ( | VALUE | str | ) |

I guess there is no use case of this function in extension libraries, but this is a routine identical to rb_str_dup(), except it always creates an instance of rb_cString regardless of the given object's class.

This makes the most sense when the passed string is formerly hidden by rb_obj_hide().

Parameters

  [in] | str | A string, possibly hidden.

Returns
  A duplicated new instance of rb_cString.

Definition at line 1840 of file string.c.

## ◆ rb_str_scrub()

VALUE rb_str_scrub | ( | VALUE | str,
|  | VALUE | repl )

"Cleanses" the string.

A string has its encoding and its contents. They, in practice, do not always fit. There are strings in the wild that are "broken"; include bit patterns that are not allowed by its encoding. That can happen when a user copy&pasted something bad, network input got clobbered by a middleman, cosmic rays hit the physical memory, and many more occasions. This function takes such strings, and fills the "broken" portion with the passed replacement bit pattern.

This function also takes a ruby block. That is a neat way to do things, but can be annoying when the caller function want to use a block for another purpose.

Parameters

  [in] | str | Target string to scrub.
  [in] | repl | Replacement string. When it is a string, this function takes that as a replacement. When it is RUBY_Qnil, this function tries to yield a block (if any) and takes its evaluated value as a replacement. In case of RUBY_Qnil without a block, this function takes an encoding-specific default character (`U+FFFD`, for instance) as a last resort.

Exceptions

  rb_eTypeError | `repl` is neither string nor nil.
  rb_eArgError | `repl` itself is broken.
  rb_eEncCompatError | `repl` and `str` are incompatible.

Return values

  RUBY_Qnil | `str` is already clean.
  otherwise | A new, clean string.

Definition at line 10948 of file string.c.

## ◆ rb_str_set_len()

void rb_str_set_len | ( | VALUE | str,
|  | long | len )

Overwrites the length of the string.

Typically this is used to shrink a string that was formerly expanded.

extern int fd;
auto str = rb_eval_string("'...'");
rb_str_modify_expand(str, BUFSIZ);
if (auto len = recv(fd, RSTRING_PTR(str), BUFSIZ, 0); len >= 0) {
rb_str_set_len(str, len);
}
else {
rb_sys_fail("recv(2)");
}
rb_sys_fail
void rb_sys_fail(const char *mesg)
Converts a C errno into a Ruby exception, then raises it.
Definition error.c:3274
rb_eval_string
VALUE rb_eval_string(const char *str)
Evaluates the given string.
Definition vm_eval.c:1848
rb_str_set_len
void rb_str_set_len(VALUE str, long len)
Overwrites the length of the string.
Definition string.c:3020
rb_str_modify_expand
void rb_str_modify_expand(VALUE str, long capa)
Identical to rb_str_modify(), except it additionally expands the capacity of the receiver.
Definition string.c:2445
RSTRING_PTR
static char * RSTRING_PTR(VALUE str)
Queries the contents pointer of the string.
Definition rstring.h:498

Parameters

  [out] | str | String to shrink.
  [in] | len | New length of the string.

Exceptions

  rb_eRuntimeError | `str` is `locktmp`-ed.
  rb_eFrozenError | `str` is frozen.

Precondition
  `str` must not be any arbitrary objects except RString.

Postcondition
  Upon successful return `str`'s length is set to `len`.

Definition at line 3020 of file string.c.

Referenced by rb_ary_join(), rb_econv_append(), rb_find_file_ext(), and rb_str_format().

## ◆ rb_str_shared_replace()

void rb_str_shared_replace | ( | VALUE | dst,
|  | VALUE | src )

Replaces the contents of the former with the latter.

Parameters

  [out] | dst | Destination object.
  [in] | src | Source object.

Precondition
  Both objects must not be any arbitrary objects except RString.

Postcondition
  `dst`'s former components are abandoned. It now has the identical encoding, length, and contents to `src`.

See also
  rb_str_replace()

Definition at line 1618 of file string.c.

## ◆ rb_str_split()

VALUE rb_str_split | ( | VALUE | str,
|  | const char * | delim )

Divides the given string based on the given delimiter.

This is the 1-argument 0-block version of `String#split`.

Parameters

  [in] | str | Object in question to split.
  [in] | delim | Delimiter, in C string.

Exceptions

  rb_eTypeError | `str` has no implicit conversion to String.
  rb_eArgError | `delim` is a null pointer.

Returns
  An array of strings, which are substrings of the passed `str`. If `delim` is an empty C string (i.e. `""`), `str` is split into each characters. If `delim` is a C string whose sole content is a whitespace (i.e. `" "`), `str` is split on whitespaces, with leading and trailing whitespace and runs of contiguous whitespace characters ignored. Otherwise, `str` is split according to `delim`.

Definition at line 8896 of file string.c.

## ◆ rb_str_strlen()

long rb_str_strlen | ( | VALUE | str | ) |

Counts the number of characters (not bytes) that are stored inside of the given string.

This of course depends on its encoding. Also this function generally runs in O(n), because for instance you have to scan the entire string to know how many characters are there in a UTF-8 string.

Parameters

  [in] | str | Target string to query.

Returns
  Its number of characters.

Definition at line 2149 of file string.c.

## ◆ rb_str_sublen()

long rb_str_sublen | ( | VALUE | str,
|  | long | pos )

Byte offset to character offset conversion.

This makes sense when the receiver is in a multibyte encoding. The string's i-th character does not always sit at its i-th byte. This function scans the contents to find the character index that matches the byte index. Generally speaking this is an `O(n)` operation. Could be slow.

Parameters

  [in] | str | The string to scan.
  [in] | pos | Offset, in bytes.

Returns
  Offset, in characters.

Definition at line 2791 of file string.c.

Referenced by rb_reg_match(), and rb_reg_match2().

## ◆ rb_str_subpos()

char * rb_str_subpos | ( | VALUE | str,
|  | long | beg,
|  | long * | len )

Identical to rb_str_substr(), except it returns a C's string instead of Ruby's.

Parameters

  [in] | str | The string to slice.
  [in] | beg | Requested offset of the substring.
  [in,out] | len | Requested length of the substring.

Return values

  NULL | Parameters out of range.
  otherwise | A pointer inside of `str`'s backend storage where the specified substring exist.

Precondition
  `str` must not be any arbitrary objects except RString.

Postcondition
  `len` is updated to have the length of the return value.

Definition at line 2834 of file string.c.

## ◆ rb_str_subseq()

VALUE rb_str_subseq | ( | VALUE | str,
|  | long | beg,
|  | long | len )

Identical to rb_str_substr(), except the numbers are interpreted as byte offsets instead of character offsets.

Parameters

  [in] | str | The string to slice.
  [in] | beg | Requested offset of the substring.
  [in] | len | Requested length of the substring.

Returns
  A new string whose contents is the specified substring of `str`.

Precondition
  `str` must not be any arbitrary objects except RString.
  `beg` and `len` must not point to OOB contents.

Definition at line 2826 of file string.c.

Referenced by rb_path_to_class(), rb_reg_match_post(), rb_reg_match_pre(), rb_reg_nth_match(), rb_reg_regsub(), rb_str_ellipsize(), and ruby_init_loadpath().

## ◆ rb_str_substr()

VALUE rb_str_substr | ( | VALUE | str,
|  | long | beg,
|  | long | len )

This is the implementation of two-argumented `String#slice`.

- Returns the substring of the given `len` found in `str` at offset `beg`:

  'foo'[0, 2] # => "fo"
  'foo'[0, 0] # => ""

- Counts backward from the end of `str` if `beg` is negative:

  'foo'[-2, 2] # => "oo"

- Special case: returns a new empty string if `beg` is equal to the length of `str`:

  'foo'[3, 2] # => ""

- Returns a null pointer if `beg` is out of range:

  'foo'[4, 2] # => nil
  'foo'[-4, 2] # => nil

- Returns the trailing substring of `str` if `len` is large:

  'foo'[1, 50] # => "oo"

- Returns a null pointer if `len` is negative:

  'foo'[0, -1] # => nil

Parameters

  [in] | str | The string to slice.
  [in] | beg | Requested offset of the substring.
  [in] | len | Requested length of the substring.

Return values

  RUBY_Qnil | Parameters out of range.
  otherwise | A new string whose contents is the specified substring of `str`.

Precondition
  `str` must not be any arbitrary objects except RString.

Definition at line 2921 of file string.c.

## ◆ rb_str_succ()

VALUE rb_str_succ | ( | VALUE | orig | ) |

Searches for the "successor" of a string.

This function is complicated! This is the only function in the entire ruby API (either C or Ruby) that generates a string out of thin air. First, the successor to an empty string is a new empty string:

''.succ # => ""

Otherwise the successor is calculated by "incrementing" characters. The first character to be incremented is the rightmost alphanumeric: or, if no alphanumerics, the rightmost character:

'THX1138'.succ # => "THX1139"
'<<koala>>'.succ # => "<<koalb>>"
'***'.succ # => '**+'

The successor to a digit is another digit, "carrying" to the next-left character for a "rollover" from 9 to 0, and prepending another digit if necessary:

'00'.succ # => "01"
'09'.succ # => "10"
'99'.succ # => "100"
'-9'.succ # => "-10"

The successor to a letter is another letter of the same case, carrying to the next-left character for a rollover, and prepending another same-case letter if necessary:

'aa'.succ # => "ab"
'az'.succ # => "ba"
'zz'.succ # => "aaa"
'AA'.succ # => "AB"
'AZ'.succ # => "BA"
'ZZ'.succ # => "AAA"

The successor to a non-alphanumeric character is the next character in the underlying character set's collating sequence, carrying to the next-left character for a rollover, and prepending another character if necessary:

s = "\u03A1"
s.succ # => "\u03A3" # There is no such thing like \u03A2.
s = 255.chr * 3
s # => "\xFF\xFF\xFF"
s.succ # => "\x01\x00\x00\x00"

Carrying can occur between and among mixtures of alphanumeric characters:

s = 'zz99zz99'
s.succ # => "aaa00aa00"
s = '99zz99zz'
s.succ # => "100aa00aa"
s = '1.9.9'
s.succ # => "2.0.0"

Parameters

  [in] | orig | Predecessor string.

Returns
  Successor string.

Definition at line 4828 of file string.c.

## ◆ rb_str_times()

VALUE rb_str_times | ( | VALUE | str,
|  | VALUE | num )

Repetition of a string.

Parameters

  [in] | str | String to repeat.
  [in] | num | Count, something numeric.

Exceptions

  rb_eArgError | `num` is negative.

Returns
  A new string repeating `num` times of `str`.

Definition at line 2283 of file string.c.

## ◆ rb_str_tmp_new()

VALUE rb_str_tmp_new | ( | long | len | ) |

Allocates a "temporary" string.

This is a hidden empty string. Handy on occasions.

Parameters

  [in] | len | Designed length of the string.

Returns
  A hidden, empty string.

See also
  rb_obj_hide()

Definition at line 1565 of file string.c.

Referenced by rb_find_file(), and rb_find_file_ext().

## ◆ rb_str_to_interned_str()

VALUE rb_str_to_interned_str | ( | VALUE | str | ) |

Identical to rb_interned_str(), except it takes a Ruby's string instead of C's.

It can also be seen as a routine identical to to rb_str_new_shared(), except it returns an infamous "f"string.

Parameters

  [in] | str | An object of RString.

Returns
  An instance of rb_cString, either cached or allocated, which has the identical encoding, length, and contents with the passed string.

Precondition
  `str` must not be any arbitrary object except RString.

Note
  Use StringValue to enforce the precondition.

Definition at line 11951 of file string.c.

## ◆ rb_str_unlocktmp()

VALUE rb_str_unlocktmp | ( | VALUE | str | ) |

Releases a lock formerly obtained by rb_str_locktmp().

Parameters

  [out] | str | String to unlock.

Exceptions

  rb_eRuntimeError | `str` already unlocked.

Returns
  The given string.

Postcondition
  The string is locked.

Definition at line 3003 of file string.c.

## ◆ rb_str_update()

void rb_str_update | ( | VALUE | dst,
|  | long | beg,
|  | long | len,
|  | VALUE | src )

Replaces some (or all) of the contents of the given string.

This is the implementation of three-argumented `String#[]=`.

Parameters

  [out] | dst | Target string to update.
  [in] | beg | Offset of the affected portion.
  [in] | len | Length of the affected portion.
  [in] | src | Object to be assigned.

Exceptions

  rb_eTypeError | `src` has no implicit conversion to String.
  rb_eIndexError | `len` is negative, or `beg` is OOB.
  rb_eRuntimeError | `dst` is `locktmp`-ed.
  rb_eFrozenError | `dst` is frozen.

Note
  Unlike rb_str_substr(), this function raises.

Postcondition
  A portion of `dst` from `beg` to `len` is the stringised representation of `src`. If that replacement string is not the same length as the portion it is replacing, `dst` will be resized accordingly.

Definition at line 5332 of file string.c.

## ◆ rb_sym_to_s()

VALUE rb_sym_to_s | ( | VALUE | sym | ) |

This is an rb_sym2str() + rb_str_dup() combo.

Parameters

  [in] | sym | A symbol to query.

Returns
  A string duplicating the symbol's backend storage.

Definition at line 11597 of file string.c.

## ◆ rb_usascii_str_new()

VALUE rb_usascii_str_new | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new(), except it generates a string of "US ASCII" encoding.

This is different from rb_external_str_new(), not only for the output encoding, but also it doesn't convert the contents.

Parameters

  [in] | ptr | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString, of `len` bytes length, of "US ASCII" encoding, whose contents are verbatim copy of `ptr`.

Definition at line 965 of file string.c.

## ◆ rb_usascii_str_new_cstr()

VALUE rb_usascii_str_new_cstr | ( | const char * | ptr | ) |

Identical to rb_str_new_cstr(), except it generates a string of "US ASCII" encoding.

It can also be seen as a routine Identical to rb_usascii_str_new(), except it assumes the passed pointer is a pointer to a C string.

Parameters

  [in] | ptr | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.
  rb_eArgError | `ptr` is a null pointer.

Returns
  An instance of rb_cString, of "US ASCII" encoding, whose contents are verbatim copy of `ptr`.

Precondition
  `ptr` must not be a null pointer.

Definition at line 1005 of file string.c.

## ◆ rb_usascii_str_new_static()

VALUE rb_usascii_str_new_static | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new_static(), except it generates a string of "US ASCII" encoding instead of "binary".

It can also be seen as a routine identical to rb_usascii_str_new(), except it takes a C string literal.

Parameters

  [in] | ptr | A C string literal.
  [in] | len | `strlen(ptr)`.

Exceptions

  rb_eArgError | `len` out of range of `size_t`.

Precondition
  `ptr` must be a C string constant.

Returns
  An instance of rb_cString, of "US ASCII" encoding, whose backend storage is the passed C string literal.

Warning
  It is a very bad idea to write to a C string literal (often immediate SEGV shall occur). Consider return values of this function be read-only.

Definition at line 1062 of file string.c.

## ◆ rb_utf8_str_new()

VALUE rb_utf8_str_new | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new(), except it generates a string of "UTF-8" encoding.

Parameters

  [in] | ptr | A memory region of `len` bytes length.
  [in] | len | Length of `ptr`, in bytes, not including the terminating NUL character.

Exceptions

  rb_eNoMemError | Failed to allocate `len+1` bytes.
  rb_eArgError | `len` is negative.

Returns
  An instance of rb_cString, of `len` bytes length, of "UTF-8" encoding, whose contents are verbatim copy of `ptr`.

Definition at line 973 of file string.c.

## ◆ rb_utf8_str_new_cstr()

VALUE rb_utf8_str_new_cstr | ( | const char * | ptr | ) |

Identical to rb_str_new_cstr(), except it generates a string of "UTF-8" encoding.

It can also be seen as a routine Identical to rb_usascii_str_new(), except it assumes the passed pointer is a pointer to a C string.

Parameters

  [in] | ptr | A C string.

Exceptions

  rb_eNoMemError | Failed to allocate memory.
  rb_eArgError | `ptr` is a null pointer.

Returns
  An instance of rb_cString, of "UTF-8" encoding, whose contents are verbatim copy of `ptr`.

Precondition
  `ptr` must not be a null pointer.

Definition at line 1013 of file string.c.

## ◆ rb_utf8_str_new_static()

VALUE rb_utf8_str_new_static | ( | const char * | ptr,
|  | long | len )

Identical to rb_str_new_static(), except it generates a string of "UTF-8" encoding instead of "binary".

It can also be seen as a routine identical to rb_utf8_str_new(), except it takes a C string literal.

Parameters

  [in] | ptr | A C string literal.
  [in] | len | `strlen(ptr)`.

Exceptions

  rb_eArgError | `len` out of range of `size_t`.

Precondition
  `ptr` must be a C string constant.

Returns
  An instance of rb_cString, of "UTF-8" encoding, whose backend storage is the passed C string literal.

Warning
  It is a very bad idea to write to a C string literal (often immediate SEGV shall occur). Consider return values of this function be read-only.

Definition at line 1068 of file string.c.

## Variable Documentation

## ◆ rb_str_setter

rb_gvar_setter_t rb_str_setter

This is a rb_gvar_setter_t that refutes non-string assignments.

Exceptions

  rb_eTypeError | Passed something non-string.

Definition at line 1146 of file string.h.