Set representation

Comparision with Set::IntSpan

This module also represents sets as ranges of values but stores those ranges in order and uses a binary search for many internal operations so that overall performance tends towards O log N where N is the number of ranges.

"Set::IntSpan::Fast::XS"

If you have a C compiler consider installing "Set::IntSpan::Fast::XS" for even better performance.

"new"

    my $set = Set::IntSpan::Fast->new( '1, 3, 5, 10-100' );

Because "add_from_string" handles multiple arguments this will work:

    my @nums = ( 1, 2, 3, 4, 5 );
    my $set = Set::IntSpan::Fast->new( @nums );

Bear in mind though that this validates each element of the array is it would if you called "add_from_string" so for large sets it will be slightly more efficient to create an empty set and then call "add".

"invert"

As noted above "NEGATIVE_INFINITY" and "POSITIVE_INFINITY" are actually just big integers.

"copy"

    my $new_set = $set->copy();

"add( $number ... )"

"remove( $number ... )"

"add_range( $from, $to )"

    $set->add_range(1, 10, 20, 22, 15, 17);

Each pair of arguments constitute a range. The second argument in each pair must be greater than or equal to the first.

"add_from_string( $string )"

    $set->add_from_string( '1-10, 30-40', '100-200' );

is equivalent to

    $set->add_from_string( '1-10, 30-40, 100-200' );

By default items are separated by ',' and ranges delimited by '-'. You may select different punctuation like this:

    $set->add_from_string( 
        { sep => ';', range => ':' },
        '1;3;5;7:11;19:27'
    );

When supplying an options hash in this way the "sep" and "range" option may be either a regular expression or a literal string.

    $set->add_from_string( 
        { sep => qr/:+/, range => qr/[.]+/ },
        '1::3::5:7...11:19..27'
    );

Any embedded whitespace in the string will be ignored.

"remove_range( $from, $to )"

    $set->remove_range(1, 10, 20, 22, 15, 17);

Each pair of arguments constitute a range. The second argument in each pair must be greater than or equal to the first.

"remove_from_string( $string )"

"merge( $set ... )"

"empty"

Operators

Returns a new set that is the complement of this set. See the comments about our definition of infinity above.

"union( $set ... )"

Return a new set that is the union of this set and all of the supplied sets.

    $un = $set->union( $other_set );

"intersection( $set )"

Return a new set that is the intersection of this set and all the supplied sets.

    $in = $set->intersection( $other_set );

"xor( $set )"

Return a new set that contains all of the members that are in this set or the supplied set but not both. Can actually handle more than two sets in which case it returns a set that contains all the members that are in some of the sets but not all of the sets.

"diff( $set )"

Return a set containing all the elements that are in this set but not the supplied set.

Tests

Return true if the set is empty.

"contains( $number )"

Return true if the specified number is contained in the set.

"contains_any($number, $number, $number ...)"

Return true if the set contains any of the specified numbers.

"contains_all($number, $number, $number ...)"

Return true if the set contains all of the specified numbers.

"contains_all_range( $low, $high )"

Return true if all the numbers in the range $low to $high (inclusive) are in the set.

"cardinality( [ $clip_lo, $clip_hi ] )"

Returns the number of members in the set. If a clipping range is supplied return the count of members that fall within that inclusive range.

"superset( $set )"

Returns true if this set is a superset of the supplied set. A set is always a superset of itself, or in other words

    $set->superset( $set )

returns true.

"subset( $set )"

Returns true if this set is a subset of the supplied set. A set is always a subset of itself, or in other words

    $set->subset( $set )

returns true.

"equals( $set )"

Returns true if this set is identical to the supplied set.

Getting set contents

Return an array containing all the members of the set in ascending order.

"as_string"

Return a string representation of the set.

    my $set = Set::IntSpan::Fast->new();
    $set->add(1, 3, 5, 7, 9);
    $set->add_range(100, 1_000_000);
    print $set->as_string(), "\n";    # prints 1,3,5,7,9,100-1000000

You may optionally supply a hash containing "sep" and "range" options:

    print $set->as_string({ sep => ';', range => '*' ), "\n";
        # prints 1;3;5;7;9;100*1000000

"iterate_runs( [ $clip_lo, $clip_hi ] )"

Returns an iterator that returns each run of integers in the set in ascending order. To iterate all the members of the set do something like this:

    my $iter = $set->iterate_runs();
    while (my ( $from, $to ) = $iter->()) {
        for my $member ($from .. $to) {
            print "$member\n";
        }
    }

If a clipping range is specified only those members that fall within the range will be returned.

Constants

    $set->add_range(1, Set::IntSpan::Fast::POSITIVE_INFINITY);