#$@%#$%!

Ngiler SH3LL 360
: / opt / alt / ruby31 / include / ruby / internal / core /

Information Server
MySQL : OFF Perl : OFF CURL : ON WGET : OFF PKEXEC : OFF

Directive	Local Value
IP Address	162.0.209.101
System	Linux premium169.web-hosting.com 4.18.0-553.50.1.lve.el8.x86_64 #1 SMP Thu Apr 17 19:10:24 UTC 2025 x86_64
User	luxeelil
PHP Version	8.0.30
Software	LiteSpeed
Doc root	Writable

Edit File : rstring.h \| Size : 19.50 KB
#ifndef RBIMPL_RSTRING_H /--C++--vi:se ft=cpp:/ #define RBIMPL_RSTRING_H /** * @file * @author Ruby developers <ruby-core@ruby-lang.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. * @brief Defines struct ::RString. / #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" /* * Convenient casting macro. * * @param obj An object, which is in fact an ::RString. * @return The passed object casted to ::RString. / #define RSTRING(obj) RBIMPL_CAST((struct RString )(obj)) /** @cond INTERNAL_MACRO / #define RSTRING_NOEMBED RSTRING_NOEMBED #if !USE_RVARGC #define RSTRING_EMBED_LEN_MASK RSTRING_EMBED_LEN_MASK #define RSTRING_EMBED_LEN_SHIFT RSTRING_EMBED_LEN_SHIFT #define RSTRING_EMBED_LEN_MAX RSTRING_EMBED_LEN_MAX #endif #define RSTRING_FSTR RSTRING_FSTR #define RSTRING_EMBED_LEN RSTRING_EMBED_LEN #define RSTRING_LEN RSTRING_LEN #define RSTRING_LENINT RSTRING_LENINT #define RSTRING_PTR RSTRING_PTR #define RSTRING_END RSTRING_END /* @endcond / /* * @name Conversion of Ruby strings into C's * * @{ / /* * Ensures that the parameter object is a String. This is done by calling its * `to_str` method. * * @param[in,out] v Arbitrary Ruby object. * @exception rb_eTypeError No implicit conversion defined. * @post `v` is a String. / #define StringValue(v) rb_string_value(&(v)) /* * Identical to #StringValue, except it returns a `char`. * @param[in,out] v Arbitrary Ruby object. * @exception rb_eTypeError No implicit conversion defined. * @return Converted Ruby string's backend C string. * @post `v` is a String. / #define StringValuePtr(v) rb_string_value_ptr(&(v)) /* * 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. * * @param[in,out] v Arbitrary Ruby object. * @exception rb_eTypeError No implicit conversion defined. * @exception rb_eArgError String is not C-compatible. * @return Converted Ruby string's backend C string. * @post `v` is a String. / #define StringValueCStr(v) rb_string_value_cstr(&(v)) /* * @private * * @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. / #define SafeStringValue(v) StringValue(v) /* * 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. * * @param[in,out] v Arbitrary Ruby object. * @exception rb_eTypeError No implicit conversion defined. * @return Converted Ruby string's backend C string. * @post `v` is a String. * * @internal * * Not sure but it seems this macro does not raise on encoding * incompatibilities? Doesn't sound right to @shyouhei. / #define ExportStringValue(v) do { \ StringValue(v); \ (v) = rb_str_export(v); \ } while (0) /* @} / /* * @private * * Bits that you can set to ::RBasic::flags. * * @warning These enums are not the only bits we use for strings. * * @internal * * Actually all bits through FL_USER1 to FL_USER19 are used for strings. Why * only this tiny part of them are made public here? @shyouhei can find no * reason. / enum ruby_rstring_flags { /* * This flag has something to do with memory footprint. If the string is * short enough, ruby tries to be creative to abuse padding bits of struct * ::RString for storing contents. If this flag is set that string does * _not_ do that, to resort to good old fashioned external allocation * strategy instead. * * @warning This bit has to be considered read-only. Setting/clearing * this bit without corresponding fix up must cause immediate * SEGV. Also, internal structures of a string change * dynamically and transparently throughout of its lifetime. * Don't assume it being persistent. * * @internal * * 3rd parties must not be aware that there even is more than one way to * store a string. Might better be hidden. / RSTRING_NOEMBED = RUBY_FL_USER1, #if !USE_RVARGC /* * When a string employs embedded strategy (see ::RSTRING_NOEMBED), these * bits are used to store the number of bytes actually filled into * ::RString::ary. * * @internal * * 3rd parties must not be aware that there even is more than one way to * store a string. Might better be hidden. / RSTRING_EMBED_LEN_MASK = RUBY_FL_USER2 \| RUBY_FL_USER3 \| RUBY_FL_USER4 \| RUBY_FL_USER5 \| RUBY_FL_USER6, #endif / Actually, string encodings are also encoded into the flags, using * remaining bits./ /* * This flag has something to do with infamous "f"string. What is a * fstring? Well it is a special subkind of strings that is immutable, * deduped globally, and managed by our GC. It is much like a Symbol (in * fact Symbols are dynamic these days and are backended using fstrings). * This concept has been silently introduced at some point in 2.x era. * Since then it gained wider acceptance in the core. But extension * libraries could not know that until very recently. Strings of this flag * live in a special Limbo deep inside of the interpreter. Never try to * manipulate it by hand. * * @internal * * Fstrings are not the only variant strings that we implement today. * Other things are behind-the-scene. This is the only one that is visible * from extension library. There is no clear reason why it has to be. * Given there are more "polite" ways to create fstrings, it seems this bit * need not be exposed to extension libraries. Might better be hidden. / RSTRING_FSTR = RUBY_FL_USER17 }; #if !USE_RVARGC /* * This is an enum because GDB wants it (rather than a macro). People need not * bother. / enum ruby_rstring_consts { /* Where ::RSTRING_EMBED_LEN_MASK resides. / RSTRING_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 2, /* Max possible number of characters that can be embedded. / RSTRING_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(char) - 1 }; #endif /* * Ruby's String. A string in ruby conceptually has these information: * * - Encoding of the string. * - Length of the string. * - Contents of the string. * * It is worth noting that a string is _not_ an array of characters in ruby. * It has never been. In 1.x a string was an array of integers. Since 2.x a * string is no longer an array of anything. A string is a string -- just like * a Time is not an integer. / struct RString { /* Basic part, including flags and class. / struct RBasic basic; /* String's specific fields. / union { /* * Strings that use separated memory region for contents use this * pattern. / struct { /* * Length of the string, not including terminating NUL character. * * @note This is in bytes. / long len; /* * Pointer to the contents of the string. In the old days each * string had dedicated memory regions. That is no longer true * today, but there still are strings of such properties. This * field could be used to point such things. / char ptr; /** Auxiliary info. / union { /* * Capacity of `ptr`. A continuous memory region of at least `capa` bytes is expected to exist at `ptr`. This can be bigger than `len`. / long capa; /* * Parent of the string. Nowadays strings can share their * contents each other, constructing gigantic nest of objects. * This situation is called "shared", and this is the field to * control such properties. / VALUE shared; } aux; } heap; /* Embedded contents. / struct { #if USE_RVARGC short len; / This is a length 1 array because: * 1. GCC has a bug that does not optimize C flexible array members * (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102452) * 2. Zero length arrays are not supported by all compilers / char ary[1]; #else /* * When a string is short enough, it uses this area to store the * contents themselves. This was impractical in the 20th century, * but these days 64 bit machines can typically hold 24 bytes here. * Could be sufficiently large. In this case the length is encoded * into the flags. / char ary[RSTRING_EMBED_LEN_MAX + 1]; #endif } embed; } as; }; RBIMPL_SYMBOL_EXPORT_BEGIN() /* * Identical to rb_check_string_type(), except it raises exceptions in case of * conversion failures. * * @param[in] obj Target object. * @exception rb_eTypeError No implicit conversion to String. * @return Return value of `obj.to_str`. * @see rb_io_get_io * @see rb_ary_to_ary / VALUE rb_str_to_str(VALUE obj); /* * Identical to rb_str_to_str(), except it fills the passed pointer with the * converted object. * * @param[in,out] ptr Pointer to a variable of target object. * @exception rb_eTypeError No implicit conversion to String. * @return Return value of `obj.to_str`. * @post `ptr` is the return value. / VALUE rb_string_value(volatile VALUE ptr); /* * Identical to rb_str_to_str(), except it returns the converted string's * backend memory region. * * @param[in,out] ptr Pointer to a variable of target object. * @exception rb_eTypeError No implicit conversion to String. * @post `ptr` is the return value of `obj.to_str`. @return Pointer to the contents of the return value. / char rb_string_value_ptr(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. * * @param[in,out] ptr Pointer to a variable of target object. * @exception rb_eTypeError No implicit conversion to String. * @exception rb_eArgError String is not C-compatible. * @post `ptr` is the return value of `obj.to_str`. @return Pointer to the contents of the return value. / char rb_string_value_cstr(volatile VALUE ptr); /* * 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. * * @param[in] obj Target object. * @exception rb_eTypeError No implicit conversion to String. * @return Converted ruby string of default external encoding. / VALUE rb_str_export(VALUE obj); /* * Identical to rb_str_export(), except it converts into the locale encoding * instead. * * @param[in] obj Target object. * @exception rb_eTypeError No implicit conversion to String. * @return Converted ruby string of locale encoding. / VALUE rb_str_export_locale(VALUE obj); RBIMPL_ATTR_ERROR(("rb_check_safe_str() and Check_SafeStr() are obsolete; use StringValue() instead")) /* * @private * * @deprecated This function 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. / void rb_check_safe_str(VALUE); /* * @private * * @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. / #define Check_SafeStr(v) rb_check_safe_str(RBIMPL_CAST((VALUE)(v))) /* * @private * * Prints diagnostic message to stderr when RSTRING_PTR or RSTRING_END * is NULL. * * @param[in] func The function name where encountered NULL pointer. / void rb_debug_rstring_null_ptr(const char func); RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() /** * Queries the length of the string. * * @param[in] str String in question. * @return Its length, in bytes. * @pre `str` must be an instance of ::RString, and must has its * ::RSTRING_NOEMBED flag off. * * @internal * * This was a macro before. It was inevitable to be public, since macros are * global constructs. But should it be forever? Now that it is a function, * @shyouhei thinks it could just be eliminated, hidden into implementation * details. / static inline long RSTRING_EMBED_LEN(VALUE str) { RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING); RBIMPL_ASSERT_OR_ASSUME(! RB_FL_ANY_RAW(str, RSTRING_NOEMBED)); #if USE_RVARGC short f = RSTRING(str)->as.embed.len; #else VALUE f = RBASIC(str)->flags; f &= RSTRING_EMBED_LEN_MASK; f >>= RSTRING_EMBED_LEN_SHIFT; #endif return RBIMPL_CAST((long)f); } RBIMPL_WARNING_PUSH() #if RBIMPL_COMPILER_IS(Intel) RBIMPL_WARNING_IGNORED(413) #endif RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() /* * @private * * "Expands" an embedded string into an ordinal one. This is a function that * returns aggregated type. The returned struct always has its `as.heap.len` * an `as.heap.ptr` fields set appropriately. * * This is an implementation detail that 3rd parties should never bother. / static inline struct RString rbimpl_rstring_getmem(VALUE str) { RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING); if (RB_FL_ANY_RAW(str, RSTRING_NOEMBED)) { return RSTRING(str); } else { /* Expecting compilers to optimize this on-stack struct away. / struct RString retval; retval.as.heap.len = RSTRING_EMBED_LEN(str); retval.as.heap.ptr = RSTRING(str)->as.embed.ary; return retval; } } RBIMPL_WARNING_POP() RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() /* * Queries the length of the string. * * @param[in] str String in question. * @return Its length, in bytes. * @pre `str` must be an instance of ::RString. / static inline long RSTRING_LEN(VALUE str) { return rbimpl_rstring_getmem(str).as.heap.len; } RBIMPL_ATTR_ARTIFICIAL() /* * Queries the contents pointer of the string. * * @param[in] str String in question. * @return Pointer to its contents. * @pre `str` must be an instance of ::RString. / static inline char RSTRING_PTR(VALUE str) { char ptr = rbimpl_rstring_getmem(str).as.heap.ptr; if (RB_UNLIKELY(! ptr)) { / :BEWARE: @shyouhei thinks that currently, there are rooms for this * function to return NULL. In the 20th century that was a pointless * concern. However struct RString can hold fake strings nowadays. It * seems no check against NULL are exercised around handling of them * (one of such usages is located in marshal.c, which scares * @shyouhei). Better check here for maximum safety. * * Also, this is not rb_warn() because RSTRING_PTR() can be called * during GC (see what obj_info() does). rb_warn() needs to allocate * Ruby objects. That is not possible at this moment. / rb_debug_rstring_null_ptr("RSTRING_PTR"); } return ptr; } RBIMPL_ATTR_ARTIFICIAL() /* * Queries the end of the contents pointer of the string. * * @param[in] str String in question. * @return Pointer to its end of contents. * @pre `str` must be an instance of ::RString. / static inline char RSTRING_END(VALUE str) { struct RString buf = rbimpl_rstring_getmem(str); if (RB_UNLIKELY(! buf.as.heap.ptr)) { /* Ditto. / rb_debug_rstring_null_ptr("RSTRING_END"); } return &buf.as.heap.ptr[buf.as.heap.len]; } RBIMPL_ATTR_ARTIFICIAL() /* * Identical to RSTRING_LEN(), except it differs for the return type. * * @param[in] str String in question. * @exception rb_eRangeError Too long. * @return Its length, in bytes. * @pre `str` must be an instance of ::RString. * * @internal * * This API seems redundant but has actual usages. / static inline int RSTRING_LENINT(VALUE str) { return rb_long2int(RSTRING_LEN(str)); } /* * Convenient macro to obtain the contents and length at once. * * @param str String in question. * @param ptrvar Variable where its contents is stored. * @param lenvar Variable where its length is stored. / #ifdef HAVE_STMT_AND_DECL_IN_EXPR # define RSTRING_GETMEM(str, ptrvar, lenvar) \ __extension__ ({ \ struct RString rbimpl_str = rbimpl_rstring_getmem(str); \ (ptrvar) = rbimpl_str.as.heap.ptr; \ (lenvar) = rbimpl_str.as.heap.len; \ }) #else # define RSTRING_GETMEM(str, ptrvar, lenvar) \ ((ptrvar) = RSTRING_PTR(str), \ (lenvar) = RSTRING_LEN(str)) #endif / HAVE_STMT_AND_DECL_IN_EXPR / #endif / RBIMPL_RSTRING_H */ Back

