Ruby: include/ruby/internal/intern/error.h File Reference

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

Macros | Functions
error.h File Reference

Public APIs related to rb_eException. More...

`#include "ruby/internal/attr/format.h"`
`#include "ruby/internal/attr/noreturn.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/internal/fl_type.h"`
`#include "ruby/backward/2/assume.h"`

Go to the source code of this file.

## Macros
#define | UNLIMITED_ARGUMENTS (-1)
| This macro is used in conjunction with rb_check_arity().
#define | rb_exc_new2 rb_exc_new_cstr
| Old name of rb_exc_new_cstr.
#define | rb_exc_new3 rb_exc_new_str
| Old name of rb_exc_new_str.
#define | rb_check_frozen_internal(obj)
#define | rb_check_frozen rb_check_frozen_inline
| Just another name of rb_check_frozen.

## Functions
VALUE | rb_exc_new (VALUE etype, const char *ptr, long len)
| Creates an instance of the passed exception class.
VALUE | rb_exc_new_cstr (VALUE etype, const char *str)
| Identical to rb_exc_new(), except it assumes the passed pointer is a pointer to a C string.
VALUE | rb_exc_new_str (VALUE etype, VALUE str)
| Identical to rb_exc_new_cstr(), except it takes a Ruby's string instead of C's.
void | rb_loaderror (const char *fmt,...)
| Raises an instance of rb_eLoadError.
void | rb_loaderror_with_path (VALUE path, const char *fmt,...)
| Identical to rb_loaderror(), except it additionally takes which file is unable to load.
void | rb_name_error (ID name, const char *fmt,...)
| Raises an instance of rb_eNameError.
void | rb_name_error_str (VALUE name, const char *fmt,...)
| Identical to rb_name_error(), except it takes a VALUE instead of ID.
void | rb_frozen_error_raise (VALUE recv, const char *fmt,...)
| Raises an instance of rb_eFrozenError.
void | rb_invalid_str (const char *str, const char *type)
| Honestly I don't understand the name, but it raises an instance of rb_eArgError.
void | rb_error_frozen (const char *what)
| Identical to rb_frozen_error_raise(), except its raising exception has a message like "can't modify frozen /what/".
void | rb_error_frozen_object (VALUE what)
| Identical to rb_error_frozen(), except it takes arbitrary Ruby object instead of C's string.
void | rb_check_frozen (VALUE obj)
| Queries if the passed object is frozen.
void | rb_check_copyable (VALUE obj, VALUE orig)
| Ensures that the passed object can be `initialize_copy` relationship.
static void | rb_check_frozen_inline (VALUE obj)
| Just another name of rb_check_frozen.
static int | rb_check_arity (int argc, int min, int max)
| Ensures that the passed integer is in the passed range.

## Detailed Description

Public APIs related to rb_eException.

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 error.h.

## Macro Definition Documentation

## ◆ rb_check_frozen

#define rb_check_frozen rb_check_frozen_inline

Just another name of rb_check_frozen.

Definition at line 264 of file error.h.

Referenced by rb_const_remove(), rb_copy_generic_ivar(), rb_enc_associate_index(), rb_enc_set_index(), rb_io_taint_check(), rb_ivar_set(), rb_mod_remove_cvar(), rb_obj_init_copy(), rb_obj_remove_instance_variable(), and rb_undefine_finalizer().

## ◆ rb_check_frozen_internal

#define rb_check_frozen_internal | ( |  | obj | ) |

Value:
do { \
VALUE frozen_obj = (obj); \
if (RB_UNLIKELY(RB_OBJ_FROZEN(frozen_obj))) { \
rb_error_frozen_object(frozen_obj); \
} \
} while (0)
RB_OBJ_FROZEN
static bool RB_OBJ_FROZEN(VALUE obj)
Checks if an object is frozen.
Definition fl_type.h:921
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

Deprecated

Does anyone use this? Remain not deleted for compatibility.

Definition at line 247 of file error.h.

Referenced by rb_check_copyable(), and rb_check_frozen().

## ◆ UNLIMITED_ARGUMENTS

#define UNLIMITED_ARGUMENTS (-1)

This macro is used in conjunction with rb_check_arity().

If you pass it to the function's last (max) argument, that means the function does not check upper limit.

Definition at line 35 of file error.h.

Referenced by rb_check_arity(), rb_f_kill(), and rb_proc_arity().

## Function Documentation

## ◆ rb_check_arity()

static int rb_check_arity | ( | int | argc,
|  | int | min,
|  | int | max )
| inlinestatic

Ensures that the passed integer is in the passed range.

When you can use rb_scan_args() that is preferred over this one (powerful, descriptive). But it can have its own application area.

Parameters

  [in] | argc | Arbitrary integer.
  [in] | min | Minimum allowed `argv`.
  [in] | max | Maximum allowed `argv`, or `UNLIMITED_ARGUMENTS`.

Exceptions

  rb_eArgError | `argc` out of range.

Returns
  The passed `argc`.

Postcondition
  Upon successful return `argc` is in range of `min`..`max`, both inclusive.

Definition at line 280 of file error.h.

Referenced by rb_ary_aref(), rb_f_abort(), rb_f_exit(), rb_f_kill(), rb_file_s_absolute_path(), rb_file_s_expand_path(), rb_mod_class_variables(), rb_mod_constants(), and rb_obj_singleton_methods().

## ◆ rb_check_frozen_inline()

static void rb_check_frozen_inline | ( | VALUE | obj | ) |
| inlinestatic

Just another name of rb_check_frozen.

Definition at line 256 of file error.h.