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

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

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#if !USE_RVARGC
46#define RSTRING_EMBED_LEN_MASK RSTRING_EMBED_LEN_MASK
47#define RSTRING_EMBED_LEN_SHIFT RSTRING_EMBED_LEN_SHIFT
48#define RSTRING_EMBED_LEN_MAX RSTRING_EMBED_LEN_MAX
49#endif
50#define RSTRING_FSTR RSTRING_FSTR
51#define RSTRING_EMBED_LEN RSTRING_EMBED_LEN
52#define RSTRING_LEN RSTRING_LEN
53#define RSTRING_LENINT RSTRING_LENINT
54#define RSTRING_PTR RSTRING_PTR
55#define RSTRING_END RSTRING_END
72#define StringValue(v) rb_string_value(&(v))
73
82#define StringValuePtr(v) rb_string_value_ptr(&(v))
83
95#define StringValueCStr(v) rb_string_value_cstr(&(v))
96
104#define SafeStringValue(v) StringValue(v)
105
123#define ExportStringValue(v) do { \
124 StringValue(v); \
125 (v) = rb_str_export(v); \
126} while (0)
127
143enum ruby_rstring_flags {
144
163 RSTRING_NOEMBED = RUBY_FL_USER1,
164
165#if !USE_RVARGC
176 RSTRING_EMBED_LEN_MASK = RUBY_FL_USER2 | RUBY_FL_USER3 | RUBY_FL_USER4 |
177 RUBY_FL_USER5 | RUBY_FL_USER6,
178#endif
179
180 /* Actually, string encodings are also encoded into the flags, using
181 * remaining bits.*/
182
202 RSTRING_FSTR = RUBY_FL_USER17
203};
204
205#if !USE_RVARGC
210 enum ruby_rstring_consts {
212 RSTRING_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 2,
213
215 RSTRING_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(char) - 1
216};
217#endif
218
231 struct RString {
232
234 struct RBasic basic;
235
237 union {
238
243 struct {
244
250 long len;
251
258 char *ptr;
259
261 union {
262
268 long capa;
269
276 VALUE shared;
277 } aux;
278 } heap;
279
281 struct {
282#if USE_RVARGC
283 long len;
284 /* This is a length 1 array because:
285 * 1. GCC has a bug that does not optimize C flexible array members
286 * (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102452)
287 * 2. Zero length arrays are not supported by all compilers
288 */
289 char ary[1];
290#else
298 char ary[RSTRING_EMBED_LEN_MAX + 1];
299#endif
300 } embed;
301 } as;
302};
303
304 RBIMPL_SYMBOL_EXPORT_BEGIN()
315 VALUE rb_str_to_str(VALUE obj);
316
326 VALUE rb_string_value(volatile VALUE *ptr);
327
337char *rb_string_value_ptr(volatile VALUE *ptr);
338
350char *rb_string_value_cstr(volatile VALUE *ptr);
351
363 VALUE rb_str_export(VALUE obj);
364
373 VALUE rb_str_export_locale(VALUE obj);
374
375 RBIMPL_ATTR_ERROR(("rb_check_safe_str() and Check_SafeStr() are obsolete; use StringValue() instead"))
383void rb_check_safe_str(VALUE);
384
392#define Check_SafeStr(v) rb_check_safe_str(RBIMPL_CAST((VALUE)(v)))
393
402void rb_debug_rstring_null_ptr(const char *func);
403 RBIMPL_SYMBOL_EXPORT_END()
404
405 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
406 RBIMPL_ATTR_ARTIFICIAL()
422static inline long
423RSTRING_EMBED_LEN(VALUE str)
424{
425 RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING);
426 RBIMPL_ASSERT_OR_ASSUME(! RB_FL_ANY_RAW(str, RSTRING_NOEMBED));
427
428#if USE_RVARGC
429 long f = RSTRING(str)->as.embed.len;
430 return f;
431#else
432 VALUE f = RBASIC(str)->flags;
433 f &= RSTRING_EMBED_LEN_MASK;
434 f >>= RSTRING_EMBED_LEN_SHIFT;
435 return RBIMPL_CAST((long)f);
436#endif
437}
438
439 RBIMPL_WARNING_PUSH()
440#if RBIMPL_COMPILER_IS(Intel)
441 RBIMPL_WARNING_IGNORED(413)
442#endif
443
444 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
445 RBIMPL_ATTR_ARTIFICIAL()
455static inline struct RString
456rbimpl_rstring_getmem(VALUE str)
457{
458 RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING);
459
460 if (RB_FL_ANY_RAW(str, RSTRING_NOEMBED)) {
461 return *RSTRING(str);
462 }
463 else {
464 /* Expecting compilers to optimize this on-stack struct away. */
465 struct RString retval;
466 retval.as.heap.len = RSTRING_EMBED_LEN(str);
467 retval.as.heap.ptr = RSTRING(str)->as.embed.ary;
468 return retval;
469 }
470}
471
472 RBIMPL_WARNING_POP()
473
474 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
475 RBIMPL_ATTR_ARTIFICIAL()
483static inline long
484RSTRING_LEN(VALUE str)
485{
486 return rbimpl_rstring_getmem(str).as.heap.len;
487}
488
489 RBIMPL_ATTR_ARTIFICIAL()
497static inline char *
498RSTRING_PTR(VALUE str)
499{
500 char *ptr = rbimpl_rstring_getmem(str).as.heap.ptr;
501
502 if (RB_UNLIKELY(! ptr)) {
503 /* :BEWARE: @shyouhei thinks that currently, there are rooms for this
504 * function to return NULL. In the 20th century that was a pointless
505 * concern. However struct RString can hold fake strings nowadays. It
506 * seems no check against NULL are exercised around handling of them
507 * (one of such usages is located in marshal.c, which scares
508 * @shyouhei). Better check here for maximum safety.
509 *
510 * Also, this is not rb_warn() because RSTRING_PTR() can be called
511 * during GC (see what obj_info() does). rb_warn() needs to allocate
512 * Ruby objects. That is not possible at this moment. */
513 rb_debug_rstring_null_ptr("RSTRING_PTR");
514 }
515
516 return ptr;
517}
518
519 RBIMPL_ATTR_ARTIFICIAL()
527static inline char *
528RSTRING_END(VALUE str)
529{
530 struct RString buf = rbimpl_rstring_getmem(str);
531
532 if (RB_UNLIKELY(! buf.as.heap.ptr)) {
533 /* Ditto. */
534 rb_debug_rstring_null_ptr("RSTRING_END");
535 }
536
537 return &buf.as.heap.ptr[buf.as.heap.len];
538}
539
540 RBIMPL_ATTR_ARTIFICIAL()
553static inline int
554RSTRING_LENINT(VALUE str)
555{
556 return rb_long2int(RSTRING_LEN(str));
557}
558
566#ifdef HAVE_STMT_AND_DECL_IN_EXPR
567# define RSTRING_GETMEM(str, ptrvar, lenvar) \
568 __extension__ ({ \
569 struct RString rbimpl_str = rbimpl_rstring_getmem(str); \
570 (ptrvar) = rbimpl_str.as.heap.ptr; \
571 (lenvar) = rbimpl_str.as.heap.len; \
572 })
573#else
574# define RSTRING_GETMEM(str, ptrvar, lenvar) \
575 ((ptrvar) = RSTRING_PTR(str), \
576 (lenvar) = RSTRING_LEN(str))
577#endif /* HAVE_STMT_AND_DECL_IN_EXPR */
578#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
RBIMPL_ASSERT_OR_ASSUME
#define RBIMPL_ASSERT_OR_ASSUME(expr)
This is either RUBY_ASSERT or RBIMPL_ASSUME, depending on RUBY_DEBUG.
Definition assert.h:229
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:106
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:97
fl_type.h
Defines enum ruby_fl_type.
RUBY_FL_USHIFT
@ RUBY_FL_USHIFT
Number of bits in ruby_fl_type that are not open to users.
Definition fl_type.h:167
RB_FL_ANY_RAW
static bool RB_FL_ANY_RAW(VALUE obj, VALUE flags)
This is an implenentation detail of RB_FL_ANY().
Definition fl_type.h:550
RUBY_FL_USER5
@ RUBY_FL_USER5
User-defined flag.
Definition fl_type.h:365
RUBY_FL_USER3
@ RUBY_FL_USER3
User-defined flag.
Definition fl_type.h:363
RUBY_FL_USER17
@ RUBY_FL_USER17
User-defined flag.
Definition fl_type.h:377
RUBY_FL_USER6
@ RUBY_FL_USER6
User-defined flag.
Definition fl_type.h:366
RUBY_FL_USER2
@ RUBY_FL_USER2
User-defined flag.
Definition fl_type.h:362
RUBY_FL_USER4
@ RUBY_FL_USER4
User-defined flag.
Definition fl_type.h:364
RUBY_FL_USER1
@ RUBY_FL_USER1
User-defined flag.
Definition fl_type.h:361
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
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.
RBASIC
#define RBASIC(obj)
Convenient casting macro.
Definition rbasic.h:40
ruby_rstring_consts
ruby_rstring_consts
This is an enum because GDB wants it (rather than a macro).
Definition rstring.h:210
RSTRING_EMBED_LEN_SHIFT
@ RSTRING_EMBED_LEN_SHIFT
Where RSTRING_EMBED_LEN_MASK resides.
Definition rstring.h:212
RSTRING_EMBED_LEN_MAX
@ RSTRING_EMBED_LEN_MAX
Max possible number of characters that can be embedded.
Definition rstring.h:215
StringValue
#define StringValue(v)
Ensures that the parameter object is a String.
Definition rstring.h:72
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:1307
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
RSTRING_EMBED_LEN
static long RSTRING_EMBED_LEN(VALUE str)
Queries the length of the string.
Definition rstring.h:423
RSTRING_LENINT
static int RSTRING_LENINT(VALUE str)
Identical to RSTRING_LEN(), except it differs for the return type.
Definition rstring.h:554
RSTRING_END
static char * RSTRING_END(VALUE str)
Queries the end of the contents pointer of the string.
Definition rstring.h:528
Check_SafeStr
#define Check_SafeStr(v)
Definition rstring.h:392
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
RSTRING_LEN
static long RSTRING_LEN(VALUE str)
Queries the length of the string.
Definition rstring.h:484
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:1301
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
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:1609
RSTRING_PTR
static char * RSTRING_PTR(VALUE str)
Queries the contents pointer of the string.
Definition rstring.h:498
RBasic
Ruby's object's, base components.
Definition rbasic.h:64
RString
Ruby's String.
Definition rstring.h:231
RString::as
union RString::@49 as
String's specific fields.
RString::basic
struct RBasic basic
Basic part, including flags and class.
Definition rstring.h:234
RString::capa
long capa
Capacity of *ptr.
Definition rstring.h:268
RString::heap
struct RString::@49::@50 heap
Strings that use separated memory region for contents use this pattern.
RString::len
long len
Length of the string, not including terminating NUL character.
Definition rstring.h:250
RString::shared
VALUE shared
Parent of the string.
Definition rstring.h:276
RString::ptr
char * ptr
Pointer to the contents of the string.
Definition rstring.h:258
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:119
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