NAME

Set::Infinite - Sets of intervals

SYNOPSIS

use Set::Infinite;

$a = Set::Infinite->new(1,2);    # [1..2]
print $a->union(5,6);            # [1..2],[5..6]

DESCRIPTION

Set::Infinite is a Set Theory module for infinite sets.

It works with reals, integers, and objects.

When it is used dates, this module provides schedule checks (intersections), unions, and infinite recurrences.

SET FUNCTIONS

union

$set = $a->union($b);

Returns the set of all elements from both sets.

This function behaves like a "or" operation.

$set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
$set2 = new Set::Infinite( [ 7, 20 ] );
print $set1->union( $set2 );
# output: [1..4],[7..20]

intersection

$set = $a->intersection($b);

Returns the set of elements common to both sets.

This function behaves like a "and" operation.

$set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
$set2 = new Set::Infinite( [ 7, 20 ] );
print $set1->intersection( $set2 );
# output: [8..12]

complement

$set = $a->complement;

Returns the set of all elements that don't belong to the set.

$set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
print $set1->complement;
# output: (-inf..1),(4..8),(12..inf)

The complement function might take a parameter:

$set = $a->complement($b);

Returns the set-difference, that is, the elements that don't belong to the given set.

$set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
$set2 = new Set::Infinite( [ 7, 20 ] );
print $set1->complement( $set2 );
# output: [1..4]

DENSITY FUNCTIONS

real

$a->real;

Returns a set with density "0".

integer

$a->integer;

Returns a set with density "1".

LOGIC FUNCTIONS

intersects

$logic = $a->intersects($b);

contains

$logic = $a->contains($b);

is_null

$logic = $a->is_null;

is_too_complex

Sometimes a set might be too complex to enumerate or print.

This happens with sets that represent infinite recurrences, such as when you ask for a quantization on a set bounded by -inf or inf.

SCALAR FUNCTIONS

min

$i = $a->min;

max

$i = $a->max;

size

$i = $a->size;

OVERLOADED LANGUAGE OPERATORS

stringification

print $set;

$str = "$set";

comparison

sort

> < == >= <= <=>

CLASS METHODS

separators(@i)

    chooses the interval separators for stringification. 

    default are [ ] ( ) '..' ','.

inf

    returns an 'Infinity' number.

minus_inf

    returns '-Infinity' number.

type

type($i)

Chooses a default object data type.

default is none (a normal perl SCALAR).

type('Math::BigFloat');
type('Math::BigInt');
type('Set::Infinite::Date');

See notes on Set::Infinite::Date below.

SPECIAL SET FUNCTIONS (WIDGETS)

span

$i = $a->span;

    result is INTERVAL, (min .. max)

until

Extends a set until another:

0,5,7 -> until 2,6,10

gives

[0..2), [5..6), [7..10)

Note: this function is still experimental.

quantize

quantize( parameters )

    Makes equal-sized subsets.

    In array context: returns a tied reference to the subset list.
    In set context: returns an ordered set of equal-sized subsets.

    The quantization function is external to this module:
    Parameters may vary depending on implementation. 

    Positions for which a subset does not exist may show as undef.

    Example: 

        $a = Set::Infinite->new([1,3]);
        print join (" ", $a->quantize( quant => 1 ) );

    Gives: 

        [1..2) [2..3) [3..4)

select

   select( parameters )

       Selects set members based on their ordered positions
       (Selection is more useful after quantization).

           freq     - default=1
           by       - default=[0]
           count    - default=Infinity

0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15    # [0..15] quantized by "1"

0              5             10             15    # freq => 5

   1     3        6     8       11    13          # freq => 5, by => [ -2, 1 ]

   1     3        6     8                         # freq => 5, by => [ -2, 1 ], count => 2

   1                                     14       # by => [ -2, 1 ]

offset

offset ( parameters )

    Offsets the subsets. Parameters: 

        value   - default=[0,0]
        mode    - default='offset'. Possible values are: 'offset', 'begin', 'end'.
        unit    - type of value. Can be 'days', 'weeks', 'hours', 'minutes', 'seconds'.

iterate

iterate ( sub { } , @args )

Iterates on the set spans, over a callback subroutine. Returns the union of all partial results.

The callback argument $_[0] is a span. If there are additional arguments they are passed to the callback.

The callback can return a span, a hashref (see Set::Infinite::Basic), a scalar, an object, or undef.

first / last

first / last

In scalar context returns the first interval of a set.

In list context returns the first interval of a set, and the 'tail'.

Works even in unbounded sets

type

type($i)

Chooses a default object data type.

