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

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

Data Structures | Macros | Typedefs | Functions
enumerator.h File Reference

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"`

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().
#define | SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat)
| This is an implementation detail of RETURN_SIZED_ENUMERATOR_KW().
#define | RETURN_SIZED_ENUMERATOR(obj, argc, argv, size_fn)
| This roughly resembles `return enum_for(__callee__) unless block_given?`.
#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.
#define | RETURN_ENUMERATOR(obj, argc, argv)
| Identical to RETURN_SIZED_ENUMERATOR(), except its size is unknown.
#define | RETURN_ENUMERATOR_KW(obj, argc, argv, kw_splat)
| Identical to RETURN_SIZED_ENUMERATOR_KW(), except its size is unknown.

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

## Functions
VALUE | rb_enumeratorize (VALUE recv, VALUE meth, int argc, const VALUE *argv)
| Constructs an enumerator.
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.
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.
int | rb_arithmetic_sequence_extract (VALUE as, rb_arithmetic_sequence_components_t *buf)
| Extracts components of the passed arithmetic sequence.
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`.

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

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

## Macro Definition Documentation

## ◆ RETURN_ENUMERATOR

#define RETURN_ENUMERATOR | ( |  | obj,
|  |  | argc,
|  |  | argv )

Value:
RETURN_SIZED_ENUMERATOR(obj, argc, argv, 0)
RETURN_SIZED_ENUMERATOR
#define RETURN_SIZED_ENUMERATOR(obj, argc, argv, size_fn)
This roughly resembles return enum_for(__callee__) unless block_given?.
Definition enumerator.h:206

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

Parameters

  [in] | obj | A receiver.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments 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 )

Value:
RETURN_SIZED_ENUMERATOR_KW(obj, argc, argv, 0, kw_splat)
RETURN_SIZED_ENUMERATOR_KW
#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 ...
Definition enumerator.h:226

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] | obj | A receiver.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments passed to the current method.
  [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.

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)
rb_block_given_p
int rb_block_given_p(void)
Determines if the current method is given a block.
Definition eval.c:868
SIZED_ENUMERATOR
#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] | obj | A receiver.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments passed to the current method.
  [in] | size_fn | Size calculator.

Note
  This macro may return inside.

Definition at line 206 of file enumerator.h.

Referenced by rb_ary_each(), and rb_hash_delete_if().

## ◆ 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)
SIZED_ENUMERATOR_KW
#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] | obj | A receiver.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments passed to the current method.
  [in] | size_fn | Size calculator.
  [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.

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:
rb_enumeratorize_with_size((obj), ID2SYM(rb_frame_this_func()), \
(argc), (argv), (size_fn))
ID2SYM
#define ID2SYM
Old name of RB_ID2SYM.
Definition symbol.h:44
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 valu...
Definition enumerator.c:579

This is an implementation detail of RETURN_SIZED_ENUMERATOR().

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

Parameters

  [in] | obj | A receiver.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments passed to the current method.
  [in] | size_fn | Size 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:
rb_enumeratorize_with_size_kw((obj), ID2SYM(rb_frame_this_func()), \
(argc), (argv), (size_fn), (kw_splat))
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 t...
Definition enumerator.c:563

This is an implementation detail of RETURN_SIZED_ENUMERATOR_KW().

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

Parameters

  [in] | obj | A receiver.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments passed to the current method.
  [in] | size_fn | Size calculator.
  [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
  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] | recv | The original receiver of the enumerator.
  [in] | argv | Arguments passed to `Object#enum_for` etc.
  [in] | eobj | The 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] | as | An `Enumerator::ArithmericSequence` instance.
  [out] | begp | Return value buffer.
  [out] | lenp | Return value buffer.
  [out] | stepp | Return value buffer.
  [in] | len | Updated length.
  [in] | err | In case `len` is out of range... `0`: returns RUBY_Qnil. `1`: raises rb_eRangeError. `2`: `beg` and `len` expanded accordingly.

Exceptions

  rb_eRangeError | `as` cannot fit into `long`.

Return values

  RUBY_Qfalse | `as` is not `Enumerator::ArithmericSequence`.
  RUBY_Qnil | `len` is out of `as` but `err` is zero.
  RUBY_Qtrue | Otherwise.

Postcondition
  `beg` is the (possibly updated) left endpoint.
  `len` is the (possibly updated) length of the range.

Definition at line 3870 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] | as | Target instance of `Enumerator::ArithmericSequence`.
  [out] | buf | Decomposed results buffer.

Returns
  0 `as` is not `Enumerator::ArithmericSequence`.
  1 Success.

Postcondition
  `buf` is filled.

Definition at line 3852 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] | recv | A receiver of `meth`.
  [in] | meth | Method ID in a symbol object.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments passed to `meth`.

Exceptions

  rb_eTypeError | `meth` 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 554 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] | recv | A receiver of `meth`.
  [in] | meth | Method ID in a symbol object.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments passed to `meth`.
  [in] | func | Size calculator.

Exceptions

  rb_eTypeError | `meth` 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 579 of file enumerator.c.

## ◆ 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] | recv | A receiver of `meth`.
  [in] | meth | Method ID in a symbol object.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Arguments passed to `meth`.
  [in] | func | Size calculator.
  [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.

Exceptions

  rb_eTypeError | `meth` 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 563 of file enumerator.c.