Return to HashIterator.pm CVS log

Up to [LON-CAPA] / loncom / types

- adding GNU GPL header

    1: #  Implement iteration over a opaque hash.
    2: #
    3: # $Id: HashIterator.pm,v 1.2 2003/04/18 06:10:47 albertel 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.
   13: #
   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/
   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;