.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Set::Infinite 3pm"
.TH Set::Infinite 3pm "2022-10-22" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Set::Infinite \- Sets of intervals
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Set::Infinite;
\&
\&  $set = Set::Infinite\->new(1,2);    # [1..2]
\&  print $set\->union(5,6);            # [1..2],[5..6]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Set::Infinite is a Set Theory module for infinite sets.
.PP
A set is a collection of objects. 
The objects that belong to a set are called its members, or \*(L"elements\*(R".
.PP
As objects we allow (almost) anything:  reals, integers, and objects (such as dates).
.PP
We allow sets to be infinite.
.PP
There is no account for the order of elements. For example, {1,2} = {2,1}.
.PP
There is no account for repetition of elements. For example, {1,2,2} = {1,1,1,2} = {1,2}.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "new"
Creates a new set object:
.PP
.Vb 5
\&    $set = Set::Infinite\->new;             # empty set
\&    $set = Set::Infinite\->new( 10 );       # single element
\&    $set = Set::Infinite\->new( 10, 20 );   # single range
\&    $set = Set::Infinite\->new( 
\&              [ 10, 20 ], [ 50, 70 ] );    # two ranges
.Ve
.IP "empty set" 4
.IX Item "empty set"
.Vb 1
\&    $set = Set::Infinite\->new;
.Ve
.IP "set with a single element" 4
.IX Item "set with a single element"
.Vb 1
\&    $set = Set::Infinite\->new( 10 );
\&
\&    $set = Set::Infinite\->new( [ 10 ] );
.Ve
.IP "set with a single span" 4
.IX Item "set with a single span"
.Vb 1
\&    $set = Set::Infinite\->new( 10, 20 );
\&
\&    $set = Set::Infinite\->new( [ 10, 20 ] );
\&    # 10 <= x <= 20
.Ve
.IP "set with a single, open span" 4
.IX Item "set with a single, open span"
.Vb 7
\&    $set = Set::Infinite\->new(
\&        {
\&            a => 10, open_begin => 0,
\&            b => 20, open_end => 1,
\&        }
\&    );
\&    # 10 <= x < 20
.Ve
.IP "set with multiple spans" 4
.IX Item "set with multiple spans"
.Vb 1
\&    $set = Set::Infinite\->new( 10, 20,  100, 200 );
\&
\&    $set = Set::Infinite\->new( [ 10, 20 ], [ 100, 200 ] );
\&
\&    $set = Set::Infinite\->new(
\&        {
\&            a => 10, open_begin => 0,
\&            b => 20, open_end => 0,
\&        },
\&        {
\&            a => 100, open_begin => 0,
\&            b => 200, open_end => 0,
\&        }
\&    );
.Ve
.PP
The \f(CW\*(C`new()\*(C'\fR method expects \fIordered\fR parameters.
.PP
If you have unordered ranges, you can build the set using \f(CW\*(C`union\*(C'\fR:
.PP
.Vb 3
\&    @ranges = ( [ 10, 20 ], [ \-10, 1 ] );
\&    $set = Set::Infinite\->new;
\&    $set = $set\->union( @$_ ) for @ranges;
.Ve
.PP
The data structures passed to \f(CW\*(C`new\*(C'\fR must be \fIimmutable\fR.
So this is not good practice:
.PP
.Vb 2
\&    $set = Set::Infinite\->new( $object_a, $object_b );
\&    $object_a\->set_value( 10 );
.Ve
.PP
This is the recommended way to do it:
.PP
.Vb 2
\&    $set = Set::Infinite\->new( $object_a\->clone, $object_b\->clone );
\&    $object_a\->set_value( 10 );
.Ve
.SS "clone / copy"
.IX Subsection "clone / copy"
Creates a new object, and copy the object data.
.SS "empty_set"
.IX Subsection "empty_set"
Creates an empty set.
.PP
If called from an existing set, the empty set inherits
the \*(L"type\*(R" and \*(L"density\*(R" characteristics.
.SS "universal_set"
.IX Subsection "universal_set"
Creates a set containing \*(L"all\*(R" possible elements.
.PP
If called from an existing set, the universal set inherits
the \*(L"type\*(R" and \*(L"density\*(R" characteristics.
.SH "SET FUNCTIONS"
.IX Header "SET FUNCTIONS"
.SS "union"
.IX Subsection "union"
.Vb 1
\&    $set = $set\->union($b);
.Ve
.PP
Returns the set of all elements from both sets.
.PP
This function behaves like an \*(L"\s-1OR\*(R"\s0 operation.
.PP
.Vb 4
\&    $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
\&    $set2 = new Set::Infinite( [ 7, 20 ] );
\&    print $set1\->union( $set2 );
\&    # output: [1..4],[7..20]
.Ve
.SS "intersection"
.IX Subsection "intersection"
.Vb 1
\&    $set = $set\->intersection($b);
.Ve
.PP
Returns the set of elements common to both sets.
.PP
This function behaves like an \*(L"\s-1AND\*(R"\s0 operation.
.PP
.Vb 4
\&    $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
\&    $set2 = new Set::Infinite( [ 7, 20 ] );
\&    print $set1\->intersection( $set2 );
\&    # output: [8..12]
.Ve
.SS "complement"
.IX Subsection "complement"
.SS "minus"
.IX Subsection "minus"
.SS "difference"
.IX Subsection "difference"
.Vb 1
\&    $set = $set\->complement;
.Ve
.PP
Returns the set of all elements that don't belong to the set.
.PP
.Vb 3
\&    $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
\&    print $set1\->complement;
\&    # output: (\-inf..1),(4..8),(12..inf)
.Ve
.PP
The complement function might take a parameter:
.PP
.Vb 1
\&    $set = $set\->minus($b);
.Ve
.PP
Returns the set-difference, that is, the elements that don't
belong to the given set.
.PP
.Vb 4
\&    $set1 = new Set::Infinite( [ 1, 4 ], [ 8, 12 ] );
\&    $set2 = new Set::Infinite( [ 7, 20 ] );
\&    print $set1\->minus( $set2 );
\&    # output: [1..4]
.Ve
.SS "symmetric_difference"
.IX Subsection "symmetric_difference"
Returns a set containing elements that are in either set,
but not in both. This is the \*(L"set\*(R" version of \*(L"\s-1XOR\*(R".\s0
.SH "DENSITY METHODS"
.IX Header "DENSITY METHODS"
.SS "real"
.IX Subsection "real"
.Vb 1
\&    $set1 = $set\->real;
.Ve
.PP
Returns a set with density \*(L"0\*(R".
.SS "integer"
.IX Subsection "integer"
.Vb 1
\&    $set1 = $set\->integer;
.Ve
.PP
Returns a set with density \*(L"1\*(R".
.SH "LOGIC FUNCTIONS"
.IX Header "LOGIC FUNCTIONS"
.SS "intersects"
.IX Subsection "intersects"
.Vb 1
\&    $logic = $set\->intersects($b);
.Ve
.SS "contains"
.IX Subsection "contains"
.Vb 1
\&    $logic = $set\->contains($b);
.Ve
.SS "is_empty"
.IX Subsection "is_empty"
.SS "is_null"
.IX Subsection "is_null"
.Vb 1
\&    $logic = $set\->is_null;
.Ve
.SS "is_nonempty"
.IX Subsection "is_nonempty"
This set that has at least 1 element.
.SS "is_span"
.IX Subsection "is_span"
This set that has a single span or interval.
.SS "is_singleton"
.IX Subsection "is_singleton"
This set that has a single element.
.ie n .SS "is_subset( $set )"
.el .SS "is_subset( \f(CW$set\fP )"
.IX Subsection "is_subset( $set )"
Every element of this set is a member of the given set.
.ie n .SS "is_proper_subset( $set )"
.el .SS "is_proper_subset( \f(CW$set\fP )"
.IX Subsection "is_proper_subset( $set )"
Every element of this set is a member of the given set.
Some members of the given set are not elements of this set.
.ie n .SS "is_disjoint( $set )"
.el .SS "is_disjoint( \f(CW$set\fP )"
.IX Subsection "is_disjoint( $set )"
The given set has no elements in common with this set.
.SS "is_too_complex"
.IX Subsection "is_too_complex"
Sometimes a set might be too complex to enumerate or print.
.PP
This happens with sets that represent infinite recurrences, such as
when you ask for a quantization on a
set bounded by \-inf or inf.
.PP
See also: \f(CW\*(C`count\*(C'\fR method.
.SH "SCALAR FUNCTIONS"
.IX Header "SCALAR FUNCTIONS"
.SS "min"
.IX Subsection "min"
.Vb 1
\&    $i = $set\->min;
.Ve
.SS "max"
.IX Subsection "max"
.Vb 1
\&    $i = $set\->max;
.Ve
.SS "size"
.IX Subsection "size"
.Vb 1
\&    $i = $set\->size;
.Ve
.SS "count"
.IX Subsection "count"
.Vb 1
\&    $i = $set\->count;
.Ve
.SH "OVERLOADED OPERATORS"
.IX Header "OVERLOADED OPERATORS"
.SS "stringification"
.IX Subsection "stringification"
.Vb 1
\&    print $set;
\&
\&    $str = "$set";
.Ve
.PP
See also: \f(CW\*(C`as_string\*(C'\fR.
.SS "comparison"
.IX Subsection "comparison"
.Vb 1
\&    sort
\&
\&    > < == >= <= <=>
.Ve
.PP
See also: \f(CW\*(C`spaceship\*(C'\fR method.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.Vb 1
\&    Set::Infinite\->separators(@i)
\&
\&        chooses the interval separators for stringification. 
\&
\&        default are [ ] ( ) \*(Aq..\*(Aq \*(Aq,\*(Aq.
\&
\&    inf
\&
\&        returns an \*(AqInfinity\*(Aq number.
\&
\&    minus_inf
\&
\&        returns \*(Aq\-Infinity\*(Aq number.
.Ve
.SS "type"
.IX Subsection "type"
.Vb 1
\&    type( "My::Class::Name" )
.Ve
.PP
Chooses a default object data type.
.PP
Default is none (a normal Perl \s-1SCALAR\s0).
.SH "SPECIAL SET FUNCTIONS"
.IX Header "SPECIAL SET FUNCTIONS"
.SS "span"
.IX Subsection "span"
.Vb 1
\&    $set1 = $set\->span;
.Ve
.PP
Returns the set span.
.SS "until"
.IX Subsection "until"
Extends a set until another:
.PP
.Vb 1
\&    0,5,7 \-> until 2,6,10
.Ve
.PP
gives
.PP
.Vb 1
\&    [0..2), [5..6), [7..10)
.Ve
.SS "start_set"
.IX Subsection "start_set"
.SS "end_set"
.IX Subsection "end_set"
These methods do the inverse of the \*(L"until\*(R" method.
.PP
Given:
.PP
.Vb 1
\&    [0..2), [5..6), [7..10)
.Ve
.PP
start_set is:
.PP
.Vb 1
\&    0,5,7
.Ve
.PP
end_set is:
.PP
.Vb 1
\&    2,6,10
.Ve
.SS "intersected_spans"
.IX Subsection "intersected_spans"
.Vb 1
\&    $set = $set1\->intersected_spans( $set2 );
.Ve
.PP
The method returns a new set,
containing all spans that are intersected by the given set.
.PP
Unlike the \f(CW\*(C`intersection\*(C'\fR method, the spans are not modified.
See diagram below:
.PP
.Vb 2
\&               set1   [....]   [....]   [....]   [....]
\&               set2      [................]
\&
\&       intersection      [.]   [....]   [.]
\&
\&  intersected_spans   [....]   [....]   [....]
.Ve
.SS "quantize"
.IX Subsection "quantize"
.Vb 1
\&    quantize( parameters )
\&
\&        Makes equal\-sized subsets.
\&
\&        Returns an ordered set of equal\-sized subsets.
\&
\&        Example: 
\&
\&            $set = Set::Infinite\->new([1,3]);
\&            print join (" ", $set\->quantize( quant => 1 ) );
\&
\&        Gives: 
\&
\&            [1..2) [2..3) [3..4)
.Ve
.SS "select"
.IX Subsection "select"
.Vb 1
\&    select( parameters )
.Ve
.PP
Selects set spans based on their ordered positions
.PP
\&\f(CW\*(C`select\*(C'\fR has a behaviour similar to an array \f(CW\*(C`slice\*(C'\fR.
.PP
.Vb 2
\&            by       \- default=All
\&            count    \- default=Infinity
\&
\& 0  1  2  3  4  5  6  7  8      # original set
\& 0  1  2                        # count => 3 
\&    1              6            # by => [ \-2, 1 ]
.Ve
.SS "offset"
.IX Subsection "offset"
.Vb 1
\&    offset ( parameters )
.Ve
.PP
Offsets the subsets. Parameters:
.PP
.Vb 3
\&    value   \- default=[0,0]
\&    mode    \- default=\*(Aqoffset\*(Aq. Possible values are: \*(Aqoffset\*(Aq, \*(Aqbegin\*(Aq, \*(Aqend\*(Aq.
\&    unit    \- type of value. Can be \*(Aqdays\*(Aq, \*(Aqweeks\*(Aq, \*(Aqhours\*(Aq, \*(Aqminutes\*(Aq, \*(Aqseconds\*(Aq.
.Ve
.SS "iterate"
.IX Subsection "iterate"
.Vb 1
\&    iterate ( sub { } , @args )
.Ve
.PP
Iterates on the set spans, over a callback subroutine. 
Returns the union of all partial results.
.PP
The callback argument \f(CW$_[0]\fR is a span. If there are additional arguments they are passed to the callback.
.PP
The callback can return a span, a hashref (see \f(CW\*(C`Set::Infinite::Basic\*(C'\fR), a scalar, an object, or \f(CW\*(C`undef\*(C'\fR.
.PP
[\s-1EXPERIMENTAL\s0]
\&\f(CW\*(C`iterate\*(C'\fR accepts an optional \f(CW\*(C`backtrack_callback\*(C'\fR argument. 
The purpose of the \f(CW\*(C`backtrack_callback\*(C'\fR is to \fIreverse\fR the
\&\fBiterate()\fR function, overcoming the limitations of the internal
backtracking algorithm.
The syntax is:
.PP
.Vb 1
\&    iterate ( sub { } , backtrack_callback => sub { }, @args )
.Ve
.PP
The \f(CW\*(C`backtrack_callback\*(C'\fR can return a span, a hashref, a scalar, 
an object, or \f(CW\*(C`undef\*(C'\fR.
.PP
For example, the following snippet adds a constant to each
element of an unbounded set:
.PP
.Vb 5
\&    $set1 = $set\->iterate( 
\&                 sub { $_[0]\->min + 54, $_[0]\->max + 54 }, 
\&              backtrack_callback =>  
\&                 sub { $_[0]\->min \- 54, $_[0]\->max \- 54 }, 
\&              );
.Ve
.SS "first / last"
.IX Subsection "first / last"
.Vb 1
\&    first / last
.Ve
.PP
In scalar context returns the first or last interval of a set.
.PP
In list context returns the first or last interval of a set, 
and the remaining set (the 'tail').
.PP
See also: \f(CW\*(C`min\*(C'\fR, \f(CW\*(C`max\*(C'\fR, \f(CW\*(C`min_a\*(C'\fR, \f(CW\*(C`max_a\*(C'\fR methods.
.SS "type"
.IX Subsection "type"
.Vb 1
\&    type( "My::Class::Name" )
.Ve
.PP
Chooses a default object data type.
.PP
default is none (a normal perl \s-1SCALAR\s0).
.SH "INTERNAL FUNCTIONS"
.IX Header "INTERNAL FUNCTIONS"
.SS "_backtrack"
.IX Subsection "_backtrack"
.Vb 1
\&    $set\->_backtrack( \*(Aqintersection\*(Aq, $b );
.Ve
.PP
Internal function to evaluate recurrences.
.SS "numeric"
.IX Subsection "numeric"
.Vb 1
\&    $set\->numeric;
.Ve
.PP
Internal function to ignore the set \*(L"type\*(R".
It is used in some internal optimizations, when it is
possible to use scalar values instead of objects.
.SS "fixtype"
.IX Subsection "fixtype"
.Vb 1
\&    $set\->fixtype;
.Ve
.PP
Internal function to fix the result of operations
that use the \fBnumeric()\fR function.
.SS "tolerance"
.IX Subsection "tolerance"
.Vb 2
\&    $set = $set\->tolerance(0)    # defaults to real sets (default)
\&    $set = $set\->tolerance(1)    # defaults to integer sets
.Ve
.PP
Internal function for changing the set \*(L"density\*(R".
.SS "min_a"
.IX Subsection "min_a"
.Vb 1
\&    ($min, $min_is_open) = $set\->min_a;
.Ve
.SS "max_a"
.IX Subsection "max_a"
.Vb 1
\&    ($max, $max_is_open) = $set\->max_a;
.Ve
.SS "as_string"
.IX Subsection "as_string"
Implements the \*(L"stringification\*(R" operator.
.PP
Stringification of unbounded recurrences is not implemented.
.PP
Unbounded recurrences are stringified as \*(L"function descriptions\*(R",
if the class variable \f(CW$PRETTY_PRINT\fR is set.
.SS "spaceship"
.IX Subsection "spaceship"
Implements the \*(L"comparison\*(R" operator.
.PP
Comparison of unbounded recurrences is not implemented.
.SH "CAVEATS"
.IX Header "CAVEATS"
.IP "\(bu" 4
constructor \*(L"span\*(R" notation
.Sp
.Vb 1
\&    $set = Set::Infinite\->new(10,1);
.Ve
.Sp
Will be interpreted as [1..10]
.IP "\(bu" 4
constructor \*(L"multiple-span\*(R" notation
.Sp
.Vb 1
\&    $set = Set::Infinite\->new(1,2,3,4);
.Ve
.Sp
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)
.IP "\(bu" 4
\&\*(L"range operator\*(R"
.Sp
.Vb 1
\&    $set = Set::Infinite\->new(1..3);
.Ve
.Sp
Will be interpreted as [1..2],3 instead of [1,2,3].
You probably want \->new(1,3) instead.
.SH "INTERNALS"
.IX Header "INTERNALS"
The base \fIset\fR object, without recurrences, is a \f(CW\*(C`Set::Infinite::Basic\*(C'\fR.
.PP
A \fIrecurrence-set\fR is represented by a \fImethod name\fR, 
one or two \fIparent objects\fR, and extra arguments.
The \f(CW\*(C`list\*(C'\fR key is set to an empty array, and the
\&\f(CW\*(C`too_complex\*(C'\fR key is set to \f(CW1\fR.
.PP
This is a structure that holds the union of two \*(L"complex sets\*(R":
.PP
.Vb 7
\&  {
\&    too_complex => 1,             # "this is a recurrence"
\&    list   => [ ],                # not used
\&    method => \*(Aqunion\*(Aq,            # function name
\&    parent => [ $set1, $set2 ],   # "leaves" in the syntax\-tree
\&    param  => [ ]                 # optional arguments for the function
\&  }
.Ve
.PP
This is a structure that holds the complement of a \*(L"complex set\*(R":
.PP
.Vb 7
\&  {
\&    too_complex => 1,             # "this is a recurrence"
\&    list   => [ ],                # not used
\&    method => \*(Aqcomplement\*(Aq,       # function name
\&    parent => $set,               # "leaf" in the syntax\-tree
\&    param  => [ ]                 # optional arguments for the function
\&  }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See modules DateTime::Set, DateTime::Event::Recurrence, 
DateTime::Event::ICal, DateTime::Event::Cron
for up-to-date information on date-sets.
.PP
The perl-date-time project <http://datetime.perl.org>
.SH "AUTHOR"
.IX Header "AUTHOR"
Flavio S. Glock <fglock@gmail.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003 Flavio Soibelmann Glock.  All rights reserved.  
This program is free software; you can redistribute it and/or modify 
it under the same terms as Perl itself.
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included
with this module.