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

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

Namespaces | Macros | Typedefs | Functions
iterator.h File Reference

Block related APIs. More...

`#include "ruby/internal/attr/deprecated.h"`
`#include "ruby/internal/attr/noreturn.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Namespaces
namespace | ruby
| The main namespace.
namespace | ruby::backward
| Backwards compatibility layer.

## Macros
#define | RB_BLOCK_CALL_FUNC_STRICT 1
#define | RUBY_BLOCK_CALL_FUNC_TAKES_BLOCKARG 1
#define | RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)
| Shim for block function parameters.

## Typedefs
typedef VALUE | rb_block_call_func(RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg))
| This is the type of a function that the interpreter expect for C-backended blocks.
typedef rb_block_call_func * | rb_block_call_func_t
| Shorthand type that represents an iterator-written-in-C function pointer.

## Functions
VALUE | rb_each (VALUE obj)
| This is a shorthand of calling `obj.each`.
VALUE | rb_yield (VALUE val)
| Yields the block.
VALUE | rb_yield_values (int n,...)
| Identical to rb_yield(), except it takes variadic number of parameters and pass them to the block.
VALUE | rb_yield_values2 (int n, const VALUE *argv)
| Identical to rb_yield_values(), except it takes the parameters as a C array instead of variadic arguments.
VALUE | rb_yield_values_kw (int n, const VALUE *argv, int kw_splat)
| Identical to rb_yield_values2(), except you can specify how to handle the last element of the given array.
VALUE | rb_yield_splat (VALUE ary)
| Identical to rb_yield_values(), except it splats an array to generate the list of parameters.
VALUE | rb_yield_splat_kw (VALUE ary, int kw_splat)
| Identical to rb_yield_splat(), except you can specify how to handle the last element of the given array.
VALUE | rb_yield_block (RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg))
| Pass a passed block.
int | rb_keyword_given_p (void)
| Determines if the current method is given a keyword argument.
int | rb_block_given_p (void)
| Determines if the current method is given a block.
void | rb_need_block (void)
| Declares that the current method needs a block.
VALUE | rb_iterate (VALUE(*func1)(VALUE), VALUE data1, rb_block_call_func_t proc, VALUE data2)
| Old way to iterate a block.
static VALUE | ruby::backward::rb_iterate_deprecated (VALUE(*iter)(VALUE), VALUE data1, rb_block_call_func_t bl, VALUE data2)
| Old way to iterate a block.
VALUE | rb_block_call (VALUE obj, ID mid, int argc, const VALUE *argv, rb_block_call_func_t proc, VALUE data2)
| Identical to rb_funcallv(), except it additionally passes a function as a block.
VALUE | rb_block_call_kw (VALUE obj, ID mid, int argc, const VALUE *argv, rb_block_call_func_t proc, VALUE data2, int kw_splat)
| Identical to rb_funcallv_kw(), except it additionally passes a function as a block.
VALUE | rb_rescue (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*r_proc)(VALUE, VALUE), VALUE data2)
| Identical to rb_rescue2(), except it does not take a list of exception classes.
VALUE | rb_rescue2 (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*r_proc)(VALUE, VALUE), VALUE data2,...)
| An equivalent of `rescue` clause.
VALUE | rb_vrescue2 (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*r_proc)(VALUE, VALUE), VALUE data2, va_list ap)
| Identical to rb_rescue2(), except it takes `va_list` instead of variadic number of arguments.
VALUE | rb_ensure (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*e_proc)(VALUE), VALUE data2)
| An equivalent to `ensure` clause.
VALUE | rb_catch (const char *tag, rb_block_call_func_t func, VALUE data)
| Executes the passed block and catches values thrown from inside of it.
VALUE | rb_catch_obj (VALUE tag, rb_block_call_func_t func, VALUE data)
| Identical to rb_catch(), except it catches arbitrary Ruby objects.
void | rb_throw (const char *tag, VALUE val)
| Transfers control to the end of the active `catch` block waiting for `tag`.
void | rb_throw_obj (VALUE tag, VALUE val)
| Identical to rb_throw(), except it allows arbitrary Ruby object to become a tag.

## Detailed Description

Block related APIs.

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

## Macro Definition Documentation

## ◆ RB_BLOCK_CALL_FUNC_ARGLIST

#define RB_BLOCK_CALL_FUNC_ARGLIST | ( |  | yielded_arg,
|  |  | callback_arg )

Value:
VALUE yielded_arg, VALUE callback_arg, int argc, const VALUE *argv, VALUE blockarg
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

Shim for block function parameters.

Historically rb_block_call_func_t had only two parameters. Over time it evolved to have much more than that. By using this macro you can absorb such API differences.

// This works since 2.1.0
VALUE my_own_iterator(RB_BLOCK_CALL_FUNC_ARGLIST(y, c));
RB_BLOCK_CALL_FUNC_ARGLIST
#define RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)
Shim for block function parameters.
Definition iterator.h:58

Definition at line 58 of file iterator.h.

## ◆ RB_BLOCK_CALL_FUNC_STRICT

#define RB_BLOCK_CALL_FUNC_STRICT 1

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 37 of file iterator.h.

## ◆ RUBY_BLOCK_CALL_FUNC_TAKES_BLOCKARG

#define RUBY_BLOCK_CALL_FUNC_TAKES_BLOCKARG 1

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 46 of file iterator.h.

## Typedef Documentation

## ◆ rb_block_call_func

typedef VALUE rb_block_call_func(RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg))

This is the type of a function that the interpreter expect for C-backended blocks.

Blocks are often written in Ruby. But C extensions might want to have their own blocks. In order to do so authors have to create a separate C function of this type, and pass its pointer to rb_block_call().

VALUE
my_own_iterator(RB_BLOCK_CALL_FUNC_ARGLIST(y, c))
{
const auto plus = rb_intern("+");
return rb_funcall(c, plus, 1, y);
}
VALUE
my_own_method(VALUE self)
{
const auto each = rb_intern("each");
return rb_block_call(self, each, 0, 0, my_own_iterator, self);
}
rb_funcall
VALUE rb_funcall(VALUE recv, ID mid, int n,...)
Calls a method.
Definition vm_eval.c:1102
rb_intern
ID rb_intern(const char *name)
Finds or creates a symbol of the given name.
Definition symbol.c:796
rb_block_call
VALUE rb_block_call(VALUE obj, ID mid, int argc, const VALUE *argv, rb_block_call_func_t proc, VALUE data2)
Identical to rb_funcallv(), except it additionally passes a function as a block.
Definition vm_eval.c:1595

Definition at line 83 of file iterator.h.

## ◆ rb_block_call_func_t

typedef rb_block_call_func* rb_block_call_func_t

Shorthand type that represents an iterator-written-in-C function pointer.

Definition at line 88 of file iterator.h.

## Function Documentation

## ◆ rb_block_call()

VALUE rb_block_call | ( | VALUE | obj,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv,
|  | rb_block_call_func_t | proc,
|  | VALUE | data2 )

Identical to rb_funcallv(), except it additionally passes a function as a block.

When the method yields, `proc` is called with the yielded value as its first argument, and `data2` as the second. Yielded values would be packed into an array if multiple values are yielded at once.

Parameters

  [in,out] | obj | Receiver.
  [in] | mid | Method signature.
  [in] | argc | Number of arguments.
  [in] | argv | Arguments passed to `obj.mid`.
  [in] | proc | A function acts as a block.
  [in,out] | data2 | Passed to `proc` as the data2 parameter.

Returns
  What `obj.mid` returns.

Definition at line 1595 of file vm_eval.c.

## ◆ rb_block_call_kw()

VALUE rb_block_call_kw | ( | VALUE | obj,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv,
|  | rb_block_call_func_t | proc,
|  | VALUE | data2,
|  | int | kw_splat )

Identical to rb_funcallv_kw(), except it additionally passes a function as a block.

It can also be seen as a routine identical to rb_block_call(), except it handles keyword-ness of `argv[argc-1]`.

Parameters

  [in,out] | obj | Receiver.
  [in] | mid | Method signature.
  [in] | argc | Number of arguments including the keywords.
  [in] | argv | Arguments passed to `obj.mid`.
  [in] | proc | A function acts as a block.
  [in,out] | data2 | Passed to `proc` as the data2 parameter.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `argv`'s last is not a keyword argument. RB_PASS_KEYWORDS `argv`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.

Returns
  What `obj.mid` returns.

Definition at line 1602 of file vm_eval.c.

Referenced by rb_block_call(), and rb_block_call_kw().

## ◆ rb_catch()

VALUE rb_catch | ( | const char * | tag,
|  | rb_block_call_func_t | func,
|  | VALUE | data )

Executes the passed block and catches values thrown from inside of it.

In case the block does not contain any throw`, this function returns the value of the last expression evaluated.