Edit File : rstring.h | Size : 19.50 KB

#ifndef RBIMPL_RSTRING_H                             /*-*-C++-*-vi:se ft=cpp:*/
#define RBIMPL_RSTRING_H
/**
 * @file
 * @author     Ruby developers <ruby-core@ruby-lang.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.
 * @brief      Defines struct ::RString.
 */
#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"

/**
 * Convenient casting macro.
 *
 * @param   obj  An object, which is in fact an ::RString.
 * @return  The passed object casted to ::RString.
 */
#define RSTRING(obj)            RBIMPL_CAST((struct RString *)(obj))

/** @cond INTERNAL_MACRO */
#define RSTRING_NOEMBED         RSTRING_NOEMBED
#if !USE_RVARGC
#define RSTRING_EMBED_LEN_MASK  RSTRING_EMBED_LEN_MASK
#define RSTRING_EMBED_LEN_SHIFT RSTRING_EMBED_LEN_SHIFT
#define RSTRING_EMBED_LEN_MAX   RSTRING_EMBED_LEN_MAX
#endif
#define RSTRING_FSTR            RSTRING_FSTR
#define RSTRING_EMBED_LEN RSTRING_EMBED_LEN
#define RSTRING_LEN       RSTRING_LEN
#define RSTRING_LENINT    RSTRING_LENINT
#define RSTRING_PTR       RSTRING_PTR
#define RSTRING_END       RSTRING_END
/** @endcond */

