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;
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>