VALUE
iter(RB_BLOCK_CALL_FUNC_ARGLIST(yielded, callback))
{
return INT2FIX(123);
}
VALUE
method(VALUE self)
{
return rb_catch("tag", iter, Qnil); // returns 123
}
INT2FIX
#define INT2FIX
Old name of RB_INT2FIX.
Definition long.h:48
Qnil
#define Qnil
Old name of RUBY_Qnil.
Definition special_consts.h:60
rb_catch
VALUE rb_catch(const char *tag, rb_block_call_func_t func, VALUE data)
Executes the passed block and catches values thrown from inside of it.
Definition vm_eval.c:2372

In case there do exist `throw`, Ruby searches up its execution context for a `catch` block. When a matching catch is found, the block stops executing and returns that thrown value instead.

VALUE
iter(RB_BLOCK_CALL_FUNC_ARGLIST(yielded, callback))
{
rb_throw("tag", 456);
return INT2FIX(123);
}
VALUE
method(VALUE self)
{
return rb_catch("tag", iter, Qnil); // returns 456
}
rb_throw
void rb_throw(const char *tag, VALUE val)
Transfers control to the end of the active catch block waiting for tag.
Definition vm_eval.c:2302

Parameters

  [in] | tag | Arbitrary tag string.
  [in] | func | Function pointer that acts as a block.
  [in,out] | data | Extra parameter passed to `func`.