/**
 * @name Conversion of Ruby strings into C's
 *
 * @{
 */

/**
 * Ensures that the parameter object is a  String.  This is done by calling its
 * `to_str` method.
 *
 * @param[in,out]  v              Arbitrary Ruby object.
 * @exception      rb_eTypeError  No implicit conversion defined.
 * @post           `v` is a String.
 */
#define StringValue(v)     rb_string_value(&(v))

/**
 * Identical to #StringValue, except it returns a `char*`.
 *
 * @param[in,out]  v              Arbitrary Ruby object.
 * @exception      rb_eTypeError  No implicit conversion defined.
 * @return         Converted Ruby string's backend C string.
 * @post           `v` is a String.
 */
#define StringValuePtr(v)  rb_string_value_ptr(&(v))

/**
 * 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.
 *
 * @param[in,out]  v              Arbitrary Ruby object.
 * @exception      rb_eTypeError  No implicit conversion defined.
 * @exception      rb_eArgError   String is not C-compatible.
 * @return         Converted Ruby string's backend C string.
 * @post           `v` is a String.
 */
#define StringValueCStr(v) rb_string_value_cstr(&(v))

/**
 * @private
 *
 * @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.
 */
#define SafeStringValue(v) StringValue(v)

/**
 * 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.
 *
 * @param[in,out]  v              Arbitrary Ruby object.
 * @exception      rb_eTypeError  No implicit conversion defined.
 * @return         Converted Ruby string's backend C string.
 * @post           `v` is a String.
 *
 * @internal
 *
 * Not   sure  but   it  seems   this  macro   does  not   raise  on   encoding
 * incompatibilities?  Doesn't sound right to @shyouhei.
 */
