Return to HashIterator.pm CVS log

Up to [LON-CAPA] / loncom

Annotation of loncom/HashIterator.pm, revision 1.1

1.1     ! foxr        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: 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;