iterator.h File Reference

(37a72b0150ec36b4ea27175039afc28c62207b0c)

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_func *	rb_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

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 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));

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);
}

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

VALUE
iter(RB_BLOCK_CALL_FUNC_ARGLIST(yielded, callback))
{
    return INT2FIX(123);
}
 
VALUE
method(VALUE self)
{
    return rb_catch("tag", iter, Qnil); // returns 123
}

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
}

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 2505 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]	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 2547 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]

obj

The 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]	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 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]	tag	Tag string.
[in]	val	Value to throw.

Exceptions

rb_eUncughtThrow

There is no corresponding catch clause.

Note

It never returns.

Definition at line 2435 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 2410 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;
}

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

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

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 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]	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 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]	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 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]	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 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]	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 1394 of file vm_eval.c.