view release on metacpan or  search on metacpan

lib/Range/Object.pm  view on Meta::CPAN

package Range::Object;

# This is basically what common::sense does, but without the pragma itself
# to remain compatible with Perls older than 5.8

use strict;

no  warnings;
use warnings qw(FATAL closed internal debugging pack malloc portable
                prototype inplace io pipe unpack deprecated glob digit
                printf reserved taint closure semicolon);
no  warnings qw(exec newline unopened);

use Carp;
use List::Util qw( first );

### PACKAGE VARIABLE ###
#
# Version of this module.
#

# This is for compatibility with older Perls
use vars qw( $VERSION );

$VERSION = '0.94';

### PUBLIC CLASS METHOD (CONSTRUCTOR) ###
#
# Initializes new instance of $class from @input_range.
#

sub new {
    my ($class, @input_range) = @_;

    my $self = bless { range => [] }, $class;

    return $self->add(@input_range);
}

### PUBLIC INSTANCE METHOD ###
#
# Validates @input_range of items and adds them to internal storage.
#

sub add {
    my ($self, @input_range) = @_;

    # Nothing to do
    return $self unless @input_range;

    my @validated_input = $self->_validate_and_expand(@input_range);

    # Expand existing range and overlay the new one
    my %existing_values = map {; "$_" => 1 } $self->_full_range();
    @existing_values{ @validated_input } = (1) x @validated_input;

    # Collapse resulting hash and replace current range with new values
    $self->{range} = [ $self->_collapse_range( keys %existing_values ) ];

    return $self;
}

### PUBLIC INSTANCE METHOD ###
#
# Removes items in @input_range from internal storage.
#

sub remove {
    my ($self, @input_range) = @_;

    # Nothing to do
    return $self unless @input_range;

    my @validated_input = $self->_validate_and_expand(@input_range);

    # Expand existing range and remove what needs to be removed
    my %existing_values = map {; "$_" => 1 } $self->_full_range();
    delete @existing_values{ @validated_input };

    # Collapse resulting hash and replace current range with new values
    $self->{range} = [ $self->_collapse_range( keys %existing_values ) ];

    return $self;
}

### PUBLIC INSTANCE METHOD ###
#
# Returns sorted array or string representation of internal storage.
# In scalar context it can use optional list separator instead of
# default one.
#

sub range {
    my ($self, $separator) = @_;

    return wantarray    ? $self->_sort_range()
         :                $self->stringify($separator)
         ;
}

### PUBLIC INSTANCE METHOD ###
#
# Returns sorted and collapsed representation of internal storage.
# In list context, resulting list consists of separate values and/or
# range hashrefs with three elements: start, end and count.
# In scalar context, result is a string of separate values and/or
# ranges separated by value returned by delimiter() method.
# Optional list separator can be used instead of default one in
# scalar context.
#

sub collapsed {
    my ($self, $separator) = @_;