3 # This file is part of Stem.
4 # Copyright (C) 1999, 2000, 2001 Stem Systems, Inc.
6 # Stem is free software; you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation; either version 2 of the License, or
9 # (at your option) any later version.
11 # Stem is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with Stem; if not, write to the Free Software
18 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 # For a license to use the Stem under conditions other than those
21 # described here, to purchase support for this software, or to purchase a
22 # commercial warranty contract, please contact Stem Systems at:
24 # Stem Systems, Inc. 781-643-7504
25 # 79 Everett St. info@stemsystems.com
35 This module generates unique Id strings for use as names in Stem
36 addresses. Its most common use is by parent Cells which clone
37 themselves and need a unique Target. The parent Cell uses its Cell
38 name and the new Target to register the cloned Cell.
48 This sets the number of characters in the Id. It defaults to 6.
56 # This POD section is autoegenerated. Any edits to it will be lost.
58 =head2 Constructor Attributes for Class Stem::Id
63 =item * Attribute - B<size>
69 This sets the number of characters in the Id. It defaults to 6.
72 =item It B<defaults> to: 6
80 # End of autogenerated POD
87 The new method constructs a Stem::Id object. It initializes the Id
88 string to a string of 'a's. The string size determines how long this
89 object can go before it has to reuse previously deleted Id strings.
95 my( $class ) = shift ;
97 my $self = Stem::Class::parse_args( $attr_spec, @_ ) ;
98 return $self unless ref $self ;
100 my $size = $self->{'size'} ;
102 $self->{'start'} = 'a' x $size ;
103 $self->{'next'} = 'a' x $size ;
104 $self->{'end'} = 'a' x ( $size + 1 ) ;
105 $self->{'in_use'} = {} ;
112 The next method returns the next available Id in the object and marks
113 that as in use. It fails if all possible Id's are in use.
121 my $next = $self->{'next'} ;
122 my $curr_next = $next ;
123 my $end = $self->{'end'} ;
124 my $in_use = $self->{'in_use'} ;
126 while( exists( $in_use->{$next} ) ) {
130 # fail if we looped around.
132 #print "curr $curr_next $next\n" ;
134 return if $next eq $curr_next ;
136 $next = $self->{'start'} if $next eq $end ;
139 $in_use->{$next} = 1 ;
140 $self->{'next'} = $next ;
147 The delete method allows this Id to be reused by a call to the next
154 my( $self, $id ) = @_ ;
156 delete $self->{'in_use'}{ $id } ;
161 The dump method returns a the list of Ids that are in use. used. It
162 either returns the list of keys or an anonymous array with them
163 depending on the calling context.
171 return( wantarray ? keys %{ $self->{'in_use'} } :
172 [ keys %{ $self->{'in_use'} } ] ) ;