#define ExportStringValue(v) do { \
    StringValue(v);               \
    (v) = rb_str_export(v);       \
} while (0)

/** @} */

/**
 * @private
 *
 * Bits that you can set to ::RBasic::flags.
 *
 * @warning  These enums are not the only bits we use for strings.
 *
 * @internal
 *
 * Actually all bits  through FL_USER1 to FL_USER19 are used  for strings.  Why
 * only this  tiny part of  them are made public  here?  @shyouhei can  find no
 * reason.
 */
enum ruby_rstring_flags {

/**
     * This flag has  something to do with memory footprint.   If the string is
     * short enough, ruby tries to be  creative to abuse padding bits of struct
     * ::RString for  storing contents.  If this  flag is set that  string does
     * _not_  do that,  to resort  to  good old  fashioned external  allocation
     * strategy instead.
     *
     * @warning  This  bit has  to be  considered read-only.   Setting/clearing
     *           this  bit without  corresponding fix  up must  cause immediate
     *           SEGV.    Also,  internal   structures  of   a  string   change
     *           dynamically  and  transparently  throughout of  its  lifetime.
     *           Don't assume it being persistent.
     *
     * @internal
     *
     * 3rd parties must  not be aware that  there even is more than  one way to
     * store a string.  Might better be hidden.
     */
    RSTRING_NOEMBED         = RUBY_FL_USER1,

#if !USE_RVARGC
    /**
     * When a  string employs embedded strategy  (see ::RSTRING_NOEMBED), these
     * bits  are  used to  store  the  number  of  bytes actually  filled  into
     * ::RString::ary.
     *
     * @internal
     *
     * 3rd parties must  not be aware that  there even is more than  one way to
     * store a string.  Might better be hidden.
     */
    RSTRING_EMBED_LEN_MASK  = RUBY_FL_USER2 | RUBY_FL_USER3 | RUBY_FL_USER4 |
                              RUBY_FL_USER5 | RUBY_FL_USER6,
#endif

/* Actually,  string  encodings are  also  encoded  into the  flags,  using
     * remaining bits.*/

/**
     * This  flag has  something  to do  with infamous  "f"string.   What is  a
     * fstring?  Well  it is a  special subkind  of strings that  is immutable,
     * deduped globally, and managed  by our GC.  It is much  like a Symbol (in
     * fact Symbols are  dynamic these days and are  backended using fstrings).
     * This concept  has been  silently introduced  at some  point in  2.x era.
     * Since  then it  gained  wider  acceptance in  the  core.  But  extension
     * libraries could not know that until very recently.  Strings of this flag
     * live in  a special Limbo deep  inside of the interpreter.   Never try to
     * manipulate it by hand.
     *
     * @internal
     *
     * Fstrings  are not  the only  variant  strings that  we implement  today.
     * Other things are behind-the-scene.  This is the only one that is visible
     * from extension  library.  There  is no  clear reason why  it has  to be.
     * Given there are more "polite" ways to create fstrings, it seems this bit
     * need not be exposed to extension libraries.  Might better be hidden.
     */
    RSTRING_FSTR            = RUBY_FL_USER17
};

