(348a53415339076afc4a02fcd09f3ae36e9c4c61)

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

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

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

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

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

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.

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

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.

◆ 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] 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.

◆ 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] 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 ) 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 "") - 1)

Length of a string literal.

Parameters

[in] str A C String literal.

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

Definition at line 1692 of file string.h.

◆ 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]	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.

◆ 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] 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.

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

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 ) 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 ) 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] 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 2845 of file string.c.

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

◆ rb_external_str_new()

VALUE rb_external_str_new	(	const char *	ptr,
		long	len
	)

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

Parameters

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

Exceptions

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

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

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

Definition at line 1327 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 1333 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 1351 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 1357 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);

Parameters

[in] i Initial 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]	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 12493 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 12500 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 1339 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 1345 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,

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] obj An instance of rb_cString.

Exceptions

rb_eEncCompatError obj is ASCII incompatible.

Definition at line 2694 of file string.c.

Referenced by rb_str_format().

◆ rb_obj_as_string()

VALUE rb_obj_as_string ( VALUE obj )

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

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

Parameters

[in] obj Arbitrary ruby object to stringise.

Returns: An instance of rb_cString.

Definition at line 1770 of file string.c.

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

◆ rb_str_append()

VALUE rb_str_append	(	VALUE	dst,
		VALUE	src
	)

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

Parameters

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

Exceptions

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

Returns: The passed dst.

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

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

Definition at line 3662 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 3628 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]	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 3604 of file string.c.

◆ rb_str_buf_new()

VALUE rb_str_buf_new ( long capa )

Allocates a "string buffer".

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

Parameters

[in] capa Designed capacity of the generating string.

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

Definition at line 1627 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 1643 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 934 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 3430 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]	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 3440 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]	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 4087 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 4062 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 3904 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 5684 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 7299 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 1911 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]	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 11437 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 4133 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 1661 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 3163 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 4017 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 4031 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 7185 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 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] str Target string to query.

Returns: Its number of characters.

Definition at line 2354 of file string.c.

◆ rb_str_locktmp()

VALUE rb_str_locktmp ( VALUE str )

Obtains a "temporary lock" of the string.

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

Parameters

[out] str String to lock.

Exceptions

rb_eRuntimeError str already locked.

Returns: The given string.

Postcondition: The string is locked.

◆ rb_str_modify()

void rb_str_modify ( VALUE str )

Declares that the string is about to be modified.

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

Parameters

[out] str String about to be modified.

Exceptions

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

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

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

Definition at line 2642 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]	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 2650 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 1020 of file string.c.

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

◆ rb_str_new_cstr()

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 1054 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(), rb_throw_obj(), rb_usascii_str_new_cstr(), and rb_utf8_str_new_cstr().

◆ 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 1446 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] 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 1440 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 1117 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 1611 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 2949 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 2402 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 6464 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 3302 of file string.c.

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

◆ rb_str_resurrect()

VALUE rb_str_resurrect ( VALUE str )

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

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

Parameters

[in] str A string, possibly hidden.

Returns: A duplicated new instance of rb_cString.

Definition at line 1929 of file string.c.

◆ rb_str_scrub()

VALUE rb_str_scrub	(	VALUE	str,
		VALUE	repl
	)

"Cleanses" the string.

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

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

Parameters

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

Exceptions

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

Return values

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

Definition at line 11495 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)");
}

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 3254 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 1708 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 9392 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 2340 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 2996 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 3054 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 3046 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]	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 3141 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 5254 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 2474 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 1655 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 12487 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 3237 of file string.c.

◆ rb_str_update()

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

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

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

Parameters

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

Exceptions

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

Note: Unlike rb_str_substr(), this function raises.

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

Definition at line 5766 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 12138 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 1026 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] 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 1066 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]	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 1123 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 1034 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 1074 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 1129 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.

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ rb_enc_str_new_lit

◆ rb_enc_str_new_literal

◆ rb_exc_new_cstr

◆ rb_external_str_new_cstr

◆ rb_hash_end

◆ rb_hash_uint

◆ rb_hash_uint32

◆ rb_locale_str_new_cstr

◆ rb_str_buf_cat

◆ rb_str_buf_new_cstr

◆ rb_str_cat_cstr

◆ rb_str_dup_frozen

◆ rb_str_new

◆ rb_str_new_cstr

◆ rb_str_new_lit

◆ rb_str_new_literal

◆ rb_strlen_lit

◆ rb_usascii_str_new

◆ rb_usascii_str_new_cstr

◆ rb_usascii_str_new_lit

◆ rb_usascii_str_new_literal

◆ rb_utf8_str_new

◆ rb_utf8_str_new_cstr

◆ rb_utf8_str_new_lit

◆ rb_utf8_str_new_literal

Function Documentation

◆ rb_check_string_type()

◆ rb_external_str_new()

◆ rb_external_str_new_cstr()

◆ rb_filesystem_str_new()

◆ rb_filesystem_str_new_cstr()

◆ rb_hash_start()

◆ rb_interned_str()

◆ rb_interned_str_cstr()

◆ rb_locale_str_new()

◆ rb_locale_str_new_cstr()

◆ rb_memhash()

◆ rb_must_asciicompat()

◆ rb_obj_as_string()

◆ rb_str_append()

◆ rb_str_buf_append()

◆ rb_str_buf_cat()

◆ rb_str_buf_cat2()

◆ rb_str_buf_cat_ascii()

◆ rb_str_buf_new()

◆ rb_str_buf_new_cstr()

◆ rb_str_capacity()

◆ rb_str_cat()

◆ rb_str_cat2()

◆ rb_str_cat_cstr()

◆ rb_str_cmp()

◆ rb_str_comparable()

◆ rb_str_concat()

◆ rb_str_drop_bytes()

◆ rb_str_dump()

◆ rb_str_dup()

◆ rb_str_dup_frozen()

◆ rb_str_ellipsize()

◆ rb_str_equal()

◆ rb_str_free()

◆ rb_str_freeze()

◆ rb_str_hash()

◆ rb_str_hash_cmp()

◆ rb_str_inspect()

◆ rb_str_intern()

◆ rb_str_length()

◆ rb_str_locktmp()

◆ rb_str_modify()

◆ rb_str_modify_expand()

◆ rb_str_new()

◆ rb_str_new_cstr()

◆ rb_str_new_frozen()

◆ rb_str_new_shared()

◆ rb_str_new_static()