default is none (a normal perl SCALAR).

examples:

type('Math::BigFloat');
type('Math::BigInt');
type('Set::Infinite::Date');
    See notes on Set::Infinite::Date below.

INTERNAL FUNCTIONS

cleanup

$a->cleanup;

Internal function to fix the internal set representation. This is used after operations that might return invalid values.

backtrack

$a->backtrack( 'intersection', $b );

Internal function to evaluate recurrences.

numeric

$a->numeric;

Internal function to ignore the set "type". It is used in some internal optimizations, when it is possible to use scalar values instead of objects.

fixtype

$a->fixtype;

Internal function to fix the result of operations that use the numeric() function.

tolerance

$a->tolerance(0)    # defaults to real sets (default)
$a->tolerance(1)    # defaults to integer sets

Internal function for changing the set "density".

min_a

($min, $min_is_open) = $set->min_a;

max_a

($max, $max_is_open) = $set->max_a;

as_string

Implements the "stringification" operator.

Stringification of unbounded recurrences is not implemented.

Unbounded recurrences are stringified as "function descriptions", if the class variable $PRETTY_PRINT is set.

spaceship

Implements the "comparison" operator.

Comparison of unbounded recurrences is not implemented.

NOTES ON DATES

See modules DateTime::Set and Date::Set for up-to-date information on date-sets.

Set::Infinite::Date is a Date "plug-in" for sets.

usage:

type('Set::Infinite::Date');  # allows values like '2001-05-02 10:00:00'

Set::Infinite::Date requires Time::Local.

use Set::Infinite;
Set::Infinite->type('Set::Infinite::Date');
Set::Infinite::Date->date_format("year-month-day");

$a = Set::Infinite->new('2001-05-02', '2001-05-13');
print "Weeks in $a: ", $a->quantize(unit => 'weeks', quant => 1);

$a = Set::Infinite->new('09:30', '10:35');
print "Quarters of hour in $a: ", $a->quantize(unit => 'minutes', quant => 15);

Quantize units can be years, months, days, weeks, hours, minutes, or seconds. To quantize the year to first-week-of-year until last-week-of-year, use 'weekyears':

->quantize( unit => weekyears, wkst => 1 )

'wkst' parameter is '1' for monday (default), '7' for sunday.

max and min functions will also show in date/time format.

CAVEATS

"span" notation
```
$a = Set::Infinite->new(10,1);
```
Will be interpreted as [1..10]
"multiple-span" notation
```
$a = Set::Infinite->new(1,2,3,4);
```
Will be interpreted as [1..2],[3..4] instead of [1,2,3,4]. You probably want ->new([1],[2],[3],[4]) instead, or maybe ->new(1,4)
"range operator"
```
$a = Set::Infinite->new(1..3);
```
Will be interpreted as [1..2],3 instead of [1,2,3]. You probably want ->new(1,3) instead.

INTERNALS

The base set object, without recurrences, is a Set::Infinite::Basic.

A recurrence-set is represented by a method name, one or two parent objects, and extra arguments. The list key is set to an empty array, and the too_complex key is set to 1.

This is a structure that holds a union of two "complex sets":

{
  too_complex => 1,             # "this is a recurrence"
  list   => [ ],                # not used
  method => 'union',            # function name
  parent => [ $set1, $set2 ],   # "leaves" in the syntax-tree
  param  => [ ]                 # optional arguments for the function
}

This is a structure that holds the complement of a "complex set":

{
  too_complex => 1,             # "this is a recurrence"
  list   => [ ],                # not used
  method => 'complement',       # function name
  parent => $set,               # "leaf" in the syntax-tree
  param  => [ ]                 # optional arguments for the function
}

AUTHOR

Flavio Soibelmann Glock <fglock@pucrs.br>

To install Set::Infinite, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Set::Infinite

CPAN shell

perl -MCPAN -e shell
install Set::Infinite

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

SET FUNCTIONS

union

intersection

complement

DENSITY FUNCTIONS

real

integer

LOGIC FUNCTIONS

intersects

contains

is_null

is_too_complex

SCALAR FUNCTIONS

min

max

size

OVERLOADED LANGUAGE OPERATORS

stringification

comparison

CLASS METHODS

type

SPECIAL SET FUNCTIONS (WIDGETS)

span

until

quantize

select

offset

iterate

first / last

type

INTERNAL FUNCTIONS

cleanup

backtrack

numeric

fixtype

tolerance

min_a

max_a

as_string

spaceship

NOTES ON DATES

CAVEATS

INTERNALS

SEE ALSO

AUTHOR

Module Install Instructions