Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Macros | Functions
symbol.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

Defines rb_intern. More...

#include "ruby/internal/config.h"
#include "ruby/internal/attr/noalias.h"
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/pure.h"
#include "ruby/internal/cast.h"
#include "ruby/internal/constant_p.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/has/builtin.h"
#include "ruby/internal/value.h"
Include dependency graph for symbol.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define RB_ID2SYM   rb_id2sym
 Just another name of rb_id2sym. More...
 
#define RB_SYM2ID   rb_sym2id
 Just another name of rb_sym2id. More...
 
#define ID2SYM   RB_ID2SYM
 Old name of RB_ID2SYM. More...
 
#define SYM2ID   RB_SYM2ID
 Old name of RB_SYM2ID. More...
 
#define CONST_ID_CACHE   RUBY_CONST_ID_CACHE
 Old name of RUBY_CONST_ID_CACHE. More...
 
#define CONST_ID   RUBY_CONST_ID
 Old name of RUBY_CONST_ID. More...
 
#define RUBY_CONST_ID_CACHE(result, str)
 Old implementation detail of rb_intern(). More...
 
#define RUBY_CONST_ID(var, str)
 Old implementation detail of rb_intern(). More...
 

Functions

ID rb_sym2id (VALUE obj)
 Converts an instance of rb_cSymbol into an ID. More...
 
VALUE rb_id2sym (ID id)
 Allocates an instance of rb_cSymbol that has the given id. More...
 
ID rb_intern (const char *name)
 Finds or creates a symbol of the given name. More...
 
ID rb_intern2 (const char *name, long len)
 Identical to rb_intern(), except it additionally takes the length of the string. More...
 
ID rb_intern_str (VALUE str)
 Identical to rb_intern(), except it takes an instance of rb_cString. More...
 
const char * rb_id2name (ID id)
 Retrieves the name mapped to the given id. More...
 
ID rb_check_id (volatile VALUE *namep)
 Detects if the given name is already interned or not. More...
 
ID rb_to_id (VALUE str)
 Identical to rb_intern(), except it takes an instance of rb_cString. More...
 
VALUE rb_id2str (ID id)
 Identical to rb_id2name(), except it returns a frozen Ruby String instead of a C String. More...
 
VALUE rb_sym2str (VALUE symbol)
 Obtain a frozen string representation of a symbol (not including the leading colon). More...
 
VALUE rb_to_symbol (VALUE name)
 Identical to rb_intern_str(), except it generates a dynamic symbol if necessary. More...
 
VALUE rb_check_symbol (volatile VALUE *namep)
 Identical to rb_check_id(), except it returns an instance of rb_cSymbol instead. More...
 
static ID rb_intern_const (const char *str)
 This is a "tiny optimisation" over rb_intern(). More...
 

Detailed Description

Defines rb_intern.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
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 symbol.h.

Macro Definition Documentation

◆ RB_ID2SYM

#define RB_ID2SYM   rb_id2sym

Just another name of rb_id2sym.

Definition at line 42 of file symbol.h.

◆ RB_SYM2ID

#define RB_SYM2ID   rb_sym2id

Just another name of rb_sym2id.

Definition at line 43 of file symbol.h.

◆ RUBY_CONST_ID

#define RUBY_CONST_ID (   var,
  str 
)
Value:
do { \
static ID rbimpl_id; \
(var) = rbimpl_intern_const(&rbimpl_id, (str)); \
} while (0)
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition: value.h:52

Old implementation detail of rb_intern().

Deprecated:
Does anyone use it? Preserved for backward compat.

Definition at line 315 of file symbol.h.

◆ RUBY_CONST_ID_CACHE

#define RUBY_CONST_ID_CACHE (   result,
  str 
)
Value:
{ \
static ID rb_intern_id_cache; \
rbimpl_intern_const(&rb_intern_id_cache, (str)); \
result rb_intern_id_cache; \
}

Old implementation detail of rb_intern().

Deprecated:
Does anyone use it? Preserved for backward compat.

Definition at line 304 of file symbol.h.

Function Documentation

◆ rb_check_id()

ID rb_check_id ( volatile VALUE namep)

Detects if the given name is already interned or not.

It first tries to convert the argument to an instance of rb_cString if it is neither an instance of rb_cString nor rb_cSymbol. The conversion result is written back to the variable. Then queries if that name was already interned before. If found it returns such id, otherwise zero.

