Ruby: RString Struct Reference

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

Data Fields
RString Struct Reference

Ruby's String. More...

`#include <rstring.h>`

## Data Fields
struct RBasic | basic
| Basic part, including flags and class.
union { |
struct { |
long len |
| Length of the string, not including terminating NUL character. More...
char * ptr |
| Pointer to the contents of the string. More...
union { |
long capa |
| Capacity of `*ptr`. More...
VALUE shared |
| Parent of the string. More...
} aux |
| Auxiliary info. More...
} heap |
| Strings that use separated memory region for contents use this pattern. More...
struct { |
char ary [RSTRING_EMBED_LEN_MAX+1] |
| When a string is short enough, it uses this area to store the contents themselves. More...
} embed |
| Embedded contents. More...
} | as |
| String's specific fields.

## Detailed Description

Ruby's String.

A string in ruby conceptually has these information:

- Encoding of the string.
- Length of the string.
- Contents of the string.

It is worth noting that a string is not an array of characters in ruby. It has never been. In 1.x a string was an array of integers. Since 2.x a string is no longer an array of anything. A string is a string – just like a Time is not an integer.

Definition at line 231 of file rstring.h.

## Field Documentation

## ◆ ary

char RString::ary[RSTRING_EMBED_LEN_MAX+1]

When a string is short enough, it uses this area to store the contents themselves.

This was impractical in the 20th century, but these days 64 bit machines can typically hold 24 bytes here. Could be sufficiently large. In this case the length is encoded into the flags.

Definition at line 298 of file rstring.h.

Referenced by rb_sym_all_symbols().

## ◆ [union]

union { ... } RString::as

String's specific fields.

Referenced by rb_str_resize(), RSTRING_END(), RSTRING_LEN(), and RSTRING_PTR().

## ◆ [union]

union { ... } RString::aux

Auxiliary info.

## ◆ basic

struct RBasic RString::basic

Basic part, including flags and class.

Definition at line 234 of file rstring.h.

## ◆ capa

long RString::capa

Capacity of `*ptr`.

A continuous memory region of at least `capa` bytes is expected to exist at `*ptr`. This can be bigger than `len`.

Definition at line 268 of file rstring.h.

Referenced by rb_str_buf_new(), rb_str_resize(), and rb_str_set_len().

## ◆ [struct]

struct { ... } RString::embed

Embedded contents.

## ◆ [struct]

struct { ... } RString::heap

Strings that use separated memory region for contents use this pattern.

Referenced by RSTRING_END(), RSTRING_LEN(), and RSTRING_PTR().

## ◆ len

long RString::len

Length of the string, not including terminating NUL character.

Note
  This is in bytes.

Definition at line 250 of file rstring.h.

Referenced by rb_check_id_cstr(), rb_check_symbol_cstr(), rb_enc_interned_str(), rb_enc_str_buf_cat(), rb_enc_str_new(), rb_enc_str_new_static(), rb_external_str_new(), rb_external_str_new_with_enc(), rb_filesystem_str_new(), rb_intern2(), rb_intern3(), rb_interned_str(), rb_locale_str_new(), rb_str_buf_cat_ascii(), rb_str_buf_new_cstr(), rb_str_cat(), rb_str_concat(), rb_str_conv_enc_opts(), rb_str_modify_expand(), rb_str_new(), rb_str_new_static(), rb_str_new_with_class(), rb_str_resize(), rb_str_set_len(), rb_str_subpos(), rb_str_subseq(), rb_str_substr(), rb_str_times(), rb_str_tmp_new(), rb_usascii_str_new(), rb_usascii_str_new_static(), rb_utf8_str_new(), rb_utf8_str_new_static(), RSTRING_END(), and RSTRING_LEN().

## ◆ ptr

char* RString::ptr

Pointer to the contents of the string.

In the old days each string had dedicated memory regions. That is no longer true today, but there still are strings of such properties. This field could be used to point such things.

Definition at line 258 of file rstring.h.

Referenced by rb_check_id_cstr(), rb_check_symbol_cstr(), rb_enc_interned_str(), rb_enc_interned_str_cstr(), rb_enc_str_buf_cat(), rb_enc_str_new(), rb_enc_str_new_cstr(), rb_enc_str_new_static(), rb_external_str_new(), rb_external_str_new_cstr(), rb_external_str_new_with_enc(), rb_filesystem_str_new(), rb_filesystem_str_new_cstr(), rb_interned_str(), rb_interned_str_cstr(), rb_locale_str_new(), rb_locale_str_new_cstr(), rb_str_buf_cat_ascii(), rb_str_buf_new_cstr(), rb_str_cat(), rb_str_cat_cstr(), rb_str_conv_enc_opts(), rb_str_new(), rb_str_new_cstr(), rb_str_new_static(), rb_str_new_with_class(), rb_str_resize(), rb_string_value(), rb_string_value_cstr(), rb_string_value_ptr(), rb_usascii_str_new(), rb_usascii_str_new_cstr(), rb_usascii_str_new_static(), rb_utf8_str_new(), rb_utf8_str_new_cstr(), rb_utf8_str_new_static(), RSTRING_END(), and RSTRING_PTR().

## ◆ shared

VALUE RString::shared

Parent of the string.

Nowadays strings can share their contents each other, constructing gigantic nest of objects. This situation is called "shared", and this is the field to control such properties.

Definition at line 276 of file rstring.h.

The documentation for this struct was generated from the following file:

- include/ruby/internal/core/rstring.h