#if !USE_RVARGC
/**
 * This is an enum because GDB wants it (rather than a macro).  People need not
 * bother.
 */
enum ruby_rstring_consts {
    /** Where ::RSTRING_EMBED_LEN_MASK resides. */
    RSTRING_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 2,

/** Max possible number of characters that can be embedded. */
    RSTRING_EMBED_LEN_MAX   = RBIMPL_EMBED_LEN_MAX_OF(char) - 1
};
#endif

/**
 * Ruby's String.  A string in ruby conceptually has these information:
 *
 * - Encoding of the string.
 * - Length of the string.
 * - Contents of the string.
 *
 * It is worth  noting that a string  is _not_ an array of  characters in ruby.
 * It has never been.   In 1.x a string was an array of  integers.  Since 2.x a
 * string is no longer an array of anything.  A string is a string -- just like
 * a Time is not an integer.
 */
struct RString {

/** Basic part, including flags and class. */
    struct RBasic basic;

/** String's specific fields. */
    union {

/**
         * Strings  that use  separated  memory region  for  contents use  this
         * pattern.
         */
        struct {

/**
             * Length of the string, not including terminating NUL character.
             *
             * @note  This is in bytes.
             */
            long len;

/**
             * Pointer to  the contents of  the string.   In the old  days each
             * string had  dedicated memory  regions.  That  is no  longer true
             * today,  but there  still are  strings of  such properties.  This
             * field could be used to point such things.
             */
            char *ptr;

/** Auxiliary info. */
            union {

/**
                 * Capacity of `*ptr`.  A continuous  memory region of at least
                 * `capa` bytes  is expected to  exist at `*ptr`.  This  can be
                 * bigger than `len`.
                 */
                long capa;

/**
                 * Parent  of the  string.   Nowadays strings  can share  their
                 * contents each other, constructing  gigantic nest of objects.
                 * This situation is called "shared",  and this is the field to
                 * control such properties.
                 */
                VALUE shared;
            } aux;
        } heap;

/** Embedded contents. */
        struct {
#if USE_RVARGC
            short len;
            /* This is a length 1 array because:
             *   1. GCC has a bug that does not optimize C flexible array members
             *      (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102452)
             *   2. Zero length arrays are not supported by all compilers
             */
            char ary[1];
#else
            /**
             * When a  string is short enough,  it uses this area  to store the
             * contents themselves.  This was  impractical in the 20th century,
             * but these days 64 bit machines can typically hold 24 bytes here.
             * Could be sufficiently large.  In this case the length is encoded
             * into the flags.
             */
            char ary[RSTRING_EMBED_LEN_MAX + 1];
#endif
        } embed;
    } as;
};