We eventually introduced this API to avoid inadvertent symbol pin-down. Before, there was no way to know if an ID was already interned or not without actually creating one (== leaking memory). By using this API you can avoid such situations:

bool does_interning_this_leak_memory(VALUE obj)
{
auto tmp = obj;
if (auto id = rb_check_id(&tmp); id) {
return false;
}
else {
return true; // Let GC sweep tmp if necessary.
}
}
ID rb_check_id(volatile VALUE *namep)
Detects if the given name is already interned or not.
Definition: symbol.c:1117
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40
Parameters
[in,out]namepA pointer to a name to query.
Precondition
The object referred by *namep must either be an instance of rb_cSymbol, or an instance of rb_cString, or responds to #to_str method.
Exceptions
rb_eTypeErrorCan't convert *namep into rb_cString.
rb_eEncodingErrorGiven string is non-ASCII.
Return values
0No such id ever existed in the history.
otherwiseThe id that represents the given name.
Postcondition
The object that *namep points to is a converted result object, which is always an instance of either rb_cSymbol or rb_cString.
See also
https://bugs.ruby-lang.org/issues/5072

Definition at line 1117 of file symbol.c.

Referenced by rb_f_untrace_var().

◆ rb_check_symbol()

VALUE rb_check_symbol ( volatile VALUE namep)

Identical to rb_check_id(), except it returns an instance of rb_cSymbol instead.

Parameters
[in,out]namepA pointer to a name to query.
Precondition
The object referred by *namep must either be an instance of rb_cSymbol, or an instance of rb_cString, or responds to #to_str method.
Exceptions
rb_eTypeErrorCan't convert *namep into rb_cString.
rb_eEncodingErrorGiven string is non-ASCII.
Return values
RUBY_QnilNo such id ever existed in the history.
otherwiseThe id that represents the given name.
Postcondition
The object that *namep points to is a converted result object, which is always an instance of either rb_cSymbol or rb_cString.
See also
https://bugs.ruby-lang.org/issues/5072

Definition at line 1174 of file symbol.c.

◆ rb_id2name()

const char* rb_id2name ( ID  id)

Retrieves the name mapped to the given id.

Parameters
[in]idAn id to query.
Return values
NULLNo such id ever existed in the history.
otherwiseA name that the id represents.
Note
The return value is managed by the interpreter. Don't pass it to free().

Definition at line 992 of file symbol.c.

Referenced by rb_undef().

◆ rb_id2str()

VALUE rb_id2str ( ID  id)

Identical to rb_id2name(), except it returns a frozen Ruby String instead of a C String.

Parameters
[in]idAn id to query.
Return values
RUBY_QfalseNo such id ever existed in the history.
otherwiseAn instance of rb_cString with the name of id.

Definition at line 986 of file symbol.c.

Referenced by rb_attr(), rb_define_module_id_under(), rb_id2name(), rb_id_attrset(), rb_notimplement(), rb_sym2str(), and rb_undef().

◆ rb_id2sym()

VALUE rb_id2sym ( ID  id)

Allocates an instance of rb_cSymbol that has the given id.

Parameters
[in]idAn id.
Return values
RUBY_QfalseNo such id ever existed in the history.
OtherwiseAn allocated rb_cSymbol instance.

Definition at line 951 of file symbol.c.

◆ rb_intern()

ID rb_intern ( const char *  name)

Finds or creates a symbol of the given name.

Parameters
[in]nameThe name of the id.
Exceptions
rb_eRuntimeErrorToo many symbols.
Returns
A (possibly new) id whose value is the given name.
Note
These days Ruby internally has two kinds of symbols (static / dynamic). Symbols created using this function would become a static one; i.e. would never be garbage collected. It is up to you to avoid memory leaks. Think twice before using it.

Definition at line 823 of file symbol.c.

Referenced by rb_define_alias(), rb_define_attr(), rb_define_class(), rb_define_class_under(), rb_define_const(), rb_define_method(), rb_define_module(), rb_define_module_under(), rb_define_private_method(), rb_define_protected_method(), rb_enc_get_index(), rb_ext_resolve_symbol(), rb_iv_set(), rb_range_values(), rb_remove_method(), rb_struct_define_under(), and rb_undef_method().

◆ rb_intern2()

ID rb_intern2 ( const char *  name,
long  len 
)

Identical to rb_intern(), except it additionally takes the length of the string.

This way you can have a symbol that contains NUL characters.

