Ruby  3.4.0dev (2024-11-22 revision 37a72b0150ec36b4ea27175039afc28c62207b0c)
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 #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
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 
137 enum 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 
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 
268 
278 VALUE rb_string_value(volatile VALUE *ptr);
279 
289 char *rb_string_value_ptr(volatile VALUE *ptr);
290 
302 char *rb_string_value_cstr(volatile VALUE *ptr);
303 
316 
326 
327 RBIMPL_ATTR_ERROR(("rb_check_safe_str() and Check_SafeStr() are obsolete; use StringValue() instead"))
335 void rb_check_safe_str(VALUE);
336 
344 #define Check_SafeStr(v) rb_check_safe_str(RBIMPL_CAST((VALUE)(v)))
345 
354 void rb_debug_rstring_null_ptr(const char *func);
356 
366 static inline long
368 {
369  return RSTRING(str)->len;
370 }
371 
373 #if RBIMPL_COMPILER_IS(Intel)
375 #endif
376 
388 static inline struct RString
389 rbimpl_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 
406 
415 static inline char *
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 
441 static inline char *
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 
467 static inline int
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 */
Defines RBIMPL_ATTR_ARTIFICIAL.
#define RBIMPL_ATTR_ARTIFICIAL()
Wraps (or simulates) __attribute__((artificial))
Definition: artificial.h:41
#define RUBY_DEBUG
Define this macro when you want assertions.
Definition: assert.h:88
#define RB_UNLIKELY(x)
Asserts that the given Boolean expression likely doesn't hold.
Definition: assume.h:50
Tweaking visibility of C variables/functions.
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition: dllexport.h:74
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition: dllexport.h:65
Defines enum ruby_fl_type.
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
User-defined flag.
Definition: fl_type.h:345
@ RUBY_FL_USER1
User-defined flag.
Definition: fl_type.h:329
#define RBIMPL_ATTR_ERROR(msg)
Wraps (or simulates) __attribute__((error))
Definition: error.h:27
char * ptr
Pointer to the underlying memory region, of at least capa bytes.
Definition: io.h:2
Arithmetic conversion between C's long and Ruby's.
#define rb_long2int
Just another name of rb_long2int_inline.
Definition: long.h:62
#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
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 StringValue(v)
Ensures that the parameter object is a String.
Definition: rstring.h:66
VALUE rb_str_export_locale(VALUE obj)
Identical to rb_str_export(), except it converts into the locale encoding instead.
Definition: string.c:1384
static char * RSTRING_END(VALUE str)
Queries the end of the contents pointer of the string.
Definition: rstring.h:442
static char * RSTRING_PTR(VALUE str)
Queries the contents pointer of the string.
Definition: rstring.h:416
static int RSTRING_LENINT(VALUE str)
Identical to RSTRING_LEN(), except it differs for the return type.
Definition: rstring.h:468
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:2726
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:2831
#define Check_SafeStr(v)
Definition: rstring.h:344
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:2715
static long RSTRING_LEN(VALUE str)
Queries the length of the string.
Definition: rstring.h:367
#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:1378
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:1715
Ruby object's base components.
Definition: rbasic.h:63
Ruby's String.
Definition: rstring.h:196
struct RBasic basic
Basic part, including flags and class.
Definition: rstring.h:199
union RString::@48::@49::@51 aux
Auxiliary info.
long capa
Capacity of *ptr.
Definition: rstring.h:232
union RString::@48 as
String's specific fields.
long len
Length of the string, not including terminating NUL character.
Definition: rstring.h:206
struct RString::@48::@50 embed
Embedded contents.
struct RString::@48::@49 heap
Strings that use separated memory region for contents use this pattern.
VALUE shared
Parent of the string.
Definition: rstring.h:240
char * ptr
Pointer to the contents of the string.
Definition: rstring.h:222
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:120
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