RBIMPL_SYMBOL_EXPORT_BEGIN()
/**
 * Identical to rb_check_string_type(), except it  raises exceptions in case of
 * conversion failures.
 *
 * @param[in]  obj            Target object.
 * @exception  rb_eTypeError  No implicit conversion to String.
 * @return     Return value of `obj.to_str`.
 * @see        rb_io_get_io
 * @see        rb_ary_to_ary
 */
VALUE rb_str_to_str(VALUE obj);

/**
 * Identical to  rb_str_to_str(), except it  fills the passed pointer  with the
 * converted object.
 *
 * @param[in,out]  ptr            Pointer to a variable of target object.
 * @exception      rb_eTypeError  No implicit conversion to String.
 * @return         Return value of `obj.to_str`.
 * @post           `*ptr` is the return value.
 */
VALUE rb_string_value(volatile VALUE *ptr);

/**
 * Identical  to  rb_str_to_str(), except  it  returns  the converted  string's
 * backend memory region.
 *
 * @param[in,out]  ptr            Pointer to a variable of target object.
 * @exception      rb_eTypeError  No implicit conversion to String.
 * @post           `*ptr` is the return value of `obj.to_str`.
 * @return         Pointer to the contents of the return value.
 */
char *rb_string_value_ptr(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.
 *
 * @param[in,out]  ptr            Pointer to a variable of target object.
 * @exception      rb_eTypeError  No implicit conversion to String.
 * @exception      rb_eArgError   String is not C-compatible.
 * @post           `*ptr` is the return value of `obj.to_str`.
 * @return         Pointer to the contents of the return value.
 */
char *rb_string_value_cstr(volatile VALUE *ptr);

/**
 * 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.
 *
 * @param[in]  obj            Target object.
 * @exception  rb_eTypeError  No implicit conversion to String.
 * @return     Converted ruby string of default external encoding.
 */
VALUE rb_str_export(VALUE obj);

/**
 * Identical to  rb_str_export(), except it  converts into the  locale encoding
 * instead.
 *
 * @param[in]  obj            Target object.
 * @exception  rb_eTypeError  No implicit conversion to String.
 * @return     Converted ruby string of locale encoding.
 */
VALUE rb_str_export_locale(VALUE obj);

RBIMPL_ATTR_ERROR(("rb_check_safe_str() and Check_SafeStr() are obsolete; use StringValue() instead"))
/**
 * @private
 *
 * @deprecated  This function  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.
 */
void rb_check_safe_str(VALUE);

/**
 * @private
 *
 * Prints diagnostic message to stderr when RSTRING_PTR or RSTRING_END
 * is NULL.
 *
 * @param[in]  func           The function name where encountered NULL pointer.
 */
void rb_debug_rstring_null_ptr(const char *func);
RBIMPL_SYMBOL_EXPORT_END()

RBIMPL_ATTR_PURE_UNLESS_DEBUG()
RBIMPL_ATTR_ARTIFICIAL()
/**
 * Queries the length of the string.
 *
 * @param[in]  str  String in question.
 * @return     Its length, in bytes.
 * @pre        `str`  must  be an  instance  of  ::RString,  and must  has  its
 *             ::RSTRING_NOEMBED flag off.
 *
 * @internal
 *
 * This was a macro  before.  It was inevitable to be  public, since macros are
 * global constructs.   But should it be  forever?  Now that it  is a function,
 * @shyouhei thinks  it could  just be  eliminated, hidden  into implementation
 * details.
 */
static inline long
RSTRING_EMBED_LEN(VALUE str)
{
    RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING);
    RBIMPL_ASSERT_OR_ASSUME(! RB_FL_ANY_RAW(str, RSTRING_NOEMBED));

#if USE_RVARGC
    short f = RSTRING(str)->as.embed.len;
#else
    VALUE f = RBASIC(str)->flags;
    f &= RSTRING_EMBED_LEN_MASK;
    f >>= RSTRING_EMBED_LEN_SHIFT;
#endif
    return RBIMPL_CAST((long)f);
}

