File Coverage

lib/Google/RestApi/SheetsApi4/Range/Iterator.pm
Criterion Covered Total %
statement 3 16 18.7
branch 0 4 0.0
condition 0 5 0.0
subroutine 1 6 16.6
pod 5 5 100.0
total 9 36 25.0


line stmt bran cond sub pod time code
1             package Google::RestApi::SheetsApi4::Range::Iterator;
2              
3             our $VERSION = '1.0.4';
4              
5 1     1   607 use Google::RestApi::Setup;
  1         5  
  1         18  
6              
7             sub new {
8 0     0 1   my $class = shift;
9 0           state $check = compile_named(
10             range => HasMethods[qw(range worksheet)],
11             dim => StrMatch[qr/^(col|row)$/], { default => 'row' },
12             by => PositiveInt, { default => 1 },
13             from => PositiveOrZeroInt, { optional => 1 },
14             to => PositiveOrZeroInt, { optional => 1 },
15             );
16 0           my $self = $check->(@_);
17 0   0       $self->{current} = delete $self->{from} || 0;
18 0           return bless $self, $class;
19             }
20              
21             sub iterate {
22 0     0 1   my $self = shift;
23 0 0 0       return if defined $self->{to} && $self->{current} + 1 > $self->{to};
24 0           my $cell = $self->range()->cell_at_offset($self->{current}, $self->{dim});
25 0 0         $self->{current} += $self->{by} if $cell;
26 0           return $cell;
27             }
28 0     0 1   sub next { iterate(@_); }
29              
30 0     0 1   sub range { shift->{range}; }
31 0     0 1   sub worksheet { shift->range()->worksheet(); }
32              
33             1;
34              
35             __END__
36              
37             =head1 NAME
38              
39             Google::RestApi::SheetsApi4::Range::Iterator - An iterator for an arbitrary Range.
40              
41             =head1 DESCRIPTION
42              
43             A Range::Iterator is used to iterate through a range, returning each
44             cell, one at a time.
45              
46             See the description and synopsis at Google::RestApi::SheetsApi4.
47              
48             =head1 SUBROUTINES
49              
50             =over
51              
52             =item new(range => <Range>, dim => <dimension>, by => <int>);
53              
54             Creates a new Iterator object for the given range.
55              
56             range: The Range object for which we are iterating.
57             dim: The direction of the iteration ('col' or 'row'). The default is 'row'.
58             by: The number of cells to skip between each iteration.
59              
60             'dim' is used to specify which major dimension is used for the iteration.
61             For a given range 'A1:B2', a 'dim' of 'col' will return A1, A2, B1, B2
62             for each successive iteration. For a 'dim' of 'row', it will return
63             A1, B1, A2, B2 for each successive iteration.
64              
65             'by' is used to allow you to only return, say, every second cell in the
66             iteration ('by' = '2'). For a given range 'A1:B4' and a 'by' of '2',
67             it will return A1, A3, B1, B3 for each succesive iteration.
68              
69             You would not normally call this directly, you'd use the Range::iterator
70             method to create the iterator object for you.
71              
72             =item iterate();
73              
74             Return the next cell in the iteration sequence.
75              
76             =item next();
77              
78             An alias for iterate().
79              
80             =item range();
81              
82             Returns the Range object for this iterator.
83              
84             =item worksheet();
85              
86             # Returns the Worksheet object for this iterator.
87              
88             =back
89              
90             =head1 AUTHORS
91              
92             =over
93              
94             =item
95              
96             Robin Murray mvsjes@cpan.org
97              
98             =back
99              
100             =head1 COPYRIGHT
101              
102             Copyright (c) 2021, Robin Murray. All rights reserved.
103              
104             This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.