import Set-Scalar 1.12 from CPAN

git-cpan-module:   Set-Scalar
git-cpan-version:  1.12
git-cpan-authorid: JHI
git-cpan-file:     authors/id/J/JH/JHI/Set-Scalar-1.12.tar.gz

Author: jhi

ChangeLog

@@ -1,3 +1,10 @@
+Sat Oct 13 17:40:28 2001  Jarkko Hietaniemi  <jhi@alpha.hut.fi>
+
+	* Add each() as a lighter weight way of iterating
+	  over sets, as suggested by Dave Lewis.
+
+	* Released as 1.12.
+	  
 Wed Oct 10 17:31:12 2001  Jarkko Hietaniemi  <jhi@alpha.hut.fi>
 
 	* In boolean contexts the string representation of sets

MANIFEST

@@ -15,6 +15,7 @@ t/basic_overload.t
 t/boolean.t
 t/compare.t
 t/difference.t
+t/each.t
 t/intersection.t
 t/laws.t
 t/misc.t

lib/Set/Scalar.pm

@@ -5,7 +5,7 @@ local $^W = 1;
 
 use vars qw($VERSION @ISA);
 
-$VERSION = '1.11';
+$VERSION = '1.12';
 
 @ISA = qw(Set::Scalar::Real Set::Scalar::Null Set::Scalar::Base);
 
@@ -168,13 +168,66 @@ These methods have operator overloads:
 
     $cmp = $s <=> $t;
 
+=head2 Boolean contexts
+
 In Boolean contexts such as
 
     if ($set) { ... }
+    while ($set1 && $set2) { ... }
 
 the size of the C<$set> is tested, so empty sets test as false,
 and non-empty sets as true.
 
+=head2 Iterating
+
+    while (defined(my $e = $s->each)) { ... }
+
+This is more memory-friendly than
+
+    for my $e ($s->elements) { ... }
+
+which would first construct the full list of elements and then
+walk through it: the C<$s->each> handles one element at a time.
+
+Analogously to using normal C<each(%hash)> in scalar context,
+using C<$s->each> has the following caveats:
+
+=over 4
+
+=item *
+
+The elements are returned in (apparently) random order.
+So don't expect any particular order.
+
+=item *
+
+When no more elements remain C<undef> is returned.  Since you may one
+day have elements named C<"0"> don't test just like this
+
+    while (my $e = $s->each) { ... }          # WRONG
+
+but instead like this
+
+    while (defined(my $e = $s->each)) { ... } # right
+
+=item *
+
+There is one iterator per one set which is shared by many
+element-accessing interfaces-- using the following will reset the
+iterator: elements(), insert(), members(), size(), unique().  insert()
+causes the iterator of the set being inserted (not the set being the
+target of insertion) becoming reset.  unique() causes the iterators of
+all the participant sets becoming reset.  B<The iterator getting reset
+most probably causes an endless loop.>  So avoid doing that.
+
+=item *
+
+Modifying the set during the iteration may cause elements to be missed
+or duplicated, or in the worst case, an endless loop; so don't do
+that, either.
+
+=back
+
 =head1 AUTHOR
 
 Jarkko Hietaniemi <jhi@iki.fi>

lib/Set/Scalar/Base.pm

@@ -144,6 +144,14 @@ sub element {
 *has      = \&element;
 *contains = \&element;
 
+sub each {
+    my $self = shift;
+
+    my ($k, $e) = each %{ $self->{'elements'} };
+
+    return $e;
+}
+
 sub _clone {
     my $self     = shift;
     my $original = shift;

t/each.t

@@ -0,0 +1,30 @@
+use Set::Scalar;
+
+print "1..2\n";
+
+my @a = ("a".."e",0);
+my $a = Set::Scalar->new(@a);
+
+my $e;
+my %e;
+
+while (defined($e = $a->each)) {
+    print "# e = $e\n";
+    $e{$e}++;
+}
+
+print "not " if defined $e;
+print "ok 1\n";
+
+my $n;
+
+for my $e (@a) {
+    $n++ if exists $e{$e} && $e{$e} == 1;
+}
+
+print "not " unless $n == @a && keys %e == @a;
+print "ok 2\n";
+
+
+
+