Ruby  3.4.0dev (2024-11-22 revision 37a72b0150ec36b4ea27175039afc28c62207b0c)
Macros | Functions | Variables
string.h File Reference

(37a72b0150ec36b4ea27175039afc28c62207b0c)

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"
Include dependency graph for string.h:
This graph shows which files directly or indirectly include this file:

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

Functions

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

Variables

rb_gvar_setter_t rb_str_setter
 This is a rb_gvar_setter_t that refutes non-string assignments. More...
 

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
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 
)    rb_enc_str_new_static((str), rb_strlen_lit(str), (enc))

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

Parameters
[in]strA C string literal.
[in]encA 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 
)    rb_enc_str_new_lit(str, enc)

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)))
#define RBIMPL_CONSTANT_P(expr)
Wraps (or simulates) __builtin_constant_p
Definition: constant_p.h:33

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

Parameters
[out]excA subclass of rb_eException.
[in]strMessage 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))

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

Parameters
[in]strA C string.
Exceptions
rb_eNoMemErrorFailed 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)    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,
 
)    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,
 
)    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))

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

Parameters
[in]strA C string.
Exceptions
rb_eNoMemErrorFailed 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.

◆ 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))

Identical to rb_str_new_cstr, except done differently.

Parameters
[in]strA C string.
Exceptions
rb_eNoMemErrorFailed 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)))

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

Parameters
[out]bufDestination object.
[in]strContents to append.
Exceptions
rb_eArgErrorResult 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.

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

Allocates an instance of rb_cString.

Parameters
[in]strA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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.

◆ rb_str_new_cstr

#define rb_str_new_cstr (   str)
Value:
((RBIMPL_CONSTANT_P(str) ? \
rbimpl_str_new_cstr : \
rb_str_new_cstr) (str))

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

Parameters
[in]strA C string.
Exceptions
rb_eNoMemErrorFailed 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.

◆ rb_str_new_lit

#define rb_str_new_lit (   str)    rb_str_new_static((str), rb_strlen_lit(str))

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

Parameters
[in]strA 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)    rb_str_new_lit(str)

Just another name of rb_str_new_lit.

Definition at line 1750 of file string.h.

◆ rb_strlen_lit

#define rb_strlen_lit (   str)    ((sizeof(str "") / sizeof(str ""[0])) - 1)

Length of a string literal.

Parameters
[in]strA 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.

◆ 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)))

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]strA memory region of len bytes length.
[in]lenLength of str, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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.

◆ 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))

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]strA C string.
Exceptions
rb_eNoMemErrorFailed 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.

◆ rb_usascii_str_new_lit

#define rb_usascii_str_new_lit (   str)    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]strA 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)    rb_usascii_str_new_lit(str)

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

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

Parameters
[in]strA memory region of len bytes length.
[in]lenLength of str, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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))

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]strA C string.
Exceptions
rb_eNoMemErrorFailed 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)    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]strA 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)    rb_utf8_str_new_lit(str)

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]objArbitrary ruby object to stringise.
Exceptions
rb_eTypeErrorobj.to_str returned something non-String.
Return values
RUBY_QnilNo 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 2854 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]ptrA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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 1342 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]ptrA C string.
Exceptions
rb_eNoMemErrorFailed 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 1348 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]ptrA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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 1366 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]ptrA C string.
Exceptions
rb_eNoMemErrorFailed 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 1372 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);
#define rb_hash_uint(h, i)
Just another name of st_hash_uint.
Definition: string.h:942
#define rb_hash_end(h)
Just another name of st_hash_end.
Definition: string.h:945
#define rb_hash_uint32(h, i)
Just another name of st_hash_uint32.
Definition: string.h:939
st_index_t rb_hash_start(st_index_t i)
Starts a series of hashing.
Definition: random.c:1746
Parameters
[in]iInitial value.
Returns
A hash value.

Definition at line 1746 of file random.c.

◆ 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]ptrA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eArgErrorlen 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 12508 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]ptrA C string.
Exceptions
rb_eNoMemErrorFailed 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 12515 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]ptrA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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 1354 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]ptrA C string.
Exceptions
rb_eNoMemErrorFailed 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 1360 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]ptrTarget message.
[in]lenLength 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 1752 of file random.c.

◆ 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]objAn instance of rb_cString.
Exceptions
rb_eEncCompatErrorobj is ASCII incompatible.

Definition at line 2703 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]objArbitrary ruby object to stringise.
Returns
An instance of rb_cString.

Definition at line 1786 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]dstDestination object.
[in]srcSource object.
Exceptions
rb_eEncCompatErrorCan't mix the encodings.
rb_eArgErrorResult 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 3677 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]dstDestination object.
[in]srcSource object.
Exceptions
rb_eEncCompatErrorCan't mix the encodings.
rb_eArgErrorResult 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 3643 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.

Referenced by rb_str_buf_new_cstr(), and rb_str_cat_cstr().

