(34098b669c0cbc024cd08e686891f1dfe0a10aaf)

Defines struct RString. More...

#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"

Include dependency graph for rstring.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	RString
	Ruby's String. More...

Macros
#define	RSTRING(obj) RBIMPL_CAST((struct RString *)(obj))
	Convenient casting macro.

#define	Check_SafeStr(v) rb_check_safe_str(RBIMPL_CAST((VALUE)(v)))

#define	RSTRING_GETMEM(str, ptrvar, lenvar)
	Convenient macro to obtain the contents and length at once.

Conversion of Ruby strings into C's
#define	StringValue(v) rb_string_value(&(v))
	Ensures that the parameter object is a String.

#define	StringValuePtr(v) rb_string_value_ptr(&(v))
	Identical to StringValue, except it returns a `char*`.

#define	StringValueCStr(v) rb_string_value_cstr(&(v))
	Identical to StringValuePtr, except it additionally checks for the contents for viability as a C string.

#define	SafeStringValue(v) StringValue(v)

#define	ExportStringValue(v)
	Identical to StringValue, except it additionally converts the string's encoding to default external encoding.

Functions
VALUE	rb_str_to_str (VALUE obj)
	Identical to rb_check_string_type(), except it raises exceptions in case of conversion failures.

VALUE	rb_string_value (volatile VALUE *ptr)
	Identical to rb_str_to_str(), except it fills the passed pointer with the converted object.

char *	rb_string_value_ptr (volatile VALUE *ptr)
	Identical to rb_str_to_str(), except it returns the converted string's backend memory region.

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.

VALUE	rb_str_export (VALUE obj)
	Identical to rb_str_to_str(), except it additionally converts the string into default external encoding.

VALUE	rb_str_export_locale (VALUE obj)
	Identical to rb_str_export(), except it converts into the locale encoding instead.

static long	RSTRING_LEN (VALUE str)
	Queries the length of the string.

static char *	RSTRING_PTR (VALUE str)
	Queries the contents pointer of the string.

static char *	RSTRING_END (VALUE str)
	Queries the end of the contents pointer of the string.

static int	RSTRING_LENINT (VALUE str)
	Identical to RSTRING_LEN(), except it differs for the return type.

Detailed Description

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.

Macro Definition Documentation

◆ 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 344 of file rstring.h.

◆ ExportStringValue

#define ExportStringValue ( v )

Value:

    do { \
    StringValue(v);               \
    (v) = rb_str_export(v);       \
} while (0)

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 117 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 488 of file rstring.h.

◆ SafeStringValue

#define SafeStringValue ( v ) StringValue(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 98 of file rstring.h.

◆ StringValue

#define StringValue ( v ) rb_string_value(&(v))

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 66 of file rstring.h.

◆ StringValueCStr

#define StringValueCStr ( v ) rb_string_value_cstr(&(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.

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 89 of file rstring.h.

◆ StringValuePtr

#define StringValuePtr ( v ) rb_string_value_ptr(&(v))

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 76 of file rstring.h.

Function Documentation

◆ rb_str_export()

VALUE rb_str_export ( VALUE obj )

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

[in] obj Target object.

Exceptions

rb_eTypeError No implicit conversion to String.

Returns: Converted ruby string of default external encoding.

Definition at line 1379 of file string.c.

◆ rb_str_export_locale()

VALUE rb_str_export_locale ( VALUE obj )

Identical to rb_str_export(), except it converts into the locale encoding instead.

Parameters

[in] obj Target object.

Exceptions

rb_eTypeError No implicit conversion to String.

Returns: Converted ruby string of locale encoding.

Definition at line 1385 of file string.c.

◆ 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.

Parameters

[in] obj Target object.

Exceptions

rb_eTypeError No implicit conversion to String.

Returns: Return value of obj.to_str.

See also: rb_io_get_io; rb_ary_to_ary

Definition at line 1705 of file string.c.

Referenced by rb_string_value().

◆ 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.

Parameters

[in,out] ptr Pointer to a variable of target object.

Exceptions

rb_eTypeError No implicit conversion to String.

Returns: Return value of obj.to_str.

Postcondition: *ptr is the return value.

Definition at line 2712 of file string.c.

Referenced by rb_string_value_cstr(), and rb_string_value_ptr().

◆ 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 2828 of file string.c.

◆ 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 2723 of file string.c.

◆ 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 442 of file rstring.h.

Referenced by rb_enc_uint_chr(), rb_str_format(), rb_str_hash(), rb_str_inspect(), rb_str_offset(), rb_str_set_len(), rb_str_update(), rb_str_vcatf(), and RREGEXP_SRC_END().

◆ 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 367 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

rb_eRangeError Too long.

Returns: Its length, in bytes.

Precondition: str must be an instance of RString.

Definition at line 468 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 416 of file rstring.h.

(34098b669c0cbc024cd08e686891f1dfe0a10aaf)

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ Check_SafeStr

◆ ExportStringValue

◆ RSTRING

◆ RSTRING_GETMEM

◆ SafeStringValue

◆ StringValue

◆ StringValueCStr

◆ StringValuePtr

Function Documentation

◆ rb_str_export()

◆ rb_str_export_locale()

◆ rb_str_to_str()

◆ rb_string_value()

◆ rb_string_value_cstr()

◆ rb_string_value_ptr()

◆ RSTRING_END()

◆ RSTRING_LEN()

◆ RSTRING_LENINT()

◆ RSTRING_PTR()