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

Ruby 3.4.5p51 (2025-07-16 revision 20cda200d3ce092571d0b5d342dadca69636cb0f)

rstring.h
Go to the documentation of this file.
1#ifndef RBIMPL_RSTRING_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RBIMPL_RSTRING_H
23#include "ruby/internal/config.h"
24#include "ruby/internal/arithmetic/long.h"
25#include "ruby/internal/attr/artificial.h"
26#include "ruby/internal/attr/pure.h"
27#include "ruby/internal/cast.h"
28#include "ruby/internal/core/rbasic.h"
29#include "ruby/internal/dllexport.h"
30#include "ruby/internal/fl_type.h"
31#include "ruby/internal/value_type.h"
32#include "ruby/internal/warning_push.h"
33#include "ruby/assert.h"
34
41#define RSTRING(obj) RBIMPL_CAST((struct RString *)(obj))
42
44#define RSTRING_NOEMBED RSTRING_NOEMBED
45#define RSTRING_FSTR RSTRING_FSTR
46#define RSTRING_LEN RSTRING_LEN
47#define RSTRING_LENINT RSTRING_LENINT
48#define RSTRING_PTR RSTRING_PTR
49#define RSTRING_END RSTRING_END
51
57
66#define StringValue(v) rb_string_value(&(v))
67
76#define StringValuePtr(v) rb_string_value_ptr(&(v))
77
89#define StringValueCStr(v) rb_string_value_cstr(&(v))
90
98#define SafeStringValue(v) StringValue(v)
99
117#define ExportStringValue(v) do { \
118 StringValue(v); \
119 (v) = rb_str_export(v); \
120} while (0)
121
123
137enum ruby_rstring_flags {
138
157 RSTRING_NOEMBED = RUBY_FL_USER1,
158
159 /* Actually, string encodings are also encoded into the flags, using
160 * remaining bits.*/
161
181 RSTRING_FSTR = RUBY_FL_USER17
182};
183
196 struct RString {
197
199 struct RBasic basic;
200
206 long len;
207
209 union {
210
215 struct {
222 char *ptr;
223
225 union {
226
232 long capa;
233
240 VALUE shared;
241 } aux;
242 } heap;
243
245 struct {
246 /* This is a length 1 array because:
247 * 1. GCC has a bug that does not optimize C flexible array members
248 * (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102452)
249 * 2. Zero length arrays are not supported by all compilers
250 */
251 char ary[1];
252 } embed;
253 } as;
254};
255
256 RBIMPL_SYMBOL_EXPORT_BEGIN()
267 VALUE rb_str_to_str(VALUE obj);
268
278 VALUE rb_string_value(volatile VALUE *ptr);
279
289char *rb_string_value_ptr(volatile VALUE *ptr);
290
302char *rb_string_value_cstr(volatile VALUE *ptr);
303
315 VALUE rb_str_export(VALUE obj);
316
325 VALUE rb_str_export_locale(VALUE obj);
326
327 RBIMPL_ATTR_ERROR(("rb_check_safe_str() and Check_SafeStr() are obsolete; use StringValue() instead"))
335void rb_check_safe_str(VALUE);
336
344#define Check_SafeStr(v) rb_check_safe_str(RBIMPL_CAST((VALUE)(v)))
345
354void rb_debug_rstring_null_ptr(const char *func);
355 RBIMPL_SYMBOL_EXPORT_END()
356
357 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
358 RBIMPL_ATTR_ARTIFICIAL()
366static inline long
367RSTRING_LEN(VALUE str)
368{
369 return RSTRING(str)->len;
370}
371
372 RBIMPL_WARNING_PUSH()
373#if RBIMPL_COMPILER_IS(Intel)
374 RBIMPL_WARNING_IGNORED(413)
375#endif
376
377 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
378 RBIMPL_ATTR_ARTIFICIAL()
388static inline struct RString
389rbimpl_rstring_getmem(VALUE str)
390{
391 RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING);
392
393 if (RB_FL_ANY_RAW(str, RSTRING_NOEMBED)) {
394 return *RSTRING(str);
395 }
396 else {
397 /* Expecting compilers to optimize this on-stack struct away. */
398 struct RString retval;
399 retval.len = RSTRING_LEN(str);
400 retval.as.heap.ptr = RSTRING(str)->as.embed.ary;
401 return retval;
402 }
403}
404
405 RBIMPL_WARNING_POP()
406
407 RBIMPL_ATTR_ARTIFICIAL()
415static inline char *
416RSTRING_PTR(VALUE str)
417{
418 char *ptr = rbimpl_rstring_getmem(str).as.heap.ptr;
419
420 if (RUBY_DEBUG && RB_UNLIKELY(! ptr)) {
421 /* :BEWARE: @shyouhei thinks that currently, there are rooms for this
422 * function to return NULL. Better check here for maximum safety.
423 *
424 * Also, this is not rb_warn() because RSTRING_PTR() can be called
425 * during GC (see what obj_info() does). rb_warn() needs to allocate
426 * Ruby objects. That is not possible at this moment. */
427 rb_debug_rstring_null_ptr("RSTRING_PTR");
428 }
429
430 return ptr;
431}
432
433 RBIMPL_ATTR_ARTIFICIAL()
441static inline char *
442RSTRING_END(VALUE str)
443{
444 struct RString buf = rbimpl_rstring_getmem(str);
445
446 if (RUBY_DEBUG && RB_UNLIKELY(! buf.as.heap.ptr)) {
447 /* Ditto. */
448 rb_debug_rstring_null_ptr("RSTRING_END");
449 }
450
451 return &buf.as.heap.ptr[buf.len];
452}
453
454 RBIMPL_ATTR_ARTIFICIAL()
467static inline int
468RSTRING_LENINT(VALUE str)
469{
470 return rb_long2int(RSTRING_LEN(str));
471}
472
480#ifdef HAVE_STMT_AND_DECL_IN_EXPR
481# define RSTRING_GETMEM(str, ptrvar, lenvar) \
482 __extension__ ({ \
483 struct RString rbimpl_str = rbimpl_rstring_getmem(str); \
484 (ptrvar) = rbimpl_str.as.heap.ptr; \
485 (lenvar) = rbimpl_str.len; \
486 })
487#else
488# define RSTRING_GETMEM(str, ptrvar, lenvar) \
489 ((ptrvar) = RSTRING_PTR(str), \
490 (lenvar) = RSTRING_LEN(str))
491#endif /* HAVE_STMT_AND_DECL_IN_EXPR */
492#endif /* RBIMPL_RSTRING_H */
artificial.h
Defines RBIMPL_ATTR_ARTIFICIAL.
RBIMPL_ATTR_ARTIFICIAL
#define RBIMPL_ATTR_ARTIFICIAL()
Wraps (or simulates) __attribute__((artificial))
Definition artificial.h:43
assert.h
RUBY_DEBUG
#define RUBY_DEBUG
Define this macro when you want assertions.
Definition assert.h:88
dllexport.h
Tweaking visibility of C variables/functions.
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
fl_type.h
Defines enum ruby_fl_type.
RB_FL_ANY_RAW
static bool RB_FL_ANY_RAW(VALUE obj, VALUE flags)
This is an implementation detail of RB_FL_ANY().
Definition fl_type.h:518
RUBY_FL_USER17
@ RUBY_FL_USER17
User-defined flag.
Definition fl_type.h:345
RUBY_FL_USER1
@ RUBY_FL_USER1
User-defined flag.
Definition fl_type.h:329
RBIMPL_ATTR_ERROR
#define RBIMPL_ATTR_ERROR(msg)
Wraps (or simulates) __attribute__((error))
Definition error.h:29
long.h
Arithmetic conversion between C's long and Ruby's.
rb_long2int
#define rb_long2int
Just another name of rb_long2int_inline.
Definition long.h:62
inline
#define inline
Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.
Definition defines.h:88
pure.h
Defines RBIMPL_ATTR_PURE.
RBIMPL_ATTR_PURE_UNLESS_DEBUG
#define RBIMPL_ATTR_PURE_UNLESS_DEBUG()
Enables RBIMPL_ATTR_PURE if and only if.
Definition pure.h:38
rbasic.h
Defines struct RBasic.
rb_str_export_locale
VALUE rb_str_export_locale(VALUE obj)
Identical to rb_str_export(), except it converts into the locale encoding instead.
Definition string.c:1389
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:2832
RSTRING_LENINT
static int RSTRING_LENINT(VALUE str)
Identical to RSTRING_LEN(), except it differs for the return type.
Definition rstring.h:468
RSTRING_END
static char * RSTRING_END(VALUE str)
Queries the end of the contents pointer of the string.
Definition rstring.h:442
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:2716
RSTRING_LEN
static long RSTRING_LEN(VALUE str)
Queries the length of the string.
Definition rstring.h:367
RSTRING
#define RSTRING(obj)
Convenient casting macro.
Definition rstring.h:41
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:1383
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:2727
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.
Definition string.c:1709
RBasic
Ruby object's base components.
Definition rbasic.h:63
RString
Ruby's String.
Definition rstring.h:196
RString::basic
struct RBasic basic
Basic part, including flags and class.
Definition rstring.h:199
RString::capa
long capa
Capacity of *ptr.
Definition rstring.h:232
RString::len
long len
Length of the string, not including terminating NUL character.
Definition rstring.h:206
RString::shared
VALUE shared
Parent of the string.
Definition rstring.h:240
RString::ptr
char * ptr
Pointer to the contents of the string.
Definition rstring.h:222
RString::as
union RString::@157025041137035241047331270155043025061071337053 as
String's specific fields.
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40
value_type.h
Defines enum ruby_value_type.
RUBY_T_STRING
@ RUBY_T_STRING
Definition value_type.h:120
warning_push.h
Defines RBIMPL_WARNING_PUSH.
RBIMPL_WARNING_IGNORED
#define RBIMPL_WARNING_IGNORED(flag)
Suppresses a warning.
Definition warning_push.h:80
RBIMPL_WARNING_PUSH
#define RBIMPL_WARNING_PUSH()
Pushes compiler warning state.
Definition warning_push.h:55
RBIMPL_WARNING_POP
#define RBIMPL_WARNING_POP()
Pops compiler warning state.
Definition warning_push.h:62