Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Namespaces | Macros | Typedefs | Functions
iterator.h File Reference

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

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"
Include dependency graph for iterator.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces

 ruby
 The main 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)    VALUE yielded_arg, VALUE callback_arg, int argc, const VALUE *argv, VALUE blockarg
 Shim for block function parameters. More...
 

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. More...
 
typedef rb_block_call_funcrb_block_call_func_t
 Shorthand type that represents an iterator-written-in-C function pointer. More...
 

Functions

VALUE rb_each (VALUE obj)
 This is a shorthand of calling obj.each. More...
 
VALUE rb_yield (VALUE val)
 Yields the block. More...
 
VALUE rb_yield_values (int n,...)
 Identical to rb_yield(), except it takes variadic number of parameters and pass them to the block. More...
 
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. More...
 
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. More...
 
VALUE rb_yield_splat (VALUE ary)
 Identical to rb_yield_values(), except it splats an array to generate the list of parameters. More...
 
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. More...
 
VALUE rb_yield_block (RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg))
 Pass a passed block. More...
 
int rb_keyword_given_p (void)
 Determines if the current method is given a keyword argument. More...
 
int rb_block_given_p (void)
 Determines if the current method is given a block. More...
 
void rb_need_block (void)
 Declares that the current method needs a block. More...
 
VALUE rb_iterate (VALUE(*func1)(VALUE), VALUE data1, rb_block_call_func_t proc, VALUE data2)
 Old way to iterate a block. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
VALUE rb_rescue2 (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*r_proc)(VALUE, VALUE), VALUE data2,...)
 An equivalent of rescue clause. More...
 
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. More...
 
VALUE rb_ensure (VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*e_proc)(VALUE), VALUE data2)
 An equivalent to ensure clause. More...
 
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. More...
 
VALUE rb_catch_obj (VALUE tag, rb_block_call_func_t func, VALUE data)
 Identical to rb_catch(), except it catches arbitrary Ruby objects. More...
 
void rb_throw (const char *tag, VALUE val)
 Transfers control to the end of the active catch block waiting for tag. More...
 
void rb_throw_obj (VALUE tag, VALUE val)
 Identical to rb_throw(), except it allows arbitrary Ruby object to become a tag. More...
 

Detailed Description

Block related APIs.

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

Macro Definition Documentation

◆ RB_BLOCK_CALL_FUNC_ARGLIST

#define RB_BLOCK_CALL_FUNC_ARGLIST (   yielded_arg,
  callback_arg 
)     VALUE yielded_arg, VALUE callback_arg, int argc, const VALUE *argv, VALUE blockarg

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));
#define RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)
Shim for block function parameters.
Definition: iterator.h:58
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40

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().

my_own_iterator(RB_BLOCK_CALL_FUNC_ARGLIST(y, c))
{
const auto plus = rb_intern("+");
return rb_funcall(c, plus, 1, y);
}
my_own_method(VALUE self)
{
const auto each = rb_intern("each");
return rb_block_call(self, each, 0, 0, my_own_iterator, self);
}
VALUE rb_funcall(VALUE recv, ID mid, int n,...)
Calls a method.
Definition: vm_eval.c:1099
ID rb_intern(const char *name)
Finds or creates a symbol of the given name.
Definition: symbol.c:823
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:1534

Definition at line 83 of file iterator.h.

◆ 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]objReceiver.
[in]midMethod signature.
[in]argcNumber of arguments.
[in]argvArguments passed to obj.mid.
[in]procA function acts as a block.
[in,out]data2Passed to proc as the data2 parameter.
Returns
What obj.mid returns.

Definition at line 1534 of file vm_eval.c.

Referenced by ruby::backward::cxxanyargs::rb_block_call(), and rb_proc_new().

◆ 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]objReceiver.
[in]midMethod signature.
[in]argcNumber of arguments including the keywords.
[in]argvArguments passed to obj.mid.
[in]procA function acts as a block.
[in,out]data2Passed to proc as the data2 parameter.
[in]kw_splatHandling 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 1541 of file vm_eval.c.