◆ 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]dstDestination object.
[in]srcSource string.
Exceptions
rb_eArgErrorResult 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 3619 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]capaDesigned capacity of the generating string.
Returns
An empty string, of "binary" encoding, whose capacity is capa.

Definition at line 1643 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]ptrA C string.
Exceptions
rb_eNoMemErrorFailed 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 1659 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]strString in question.
Returns
Its capacity.

Definition at line 954 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]dstDestination object.
[in]srcContents to append.
[in]srclenLength of src.
Exceptions
rb_eArgErrorsrclen 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 3445 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.

Referenced by rb_econv_open_exc(), and rb_find_file_ext().

◆ 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]dstDestination object.
[in]srcContents to append.
Exceptions
rb_eArgErrorResult string too big.
rb_eArgErrorsrc 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 3455 of file string.c.

Referenced by rb_ext_resolve_symbol(), and ruby_init_loadpath().

◆ 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]lhsA string.
[in]rhsAnother string.
Return values
-1lhs is "bigger than" rhs.
1rhs is "bigger than" lhs.
0Otherwise, e.g. not comparable.
Precondition
Both objects must not be any arbitrary objects except RString.

Definition at line 4102 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]str1A string.
[in]str2Another string.
Return values
1They agree on a total order.
0Otherwise.
Precondition
Both objects must not be any arbitrary objects except RString.

Definition at line 4077 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]dstDestination object.
[in]srcSource object, String or Numeric.
Exceptions
rb_eRangeErrorSource numeric is out of range.
rb_eEncCompatErrorSource string too long.
rb_eArgErrorResult 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 3919 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]strString to squash.
[in]lenNumber of bytes to reduce.
Exceptions
rb_eRuntimeErrorstr is locktmp-ed.
rb_eFrozenErrorstr 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 5697 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]strString to dump.
Exceptions
rb_eRuntimeErrorToo 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 7312 of file string.c.

Referenced by rb_econv_prepare_options().

◆ rb_str_dup()

VALUE rb_str_dup ( VALUE  str)

Duplicates a string.

Parameters
[in]strString in question to duplicate.
Returns
A duplicated new instance.
Precondition
str must be of RString.

Definition at line 1927 of file string.c.

Referenced by rb_class_path(), rb_find_file_ext(), rb_id_attrset(), 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]strThe string to shorten.
[in]lenThe maximum string length.
Exceptions
rb_eIndexErrorlen is negative.
Return values
strNo need to add ellipsis.
otherwiseA new, shortened string.
Note
The length is counted in characters.

Definition at line 11450 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]str1A string.
[in]str2Another string.
Return values
RUBY_QtrueThey are equal.
RUBY_QfalseThey are either different, or not comparable.

Definition at line 4148 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]strThe string to be executed.
Postcondition
The given string no longer exists.
Note
Maybe String#clear could be what you want.

Definition at line 1677 of file string.c.

◆ rb_str_freeze()

VALUE rb_str_freeze ( VALUE  str)

This is the implementation of String#freeze.

Parameters
[out]strTarget string to freeze.
Returns
The passed string.
Postcondition
Upon successful return the passed string is frozen.

Definition at line 3178 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]strAn object of RString.
Returns
A hash value.
Precondition
str must not be any arbitrary object except RString.

Definition at line 4032 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]str1A string.
[in]str2Another string.
Return values
1They have identical contents, length, and encodings.
0Otherwise.
Precondition
Both objects must not be any arbitrary objects except RString.

Definition at line 4046 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]strString 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 7198 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]strThe name of the id.
Exceptions
rb_eRuntimeErrorToo 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 878 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]strTarget string to query.
Returns
Its number of characters.

Definition at line 2363 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]strString to lock.
Exceptions
rb_eRuntimeErrorstr 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]strString about to be modified.
Exceptions
rb_eRuntimeErrorstr is locktmp-ed.
rb_eFrozenErrorstr 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 2651 of file string.c.

Referenced by rb_check_frozen_inline(), and 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]strTarget string to modify.
[in]capaAdditional capacity to add.
Exceptions
rb_eArgErrorcapa is negative.
rb_eRuntimeErrorstr is locktmp-ed.
rb_eFrozenErrorstr 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 2659 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]ptrA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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 1050 of file string.c.

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()

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]ptrA C string.
Exceptions
rb_eNoMemErrorFailed to allocate memory.
rb_eArgErrorptr 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 1074 of file string.c.

Referenced by 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_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]strAn 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 1461 of file string.c.

Referenced by rb_econv_prepare_options(), rb_econv_substr_append(), rb_io_open_descriptor(), 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]strAn 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 1455 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]ptrA C string literal.
[in]lenstrlen(ptr).
Exceptions
rb_eArgErrorlen 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 1132 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]objA string-ish object.
[in]ptrA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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 1627 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]strThe string to scan.
[in]posOffset, in characters.
Returns
Offset, in bytes.

