Ruby: include/ruby/internal/core/rstring.h File Reference

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

Data Structures | Macros | Enumerations | Functions
rstring.h File Reference

Defines struct RString. More...

`#include "ruby/internal/config.h"`
`#include "ruby/internal/arithmetic/long.h"`
`#include "ruby/internal/attr/artificial.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/cast.h"`
`#include "ruby/internal/core/rbasic.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/fl_type.h"`
`#include "ruby/internal/value_type.h"`
`#include "ruby/internal/warning_push.h"`
`#include "ruby/assert.h"`

Go to the source code of this file.

## Data Structures
struct | RString
| Ruby's String. More...

## Macros
#define | RSTRING(obj)
| Convenient casting macro.
#define | Check_SafeStr(v)
#define | RSTRING_GETMEM(str, ptrvar, lenvar)
| Convenient macro to obtain the contents and length at once.
Conversion of Ruby strings into C's
#define | StringValue(v)
| Ensures that the parameter object is a String.
#define | StringValuePtr(v)
| Identical to StringValue, except it returns a `char*`.
#define | StringValueCStr(v)
| Identical to StringValuePtr, except it additionally checks for the contents for viability as a C string.
#define | SafeStringValue(v)
#define | ExportStringValue(v)
| Identical to StringValue, except it additionally converts the string's encoding to default external encoding.

## Enumerations
enum | ruby_rstring_consts { RSTRING_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 2 , RSTRING_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(char) - 1 }
| This is an enum because GDB wants it (rather than a macro). More...

## Functions
VALUE | rb_str_to_str (VALUE obj)
| Identical to rb_check_string_type(), except it raises exceptions in case of conversion failures.
VALUE | rb_string_value (volatile VALUE *ptr)
| Identical to rb_str_to_str(), except it fills the passed pointer with the converted object.
char * | rb_string_value_ptr (volatile VALUE *ptr)
| Identical to rb_str_to_str(), except it returns the converted string's backend memory region.
char * | rb_string_value_cstr (volatile VALUE *ptr)
| Identical to rb_string_value_ptr(), except it additionally checks for the contents for viability as a C string.
VALUE | rb_str_export (VALUE obj)
| Identical to rb_str_to_str(), except it additionally converts the string into default external encoding.
VALUE | rb_str_export_locale (VALUE obj)
| Identical to rb_str_export(), except it converts into the locale encoding instead.
static long | RSTRING_EMBED_LEN (VALUE str)
| Queries the length of the string.
static long | RSTRING_LEN (VALUE str)
| Queries the length of the string.
static char * | RSTRING_PTR (VALUE str)
| Queries the contents pointer of the string.
static char * | RSTRING_END (VALUE str)
| Queries the end of the contents pointer of the string.
static int | RSTRING_LENINT (VALUE str)
| Identical to RSTRING_LEN(), except it differs for the return type.

## Detailed Description

Defines struct RString.

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 rstring.h.

## Macro Definition Documentation

## ◆ Check_SafeStr

#define Check_SafeStr | ( |  | v | ) |

Value:
rb_check_safe_str(RBIMPL_CAST((VALUE)(v)))
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 392 of file rstring.h.

## ◆ ExportStringValue

#define ExportStringValue | ( |  | v | ) |

Value:
do { \
StringValue(v); \
(v) = rb_str_export(v); \
} while (0)
rb_str_export
VALUE rb_str_export(VALUE obj)
Identical to rb_str_to_str(), except it additionally converts the string into default external encodi...
Definition string.c:1301

Identical to StringValue, except it additionally converts the string's encoding to default external encoding.

Ruby has a concept called encodings. A string can have different encoding than the environment expects. Someone has to make sure its contents be converted to something suitable. This is that routine. Call it when necessary.

Parameters

  [in,out] | v | Arbitrary Ruby object.

Exceptions

  rb_eTypeError | No implicit conversion defined.

Returns
  Converted Ruby string's backend C string.

Postcondition
  `v` is a String.

