Ruby: include/ruby/internal/symbol.h File Reference

Ruby 4.0.5p0 (2026-05-20 revision 64336ffd0ee9e1f4c05891695a3d7b49cb709721)

Macros | Functions
symbol.h File Reference

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

Go to the source code of this file.

## Macros
#define | RB_ID2SYM rb_id2sym
| Just another name of rb_id2sym.
#define | RB_SYM2ID rb_sym2id
| Just another name of rb_sym2id.
#define | ID2SYM RB_ID2SYM
| Old name of RB_ID2SYM.
#define | SYM2ID RB_SYM2ID
| Old name of RB_SYM2ID.
#define | CONST_ID_CACHE RUBY_CONST_ID_CACHE
| Old name of RUBY_CONST_ID_CACHE.
#define | CONST_ID RUBY_CONST_ID
| Old name of RUBY_CONST_ID.
#define | RUBY_CONST_ID_CACHE(result, str)
| Old implementation detail of rb_intern().
#define | RUBY_CONST_ID(var, str)
| Returns the cached ID for the given str in var, in compiler independent manner.

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

## Detailed Description

Defines rb_intern.

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 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)
ID
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition value.h:52

Returns the cached ID for the given str in var, in compiler independent manner.

Use this instead of GCC specific rb_intern() when you want to cache the ID on all platforms certainly.

Definition at line 324 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 312 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.
}
}
rb_check_id
ID rb_check_id(volatile VALUE *namep)
Detects if the given name is already interned or not.
Definition symbol.c:1133
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

Parameters

  [in,out] | namep | A 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_eTypeError | Can't convert `*namep` into rb_cString.
  rb_eEncodingError | Given string contains invalid character(s).

Return values

  0 | No such id ever existed in the history.
  otherwise | The 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
  rb_str_to_str
  https://bugs.ruby-lang.org/issues/5072

Definition at line 1133 of file symbol.c.

Referenced by rb_check_id(), and 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] | namep | A 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_eTypeError | Can't convert `*namep` into rb_cString.
  rb_eEncodingError | Given string contains invalid character(s).

Return values

  RUBY_Qnil | No such id ever existed in the history.
  otherwise | The 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
  rb_str_to_str

Definition at line 1190 of file symbol.c.

Referenced by rb_check_symbol().

## ◆ rb_id2name()

const char * rb_id2name | ( | ID | id | ) |

Retrieves the name mapped to the given id.

Parameters

  [in] | id | An id to query.

Return values

  NULL | Unknown id.
  otherwise | A name that the id represents.

Note
  The return value is managed by the interpreter. Don't pass it to free().
  The underlying name can contain internal NUL bytes, so the return value might be a truncated representation due to the nature of C strings.
  This C string is backed by an underlying Ruby string. The Ruby string may move during GC compaction which would make this C string point to invalid memory. Do not use the return value of this function after a potential GC entry point.

Definition at line 1015 of file symbol.c.

## ◆ 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] | id | An id to query.

Return values

  RUBY_Qfalse | No such id ever existed in the history.
  otherwise | An instance of rb_cString with the name of id.

Definition at line 1009 of file symbol.c.

## ◆ rb_id2sym()

VALUE rb_id2sym | ( | ID | id | ) |

Allocates an instance of rb_cSymbol that has the given id.

Parameters

  [in] | id | An id.

Return values

  RUBY_Qfalse | No such id ever existed in the history.
  Otherwise | An allocated rb_cSymbol instance.

Definition at line 974 of file symbol.c.

Referenced by rb_id2sym().

## ◆ rb_intern()

ID rb_intern | ( | const char * | name | ) |

Finds or creates a symbol of the given name.

Parameters

  [in] | name | The name of the id.

Exceptions

  rb_eRuntimeError | Too 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 864 of file symbol.c.

## ◆ 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] | name | The name of the id.
  [in] | len | Length of name.

Exceptions

  rb_eRuntimeError | Too 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 857 of file symbol.c.

Referenced by rb_intern_const().

## ◆ rb_intern_const()

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] | str | The name of the id.

Exceptions

  rb_eRuntimeError | Too 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 285 of file symbol.h.

Referenced by Init_class_hierarchy(), and rb_intern_const().

## ◆ rb_intern_str()

ID rb_intern_str | ( | VALUE | str | ) |

Identical to rb_intern(), except it takes a T_STRING object.

Parameters

  [in] | str | The name of the id.

Precondition
  rb_type(str) must be T_STRING.

Exceptions

  rb_eEncodingError | `str` contains invalid character(s).
  rb_eRuntimeError | Too 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 870 of file symbol.c.

## ◆ rb_sym2id()

ID rb_sym2id | ( | VALUE | obj | ) |

Converts an instance of rb_cSymbol into an ID.

Parameters

  [in] | obj | An instance of rb_cSymbol.

Exceptions

  rb_eTypeError | `obj` is not an instance of rb_cSymbol.

Returns
  An ID of the identical symbol.

Definition at line 943 of file symbol.c.

Referenced by rb_id_attrset(), rb_intern3(), and rb_sym2id().

## ◆ 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] | symbol | A 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 993 of file symbol.c.

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

## ◆ rb_to_id()

ID rb_to_id | ( | VALUE | str | ) |

Identical to rb_intern_str(), except it tries to convert the parameter object to an instance of rb_cString or its subclasses.

Parameters

  [in] | str | The 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_eTypeError | Can't convert `str` into rb_cString.
  rb_eEncodingError | Given string contains invalid character(s).
  rb_eRuntimeError | Too 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.

See also
  rb_str_to_str

Definition at line 12664 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] | name | The 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_eTypeError | Can't convert `name` into rb_cString.
  rb_eRuntimeError | Too 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 12674 of file string.c.