Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Data Structures | Macros | Typedefs | Functions
enumerator.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

Public APIs related to rb_cEnumerator. More...

#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/intern/eval.h"
#include "ruby/internal/iterator.h"
#include "ruby/internal/symbol.h"
#include "ruby/internal/value.h"
Include dependency graph for enumerator.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  rb_arithmetic_sequence_components_t
 Decomposed Enumerator::ArithmeicSequence. More...
 

Macros

#define SIZED_ENUMERATOR(obj, argc, argv, size_fn)
 This is an implementation detail of RETURN_SIZED_ENUMERATOR(). More...
 
#define SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat)
 This is an implementation detail of RETURN_SIZED_ENUMERATOR_KW(). More...
 
#define RETURN_SIZED_ENUMERATOR(obj, argc, argv, size_fn)
 This roughly resembles return enum_for(__callee__) unless block_given?. More...
 
#define RETURN_SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat)
 Identical to RETURN_SIZED_ENUMERATOR(), except you can specify how to handle the last element of the given array. More...
 
#define RETURN_ENUMERATOR(obj, argc, argv)    RETURN_SIZED_ENUMERATOR(obj, argc, argv, 0)
 Identical to RETURN_SIZED_ENUMERATOR(), except its size is unknown. More...
 
#define RETURN_ENUMERATOR_KW(obj, argc, argv, kw_splat)    RETURN_SIZED_ENUMERATOR_KW(obj, argc, argv, 0, kw_splat)
 Identical to RETURN_SIZED_ENUMERATOR_KW(), except its size is unknown. More...
 

Typedefs

typedef VALUE rb_enumerator_size_func(VALUE recv, VALUE argv, VALUE eobj)
 This is the type of functions that rb_enumeratorize_with_size() expects. More...
 

Functions

VALUE rb_enumeratorize (VALUE recv, VALUE meth, int argc, const VALUE *argv)
 Constructs an enumerator. More...
 
VALUE rb_enumeratorize_with_size (VALUE recv, VALUE meth, int argc, const VALUE *argv, rb_enumerator_size_func *func)
 Identical to rb_enumeratorize(), except you can additionally specify the size function of return value. More...
 
VALUE rb_enumeratorize_with_size_kw (VALUE recv, VALUE meth, int argc, const VALUE *argv, rb_enumerator_size_func *func, int kw_splat)
 Identical to rb_enumeratorize_with_func(), except you can specify how to handle the last element of the given array. More...
 
int rb_arithmetic_sequence_extract (VALUE as, rb_arithmetic_sequence_components_t *buf)
 Extracts components of the passed arithmetic sequence. More...
 
VALUE rb_arithmetic_sequence_beg_len_step (VALUE as, long *begp, long *lenp, long *stepp, long len, int err)
 Identical to rb_range_beg_len(), except it takes an instance of Enumerator::ArithmericSequence. More...
 

Detailed Description

Public APIs related to rb_cEnumerator.

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

Macro Definition Documentation

◆ RETURN_ENUMERATOR

#define RETURN_ENUMERATOR (   obj,
  argc,
  argv 
)     RETURN_SIZED_ENUMERATOR(obj, argc, argv, 0)

Identical to RETURN_SIZED_ENUMERATOR(), except its size is unknown.

Parameters
[in]objA receiver.
[in]argcNumber of objects of argv.
[in]argvArguments passed to the current method.
Note
This macro may return inside.

Definition at line 239 of file enumerator.h.

◆ RETURN_ENUMERATOR_KW

#define RETURN_ENUMERATOR_KW (   obj,
  argc,
  argv,
  kw_splat 
)     RETURN_SIZED_ENUMERATOR_KW(obj, argc, argv, 0, kw_splat)

Identical to RETURN_SIZED_ENUMERATOR_KW(), except its size is unknown.

It can also be seen as a routine identical to RETURN_ENUMERATOR(), except you can specify how to handle the last element of the given array.

