Range::Object - Basic facilities for manipulating different kinds of object ranges
This module is not to be used directly. See Range::Serial, Range::Strings, Range::Extension, Range::DigitString, Range::Date and Range::Interval.
This module provides abstract methods for Range::* family of modules.
The purpose of these modules is to provide unified interface for storing, retrieving and testing for existence of different kinds of objects and object ranges.
In terms of this namespace, a range is defined as a set of items, either disjointed (individual) or contiguous, or a combination of separate items and ranges. Intersecting or adjacent ranges are not supported directly and will be collapsed silently into wider contiguous range.
Although Range::Object descendant module can store any number of separate values (objects) and ranges, it is optimized for storing contiguous ranges of arbitrary length with minimal memory and storage footprint; the other effect of this being fast serialization and deserialization of Range::Object instances. It cannot come without cost though; Range::Object uses more CPU cycles than similar hash-based modules.
Good application for this kind of object storage can be an implementation of user permission tables for large number of objects, especially if such permissions are typically assigned in large contiguous ranges. For example, if User has read permission for objects 1-10000 and write permission for objects 1-100, 200-300 and 1000-9999, storing these identificators as hash keys is memory expensive, and can become prohibive when number of tables and users increase. Compared to that approach, Range::Object can be a reasonable compromise between memory and CPU utilization.
Takes a @list of arguments, expands them and creates range object. The following separators are allowed: comma (,), semicolon (;) and dash (-) which means literal range between two items.
Adds items to range using the same rules as with new(). In fact, new() will call add() after initialization.
Removes items in @list from current range. As with add(), @list can contain individual items as well as stringified item ranges.
Returns the number of single individual items in the range.
Checks if items in @list are within our current range. In scalar context, returns true or false; in list context returns items from expanded @list that are not in range or empty list if they are all in range.
N.B: it means that results in scalar and list context are opposite: true in scalar context would be empty list in list context which evaluates to false.
Returns the list of items in current range in list context, or range string in scalar context. Stringified version of range() is join()ed using optional $separator or default comma (,).
Returns collapsed list of items in current range in list context, or stringified version of collapsed list in scalar context.
Collapsed list consists of either individual items or hashrefs representing ranges in the following format: { start => <starting item>, end => <ending item>, count => <number of items> }
In stringified version, ranges are delimited with whatever character or string is returned by delimiter(). Optional $separator can specify a character or string to be used as list separator for range items.
Returns string representation of current range. This method can be used instead of range() in scalar context to provide the same results.
Optional $separator can specify a character or string to be used as list separator for range items.
Returns string representation of collapsed current range, following the same rules as used by new() for expanding ranges. In fact, the output of stringify_collapsed() can be fed back to new() to create an exact copy of the current range. This method also can be used instead of collapsed() in scalar context to provide the same results.
Optional $separator specifies a character or string to be used as list separator for range items.
Returns regex that is used to validate range items.
Returns regex that is used to split input range items.
Returns range delimiter for current class, default is dash (-).
add() will fail with this message if input list item or range is not matched by pattern defined by current module.
add() will fail with this message if input list *range* item is not matched by pattern defined by current module.
This module is dependent on the following standard modules: Carp, List::Util.
Addition/removal operations are quite resource heavy in present implementation as they require complete unpacking/collapsing of the current range for each add or remove. There are no plans for optimization on this part, since permission tables are usually very long lived and relatively rarely changed. Patches and ideas are welcome though.
Only forward ranges are supported, i.e. starting value should be less than or equal to ending value.
There are no known bugs in this module. Please report problems to author, patches are welcome.
Alexander Tokarev <tokarev@cpan.org>.
Copyright (c) 2011 by Alexander Tokarev.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
To install Range::Object, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Range::Object
CPAN shell
perl -MCPAN -e shell install Range::Object
For more information on module installation, please visit the detailed CPAN module installation guide.