Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Functions
symbol.h File Reference

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

Routines to manipulate encodings of symbols. More...

#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/encoding/encoding.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.

Functions

ID rb_intern3 (const char *name, long len, rb_encoding *enc)
 Identical to rb_intern2(), except it additionally takes an encoding. More...
 
int rb_enc_symname_p (const char *str, rb_encoding *enc)
 Identical to rb_symname_p(), except it additionally takes an encoding. More...
 
int rb_enc_symname2_p (const char *name, long len, rb_encoding *enc)
 Identical to rb_enc_symname_p(), except it additionally takes the passed string's length. More...
 
ID rb_check_id_cstr (const char *ptr, long len, rb_encoding *enc)
 Identical to rb_check_id(), except it takes a pointer to a memory region instead of Ruby's string. More...
 
VALUE rb_check_symbol_cstr (const char *ptr, long len, rb_encoding *enc)
 Identical to rb_check_id_cstr(), except for the return type. More...
 

Detailed Description

Routines to manipulate encodings of symbols.

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.

Function Documentation

◆ rb_check_id_cstr()

ID rb_check_id_cstr ( const char *  ptr,
long  len,
rb_encoding enc 
)

Identical to rb_check_id(), except it takes a pointer to a memory region instead of Ruby's string.

Parameters
[in]ptrA pointer to a memory region.
[in]lenNumber of bytes of ptr.
[in]encEncoding of ptr.
Exceptions
rb_eEncodingErrorptr contains non-ASCII according to enc.
Return values
0No such id ever existed in the history.
otherwiseThe id that represents the given name.

Definition at line 1215 of file symbol.c.

Referenced by rb_deprecate_constant(), and rb_iv_get().

◆ rb_check_symbol_cstr()

VALUE rb_check_symbol_cstr ( const char *  ptr,
long  len,
rb_encoding enc 
)

Identical to rb_check_id_cstr(), except for the return type.

It can also be seen as a routine identical to rb_check_symbol(), except it takes a pointer to a memory region instead of Ruby's string.

Parameters
[in]ptrA pointer to a memory region.
[in]lenNumber of bytes of ptr.
[in]encEncoding of ptr.
Exceptions
rb_eEncodingErrorptr contains non-ASCII according to enc.
Return values
RUBY_QnilNo such id ever existed in the history.
otherwiseThe id that represents the given name.

Definition at line 1226 of file symbol.c.

Referenced by rb_str_format().

◆ rb_enc_symname2_p()

int rb_enc_symname2_p ( const char *  name,
long  len,
rb_encoding enc 
)

Identical to rb_enc_symname_p(), except it additionally takes the passed string's length.

This is needed for strings containing NUL bytes, like in case of UTF-32.

Parameters
[in]nameA C string to check.
[in]lenNumber of bytes of str.
[in]encstr's encoding.
Return values
1It is a valid symbol name.
0It is invalid as a symbol name.

Definition at line 414 of file symbol.c.

Referenced by rb_enc_symname_p().

◆ rb_enc_symname_p()

int rb_enc_symname_p ( const char *  str,
rb_encoding enc 
)

Identical to rb_symname_p(), except it additionally takes an encoding.

Parameters
[in]strA C string to check.
[in]encstr's encoding.
Return values
1It is a valid symbol name.
0It is invalid as a symbol name.

Definition at line 211 of file symbol.c.

Referenced by rb_symname_p().

◆ rb_intern3()

ID rb_intern3 ( const char *  name,
long  len,
rb_encoding enc 
)

Identical to rb_intern2(), except it additionally takes an encoding.

Parameters
[in]nameThe name of the id.
[in]lenLength of name.
[in]encname's encoding.
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 752 of file symbol.c.

Referenced by rb_intern2().