Parameters
[in]objA receiver.
[in]argcNumber of objects of argv.
[in]argvArguments passed to the current method.
[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.
Note
This macro may return inside.

Definition at line 256 of file enumerator.h.

◆ RETURN_SIZED_ENUMERATOR

#define RETURN_SIZED_ENUMERATOR (   obj,
  argc,
  argv,
  size_fn 
)
Value:
do { \
if (!rb_block_given_p()) \
return SIZED_ENUMERATOR(obj, argc, argv, size_fn); \
} while (0)
int rb_block_given_p(void)
Determines if the current method is given a block.
Definition: eval.c:916
#define SIZED_ENUMERATOR(obj, argc, argv, size_fn)
This is an implementation detail of RETURN_SIZED_ENUMERATOR().
Definition: enumerator.h:174

This roughly resembles return enum_for(__callee__) unless block_given?.

Parameters
[in]objA receiver.
[in]argcNumber of objects of argv.
[in]argvArguments passed to the current method.
[in]size_fnSize calculator.
Note
This macro may return inside.

Definition at line 206 of file enumerator.h.

◆ RETURN_SIZED_ENUMERATOR_KW

#define RETURN_SIZED_ENUMERATOR_KW (   obj,
  argc,
  argv,
  size_fn,
  kw_splat 
)
Value:
do { \
if (!rb_block_given_p()) \
return SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat); \
} while (0)
#define SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat)
This is an implementation detail of RETURN_SIZED_ENUMERATOR_KW().
Definition: enumerator.h:193

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

Parameters
[in]objA receiver.
[in]argcNumber of objects of argv.
[in]argvArguments passed to the current method.
[in]size_fnSize calculator.
[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.
Note
This macro may return inside.

Definition at line 226 of file enumerator.h.

◆ SIZED_ENUMERATOR

#define SIZED_ENUMERATOR (   obj,
  argc,
  argv,
  size_fn 
)
Value:
(argc), (argv), (size_fn))
#define ID2SYM
Old name of RB_ID2SYM.
Definition: symbol.h:44
VALUE rb_enumeratorize_with_size(VALUE recv, VALUE meth, int argc, const VALUE *argv, rb_enumerator_size_func *func)
Identical to rb_enumeratorize(), except you can additionally specify the size function of return valu...
Definition: enumerator.c:549
ID rb_frame_this_func(void)
Queries the name of the Ruby level method that is calling this function.
Definition: eval.c:1094

This is an implementation detail of RETURN_SIZED_ENUMERATOR().

You could use it directly, but can hardly be handy.

Parameters
[in]objA receiver.
[in]argcNumber of objects of argv.
[in]argvArguments passed to the current method.
[in]size_fnSize calculator.
Returns
A new instance of rb_cEnumerator which, when yielded, enumerates by calling the current method on recv with argv.

Definition at line 174 of file enumerator.h.

◆ SIZED_ENUMERATOR_KW

#define SIZED_ENUMERATOR_KW (   obj,
  argc,
  argv,
  size_fn,
  kw_splat 
)
Value:
(argc), (argv), (size_fn), (kw_splat))
VALUE rb_enumeratorize_with_size_kw(VALUE recv, VALUE meth, int argc, const VALUE *argv, rb_enumerator_size_func *func, int kw_splat)
Identical to rb_enumeratorize_with_func(), except you can specify how to handle the last element of t...
Definition: enumerator.c:533

This is an implementation detail of RETURN_SIZED_ENUMERATOR_KW().

You could use it directly, but can hardly be handy.

