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

Ruby 3.4.8p72 (2025-12-17 revision 995b59f66677d44767ce9faac6957e5543617ff9)

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:1155
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_cat(), 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 rb_ext_resolve_symbol(), and 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.

Referenced by rb_str_dup_frozen().

## ◆ 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:1137
len
int len
Length of the buffer.
Definition io.h:8

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_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(), 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_ext_resolve_symbol(), rb_file_open(), rb_load_file(), rb_path2class(), rb_str_split(), and rb_throw_obj().

## ◆ 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 "") / sizeof(str ""[0])) - 1)

Length of a string literal.

Parameters

  [in] | str | A C String literal.

Returns
  An integer constant expression that represents the number of str's elements, 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:1143

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:1149
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 2855 of file string.c.

Referenced by rb_ary_join(), rb_check_id(), rb_check_symbol(), rb_io_extract_encoding_option(), rb_str_buf_cat2(), 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 1347 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 1353 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 1371 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 1377 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:1764

Parameters

  [in] | i | Initial value.

Returns
  A hash value.

Definition at line 1764 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 12515 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 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 12522 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 1359 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 1365 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 1770 of file random.c.

Referenced by rb_memhash().

## ◆ 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 2697 of file string.c.

Referenced by rb_str_buf_cat2(), and 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 1780 of file string.c.

## ◆ 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 3681 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 3647 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 3623 of file string.c.

Referenced by rb_str_buf_cat2().

## ◆ 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 1648 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 1664 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 959 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 3449 of file string.c.

Referenced by rb_id_attrset(), 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 3459 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 4106 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 4081 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 3923 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 5701 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 7316 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 1921 of file string.c.

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

## ◆ 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 11457 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 4152 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 1682 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 3181 of file string.c.

Referenced by ruby_script().

## ◆ 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 4036 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 4050 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 7202 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 879 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 2357 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.

Referenced by rb_str_locktmp().

## ◆ 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 2645 of file string.c.

## ◆ 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 2653 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 1055 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 1079 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 1466 of file string.c.

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

## ◆ 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 1460 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 1137 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 1632 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 2959 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 2405 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 6481 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 3321 of file string.c.

## ◆ 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 1939 of file string.c.

Referenced by rb_str_buf_cat2().

## ◆ 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 11515 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_eval_string
VALUE rb_eval_string(const char *str)
Evaluates the given string.
Definition vm_eval.c:2058
rb_str_set_len
void rb_str_set_len(VALUE str, long len)
Overwrites the length of the string.
Definition string.c:3273
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:2653

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 3273 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 1718 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 9412 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 2343 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 3006 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 3064 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 3056 of file string.c.

Referenced by rb_path_to_class(), rb_reg_match_last(), 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 3153 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 5273 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 2477 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 1676 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 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 12509 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 3256 of file string.c.

Referenced by rb_str_locktmp().

## ◆ 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 5783 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 12158 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 1061 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 1091 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 1143 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 1067 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 1097 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 1149 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.