Definition at line 123 of file rstring.h.

## ◆ RSTRING

#define RSTRING | ( |  | obj | ) |

Value:
RBIMPL_CAST((struct RString *)(obj))
RString
Ruby's String.
Definition rstring.h:231

Convenient casting macro.

Parameters

  obj | An object, which is in fact an RString.

Returns
  The passed object casted to RString.

Definition at line 41 of file rstring.h.

Referenced by rb_str_buf_new(), rb_str_drop_bytes(), rb_str_resize(), rb_str_times(), and RSTRING_EMBED_LEN().

## ◆ RSTRING_GETMEM

#define RSTRING_GETMEM | ( |  | str,
|  |  | ptrvar,
|  |  | lenvar )

Value:
((ptrvar) = RSTRING_PTR(str), \
(lenvar) = RSTRING_LEN(str))
RSTRING_LEN
static long RSTRING_LEN(VALUE str)
Queries the length of the string.
Definition rstring.h:484
RSTRING_PTR
static char * RSTRING_PTR(VALUE str)
Queries the contents pointer of the string.
Definition rstring.h:498

Convenient macro to obtain the contents and length at once.

Parameters

  str | String in question.
  ptrvar | Variable where its contents is stored.
  lenvar | Variable where its length is stored.

Definition at line 574 of file rstring.h.

Referenced by rb_reg_regsub(), rb_str_cmp(), rb_str_conv_enc_opts(), rb_str_format(), rb_str_hash_cmp(), and rb_str_plus().

## ◆ SafeStringValue

#define SafeStringValue | ( |  | v | ) |

Value:
StringValue(v)
StringValue
#define StringValue(v)
Ensures that the parameter object is a String.
Definition rstring.h:72

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 104 of file rstring.h.

Referenced by rb_io_extract_modeenc(), rb_io_ungetbyte(), and rb_io_ungetc().

## ◆ StringValue

#define StringValue | ( |  | v | ) |

Value:
rb_string_value(&(v))
rb_string_value
VALUE rb_string_value(volatile VALUE *ptr)
Identical to rb_str_to_str(), except it fills the passed pointer with the converted object.
Definition string.c:2501

Ensures that the parameter object is a String.

This is done by calling its `to_str` method.

Parameters

  [in,out] | v | Arbitrary Ruby object.

Exceptions

  rb_eTypeError | No implicit conversion defined.

Postcondition
  `v` is a String.

Definition at line 72 of file rstring.h.

Referenced by rb_ary_join(), rb_econv_prepare_options(), rb_exc_new_str(), rb_f_abort(), rb_str_append(), rb_str_format(), rb_str_plus(), rb_str_replace(), rb_str_split(), rb_str_update(), and rb_str_vcatf().

## ◆ StringValueCStr

#define StringValueCStr | ( |  | v | ) |

Value:
rb_string_value_cstr(&(v))
rb_string_value_cstr
char * rb_string_value_cstr(volatile VALUE *ptr)
Identical to rb_string_value_ptr(), except it additionally checks for the contents for viability as a...
Definition string.c:2617

Identical to StringValuePtr, except it additionally checks for the contents for viability as a C string.

Ruby can accept wider range of contents as strings, compared to C. This function is to check that.

Parameters

  [in,out] | v | Arbitrary Ruby object.

Exceptions

  rb_eTypeError | No implicit conversion defined.
  rb_eArgError | String is not C-compatible.

Returns
  Converted Ruby string's backend C string.

Postcondition
  `v` is a String.

Definition at line 95 of file rstring.h.

Referenced by rb_econv_prepare_options(), rb_find_file(), rb_find_file_ext(), rb_io_extract_encoding_option(), and rb_io_extract_modeenc().

## ◆ StringValuePtr

#define StringValuePtr | ( |  | v | ) |

Value:
rb_string_value_ptr(&(v))
rb_string_value_ptr
char * rb_string_value_ptr(volatile VALUE *ptr)
Identical to rb_str_to_str(), except it returns the converted string's backend memory region.
Definition string.c:2512