Parameters
[in]nameThe name of the id.
[in]lenLength of name.
Exceptions
rb_eRuntimeErrorToo many symbols.
Returns
A (possibly new) id whose value is the given name.
Note
These days Ruby internally has two kinds of symbols (static/dynamic). Symbols created using this function would become static ones; i.e. would never be garbage collected. It is up to you to avoid memory leaks. Think twice before using it.

Definition at line 816 of file symbol.c.

Referenced by rb_f_global_variables(), rb_intern(), and rb_intern_const().

◆ rb_intern_const()

static ID rb_intern_const ( const char *  str)
inlinestatic

This is a "tiny optimisation" over rb_intern().

If you pass a string literal, and if your C compiler can special-case strlen of such literal to strength-reduce into an integer constant expression, then this inline function can precalc a part of conversion.

Note
This function also works happily for non-constant strings. Why bother then? Just apply liberally to everything.
But rb_intern() could be faster on compilers with statement expressions, because they can cache the created ID.
Parameters
[in]strThe name of the id.
Exceptions
rb_eRuntimeErrorToo many symbols.
Returns
A (possibly new) id whose value is the given str.
Note
These days Ruby internally has two kinds of symbols (static / dynamic). Symbols created using this function would become a static one; i.e. would never be garbage collected. It is up to you to avoid memory leaks. Think twice before using it.

Definition at line 277 of file symbol.h.

◆ rb_intern_str()

ID rb_intern_str ( VALUE  str)

Identical to rb_intern(), except it takes an instance of rb_cString.

Parameters
[in]strThe name of the id.
Precondition
str must either be an instance of rb_cSymbol, or an instance of rb_cString, or responds to #to_str method.
Exceptions
rb_eTypeErrorCan't convert str into rb_cString.
rb_eRuntimeErrorToo many symbols.
Returns
A (possibly new) id whose value is the given str.
Note
These days Ruby internally has two kinds of symbols (static/dynamic). Symbols created using this function would become static ones; i.e. would never be garbage collected. It is up to you to avoid memory leaks. Think twice before using it.

Definition at line 829 of file symbol.c.

Referenced by rb_attr(), and rb_to_id().

◆ rb_sym2id()

ID rb_sym2id ( VALUE  obj)

Converts an instance of rb_cSymbol into an ID.

Parameters
[in]objAn instance of rb_cSymbol.
Exceptions
rb_eTypeErrorobj is not an instance of rb_cSymbol.
Returns
An ID of the identical symbol.

Definition at line 917 of file symbol.c.

Referenced by rb_id_attrset(), and rb_intern3().

◆ rb_sym2str()

VALUE rb_sym2str ( VALUE  symbol)

Obtain a frozen string representation of a symbol (not including the leading colon).

Done without any object allocations.

Parameters
[in]symbolA rb_cSymbol instance to query.
Returns
A frozen instance of rb_cString with the name of symbol.
Note
This does not create a permanent ID using the symbol.

Definition at line 970 of file symbol.c.

Referenced by rb_enc_get_index(), rb_gc_latest_gc_info(), rb_gc_stat(), rb_str_format(), and rb_sym_to_s().

◆ rb_to_id()

ID rb_to_id ( VALUE  str)

Identical to rb_intern(), except it takes an instance of rb_cString.

Parameters
[in]strThe name of the id.
Precondition
str must either be an instance of rb_cSymbol, or an instance of rb_cString, or responds to #to_str method.
Exceptions
rb_eTypeErrorCan't convert str into rb_cString.
rb_eRuntimeErrorToo many symbols.
Returns
A (possibly new) id whose value is the given str.
Note
These days Ruby internally has two kinds of symbols (static/dynamic). Symbols created using this function would become static ones; i.e. would never be garbage collected. It is up to you to avoid memory leaks. Think twice before using it.

Definition at line 12463 of file string.c.

Referenced by rb_f_trace_var().

◆ rb_to_symbol()

VALUE rb_to_symbol ( VALUE  name)

Identical to rb_intern_str(), except it generates a dynamic symbol if necessary.

Parameters
[in]nameThe name of the id.
Precondition
name must either be an instance of rb_cSymbol, or an instance of rb_cString, or responds to #to_str method.
Exceptions
rb_eTypeErrorCan't convert name into rb_cString.
rb_eRuntimeErrorToo many symbols.
Returns
A (possibly new) id whose value is the given name.
Note
These days Ruby internally has two kinds of symbols (static/dynamic). Symbols created using this function would become dynamic ones; i.e. would be garbage collected. It could be safer for you to use it than alternatives, when applicable.

Definition at line 12473 of file string.c.