---
name: "DR::Tarantool::Iterator"
section: "3pm"
platform: "linux"
package: "libdr-tarantool-perl"
version: "0.45-2+b2"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/DR::Tarantool::Iterator"
---

# DR::Tarantool::Iterator(3pm)

an iterator and a container class for DR::Tarantool

## NAME

DR::Tarantool::Iterator - an iterator and a container class for DR::Tarantool

## SYNOPSIS

```
    use DR::Tarantool::Iterator;
    my $iter = DR::Tarantool::Iterator->new([1, 2, 3]);
    my $item0 = $iter->item(0);
    my @all = $iter->all;
    my $all = $iter->all;
    while(my $item = $iter->next) {
        do_something_with_item( $item );
    }
```

## METHODS

### new

A constructor.

*Arguments*

- •

  An array of tuples to iterate over.

- •

  A list of named arguments:

  - item\_class

    Name of the class to bless each tuple in the iterator with. If the field is '**ARRAYREF**' then the first element of the array is **item\_class**, and the second element is **item\_constructor**.

  - item\_constructor

    Name of a constructor to invoke for each tuple. If this value is undefined and **item\_class** is defined, the iterator blesses each tuple but does not invoke a constructor on it.

    The constructor is invoked on with three arguments: **item**, **item\_index** and **iterator**, for example:

    ```
        my $iter = DR::Tarantool::Iterator->new(
            [ [1], [2], [3] ],
            item_class => 'MyClass',
            item_constructor => 'new'
        );
        my $iter = DR::Tarantool::Iterator->new(    # the same
            [ [1], [2], [3] ],
            item_class => [ 'MyClass', 'new' ]
        );
        my $item = $iter->item(0);
        my $item = MyClass->new( [1], 0, $iter );  # the same
        my $item = $iter->item(2);
        my $item = MyClass->new( [3], 2, $iter );  # the same
    ```

  - data

    Application state to store in the iterator. Is useful if additional state needs to be passed into tuple constructor.

### clone(%opt)

Clone the iterator object, but do not clone the tuples. This method can be used to create an iterator that has a different **item\_class** and (or) **item\_constructor**.

If **clone\_items** argument is true, the function clones the  tuple list as well.

```
    my $iter1 = $old_iter->clone(item_class => [ 'MyClass', 'new' ]);
    my $iter2 = $old_iter->clone(item_class => [ 'MyClass', 'new' ],
        clone_items => 1);
    $old_iter->sort(sub { $_[0]->name cmp $_[1]->name });
    # $iter1 is sorted, too, but $iter2 is not
```

### count

Return the number of tuples available through the iterator.

### item

Return one tuple from the iterator by its index  (or croak an error if the index is out of range).

### raw\_item

Return one raw tuple from the iterator by its index  (or croak error if the index is out of range).

In other words, this method ignores **item\_class** and **item\_constructor**.

### raw\_sort(&)

Sort the contents referred to by the iterator (changes the current  iterator object). The compare function receives two **raw** objects:

```
    $iter->raw_sort(sub { $_[0]->field cmp $_[1]->field });
```

### sort(&)

Sort the contents referred to by the iterator (changes the current object). The compare function receives two constructed objects:

```
    $iter->sort(sub { $_[0]->field <=> $_[1]->field });
```

### grep(&)

Find all objects in the set referred to by the iterator that match a given search criteria (linear search).

```
    my $admins = $users->grep(sub { $_[0]->is_admin });
```

### raw\_grep(&)

Same as grep, but works on raw objects.

```
    my $admins = $users->raw_grep(sub { $_[0]->is_admin });
```

### get

An alias for item method.

### exists

Return **true** if the iterator contains a tuple with the given index.

```
    my $item = $iter->exists(10) ? $iter->get(10) : somethig_else();
```

### next

Return the next tuple, or **undef** in case of eof.

```
    while(my $item = $iter->next) {
        do_something_with( $item );
    }
```

Index of the current tuple can be queried with function 'iter'.

### iter

Return index of the tuple at the current iterator position.

### reset

Reset iteration index, return the previous value of the index.

### all

Return all tuples available through the iterator.

```
    my @list = $iter->all;
    my $list_aref = $iter->all;
    my @abc_list = map { $_->abc } $iter->all;
    my @abc_list = $iter->all('abc');               # the same
    my @list = map { [ $_->abc, $_->cde ] } $iter->all;
    my @list = $iter->all('abc', 'cde');                # the same
    my @list = map { $_->abc + $_->cde } $iter->all;
    my @list = $iter->all(sub { $_[0]->abc + $_->cde }); # the same
```

### item\_class

Set/return the tuple class. If the value is defined, the iterator blesses tuples with it (and also calls item\_constructor if it is set).

### item\_constructor

Set/return the tuple constructor. The value is used only if item\_class is defined.

### push

Push a tuple into the iterator.

### data

Return/set an application-specific context maintained in the iterator object. This can be useful to pass additional state to **item\_constructor**.