Identical to StringValue, except it returns a `char*`.

Parameters

  [in,out] | v | Arbitrary Ruby object.

Exceptions

  rb_eTypeError | No implicit conversion defined.

Returns
  Converted Ruby string's backend C string.

Postcondition
  `v` is a String.

Definition at line 82 of file rstring.h.

## Enumeration Type Documentation

## ◆ ruby_rstring_consts

enum ruby_rstring_consts

This is an enum because GDB wants it (rather than a macro).

People need not bother.

Enumerator
RSTRING_EMBED_LEN_SHIFT | Where RSTRING_EMBED_LEN_MASK resides.
RSTRING_EMBED_LEN_MAX | Max possible number of characters that can be embedded.

Definition at line 210 of file rstring.h.

## Function Documentation

## ◆ rb_str_export()

VALUE rb_str_export | ( | VALUE | obj | ) |

Identical to rb_str_to_str(), except it additionally converts the string into default external encoding.

Ruby has a concept called encodings. A string can have different encoding than the environment expects. Someone has to make sure its contents be converted to something suitable. This is that routine. Call it when necessary.

Parameters

  [in] | obj | Target object.

Exceptions

  rb_eTypeError | No implicit conversion to String.

Returns
  Converted ruby string of default external encoding.

Definition at line 1301 of file string.c.

## ◆ rb_str_export_locale()

VALUE rb_str_export_locale | ( | VALUE | obj | ) |

Identical to rb_str_export(), except it converts into the locale encoding instead.

Parameters

  [in] | obj | Target object.

Exceptions

  rb_eTypeError | No implicit conversion to String.

Returns
  Converted ruby string of locale encoding.

Definition at line 1307 of file string.c.

## ◆ rb_str_to_str()

VALUE rb_str_to_str | ( | VALUE | obj | ) |

Identical to rb_check_string_type(), except it raises exceptions in case of conversion failures.

Parameters

  [in] | obj | Target object.

Exceptions

  rb_eTypeError | No implicit conversion to String.

Returns
  Return value of `obj.to_str`.

See also
  rb_io_get_io
  rb_ary_to_ary

Definition at line 1609 of file string.c.

Referenced by rb_string_value().

## ◆ rb_string_value()

VALUE rb_string_value | ( | volatile VALUE * | ptr | ) |

Identical to rb_str_to_str(), except it fills the passed pointer with the converted object.

Parameters

  [in,out] | ptr | Pointer to a variable of target object.

Exceptions

  rb_eTypeError | No implicit conversion to String.

Returns
  Return value of `obj.to_str`.

Postcondition
  `*ptr` is the return value.

Definition at line 2501 of file string.c.

Referenced by rb_string_value_cstr(), and rb_string_value_ptr().

## ◆ rb_string_value_cstr()

char * rb_string_value_cstr | ( | volatile VALUE * | ptr | ) |

Identical to rb_string_value_ptr(), except it additionally checks for the contents for viability as a C string.

Ruby can accept wider range of contents as strings, compared to C. This function is to check that.

Parameters

  [in,out] | ptr | Pointer to a variable of target object.

Exceptions

  rb_eTypeError | No implicit conversion to String.
  rb_eArgError | String is not C-compatible.

Postcondition
  `*ptr` is the return value of `obj.to_str`.

Returns
  Pointer to the contents of the return value.

Definition at line 2617 of file string.c.

## ◆ rb_string_value_ptr()

char * rb_string_value_ptr | ( | volatile VALUE * | ptr | ) |

Identical to rb_str_to_str(), except it returns the converted string's backend memory region.

Parameters

  [in,out] | ptr | Pointer to a variable of target object.

Exceptions

  rb_eTypeError | No implicit conversion to String.

Postcondition
  `*ptr` is the return value of `obj.to_str`.

Returns
  Pointer to the contents of the return value.

Definition at line 2512 of file string.c.

## ◆ RSTRING_EMBED_LEN()

