File Coverage

lib/Queue/Base.pm
Criterion Covered Total %
statement 44 46 95.6
branch 7 8 87.5
condition 4 5 80.0
subroutine 11 12 91.6
pod 9 9 100.0
total 75 80 93.7


line stmt bran cond sub pod time code
1             package Queue::Base;
2              
3 4     4   111965 use strict;
  4         9  
  4         155  
4 4     4   21 use warnings;
  4         6  
  4         177  
5              
6             # ABSTRACT: Simple OO style queue implementation.
7              
8             our $VERSION = '2.203'; # VERSION
9              
10 4     4   22 use Carp;
  4         7  
  4         2322  
11              
12             sub new {
13 7     7 1 1597 my ( $class, $elems ) = @_;
14 7         139 my $self = bless( { list => [] }, $class );
15              
16 7 100 66     44 if ( defined $elems && ref($elems) eq 'ARRAY' ) {
17 3         4 @{ $self->{list} } = @{$elems};
  3         11  
  3         5  
18             }
19              
20 7         24 return $self;
21             }
22              
23             sub add {
24 12     12 1 44 my ( $self, @args ) = @_;
25 12         16 push @{ $self->{list} }, @args;
  12         28  
26 12         26 return;
27             }
28              
29             sub remove_all {
30 1     1 1 7 my $self = shift;
31 1         3 return ( $self->remove( $self->size ) );
32             }
33              
34             sub remove {
35 14     14 1 1850 my $self = shift;
36 14   100     59 my $num = shift || 1;
37              
38 14 100       42 return shift @{ $self->{list} } unless wantarray;
  9         33  
39              
40 5 50       13 croak 'Paramater must be a positive number' unless 0 < $num;
41              
42 5         9 my @removed = ();
43              
44 5         7 my $count = $num;
45 5         11 while ($count) {
46 10         12 my $elem = shift @{ $self->{list} };
  10         16  
47 10 100       22 last unless defined $elem;
48 9         14 push @removed, $elem;
49 9         17 $count--;
50             }
51              
52 5         21 return @removed;
53             }
54              
55             sub size {
56 6     6 1 1016 return scalar( @{ shift->{list} } );
  6         290  
57             }
58              
59             sub empty {
60 2     2 1 9 return shift->size == 0;
61             }
62              
63             sub clear {
64 1     1 1 6 shift->{list} = [];
65 1         3 return;
66             }
67              
68             sub copy_elem {
69 1     1 1 1351 my @elems = @{ shift->{list} };
  1         5  
70 1         6 return @elems;
71             }
72              
73             sub peek {
74 0     0 1   my $self = shift;
75 0           return $self->{list}->[0];
76             }
77              
78             1;
79              
80              
81              
82             =pod
83              
84             =encoding utf-8
85              
86             =head1 NAME
87              
88             Queue::Base - Simple OO style queue implementation.
89              
90             =head1 VERSION
91              
92             version 2.203
93              
94             =head1 SYNOPSIS
95              
96             use Queue::Base;
97              
98             # construction
99             my $queue = new Queue::Base;
100             # or
101             my $queue = new Queue::Base(\@elements);
102              
103             # add a new element to the queue
104             $queue->add($element);
105              
106             # remove the next element from the queue
107             if (! $queue->empty) {
108             my $element = $queue->remove;
109             }
110              
111             # or
112             $element = $queue->remove;
113             if (defined $element) {
114             # do some processing here
115             }
116              
117             # add/remove more than just one element
118             $queue->add($elem1, $elem2 ...)
119             # and
120             @elements = $queue->remove(5);
121              
122             =head1 DESCRIPTION
123              
124             The Queue::Base is a simple implementation for queue structures using an
125             OO interface. Provides basic functionality: nothing less - nothing more.
126              
127             =head1 METHODS
128              
129             =head2 new [ELEMENTS]
130              
131             Creates a new empty queue.
132              
133             ELEMENTS is an array reference with elements the queue to be initialized with.
134              
135             =head2 add [LIST_OF_ELEMENTS]
136              
137             Adds the LIST OF ELEMENTS to the end of the queue.
138              
139             =head2 remove [NUMBER_OF_ELEMENTS]
140              
141             In scalar context it returns the first element from the queue.
142              
143             In array context it attempts to return NUMBER_OF_ELEMENTS requested;
144             when NUMBER_OF_ELEMENTS is not given, it defaults to 1.
145              
146             =head2 remove_all
147              
148             Returns an array with all the elements in the queue, and clears the queue.
149              
150             =head2 size
151              
152             Returns the size of the queue.
153              
154             =head2 empty
155              
156             Returns whether the queue is empty, which means its size is 0.
157              
158             =head2 clear
159              
160             Removes all elements from the queue.
161              
162             =head2 copy_elem
163              
164             Returns a copy (shallow) of the underlying array with the queue elements.
165              
166             =head2 peek
167              
168             Returns the value of the first element of the queue, wihtout removing it.
169              
170             =head1 CAVEATS
171              
172             The module works only with scalar values. If you want to use more complex
173             structures (and there's a big change you want that) please use references,
174             which in perl5 are basically scalars.
175              
176             =for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders
177              
178             =head1 SUPPORT
179              
180             =head2 Perldoc
181              
182             You can find documentation for this module with the perldoc command.
183              
184             perldoc Queue::Base
185              
186             =head2 Websites
187              
188             The following websites have more information about this module, and may be of help to you. As always,
189             in addition to those websites please use your favorite search engine to discover more resources.
190              
191             =over 4
192              
193             =item *
194              
195             Search CPAN
196              
197             The default CPAN search engine, useful to view POD in HTML format.
198              
199             L<http://search.cpan.org/dist/Queue-Base>
200              
201             =item *
202              
203             AnnoCPAN
204              
205             The AnnoCPAN is a website that allows community annonations of Perl module documentation.
206              
207             L<http://annocpan.org/dist/Queue-Base>
208              
209             =item *
210              
211             CPAN Ratings
212              
213             The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.
214              
215             L<http://cpanratings.perl.org/d/Queue-Base>
216              
217             =item *
218              
219             CPAN Forum
220              
221             The CPAN Forum is a web forum for discussing Perl modules.
222              
223             L<http://cpanforum.com/dist/Queue-Base>
224              
225             =item *
226              
227             CPANTS
228              
229             The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.
230              
231             L<http://cpants.perl.org/dist/overview/Queue-Base>
232              
233             =item *
234              
235             CPAN Testers
236              
237             The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.
238              
239             L<http://www.cpantesters.org/distro/Q/Queue-Base>
240              
241             =item *
242              
243             CPAN Testers Matrix
244              
245             The CPAN Testers Matrix is a website that provides a visual way to determine what Perls/platforms PASSed for a distribution.
246              
247             L<http://matrix.cpantesters.org/?dist=Queue-Base>
248              
249             =back
250              
251             =head2 Email
252              
253             You can email the author of this module at C<RUSSOZ at cpan.org> asking for help with any problems you have.
254              
255             =head2 Internet Relay Chat
256              
257             You can get live help by using IRC ( Internet Relay Chat ). If you don't know what IRC is,
258             please read this excellent guide: L<http://en.wikipedia.org/wiki/Internet_Relay_Chat>. Please
259             be courteous and patient when talking to us, as we might be busy or sleeping! You can join
260             those networks/channels and get help:
261              
262             =over 4
263              
264             =item *
265              
266             irc.perl.org
267              
268             You can connect to the server at 'irc.perl.org' and join this channel: #sao-paulo.pm then talk to this person for help: russoz.
269              
270             =back
271              
272             =head2 Bugs / Feature Requests
273              
274             Please report any bugs or feature requests by email to C<bug-queue-base at rt.cpan.org>, or through
275             the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Queue-Base>. You will be automatically notified of any
276             progress on the request by the system.
277              
278             =head2 Source Code
279              
280             The code is open to the world, and available for you to hack on. Please feel free to browse it and play
281             with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull
282             from your repository :)
283              
284             L<https://github.com/russoz/Queue-Base>
285              
286             git clone https://github.com/russoz/Queue-Base
287              
288             =head1 AUTHOR
289              
290             Alexei Znamensky <russoz@cpan.org>
291              
292             =head1 COPYRIGHT AND LICENSE
293              
294             This software is copyright (c) 2011 by Farkas Arpad, Alexei Znamensky.
295              
296             This is free software; you can redistribute it and/or modify it under
297             the same terms as the Perl 5 programming language system itself.
298              
299             =head1 BUGS AND LIMITATIONS
300              
301             No bugs have been reported.
302              
303             Please report any bugs or feature requests through the web interface at
304             L<http://rt.cpan.org>.
305              
306             =head1 DISCLAIMER OF WARRANTY
307              
308             BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
309             FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
310             WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
311             PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
312             EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
313             IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
314             PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
315             SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME
316             THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
317              
318             IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
319             WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
320             REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
321             TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
322             CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
323             SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
324             RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
325             FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
326             SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
327             DAMAGES.
328              
329             =cut
330              
331              
332             __END__
333