Parameters
[in]objA receiver.
[in]argcNumber of objects of argv.
[in]argvArguments passed to the current method.
[in]size_fnSize calculator.
[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
A new instance of rb_cEnumerator which, when yielded, enumerates by calling the current method on recv with argv.

Definition at line 193 of file enumerator.h.

Typedef Documentation

◆ rb_enumerator_size_func

typedef VALUE rb_enumerator_size_func(VALUE recv, VALUE argv, VALUE eobj)

This is the type of functions that rb_enumeratorize_with_size() expects.

In theory an enumerator can have indefinite number of elements, but in practice it often is the case we can compute the size of an enumerator beforehand. If your enumerator has such property, supply a function that calculates such values.

Parameters
[in]recvThe original receiver of the enumerator.
[in]argvArguments passed to Object#enum_for etc.
[in]eobjThe enumerator object.
Returns
The size of eobj, in rb_cNumeric, or RUBY_Qnil if the size is not known until we actually iterate.

Definition at line 45 of file enumerator.h.

Function Documentation

◆ rb_arithmetic_sequence_beg_len_step()

VALUE rb_arithmetic_sequence_beg_len_step ( VALUE  as,
long *  begp,
long *  lenp,
long *  stepp,
long  len,
int  err 
)

Identical to rb_range_beg_len(), except it takes an instance of Enumerator::ArithmericSequence.

Parameters
[in]asAn Enumerator::ArithmericSequence instance.
[out]begpReturn value buffer.
[out]lenpReturn value buffer.
[out]steppReturn value buffer.
[in]lenUpdated length.
[in]errIn case len is out of range...
Exceptions
rb_eRangeErroras cannot fit into long.
Return values
RUBY_Qfalseas is not Enumerator::ArithmericSequence.
RUBY_Qnillen is out of as but err is zero.
RUBY_QtrueOtherwise.
Postcondition
beg is the (possibly updated) left endpoint.
len is the (possibly updated) length of the range.

Definition at line 3848 of file enumerator.c.

◆ rb_arithmetic_sequence_extract()

int rb_arithmetic_sequence_extract ( VALUE  as,
rb_arithmetic_sequence_components_t buf 
)

Extracts components of the passed arithmetic sequence.

This can be seen as an extended version of rb_range_values().

Parameters
[in]asTarget instance of Enumerator::ArithmericSequence.
[out]bufDecomposed results buffer.
Returns
0 as is not Enumerator::ArithmericSequence.
1 Success.
Postcondition
buf is filled.

Definition at line 3830 of file enumerator.c.

◆ rb_enumeratorize()

VALUE rb_enumeratorize ( VALUE  recv,
VALUE  meth,
int  argc,
const VALUE argv 
)

Constructs an enumerator.

This roughly resembles Object#enum_for.

Parameters
[in]recvA receiver of meth.
[in]methMethod ID in a symbol object.
[in]argcNumber of objects of argv.
[in]argvArguments passed to meth.
Exceptions
rb_eTypeErrormeth is not an instance of rb_cSymbol.
Returns
A new instance of rb_cEnumerator which, when yielded, enumerates by calling meth on recv with argv.

Definition at line 524 of file enumerator.c.

◆ rb_enumeratorize_with_size()

VALUE rb_enumeratorize_with_size ( VALUE  recv,
VALUE  meth,
int  argc,
const VALUE argv,
rb_enumerator_size_func func 
)

Identical to rb_enumeratorize(), except you can additionally specify the size function of return value.

Parameters
[in]recvA receiver of meth.
[in]methMethod ID in a symbol object.
[in]argcNumber of objects of argv.
[in]argvArguments passed to meth.
[in]funcSize calculator.
Exceptions
rb_eTypeErrormeth is not an instance of rb_cSymbol.
Returns
A new instance of rb_cEnumerator which, when yielded, enumerates by calling meth on recv with argv.
Note
func can be zero, which means the size is unknown.

Definition at line 549 of file enumerator.c.

Referenced by rb_enumeratorize().

◆ rb_enumeratorize_with_size_kw()

VALUE rb_enumeratorize_with_size_kw ( VALUE  recv,
VALUE  meth,
int  argc,
const VALUE argv,
rb_enumerator_size_func func,
int  kw_splat 
)

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

Parameters
[in]recvA receiver of meth.
[in]methMethod ID in a symbol object.
[in]argcNumber of objects of argv.
[in]argvArguments passed to meth.
[in]funcSize calculator.
[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.
Exceptions
rb_eTypeErrormeth is not an instance of rb_cSymbol.
Returns
A new instance of rb_cEnumerator which, when yielded, enumerates by calling meth on recv with argv.
Note
func can be zero, which means the size is unknown.

Definition at line 533 of file enumerator.c.

Referenced by rb_enumeratorize_with_size().