Referenced by rb_block_call().

◆ 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.

iter(RB_BLOCK_CALL_FUNC_ARGLIST(yielded, callback))
{
return INT2FIX(123);
}
method(VALUE self)
{
return rb_catch("tag", iter, Qnil); // returns 123
}
#define INT2FIX
Old name of RB_INT2FIX.
Definition: long.h:48
#define Qnil
Old name of RUBY_Qnil.
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:2497

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.

iter(RB_BLOCK_CALL_FUNC_ARGLIST(yielded, callback))
{
rb_throw("tag", 456);
return INT2FIX(123);
}
method(VALUE self)
{
return rb_catch("tag", iter, Qnil); // returns 456
}
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:2427
Parameters
[in]tagArbitrary tag string.
[in]funcFunction pointer that acts as a block.
[in,out]dataExtra parameter passed to func.
Returns
Either caught value for tag, or the return value of func if nothing is thrown.

Definition at line 2497 of file vm_eval.c.

Referenced by ruby::backward::cxxanyargs::rb_catch().

◆ 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]tagArbitrary tag object.
[in]funcFunction pointer that acts as a block.
[in,out]dataExtra parameter passed to func.
Returns
Either caught value for tag, or the return value of func if nothing is thrown.

Definition at line 2539 of file vm_eval.c.

Referenced by ruby::backward::cxxanyargs::rb_catch_obj().

◆ rb_each()

VALUE rb_each ( VALUE  obj)

This is a shorthand of calling obj.each.

Parameters
[in]objThe receiver.
Returns
What obj.each returns.

Definition at line 1627 of file vm_eval.c.

◆ rb_iterate()

VALUE rb_iterate ( VALUE(*)(VALUE func1,
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]func1A function that could yield a value.
[in,out]data1Passed to func1
[in]procA function acts as a block.
[in,out]data2Passed to proc as the data2 parameter.
Returns
What func1 returns.

Definition at line 1508 of file vm_eval.c.

Referenced by ruby::backward::rb_iterate_deprecated().

◆ 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]tagTag string.
[in]valValue to throw.
Exceptions
rb_eUncughtThrowThere is no corresponding catch clause.
Note
It never returns.

Definition at line 2427 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]tagArbitrary object.
[in]valValue to throw.
Exceptions
rb_eUncughtThrowThere is no corresponding catch clause.
Note
It never returns.

Definition at line 2402 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.

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);
}
return self;
}
VALUE rb_yield(VALUE val)
Yields the block.
Definition: vm_eval.c:1354
Parameters
[in]valPassed to the block.
Exceptions
rb_eLocalJumpErrorThere is no block given.
Returns
Evaluated value of the given block.

Definition at line 1354 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.

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.
}
#define Qfalse
Old name of RUBY_Qfalse.
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]aryArray to splat.
Exceptions
rb_eLocalJumpErrorThere is no block given.
Returns
Evaluated value of the given block.

Definition at line 1400 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]aryArray to splat.
[in]kw_splatHandling 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_eLocalJumpErrorThere is no block given.
Returns
Evaluated value of the given block.

Definition at line 1413 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]nNumber of parameters.
[in]...List of arguments passed to the block.
Exceptions
rb_eLocalJumpErrorThere is no block given.
Returns
Evaluated value of the given block.

Definition at line 1366 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]nNumber of parameters.
[in]argvList of arguments passed to the block.
Exceptions
rb_eLocalJumpErrorThere is no block given.
Returns
Evaluated value of the given block.

Definition at line 1388 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]nNumber of parameters.
[in]argvList of arguments passed to the block.
[in]kw_splatHandling 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_eLocalJumpErrorThere is no block given.
Returns
Evaluated value of the given block.

Definition at line 1394 of file vm_eval.c.