Definition at line 2958 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]lhsSource string #1.
[in]rhsSource string #2.
Exceptions
rb_eEncCompatErrorCan't mix the encodings.
rb_eArgErrorResult 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 2411 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]dstDestination object.
[in]srcSource object.
Exceptions
rb_eTypeErrorsrc has no implicit conversion to String.
rb_eRuntimeErrordst is locktmp-ed.
rb_eFrozenErrordst 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 6477 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]strString to shrink.
[in]lenNew length of the string.
Exceptions
rb_eArgErrorlen is negative.
rb_eRuntimeErrorstr is locktmp-ed.
rb_eFrozenErrorstr 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 3317 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]strA string, possibly hidden.
Returns
A duplicated new instance of rb_cString.

Definition at line 1945 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]strTarget string to scrub.
[in]replReplacement 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_eTypeErrorrepl is neither string nor nil.
rb_eArgErrorrepl itself is broken.
rb_eEncCompatErrorrepl and str are incompatible.
Return values
RUBY_Qnilstr is already clean.
otherwiseA new, clean string.

Definition at line 11508 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) {
}
else {
rb_sys_fail("recv(2)");
}
void rb_sys_fail(const char *mesg)
Converts a C errno into a Ruby exception, then raises it.
Definition: error.c:3760
VALUE rb_eval_string(const char *str)
Evaluates the given string.
Definition: vm_eval.c:1975
void rb_str_set_len(VALUE str, long len)
Overwrites the length of the string.
Definition: string.c:3269
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:2659
static char * RSTRING_PTR(VALUE str)
Queries the contents pointer of the string.
Definition: rstring.h:416
Parameters
[out]strString to shrink.
[in]lenNew length of the string.
Exceptions
rb_eRuntimeErrorstr is locktmp-ed.
rb_eFrozenErrorstr 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 3269 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]dstDestination object.
[in]srcSource 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 1724 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]strObject in question to split.
[in]delimDelimiter, in C string.
Exceptions
rb_eTypeErrorstr has no implicit conversion to String.
rb_eArgErrordelim 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 9405 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]strTarget string to query.
Returns
Its number of characters.

Definition at line 2349 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]strThe string to scan.
[in]posOffset, in bytes.
Returns
Offset, in characters.

Definition at line 3005 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]strThe string to slice.
[in]begRequested offset of the substring.
[in,out]lenRequested length of the substring.
Return values
NULLParameters out of range.
otherwiseA 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 3063 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]strThe string to slice.
[in]begRequested offset of the substring.
[in]lenRequested 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 3055 of file string.c.

Referenced by 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]strThe string to slice.
[in]begRequested offset of the substring.
[in]lenRequested length of the substring.
Return values
RUBY_QnilParameters out of range.
otherwiseA new string whose contents is the specified substring of str.
Precondition
str must not be any arbitrary objects except RString.

Definition at line 3150 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]origPredecessor string.
Returns
Successor string.

Definition at line 5269 of file string.c.

◆ rb_str_times()

VALUE rb_str_times ( VALUE  str,
VALUE  num 
)

Repetition of a string.

Parameters
[in]strString to repeat.
[in]numCount, something numeric.
Exceptions
rb_eArgErrornum is negative.
Returns
A new string repeating num times of str.

Definition at line 2483 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]lenDesigned length of the string.
Returns
A hidden, empty string.
See also
rb_obj_hide()

Definition at line 1671 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]strAn 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 12502 of file string.c.

◆ rb_str_unlocktmp()

VALUE rb_str_unlocktmp ( VALUE  str)

Releases a lock formerly obtained by rb_str_locktmp().

Parameters
[out]strString to unlock.
Exceptions
rb_eRuntimeErrorstr already unlocked.
Returns
The given string.
Postcondition
The string is locked.

Definition at line 3252 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]dstTarget string to update.
[in]begOffset of the affected portion.
[in]lenLength of the affected portion.
[in]srcObject to be assigned.
Exceptions
rb_eTypeErrorsrc has no implicit conversion to String.
rb_eIndexErrorlen is negative, or beg is OOB.
rb_eRuntimeErrordst is locktmp-ed.
rb_eFrozenErrordst 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 5779 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]symA symbol to query.
Returns
A string duplicating the symbol's backend storage.

Definition at line 12151 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]ptrA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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 1056 of file string.c.

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

◆ 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]ptrA C string.
Exceptions
rb_eNoMemErrorFailed to allocate memory.
rb_eArgErrorptr 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 1086 of file string.c.

Referenced by rb_locale_charmap().

◆ 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]ptrA C string literal.
[in]lenstrlen(ptr).
Exceptions
rb_eArgErrorlen 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 1138 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]ptrA memory region of len bytes length.
[in]lenLength of ptr, in bytes, not including the terminating NUL character.
Exceptions
rb_eNoMemErrorFailed to allocate len+1 bytes.
rb_eArgErrorlen 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 1062 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]ptrA C string.
Exceptions
rb_eNoMemErrorFailed to allocate memory.
rb_eArgErrorptr 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 1092 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]ptrA C string literal.
[in]lenstrlen(ptr).
Exceptions
rb_eArgErrorlen 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 1144 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_eTypeErrorPassed something non-string.

Definition at line 1146 of file string.h.