Return to HashIterator.pm CVS log

Up to [LON-CAPA] / loncom

Module to support object based iteration through a hash.  Missed adding this to the
CVS repository on the initial commits associated with loncnew.

    1: #  Implement iteration over a opaque hash.
    2: #
    3: # $Id: HashIterator.pm,v 1.1 2003/09/15 09:20:39 foxr 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: use strict;
   64: package HashIterator;
   65: 
   66: =pod
   67: 
   68: =head2 new(hash)
   69: 
   70: Create a new HashIterator object and return a reference to it.  Data
   71: members of the HashIterator include:
   72: 
   73: =over 4
   74: 
   75: =item Hash
   76: 
   77: Reference to the hash being iterated over.
   78: 
   79: =item Keylist
   80: 
   81: The set of keys in the underlying hash (an anonymous array ref).
   82: 
   83: =item KeyCount
   84: 
   85: The number of keys in the underlying hash.
   86: 
   87: =item Index
   88: 
   89: Position of the iterator within the keylist/hash table.
   90: 
   91: =back
   92: 
   93: =cut
   94: 
   95: sub new {
   96:     my $class   = shift;	# Class name...
   97:     my $hashref = shift;        # Maintain this hash.
   98:     my @keylist = keys(%$hashref);
   99:     my $keyref= \@keylist;
  100:     my $keycount = scalar @keylist;
  101: 
  102: 
  103:     my $self    = {  Hash      => $hashref,
  104: 		     Keylist      => $keyref,
  105: 		     KeyCount     => $keycount,
  106: 		     Index        => 0};
  107:     bless($self, $class);	# Type ourself...
  108: 
  109:     return $self;
  110: 		  
  111: }
  112: 
  113: =pod
  114: 
  115: =head2 begin
  116: 
  117: Reset the iterator to the start of iteration.
  118: 
  119: =cut
  120: 
  121: sub begin {
  122:     my $self  = shift;		# Get object...
  123:     $self->{Index} = 0;
  124:   
  125: }
  126: 
  127: =pod
  128: 
  129: =head2 end
  130: 
  131: Return true if the iterator is off the end of the hash.
  132: 
  133: =cut
  134: 
  135: sub end {
  136:     my $self = shift;		# Retrieve self as object.
  137:     return ($self->{Index}  >= $self->{KeyCount});
  138: }
  139: 
  140: =pod
  141: 
  142: =head2 get
  143: 
  144: Return the contents of the hash at the current key.  If the key is off
  145: the end of the hash, undef is returned.  What is returned is a copy of
  146: the element.  If the index is off the end of the iteration, undef is
  147: returned.
  148: 
  149: =cut
  150: 
  151: sub get {
  152:     my $self = shift;
  153:     if ($self->end()) {
  154: 	return undef;
  155:     }
  156:     my $hashref = $self->{Hash};
  157:     my $key     = $self->{Keylist}->[$self->{Index}];
  158:     return $$hashref{$key};
  159: }
  160: 
  161: =pod
  162: 
  163: =head2 next
  164: 
  165: Advances the iterator.
  166: 
  167: =cut
  168: 
  169: sub next {
  170:     my $self = shift;		# Get us.
  171:     $self->{Index}  = $self->{Index} + 1;
  172: }
  173: 
  174: 1;