Return to HashIterator.pm CVS log

Up to [LON-CAPA] / loncom / types

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

1.1     ! foxr        1: #
        !             2: #  Implement iteration over a opaque hash.
        !             3: #
        !             4: 
        !             5: =pod
        !             6: 
        !             7: =head1 HashIterator
        !             8: 
        !             9: A hash iterator is an object that alows iteration over a hash in a
        !            10: manner analagous to the way that STL iterators allow iteration over
        !            11: those containers.  The HashIterator has the effect of hiding the
        !            12: existence of the hash from the caller and instead presenting an
        !            13: iteratable collection to the caller.
        !            14: 
        !            15: The intent is for a hash iterator to be an object returned by another
        !            16: object or class to support iteration over some internal hash
        !            17: maintained by the object. Passing the hash itself back breaks data
        !            18: hiding and protection.
        !            19: 
        !            20: =head1 Typical usage:
        !            21: 
        !            22:     use HashIterator;
        !            23: ...
        !            24: 
        !            25:     $i = HashIterator::new(\%myhash);
        !            26: 
        !            27: ...
        !            28: 
        !            29:     $i->begin();
        !            30:     while(! $i->end()) {
        !            31: 	$itemref = $i->get();
        !            32: 	$i->next();
        !            33:     }
        !            34: 
        !            35: 
        !            36: =head1 Member Functions:
        !            37: 
        !            38: =cut
        !            39: 
        !            40: package HashIterator;
        !            41: 
        !            42: =pod
        !            43: 
        !            44: =head2 new(hash)
        !            45: 
        !            46: Create a new HashIterator object and return a reference to it.  Data
        !            47: members of the HashIterator include:
        !            48: 
        !            49: =over 4
        !            50: 
        !            51: =item Hash
        !            52: 
        !            53: Reference to the hash being iterated over.
        !            54: 
        !            55: =item Keylist
        !            56: 
        !            57: The set of keys in the underlying hash (an anonymous array ref).
        !            58: 
        !            59: =item KeyCount
        !            60: 
        !            61: The number of keys in the underlying hash.
        !            62: 
        !            63: =item Index
        !            64: 
        !            65: Position of the iterator within the keylist/hash table.
        !            66: 
        !            67: =back
        !            68: 
        !            69: =cut
        !            70: 
        !            71: sub new {
        !            72:     my $class   = shift;	# Class name...
        !            73:     my $hashref = shift;        # Maintain this hash.
        !            74:     my @keylist = keys(%$hashref);
        !            75:     my $keyref= \@keylist;
        !            76:     my $keycount = scalar @keylist;
        !            77: 
        !            78: 
        !            79:     my $self    = {  Hash      => $hashref,
        !            80: 		     Keylist      => $keyref,
        !            81: 		     KeyCount     => $keycount,
        !            82: 		     Index        => 0};
        !            83:     bless($self, $class);	# Type ourself...
        !            84: 
        !            85:     return $self;
        !            86: 		  
        !            87: }
        !            88: 
        !            89: =pod
        !            90: 
        !            91: =head2 begin
        !            92: 
        !            93: Reset the iterator to the start of iteration.
        !            94: 
        !            95: =cut
        !            96: 
        !            97: sub begin {
        !            98:     my $self  = shift;		# Get object...
        !            99:     $self->{Index} = 0;
        !           100:   
        !           101: }
        !           102: 
        !           103: =pod
        !           104: 
        !           105: =head2 end
        !           106: 
        !           107: Return true if the iterator is off the end of the hash.
        !           108: 
        !           109: =cut
        !           110: 
        !           111: sub end {
        !           112:     my $self = shift;		# Retrieve self as object.
        !           113:     return ($self->{Index}  >= $self->{KeyCount});
        !           114: }
        !           115: 
        !           116: =pod
        !           117: 
        !           118: =head2 get
        !           119: 
        !           120: Return the contents of the hash at the current key.  If the key is off
        !           121: the end of the hash, undef is returned.  What is returned is a copy of
        !           122: the element.  If the index is off the end of the iteration, undef is
        !           123: returned.
        !           124: 
        !           125: =cut
        !           126: 
        !           127: sub get {
        !           128:     my $self = shift;
        !           129:     if ($self->end()) {
        !           130: 	return undef;
        !           131:     }
        !           132:     my $hashref = $self->{Hash};
        !           133:     my $key     = $self->{Keylist}->[$self->{Index}];
        !           134:     return $$hashref{$key};
        !           135: }
        !           136: 
        !           137: =pod
        !           138: 
        !           139: =head2 next
        !           140: 
        !           141: Advances the iterator.
        !           142: 
        !           143: =cut
        !           144: 
        !           145: sub next {
        !           146:     my $self = shift;		# Get us.
        !           147:     $self->{Index}  = $self->{Index} + 1;
        !           148: }
        !           149: 
        !           150: 1;