.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 3"
.TH Set::Infinite 3 2024-07-13 "perl v5.38.2" "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 "elements".
.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(CWnew()\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 "type" and "density" characteristics.
.SS universal_set
.IX Subsection "universal_set"
Creates a set containing "all" possible elements.
.PP
If called from an existing set, the universal set inherits
the "type" and "density" 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 "OR" 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 "AND" 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 "set" version of "XOR".
.SH "DENSITY METHODS"
.IX Header "DENSITY METHODS"
.SS real
.IX Subsection "real"
.Vb 1
\&    $set1 = $set\->real;
.Ve
.PP
Returns a set with density "0".
.SS integer
.IX Subsection "integer"
.Vb 1
\&    $set1 = $set\->integer;
.Ve
.PP
Returns a set with density "1".
.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 SCALAR).
.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 "until" 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
[EXPERIMENTAL]
\&\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 SCALAR).
.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 "type".
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 "density".
.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 "stringification" operator.
.PP
Stringification of unbounded recurrences is not implemented.
.PP
Unbounded recurrences are stringified as "function descriptions",
if the class variable \f(CW$PRETTY_PRINT\fR is set.
.SS spaceship
.IX Subsection "spaceship"
Implements the "comparison" operator.
.PP
Comparison of unbounded recurrences is not implemented.
.SH CAVEATS
.IX Header "CAVEATS"
.IP \(bu 4
constructor "span" notation
.Sp
.Vb 1
\&    $set = Set::Infinite\->new(10,1);
.Ve
.Sp
Will be interpreted as [1..10]
.IP \(bu 4
constructor "multiple-span" 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
"range operator"
.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 "complex sets":
.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 "complex set":
.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 LICENSE file included
with this module.