static long RSTRING_EMBED_LEN | ( | VALUE | str | ) |
| inlinestatic

Queries the length of the string.

Parameters

  [in] | str | String in question.

Returns
  Its length, in bytes.

Precondition
  `str` must be an instance of RString, and must has its RSTRING_NOEMBED flag off.

Definition at line 423 of file rstring.h.

## ◆ RSTRING_END()

static char * RSTRING_END | ( | VALUE | str | ) |
| inlinestatic

Queries the end of the contents pointer of the string.

Parameters

  [in] | str | String in question.

Returns
  Pointer to its end of contents.

Precondition
  `str` must be an instance of RString.

Definition at line 528 of file rstring.h.

Referenced by rb_enc_uint_chr(), rb_str_format(), rb_str_inspect(), rb_str_offset(), rb_str_set_len(), rb_str_update(), rb_str_vcatf(), and RREGEXP_SRC_END().

## ◆ RSTRING_LEN()

static long RSTRING_LEN | ( | VALUE | str | ) |
| inlinestatic

Queries the length of the string.

Parameters

  [in] | str | String in question.

Returns
  Its length, in bytes.

Precondition
  `str` must be an instance of RString.

Definition at line 484 of file rstring.h.

Referenced by rb_ary_join(), rb_econv_append(), rb_econv_open_opts(), rb_econv_str_append(), rb_econv_str_convert(), rb_find_file(), rb_find_file_ext(), rb_io_puts(), rb_io_ungetc(), rb_num2char_inline(), rb_path_to_class(), rb_profile_frame_full_label(), rb_reg_adjust_startpos(), rb_reg_match_post(), rb_reg_quote(), rb_reg_regcomp(), rb_reg_regsub(), rb_str_buf_append(), rb_str_comparable(), rb_str_concat(), rb_str_drop_bytes(), rb_str_dump(), rb_str_ellipsize(), rb_str_format(), rb_str_freeze(), rb_str_hash(), rb_str_modify_expand(), rb_str_resize(), rb_str_resurrect(), rb_str_set_len(), rb_str_subpos(), rb_str_succ(), rb_str_times(), RREGEXP_SRC_LEN(), and RSTRING_LENINT().

## ◆ RSTRING_LENINT()

static int RSTRING_LENINT | ( | VALUE | str | ) |
| inlinestatic

Identical to RSTRING_LEN(), except it differs for the return type.

Parameters

  [in] | str | String in question.

Exceptions

  rb_eRangeError | Too long.

Returns
  Its length, in bytes.

Precondition
  `str` must be an instance of RString.

Definition at line 554 of file rstring.h.

## ◆ RSTRING_PTR()

static char * RSTRING_PTR | ( | VALUE | str | ) |
| inlinestatic

Queries the contents pointer of the string.

Parameters

  [in] | str | String in question.

Returns
  Pointer to its contents.

Precondition
  `str` must be an instance of RString.

Definition at line 498 of file rstring.h.

Referenced by rb_class2name(), rb_econv_append(), rb_econv_open_opts(), rb_econv_substr_append(), rb_enc_uint_chr(), rb_enc_vsprintf(), rb_env_clear(), rb_find_file(), rb_find_file_ext(), rb_id2name(), rb_io_ungetc(), rb_num2char_inline(), rb_path_to_class(), rb_profile_frame_full_label(), rb_reg_adjust_startpos(), rb_reg_quote(), rb_reg_regcomp(), rb_reg_regsub(), rb_sourcefile(), rb_str_buf_append(), rb_str_concat(), rb_str_drop_bytes(), rb_str_dump(), rb_str_ellipsize(), rb_str_format(), rb_str_hash(), rb_str_inspect(), rb_str_offset(), rb_str_plus(), rb_str_set_len(), rb_str_sublen(), rb_str_subpos(), rb_str_succ(), rb_str_times(), rb_str_update(), rb_string_value_ptr(), RREGEXP_SRC_PTR(), and ruby_init_loadpath().