lib/DBM/Deep/Iterator/Index.pm

   1 package DBM::Deep::Iterator::Index;
   2
   3 use 5.006_000;
   4
   5 use strict;
   6 use warnings FATAL => 'all';
   7
   8 =head1 NAME
   9
  10 DBM::Deep::Iterator::Index
  11
  12 =head1 PURPOSE
  13
  14 This is an internal-use-only object for L<DBM::Deep/>. It acts as the mediator
  15 between the L<DBM::Deep::Iterator/> object and a L<DBM::Deep::Engine::Sector::Index/>
  16 sector.
  17
  18 =head1 OVERVIEW
  19
  20 This object, despite the implied class hiearchy, does B<NOT> inherit from
  21 L<DBM::Deep::Iterator/>. Instead, it delegates to it, essentially acting as a
  22 facade over it. L<DBM::Deep::Iterator/get_next_key> will instantiate one of
  23 these objects as needed to handle an Index sector.
  24
  25 =head1 METHODS
  26
  27 =head2 new(\%params)
  28
  29 The constructor takes a hashref of params and blesses it into the invoking class. The
  30 hashref is assumed to have the following elements:
  31
  32 =over 4
  33
  34 =item * iterator (of type L<DBM::Deep::Iterator/>
  35
  36 =item * sector (of type L<DBM::Deep::Engine::Sector::Index/>
  37
  38 =back
  39
  40 =cut
  41
  42 sub new {
  43     my $self = bless $_[1] => $_[0];
  44     $self->{curr_index} = 0;
  45     return $self;
  46 }
  47
  48 =head2 at_end()
  49
  50 This takes no arguments.
  51
  52 This returns true/false indicating whether this sector has any more elements that can be
  53 iterated over.
  54
  55 =cut
  56
  57 sub at_end {
  58     my $self = shift;
  59     return $self->{curr_index} >= $self->{iterator}{engine}->hash_chars;
  60 }
  61
  62 =head2 get_next_iterator()
  63
  64 This takes no arguments.
  65
  66 This returns an iterator (built by L<DBM::Deep::Iterator/get_sector_iterator>) based
  67 on the sector pointed to by the next occupied location in this index.
  68
  69 If the sector is exhausted, it returns nothing.
  70
  71 =cut
  72
  73 sub get_next_iterator {
  74     my $self = shift;
  75
  76     my $loc;
  77     while ( !$loc ) {
  78         return if $self->at_end;
  79         $loc = $self->{sector}->get_entry( $self->{curr_index}++ );
  80     }
  81
  82     return $self->{iterator}->get_sector_iterator( $loc );
  83 }
  84
  85 1;
  86 __END__