RBIMPL_WARNING_PUSH()
#if RBIMPL_COMPILER_IS(Intel)
RBIMPL_WARNING_IGNORED(413)
#endif

RBIMPL_ATTR_PURE_UNLESS_DEBUG()
RBIMPL_ATTR_ARTIFICIAL()
/**
 * @private
 *
 * "Expands" an embedded  string into an ordinal one.  This  is a function that
 * returns aggregated type.   The returned struct always  has its `as.heap.len`
 * an `as.heap.ptr` fields set appropriately.
 *
 * This is an implementation detail that 3rd parties should never bother.
 */
static inline struct RString
rbimpl_rstring_getmem(VALUE str)
{
    RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING);

if (RB_FL_ANY_RAW(str, RSTRING_NOEMBED)) {
        return *RSTRING(str);
    }
    else {
        /* Expecting compilers to optimize this on-stack struct away. */
        struct RString retval;
        retval.as.heap.len = RSTRING_EMBED_LEN(str);
        retval.as.heap.ptr = RSTRING(str)->as.embed.ary;
        return retval;
    }
}

RBIMPL_WARNING_POP()

RBIMPL_ATTR_ARTIFICIAL()
/**
 * Queries the contents pointer of the string.
 *
 * @param[in]  str  String in question.
 * @return     Pointer to its contents.
 * @pre        `str` must be an instance of ::RString.
 */