Returns
  Either caught value for `tag`, or the return value of `func` if nothing is thrown.

Definition at line 2372 of file vm_eval.c.

## ◆ rb_catch_obj()

VALUE rb_catch_obj | ( | VALUE | tag,
|  | rb_block_call_func_t | func,
|  | VALUE | data )

Identical to rb_catch(), except it catches arbitrary Ruby objects.

Parameters

  [in] | tag | Arbitrary tag object.
  [in] | func | Function pointer that acts as a block.
  [in,out] | data | Extra parameter passed to `func`.

Returns
  Either caught value for `tag`, or the return value of `func` if nothing is thrown.

Definition at line 2414 of file vm_eval.c.

## ◆ rb_each()

VALUE rb_each | ( | VALUE | obj | ) |

This is a shorthand of calling `obj.each`.

Parameters

  [in] | obj | The receiver.

Returns
  What `obj.each` returns.

Definition at line 1657 of file vm_eval.c.

Referenced by rb_each().

## ◆ rb_iterate()

VALUE rb_iterate | ( | VALUE(* | func1 )(VALUE),
|  | VALUE | data1,
|  | rb_block_call_func_t | proc,
|  | VALUE | data2 )

Old way to iterate a block.

Deprecated
  This is an old API. Use rb_block_call() instead.

Warning
  The passed function must at least once call a ruby method (to handle interrupts etc.)

Parameters

  [in] | func1 | A function that could yield a value.
  [in,out] | data1 | Passed to `func1`
  [in] | proc | A function acts as a block.
  [in,out] | data2 | Passed to `proc` as the data2 parameter.

Returns
  What `func1` returns.

Definition at line 1569 of file vm_eval.c.

## ◆ rb_throw()

void rb_throw | ( | const char * | tag,
|  | VALUE | val )

Transfers control to the end of the active `catch` block waiting for `tag`.

Raises rb_eUncughtThrow if there is no `catch` block for the tag. The second parameter supplies a return value for the `catch` block, which otherwise defaults to RUBY_Qnil. For examples, see rb_catch().

Parameters

  [in] | tag | Tag string.
  [in] | val | Value to throw.

Exceptions

  rb_eUncughtThrow | There is no corresponding `catch` clause.

Note
  It never returns.

Definition at line 2302 of file vm_eval.c.

## ◆ rb_throw_obj()

void rb_throw_obj | ( | VALUE | tag,
|  | VALUE | val )

Identical to rb_throw(), except it allows arbitrary Ruby object to become a tag.

Parameters

  [in] | tag | Arbitrary object.
  [in] | val | Value to throw.

Exceptions

  rb_eUncughtThrow | There is no corresponding `catch` clause.

