|
Ruby 4.1.0dev (2026-11-17 revision b4ade67ba58e9a4d70f887701cb8692d67093087)
|
Routines to manipulate encodings of strings. More...
#include "ruby/internal/dllexport.h"#include "ruby/internal/value.h"#include "ruby/internal/encoding/encoding.h"#include "ruby/internal/attr/nonnull.h"#include "ruby/internal/intern/string.h"

Go to the source code of this file.
Macros | |
| #define | rb_enc_str_coderange rb_enc_str_coderange_inline |
Functions | |
| VALUE | rb_enc_str_new (const char *ptr, rb_len_t len, rb_encoding *enc) |
| Identical to rb_str_new(), except it additionally takes an encoding. | |
| VALUE | rb_enc_str_new_cstr (const char *ptr, rb_encoding *enc) |
| Identical to rb_enc_str_new(), except it assumes the passed pointer is a pointer to a C string. | |
| VALUE | rb_enc_str_new_static (const char *ptr, rb_len_t len, rb_encoding *enc) |
| Identical to rb_enc_str_new(), except it takes a C string literal. | |
| VALUE | rb_enc_interned_str (const char *ptr, rb_len_t len, rb_encoding *enc) |
| Identical to rb_enc_str_new(), except it returns a "f"string. | |
| VALUE | rb_enc_interned_str_cstr (const char *ptr, rb_encoding *enc) |
| Identical to rb_enc_str_new_cstr(), except it returns a "f"string. | |
| rb_len_t | rb_enc_strlen (const char *head, const char *tail, rb_encoding *enc) |
| Counts the number of characters of the passed string, according to the passed encoding. | |
| char * | rb_enc_nth (const char *head, const char *tail, rb_len_t nth, rb_encoding *enc) |
| Queries the n-th character. | |
| VALUE | rb_obj_encoding (VALUE obj) |
| Identical to rb_enc_get_index(), except the return type. | |
| VALUE | rb_enc_str_buf_cat (VALUE str, const char *ptr, rb_len_t len, rb_encoding *enc) |
| Identical to rb_str_cat(), except it additionally takes an encoding. | |
| VALUE | rb_enc_uint_chr (unsigned int code, rb_encoding *enc) |
| Encodes the passed code point into a series of bytes. | |
| VALUE | rb_external_str_new_with_enc (const char *ptr, rb_len_t len, rb_encoding *enc) |
| Identical to rb_external_str_new(), except it additionally takes an encoding. | |
| VALUE | rb_str_export_to_enc (VALUE obj, rb_encoding *enc) |
| Identical to rb_str_export(), except it additionally takes an encoding. | |
| VALUE | rb_str_conv_enc (VALUE str, rb_encoding *from, rb_encoding *to) |
| Encoding conversion main routine. | |
| VALUE | rb_str_conv_enc_opts (VALUE str, rb_encoding *from, rb_encoding *to, int ecflags, VALUE ecopts) |
| Identical to rb_str_conv_enc(), except it additionally takes IO encoder options. | |
| int | rb_enc_str_coderange (VALUE str) |
| Scans the passed string to collect its code range. | |
| static int | rb_enc_str_coderange_inline (VALUE str) |
| Scans the passed string to collect its code range. | |
| rb_len_t | rb_str_coderange_scan_restartable (const char *str, const char *end, rb_encoding *enc, int *cr) |
| Scans the passed string until it finds something odd. | |
| int | rb_enc_str_asciionly_p (VALUE str) |
| Queries if the passed string is "ASCII only". | |
| rb_len_t | rb_memsearch (const void *x, rb_len_t m, const void *y, rb_len_t n, rb_encoding *enc) |
| Looks for the passed string in the passed buffer. | |
Routines to manipulate encodings of strings.
Definition in file string.h.
| #define rb_enc_str_coderange rb_enc_str_coderange_inline |
| VALUE rb_enc_interned_str | ( | const char * | ptr, |
| rb_len_t | len, | ||
| rb_encoding * | enc ) |
Identical to rb_enc_str_new(), except it returns a "f"string.
It can also be seen as a routine identical to rb_interned_str(), except it additionally takes an encoding.
| [in] | ptr | A memory region of len bytes length. |
| [in] | len | Length of ptr, in bytes, not including the terminating NUL character. |
| [in] | enc | Encoding of ptr. |
| rb_eArgError | `len` is negative. |
Definition at line 16303 of file string.c.
Referenced by rb_enc_interned_str_cstr().
| VALUE rb_enc_interned_str_cstr | ( | const char * | ptr, |
| rb_encoding * | enc ) |
Identical to rb_enc_str_new_cstr(), except it returns a "f"string.
It can also be seen as a routine identical to rb_interned_str_cstr(), except it additionally takes an encoding.
Definition at line 16327 of file string.c.
Referenced by rb_struct_define(), and rb_struct_define_under().
| char * rb_enc_nth | ( | const char * | head, |
| const char * | tail, | ||
| rb_len_t | nth, | ||
| rb_encoding * | enc ) |
Queries the n-th character.
Like rb_enc_strlen() this function can be fast or slow depending on the contents. Don't expect characters to be uniformly distributed across the entire string.
| [in] | head | Leftmost pointer to the string. |
| [in] | tail | Rightmost pointer to the string. |
| [in] | nth | Requested index of characters. |
| [in] | enc | Encoding of the string. |
Definition at line 3145 of file string.c.
Referenced by rb_str_ellipsize().
| int rb_enc_str_asciionly_p | ( | VALUE | str | ) |
Queries if the passed string is "ASCII only".
An ASCII only string is a string who doesn't have any non-ASCII characters at all. This doesn't necessarily mean the string is in ASCII encoding. For instance a String of CP932 encoding can quite much be ASCII only, depending on its contents.
| [in] | str | String in question. |
| 1 | It doesn't have non-ASCII characters. |
| 0 | It has characters that are out of ASCII. |
Definition at line 1002 of file string.c.
Referenced by rb_inspect().
| VALUE rb_enc_str_buf_cat | ( | VALUE | str, |
| const char * | ptr, | ||
| rb_len_t | len, | ||
| rb_encoding * | enc ) |
Identical to rb_str_cat(), except it additionally takes an encoding.
| [out] | str | Destination object. |
| [in] | ptr | Contents to append. |
| [in] | len | Length of src, in bytes. |
| [in] | enc | Encoding of ptr. |
| rb_eArgError | `len` is negative. |
| rb_eEncCompatError | `enc` is not compatible with `str`. |
| int rb_enc_str_coderange | ( | VALUE | str | ) |
Scans the passed string to collect its code range.
Because a Ruby's string is mutable, its contents change from time to time; so does its code range. A long-lived string tends to fall back to RUBY_ENC_CODERANGE_UNKNOWN. This API scans it and re-assigns a fine-grained code range constant.
| [out] | str | A string. |
|
inlinestatic |
Scans the passed string to collect its code range.
Because a Ruby's string is mutable, its contents change from time to time; so does its code range. A long-lived string tends to fall back to RUBY_ENC_CODERANGE_UNKNOWN. This API scans it and re-assigns a fine-grained code range constant.
| [out] | str | A string. |
Definition at line 295 of file string.h.
Referenced by rb_enc_str_coderange_inline().
| VALUE rb_enc_str_new | ( | const char * | ptr, |
| rb_len_t | len, | ||
| rb_encoding * | enc ) |
Identical to rb_str_new(), except it additionally takes an encoding.
| [in] | ptr | A memory region of len bytes length. |
| [in] | len | Length of ptr, in bytes, not including the terminating NUL character. |
| [in] | enc | Encoding of ptr. |
| rb_eNoMemError | Failed to allocate `len+1` bytes. |
| rb_eArgError | `len` is negative. |
| VALUE rb_enc_str_new_cstr | ( | const char * | ptr, |
| rb_encoding * | enc ) |
Identical to rb_enc_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 additionally takes an encoding.
| [in] | ptr | A C string. |
| [in] | enc | Encoding of ptr. |
| rb_eNoMemError | Failed to allocate memory. |
Definition at line 1189 of file string.c.
Referenced by rb_usascii_str_new_cstr(), and rb_utf8_str_new_cstr().
| VALUE rb_enc_str_new_static | ( | const char * | ptr, |
| rb_len_t | len, | ||
| rb_encoding * | enc ) |
Identical to rb_enc_str_new(), except it takes a C string literal.
It can also be seen as a routine identical to rb_str_new_static(), except it additionally takes an encoding.
| [in] | ptr | A C string literal. |
| [in] | len | strlen(ptr). |
| [in] | enc | Encoding of ptr. |
| rb_eArgError | `len` out of range of `size_t`. |
| rb_len_t rb_enc_strlen | ( | const char * | head, |
| const char * | tail, | ||
| rb_encoding * | enc ) |
Counts the number of characters of the passed string, according to the passed encoding.
This has to be complicated. The passed string could be invalid and/or broken. This routine would scan from the beginning til the end, byte by byte, to seek out character boundaries. Could be super slow.
| [in] | head | Leftmost pointer to the string. |
| [in] | tail | Rightmost pointer to the string. |
| [in] | enc | Encoding of the string. |
| VALUE rb_enc_uint_chr | ( | unsigned int | code, |
| rb_encoding * | enc ) |
Encodes the passed code point into a series of bytes.
| [in] | code | Code point. |
| [in] | enc | Target encoding scheme. |
| rb_eRangeError | `enc` does not glean `code`. |
Definition at line 3953 of file numeric.c.
Referenced by rb_io_ungetc().
| VALUE rb_external_str_new_with_enc | ( | const char * | ptr, |
| rb_len_t | len, | ||
| rb_encoding * | enc ) |
Identical to rb_external_str_new(), except it additionally takes an encoding.
However the whole point of rb_external_str_new() is to encode a string into default external encoding. Being able to specify arbitrary encoding just ruins the designed purpose the function meseems.
| [in] | ptr | A memory region of len bytes length. |
| [in] | len | Length of ptr, in bytes, not including the terminating NUL character. |
| [in] | enc | Target encoding scheme. |
| rb_eArgError | `len` is negative. |
Definition at line 1399 of file string.c.
Referenced by rb_external_str_new(), rb_external_str_new_cstr(), rb_filesystem_str_new(), rb_filesystem_str_new_cstr(), rb_locale_str_new(), and rb_locale_str_new_cstr().
| rb_len_t rb_memsearch | ( | const void * | x, |
| rb_len_t | m, | ||
| const void * | y, | ||
| rb_len_t | n, | ||
| rb_encoding * | enc ) |
Looks for the passed string in the passed buffer.
| [in] | x | Query string. |
| [in] | m | Number of bytes of x. |
| [in] | y | Buffer that potentially includes x. |
| [in] | n | Number of bytes of y. |
| [in] | enc | Encoding of both x and y. |
| -1 | Not found. |
| otherwise | Found index in y. |
Identical to rb_enc_get_index(), except the return type.
| [in] | obj | Object in question. |
| rb_eTypeError | `obj` is incapable of having an encoding. |
Definition at line 1278 of file encoding.c.
| rb_len_t rb_str_coderange_scan_restartable | ( | const char * | str, |
| const char * | end, | ||
| rb_encoding * | enc, | ||
| int * | cr ) |
Scans the passed string until it finds something odd.
Returns the number of bytes scanned. As the name implies this is suitable for repeated call. One of its application is IO#readlines. The method reads from its receiver's read buffer, maybe more than once, looking for newlines. But "newline" can be different among encodings. This API is used to detect broken contents to properly mark them as such.
| [in] | str | String to scan. |
| [in] | end | End of str. |
| [in] | enc | str's encoding. |
| [out] | cr | Return buffer. |
Definition at line 855 of file string.c.
Referenced by rb_econv_append(), and rb_str_set_len().
| VALUE rb_str_conv_enc | ( | VALUE | str, |
| rb_encoding * | from, | ||
| rb_encoding * | to ) |
Encoding conversion main routine.
| [in] | str | String to convert. |
| [in] | from | Source encoding. |
| [in] | to | Destination encoding. |
Definition at line 1393 of file string.c.
Referenced by rb_dir_getwd(), rb_str_encode_ospath(), and rb_str_export_to_enc().
| VALUE rb_str_conv_enc_opts | ( | VALUE | str, |
| rb_encoding * | from, | ||
| rb_encoding * | to, | ||
| int | ecflags, | ||
| VALUE | ecopts ) |
Identical to rb_str_conv_enc(), except it additionally takes IO encoder options.
The extra arguments can be constructed using io_extract_modeenc() etc.
| [in] | str | String to convert. |
| [in] | from | Source encoding. |
| [in] | to | Destination encoding. |
| [in] | ecflags | A set of enum ruby_econv_flag_type. |
| [in] | ecopts | Optional hash. |
Definition at line 1277 of file string.c.
Referenced by rb_str_conv_enc().
| VALUE rb_str_export_to_enc | ( | VALUE | obj, |
| rb_encoding * | enc ) |
Identical to rb_str_export(), except it additionally takes an encoding.
| [in] | obj | Target object. |
| [in] | enc | Target encoding. |
| rb_eTypeError | No implicit conversion to String. |
Definition at line 1498 of file string.c.
Referenced by rb_str_export(), and rb_str_export_locale().