static inline char *
RSTRING_PTR(VALUE str)
{
    char *ptr = rbimpl_rstring_getmem(str).as.heap.ptr;

if (RB_UNLIKELY(! ptr)) {
        /* :BEWARE: @shyouhei thinks  that currently, there are  rooms for this
         * function to return  NULL.  In the 20th century that  was a pointless
         * concern.  However struct RString can hold fake strings nowadays.  It
         * seems no  check against NULL  are exercised around handling  of them
         * (one  of  such   usages  is  located  in   marshal.c,  which  scares
         * @shyouhei).  Better check here for maximum safety.
         *
         * Also,  this is  not rb_warn()  because RSTRING_PTR()  can be  called
         * during GC (see  what obj_info() does).  rb_warn()  needs to allocate
         * Ruby objects.  That is not possible at this moment. */
        rb_debug_rstring_null_ptr("RSTRING_PTR");
    }

return ptr;
}

RBIMPL_ATTR_ARTIFICIAL()
/**
 * Queries the end of the contents pointer of the string.
 *
 * @param[in]  str  String in question.
 * @return     Pointer to its end of contents.
 * @pre        `str` must be an instance of ::RString.
 */
static inline char *
RSTRING_END(VALUE str)
{
    struct RString buf = rbimpl_rstring_getmem(str);

if (RB_UNLIKELY(! buf.as.heap.ptr)) {
        /* Ditto. */
        rb_debug_rstring_null_ptr("RSTRING_END");
    }

return &buf.as.heap.ptr[buf.as.heap.len];
}

RBIMPL_ATTR_ARTIFICIAL()
/**
 * Identical to RSTRING_LEN(), except it differs for the return type.
 *
 * @param[in]  str             String in question.
 * @exception  rb_eRangeError  Too long.
 * @return     Its length, in bytes.
 * @pre        `str` must be an instance of ::RString.
 *
 * @internal
 *
 * This API seems redundant but has actual usages.
 */
static inline int
RSTRING_LENINT(VALUE str)
{
    return rb_long2int(RSTRING_LEN(str));
}

/**
 * Convenient macro to obtain the contents and length at once.
 *
 * @param  str     String in question.
 * @param  ptrvar  Variable where its contents is stored.
 * @param  lenvar  Variable where its length is stored.
 */
#ifdef HAVE_STMT_AND_DECL_IN_EXPR
# define RSTRING_GETMEM(str, ptrvar, lenvar) \
    __extension__ ({ \
        struct RString rbimpl_str = rbimpl_rstring_getmem(str); \
        (ptrvar) = rbimpl_str.as.heap.ptr; \
        (lenvar) = rbimpl_str.as.heap.len; \
    })
#else
# define RSTRING_GETMEM(str, ptrvar, lenvar) \
    ((ptrvar) = RSTRING_PTR(str),           \
     (lenvar) = RSTRING_LEN(str))
#endif /* HAVE_STMT_AND_DECL_IN_EXPR */
#endif /* RBIMPL_RSTRING_H */

Back