Defines struct RString.
More...
Go to the source code of this file.
Defines struct RString.
- Author
- Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.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.
Definition in file rstring.h.
◆ Check_SafeStr
#define Check_SafeStr |
( |
|
v | ) |
rb_check_safe_str(RBIMPL_CAST((VALUE)(v))) |
- 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.
Definition at line 392 of file rstring.h.
◆ ExportStringValue
#define ExportStringValue |
( |
|
v | ) |
|
Value: do { \
StringValue(v); \
} while (0)
VALUE rb_str_export(VALUE obj)
Identical to rb_str_to_str(), except it additionally converts the string into default external encodi...
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.
- Parameters
-
[in,out] | v | Arbitrary Ruby object. |
- Exceptions
-
rb_eTypeError | No implicit conversion defined. |
- Returns
- Converted Ruby string's backend C string.
- Postcondition
v
is a String.
Definition at line 123 of file rstring.h.
◆ RSTRING
#define RSTRING |
( |
|
obj | ) |
RBIMPL_CAST((struct RString *)(obj)) |
Convenient casting macro.
- Parameters
-
obj | An object, which is in fact an RString. |
- Returns
- The passed object casted to RString.
Definition at line 41 of file rstring.h.
◆ RSTRING_GETMEM
#define RSTRING_GETMEM |
( |
|
str, |
|
|
|
ptrvar, |
|
|
|
lenvar |
|
) |
| |
Value: ((ptrvar) = RSTRING_PTR(str), \
(lenvar) = RSTRING_LEN(str))
Convenient macro to obtain the contents and length at once.
- Parameters
-
str | String in question. |
ptrvar | Variable where its contents is stored. |
lenvar | Variable where its length is stored. |
Definition at line 574 of file rstring.h.
◆ SafeStringValue
- 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.
Definition at line 104 of file rstring.h.
◆ StringValue
Ensures that the parameter object is a String.
This is done by calling its to_str
method.
- Parameters
-
[in,out] | v | Arbitrary Ruby object. |
- Exceptions
-
rb_eTypeError | No implicit conversion defined. |
- Postcondition
v
is a String.
Definition at line 72 of file rstring.h.
◆ StringValueCStr
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.
- Parameters
-
[in,out] | v | Arbitrary Ruby object. |
- Exceptions
-
rb_eTypeError | No implicit conversion defined. |
rb_eArgError | String is not C-compatible. |
- Returns
- Converted Ruby string's backend C string.
- Postcondition
v
is a String.
Definition at line 95 of file rstring.h.
◆ StringValuePtr
Identical to StringValue, except it returns a char*
.
- Parameters
-
[in,out] | v | Arbitrary Ruby object. |
- Exceptions
-
rb_eTypeError | No implicit conversion defined. |
- Returns
- Converted Ruby string's backend C string.
- Postcondition
v
is a String.
Definition at line 82 of file rstring.h.
◆ ruby_rstring_consts
This is an enum because GDB wants it (rather than a macro).
People need not bother.
Enumerator |
---|
RSTRING_EMBED_LEN_SHIFT | Where RSTRING_EMBED_LEN_MASK resides.
|
RSTRING_EMBED_LEN_MAX | Max possible number of characters that can be embedded.
|
Definition at line 210 of file rstring.h.
◆ rb_str_export()
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.
- Parameters
-
- Exceptions
-
rb_eTypeError | No implicit conversion to String. |
- Returns
- Converted ruby string of default external encoding.
Definition at line 1301 of file string.c.
Referenced by rb_str_export().
◆ rb_str_export_locale()
Identical to rb_str_export(), except it converts into the locale encoding instead.
- Parameters
-
- Exceptions
-
rb_eTypeError | No implicit conversion to String. |
- Returns
- Converted ruby string of locale encoding.
Definition at line 1307 of file string.c.
Referenced by rb_str_export_locale().
◆ rb_str_to_str()
◆ rb_string_value()
◆ 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 C string.
Ruby can accept wider range of contents as strings, compared to C. This function is to check that.
- Parameters
-
[in,out] | ptr | Pointer to a variable of target object. |
- Exceptions
-
rb_eTypeError | No implicit conversion to String. |
rb_eArgError | String is not C-compatible. |
- Postcondition
*ptr
is the return value of obj.to_str
.
- Returns
- Pointer to the contents of the return value.
Definition at line 2617 of file string.c.
Referenced by rb_string_value_cstr().
◆ 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.
- Parameters
-
[in,out] | ptr | Pointer to a variable of target object. |
- Exceptions
-
rb_eTypeError | No implicit conversion to String. |
- Postcondition
*ptr
is the return value of obj.to_str
.
- Returns
- Pointer to the contents of the return value.
Definition at line 2512 of file string.c.
Referenced by rb_string_value_ptr().
◆ RSTRING_EMBED_LEN()
static long RSTRING_EMBED_LEN |
( |
VALUE |
str | ) |
|
|
inlinestatic |
Queries the length of the string.
- Parameters
-
[in] | str | String in question. |
- Returns
- Its length, in bytes.
- Precondition
str
must be an instance of RString, and must has its RSTRING_NOEMBED flag off.
Definition at line 423 of file rstring.h.
◆ RSTRING_END()
static char * RSTRING_END |
( |
VALUE |
str | ) |
|
|
inlinestatic |
Queries the end of the contents pointer of the string.
- Parameters
-
[in] | str | String in question. |
- Returns
- Pointer to its end of contents.
- Precondition
str
must be an instance of RString.
Definition at line 528 of file rstring.h.
◆ RSTRING_LEN()
static long RSTRING_LEN |
( |
VALUE |
str | ) |
|
|
inlinestatic |
Queries the length of the string.
- Parameters
-
[in] | str | String in question. |
- Returns
- Its length, in bytes.
- Precondition
str
must be an instance of RString.
Definition at line 484 of file rstring.h.
◆ RSTRING_LENINT()
static int RSTRING_LENINT |
( |
VALUE |
str | ) |
|
|
inlinestatic |
Identical to RSTRING_LEN(), except it differs for the return type.
- Parameters
-
[in] | str | String in question. |
- Exceptions
-
- Returns
- Its length, in bytes.
- Precondition
str
must be an instance of RString.
Definition at line 554 of file rstring.h.
◆ RSTRING_PTR()
static char * RSTRING_PTR |
( |
VALUE |
str | ) |
|
|
inlinestatic |
Queries the contents pointer of the string.
- Parameters
-
[in] | str | String in question. |
- Returns
- Pointer to its contents.
- Precondition
str
must be an instance of RString.
Definition at line 498 of file rstring.h.