Ruby  3.1.4p223 (2023-03-30 revision HEAD)
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"
27 #include "ruby/internal/cast.h"
30 #include "ruby/internal/fl_type.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 
143 enum 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 |
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
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 
277  } aux;
278  } heap;
279 
281  struct {
282 #if USE_RVARGC
283  short 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
299 #endif
300  } embed;
301  } as;
302 };
303 
316 
326 VALUE rb_string_value(volatile VALUE *ptr);
327 
337 char *rb_string_value_ptr(volatile VALUE *ptr);
338 
350 char *rb_string_value_cstr(volatile VALUE *ptr);
351 
364 
374 
375 RBIMPL_ATTR_ERROR(("rb_check_safe_str() and Check_SafeStr() are obsolete; use StringValue() instead"))
383 void rb_check_safe_str(VALUE);
384 
392 #define Check_SafeStr(v) rb_check_safe_str(RBIMPL_CAST((VALUE)(v)))
393 
402 void rb_debug_rstring_null_ptr(const char *func);
404 
422 static inline long
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  short f = RSTRING(str)->as.embed.len;
430 #else
431  VALUE f = RBASIC(str)->flags;
432  f &= RSTRING_EMBED_LEN_MASK;
434 #endif
435  return RBIMPL_CAST((long)f);
436 }
437 
439 #if RBIMPL_COMPILER_IS(Intel)
441 #endif
442 
454 static inline struct RString
455 rbimpl_rstring_getmem(VALUE str)
456 {
457  RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING);
458 
459  if (RB_FL_ANY_RAW(str, RSTRING_NOEMBED)) {
460  return *RSTRING(str);
461  }
462  else {
463  /* Expecting compilers to optimize this on-stack struct away. */
464  struct RString retval;
465  retval.as.heap.len = RSTRING_EMBED_LEN(str);
466  retval.as.heap.ptr = RSTRING(str)->as.embed.ary;
467  return retval;
468  }
469 }
470 
472 
482 static inline long
484 {
485  return rbimpl_rstring_getmem(str).as.heap.len;
486 }
487 
496 static inline char *
498 {
499  char *ptr = rbimpl_rstring_getmem(str).as.heap.ptr;
500 
501  if (RB_UNLIKELY(! ptr)) {
502  /* :BEWARE: @shyouhei thinks that currently, there are rooms for this
503  * function to return NULL. In the 20th century that was a pointless
504  * concern. However struct RString can hold fake strings nowadays. It
505  * seems no check against NULL are exercised around handling of them
506  * (one of such usages is located in marshal.c, which scares
507  * @shyouhei). Better check here for maximum safety.
508  *
509  * Also, this is not rb_warn() because RSTRING_PTR() can be called
510  * during GC (see what obj_info() does). rb_warn() needs to allocate
511  * Ruby objects. That is not possible at this moment. */
512  rb_debug_rstring_null_ptr("RSTRING_PTR");
513  }
514 
515  return ptr;
516 }
517 
526 static inline char *
528 {
529  struct RString buf = rbimpl_rstring_getmem(str);
530 
531  if (RB_UNLIKELY(! buf.as.heap.ptr)) {
532  /* Ditto. */
533  rb_debug_rstring_null_ptr("RSTRING_END");
534  }
535 
536  return &buf.as.heap.ptr[buf.as.heap.len];
537 }
538 
552 static inline int
554 {
555  return rb_long2int(RSTRING_LEN(str));
556 }
557 
565 #ifdef HAVE_STMT_AND_DECL_IN_EXPR
566 # define RSTRING_GETMEM(str, ptrvar, lenvar) \
567  __extension__ ({ \
568  struct RString rbimpl_str = rbimpl_rstring_getmem(str); \
569  (ptrvar) = rbimpl_str.as.heap.ptr; \
570  (lenvar) = rbimpl_str.as.heap.len; \
571  })
572 #else
573 # define RSTRING_GETMEM(str, ptrvar, lenvar) \
574  ((ptrvar) = RSTRING_PTR(str), \
575  (lenvar) = RSTRING_LEN(str))
576 #endif /* HAVE_STMT_AND_DECL_IN_EXPR */
577 #endif /* RBIMPL_RSTRING_H */
Defines RBIMPL_ATTR_ARTIFICIAL.
#define RBIMPL_ATTR_ARTIFICIAL()
Wraps (or simulates) __attribute__((artificial))
Definition: artificial.h:41
#define RBIMPL_ASSERT_OR_ASSUME(expr)
This is either RUBY_ASSERT or RBIMPL_ASSUME, depending on RUBY_DEBUG.
Definition: assert.h:229
#define RB_UNLIKELY(x)
Asserts that the given Boolean expression likely doesn't hold.
Definition: assume.h:52
Tweaking visibility of C variables/functions.
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition: dllexport.h:106
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition: dllexport.h:97
Defines enum ruby_fl_type.
@ RUBY_FL_USHIFT
Number of bits in ruby_fl_type that are not open to users.
Definition: fl_type.h:167
static bool RB_FL_ANY_RAW(VALUE obj, VALUE flags)
This is an implenentation detail of RB_FL_ANY().
Definition: fl_type.h:556
@ RUBY_FL_USER5
User-defined flag.
Definition: fl_type.h:365
@ RUBY_FL_USER3
User-defined flag.
Definition: fl_type.h:363
@ RUBY_FL_USER17
User-defined flag.
Definition: fl_type.h:377
@ RUBY_FL_USER6
User-defined flag.
Definition: fl_type.h:366
@ RUBY_FL_USER2
User-defined flag.
Definition: fl_type.h:362
@ RUBY_FL_USER4
User-defined flag.
Definition: fl_type.h:364
@ RUBY_FL_USER1
User-defined flag.
Definition: fl_type.h:361
#define RBIMPL_ATTR_ERROR(msg)
Wraps (or simulates) __attribute__((error))
Definition: error.h:27
Arithmetic conversion between C's long and Ruby's.
#define rb_long2int
Just another name of rb_long2int_inline.
Definition: long.h:62
Defines RBIMPL_ATTR_PURE.
#define RBIMPL_ATTR_PURE_UNLESS_DEBUG()
Enables RBIMPL_ATTR_PURE if and only if.
Definition: pure.h:38
Defines struct RBasic.
#define RBASIC(obj)
Convenient casting macro.
Definition: rbasic.h:40
ruby_rstring_consts
This is an enum because GDB wants it (rather than a macro).
Definition: rstring.h:210
@ RSTRING_EMBED_LEN_SHIFT
Where ::RSTRING_EMBED_LEN_MASK resides.
Definition: rstring.h:212
@ RSTRING_EMBED_LEN_MAX
Max possible number of characters that can be embedded.
Definition: rstring.h:215
#define StringValue(v)
Ensures that the parameter object is a String.
Definition: rstring.h:72
VALUE rb_str_export_locale(VALUE obj)
Identical to rb_str_export(), except it converts into the locale encoding instead.
Definition: string.c:1281
static char * RSTRING_END(VALUE str)
Queries the end of the contents pointer of the string.
Definition: rstring.h:527
static char * RSTRING_PTR(VALUE str)
Queries the contents pointer of the string.
Definition: rstring.h:497
static long RSTRING_EMBED_LEN(VALUE str)
Queries the length of the string.
Definition: rstring.h:423
static int RSTRING_LENINT(VALUE str)
Identical to RSTRING_LEN(), except it differs for the return type.
Definition: rstring.h:553
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:2531
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:2636
#define Check_SafeStr(v)
Definition: rstring.h:392
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:2520
static long RSTRING_LEN(VALUE str)
Queries the length of the string.
Definition: rstring.h:483
#define RSTRING(obj)
Convenient casting macro.
Definition: rstring.h:41
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:1275
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:1584
Ruby's object's, base components.
Definition: rbasic.h:64
Ruby's String.
Definition: rstring.h:231
union RString::@47::@48::@50 aux
Auxiliary info.
struct RString::@47::@48 heap
Strings that use separated memory region for contents use this pattern.
union RString::@47 as
String's specific fields.
struct RBasic basic
Basic part, including flags and class.
Definition: rstring.h:234
long capa
Capacity of *ptr.
Definition: rstring.h:268
struct RString::@47::@49 embed
Embedded contents.
long len
Length of the string, not including terminating NUL character.
Definition: rstring.h:250
char ary[RSTRING_EMBED_LEN_MAX+1]
When a string is short enough, it uses this area to store the contents themselves.
Definition: rstring.h:298
VALUE shared
Parent of the string.
Definition: rstring.h:276
char * ptr
Pointer to the contents of the string.
Definition: rstring.h:258
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40
Defines enum ruby_value_type.
@ RUBY_T_STRING
Definition: value_type.h:119
Defines RBIMPL_WARNING_PUSH.
#define RBIMPL_WARNING_IGNORED(flag)
Suppresses a warning.
Definition: warning_push.h:80
#define RBIMPL_WARNING_PUSH()
Pushes compiler warning state.
Definition: warning_push.h:55
#define RBIMPL_WARNING_POP()
Pops compiler warning state.
Definition: warning_push.h:62