Note
  It never returns.

Definition at line 2277 of file vm_eval.c.

Referenced by rb_throw().

## ◆ rb_yield()

VALUE rb_yield | ( | VALUE | val | ) |

Yields the block.

In Ruby there is a concept called a block. You can pass one to a method. In a method, when called with a block, you can yield it using this function.

VALUE
iterate(VALUE self)
{
extern int get_n(VALUE);
extern VALUE get_v(VALUE, VALUE);
const auto n = get_n(self);
for (int i=0; i<n; i++) {
auto v = get_v(self, i);
rb_yield(v);
}
return self;
}
rb_yield
VALUE rb_yield(VALUE val)
Yields the block.
Definition vm_eval.c:1357

Parameters

  [in] | val | Passed to the block.

Exceptions

  rb_eLocalJumpError | There is no block given.

Returns
  Evaluated value of the given block.

Definition at line 1357 of file vm_eval.c.

Referenced by rb_ary_delete(), and rb_ary_each().

## ◆ rb_yield_block()

VALUE rb_yield_block | ( | RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg) |  | ) |

Pass a passed block.

Sometimes you want to "pass" a block form one method to another. Suppose you have this Ruby method `foo`:

def foo(x, y)
x.open(y) do |*z|
yield(*z)
end
end

And suppose you want to translate this into C. Then rb_yield_block() function is usable in this situation.

VALUE
foo_translated_into_C(VALUE self, VALUE x, VALUE y)
{
const auto open = rb_intern("open");
return rb_block_call(x, open, 1, &y, rb_yield_block, Qfalse);
// ^^^^^^^^^^^^^^ Here.
}
Qfalse
#define Qfalse
Old name of RUBY_Qfalse.
Definition special_consts.h:59
rb_yield_block
VALUE rb_yield_block(RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg))
Pass a passed block.

See also
  rb_funcall_passing_block

## ◆ rb_yield_splat()

VALUE rb_yield_splat | ( | VALUE | ary | ) |

Identical to rb_yield_values(), except it splats an array to generate the list of parameters.

Parameters

  [in] | ary | Array to splat.

Exceptions

  rb_eLocalJumpError | There is no block given.

Returns
  Evaluated value of the given block.

Definition at line 1403 of file vm_eval.c.

## ◆ rb_yield_splat_kw()

VALUE rb_yield_splat_kw | ( | VALUE | ary,
|  | int | kw_splat )

Identical to rb_yield_splat(), except you can specify how to handle the last element of the given array.

Parameters

  [in] | ary | Array to splat.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `ary`'s last is not a keyword argument. RB_PASS_KEYWORDS `ary`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS makes no sense here.

Exceptions

  rb_eLocalJumpError | There is no block given.

Returns
  Evaluated value of the given block.

Definition at line 1416 of file vm_eval.c.

## ◆ rb_yield_values()

VALUE rb_yield_values | ( | int | n,
|  |  | ... )

Identical to rb_yield(), except it takes variadic number of parameters and pass them to the block.

Parameters

  [in] | n | Number of parameters.
  [in] | ... | List of arguments passed to the block.

Exceptions

  rb_eLocalJumpError | There is no block given.

Returns
  Evaluated value of the given block.

Definition at line 1369 of file vm_eval.c.

## ◆ rb_yield_values2()

VALUE rb_yield_values2 | ( | int | n,
|  | const VALUE * | argv )

Identical to rb_yield_values(), except it takes the parameters as a C array instead of variadic arguments.

Parameters

  [in] | n | Number of parameters.
  [in] | argv | List of arguments passed to the block.

Exceptions

  rb_eLocalJumpError | There is no block given.

Returns
  Evaluated value of the given block.

Definition at line 1391 of file vm_eval.c.

## ◆ rb_yield_values_kw()

VALUE rb_yield_values_kw | ( | int | n,
|  | const VALUE * | argv,
|  | int | kw_splat )

Identical to rb_yield_values2(), except you can specify how to handle the last element of the given array.

Parameters

  [in] | n | Number of parameters.
  [in] | argv | List of arguments passed to the block.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `ary`'s last is not a keyword argument. RB_PASS_KEYWORDS `ary`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS makes no sense here.

Exceptions

  rb_eLocalJumpError | There is no block given.

Returns
  Evaluated value of the given block.

Definition at line 1397 of file vm_eval.c.