Return to HashIterator.pm CVS log

Up to [LON-CAPA] / loncom / types

Annotation of loncom/types/HashIterator.pm, revision 1.2

1.2     ! albertel    1: #  Implement iteration over a opaque hash.
        !             2: #
        !             3: # $Id: gplheader.pl,v 1.1 2001/11/29 18:19:27 www Exp $
        !             4: #
        !             5: # Copyright Michigan State University Board of Trustees
        !             6: #
        !             7: # This file is part of the LearningOnline Network with CAPA (LON-CAPA).
        !             8: #
        !             9: # LON-CAPA is free software; you can redistribute it and/or modify
        !            10: # it under the terms of the GNU General Public License as published by
        !            11: # the Free Software Foundation; either version 2 of the License, or
        !            12: # (at your option) any later version.
1.1       foxr       13: #
1.2     ! albertel   14: # LON-CAPA is distributed in the hope that it will be useful,
        !            15: # but WITHOUT ANY WARRANTY; without even the implied warranty of
        !            16: # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        !            17: # GNU General Public License for more details.
        !            18: #
        !            19: # You should have received a copy of the GNU General Public License
        !            20: # along with LON-CAPA; if not, write to the Free Software
        !            21: # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
        !            22: #
        !            23: # /home/httpd/html/adm/gpl.txt
        !            24: #
        !            25: # http://www.lon-capa.org/
1.1       foxr       26: #
                     27: 
                     28: =pod
                     29: 
                     30: =head1 HashIterator
                     31: 
                     32: A hash iterator is an object that alows iteration over a hash in a
                     33: manner analagous to the way that STL iterators allow iteration over
                     34: those containers.  The HashIterator has the effect of hiding the
                     35: existence of the hash from the caller and instead presenting an
                     36: iteratable collection to the caller.
                     37: 
                     38: The intent is for a hash iterator to be an object returned by another
                     39: object or class to support iteration over some internal hash
                     40: maintained by the object. Passing the hash itself back breaks data
                     41: hiding and protection.
                     42: 
                     43: =head1 Typical usage:
                     44: 
                     45:     use HashIterator;
                     46: ...
                     47: 
                     48:     $i = HashIterator::new(\%myhash);
                     49: 
                     50: ...
                     51: 
                     52:     $i->begin();
                     53:     while(! $i->end()) {
                     54: 	$itemref = $i->get();
                     55: 	$i->next();
                     56:     }
                     57: 
                     58: 
                     59: =head1 Member Functions:
                     60: 
                     61: =cut
                     62: 
                     63: package HashIterator;
                     64: 
                     65: =pod
                     66: 
                     67: =head2 new(hash)
                     68: 
                     69: Create a new HashIterator object and return a reference to it.  Data
                     70: members of the HashIterator include:
                     71: 
                     72: =over 4
                     73: 
                     74: =item Hash
                     75: 
                     76: Reference to the hash being iterated over.
                     77: 
                     78: =item Keylist
                     79: 
                     80: The set of keys in the underlying hash (an anonymous array ref).
                     81: 
                     82: =item KeyCount
                     83: 
                     84: The number of keys in the underlying hash.
                     85: 
                     86: =item Index
                     87: 
                     88: Position of the iterator within the keylist/hash table.
                     89: 
                     90: =back
                     91: 
                     92: =cut
                     93: 
                     94: sub new {
                     95:     my $class   = shift;	# Class name...
                     96:     my $hashref = shift;        # Maintain this hash.
                     97:     my @keylist = keys(%$hashref);
                     98:     my $keyref= \@keylist;
                     99:     my $keycount = scalar @keylist;
                    100: 
                    101: 
                    102:     my $self    = {  Hash      => $hashref,
                    103: 		     Keylist      => $keyref,
                    104: 		     KeyCount     => $keycount,
                    105: 		     Index        => 0};
                    106:     bless($self, $class);	# Type ourself...
                    107: 
                    108:     return $self;
                    109: 		  
                    110: }
                    111: 
                    112: =pod
                    113: 
                    114: =head2 begin
                    115: 
                    116: Reset the iterator to the start of iteration.
                    117: 
                    118: =cut
                    119: 
                    120: sub begin {
                    121:     my $self  = shift;		# Get object...
                    122:     $self->{Index} = 0;
                    123:   
                    124: }
                    125: 
                    126: =pod
                    127: 
                    128: =head2 end
                    129: 
                    130: Return true if the iterator is off the end of the hash.
                    131: 
                    132: =cut
                    133: 
                    134: sub end {
                    135:     my $self = shift;		# Retrieve self as object.
                    136:     return ($self->{Index}  >= $self->{KeyCount});
                    137: }
                    138: 
                    139: =pod
                    140: 
                    141: =head2 get
                    142: 
                    143: Return the contents of the hash at the current key.  If the key is off
                    144: the end of the hash, undef is returned.  What is returned is a copy of
                    145: the element.  If the index is off the end of the iteration, undef is
                    146: returned.
                    147: 
                    148: =cut
                    149: 
                    150: sub get {
                    151:     my $self = shift;
                    152:     if ($self->end()) {
                    153: 	return undef;
                    154:     }
                    155:     my $hashref = $self->{Hash};
                    156:     my $key     = $self->{Keylist}->[$self->{Index}];
                    157:     return $$hashref{$key};
                    158: }
                    159: 
                    160: =pod
                    161: 
                    162: =head2 next
                    163: 
                    164: Advances the iterator.
                    165: 
                    166: =cut
                    167: 
                    168: sub next {
                    169:     my $self = shift;		# Get us.
                    170:     $self->{Index}  = $self->{Index} + 1;
                    171: }
                    172: 
                    173: 1;