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

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Functions
symbol.h File Reference

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

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.
int | rb_enc_symname_p (const char *str, rb_encoding *enc)
| Identical to rb_symname_p(), except it additionally takes an encoding.
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.
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.
VALUE | rb_check_symbol_cstr (const char *ptr, long len, rb_encoding *enc)
| Identical to rb_check_id_cstr(), except for the return type.

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

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.

## 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] | ptr | A pointer to a memory region.
  [in] | len | Number of bytes of `ptr`.
  [in] | enc | Encoding of `ptr`.

Exceptions

  rb_eEncodingError | `ptr` contains non-ASCII according to `enc`.

Return values

  0 | No such id ever existed in the history.
  otherwise | The id that represents the given name.

Definition at line 1181 of file symbol.c.

Referenced by rb_deprecate_constant(), rb_iv_get(), and rb_path_to_class().

## ◆ 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] | ptr | A pointer to a memory region.
  [in] | len | Number of bytes of `ptr`.
  [in] | enc | Encoding of `ptr`.

Exceptions

  rb_eEncodingError | `ptr` contains non-ASCII according to `enc`.

Return values

  RUBY_Qnil | No such id ever existed in the history.
  otherwise | The id that represents the given name.

Definition at line 1192 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] | name | A C string to check.
  [in] | len | Number of bytes of `str`.
  [in] | enc | `str`'s encoding.

Return values

  1 | It is a valid symbol name.
  0 | It is invalid as a symbol name.

Definition at line 411 of file symbol.c.

Referenced by rb_enc_symname2_p(), and 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] | str | A C string to check.
  [in] | enc | `str`'s encoding.

Return values

  1 | It is a valid symbol name.
  0 | It is invalid as a symbol name.

Definition at line 208 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] | name | The name of the id.
  [in] | len | Length of `name`.
  [in] | enc | `name`'s encoding.

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 725 of file symbol.c.

Referenced by rb_intern2(), and rb_intern3().