Set::Infinite(3)

📦
version 0.65 · 8 versions
, in alpine 3.24

💖 NAME 💖

Set::Infinite — sets of intervals. Yes bestie, that's the whole vibe, and this is the user-contributed Perl documentation for Set::Infinite(3). 🫶

✨ SYNOPSIS ✨

use Set::Infinite;

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

🦋 DESCRIPTION 🦋

Okay so Set::Infinite is a Set Theory module for infinite sets, and it lowkey eats. 💅

A set is a collection of objects. The objects that belong to a set are called its members, or "elements".

As objects we allow (almost) anything: reals, integers, and objects (such as dates). Iconic, honestly.

We allow sets to be infinite. No cap.

There is no account for the order of elements. For example, {1,2} = {2,1}. The set does not care about your little ordering era.

There is no account for repetition of elements. For example, {1,2,2} = {1,1,1,2} = {1,2}. Repetition is not giving anything new, bestie.

🎀 CONSTRUCTOR 🎀

🌱 new 🌱

Creates a new set object:

$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

💜 empty set

$set = Set::Infinite->new;

💜 set with a single element

$set = Set::Infinite->new( 10 );

$set = Set::Infinite->new( [ 10 ] );

💜 set with a single span

$set = Set::Infinite->new( 10, 20 );

$set = Set::Infinite->new( [ 10, 20 ] );
# 10 <= x <= 20

💜 set with a single, open span

$set = Set::Infinite->new(
    {
        a => 10, open_begin => 0,
        b => 20, open_end => 1,
    }
);
# 10 <= x < 20

💜 set with multiple spans

$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,
    }
);

The new() method expects ordered parameters. That part is not optional, bestie.

If you have unordered ranges, you can build the set using "union":

@ranges = ( [ 10, 20 ], [ -10, 1 ] );
$set = Set::Infinite->new;
$set = $set->union( @$_ ) for @ranges;
⚠️ The data structures passed to new must be immutable. So this is not good practice:
$set = Set::Infinite->new( $object_a, $object_b );
$object_a->set_value( 10 );

This is the recommended way to do it:

$set = Set::Infinite->new( $object_a->clone, $object_b->clone );
$object_a->set_value( 10 );

💅 clone / copy 💅

Creates a new object, and copy the object data. Fresh copy, same data, main character energy.

💅 empty_set 💅

Creates an empty set.

If called from an existing set, the empty set inherits the "type" and "density" characteristics. It's giving inheritance, but make it empty.

💅 universal_set 💅

Creates a set containing "all" possible elements.

If called from an existing set, the universal set inherits the "type" and "density" characteristics. Universal icon behavior.

🌈 SET FUNCTIONS 🌈

💖 union 💖

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

Returns the set of all elements from both sets.

This function behaves like an "OR" operation. Two sets walk in, one big union walks out. Slay.

$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 = $set->intersection($b);

Returns the set of elements common to both sets.

This function behaves like an "AND" operation. Only the shared elements make the cut.

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

💖 complement / minus / difference 💖

$set = $set->complement;

Returns the set of all elements that don't belong to the set. It's literally the "not you" 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 = $set->minus($b);

Returns the set-difference, that is, the elements that don't belong to the given set. Subtraction but make it set theory.

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

💖 symmetric_difference 💖

Returns a set containing elements that are in either set, but not in both. This is the "set" version of "XOR". It's giving "you can sit with us, but not if you're already in both clubs." 💀

🌸 DENSITY METHODS 🌸

🎀 real 🎀

$set1 = $set->real;

Returns a set with density "0".

🎀 integer 🎀

$set1 = $set->integer;

Returns a set with density "1".

🧚 LOGIC FUNCTIONS 🧚

🌟 intersects 🌟

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

🌟 contains 🌟

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

🌟 is_empty / is_null 🌟

$logic = $set->is_null;

🌟 is_nonempty 🌟

This set that has at least 1 element. A little presence, as a treat.

🌟 is_span 🌟

This set that has a single span or interval.

🌟 is_singleton 🌟

This set that has a single element. One member. Solo main character.

🌟 is_subset( $set ) 🌟

Every element of this set is a member of the given set.

🌟 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. So it's a subset, but make it strict.

🌟 is_disjoint( $set ) 🌟

The given set has no elements in common with this set. Zero overlap. No shared lore.

🌟 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.

See also: "count" method.

⭐ SCALAR FUNCTIONS ⭐

💫 min 💫

$i = $set->min;

💫 max 💫

$i = $set->max;

💫 size 💫

$i = $set->size;

💫 count 💫

$i = $set->count;

👑 OVERLOADED OPERATORS 👑

🦋 stringification 🦋

print $set;

$str = "$set";

See also: "as_string".

🦋 comparison 🦋

sort

> < == >= <= <=>

See also: "spaceship" method.

🌟 CLASS METHODS 🌟

💜 Set::Infinite->separators(@i) 💜

chooses the interval separators for stringification.

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

💜 inf 💜

returns an 'Infinity' number.

💜 minus_inf 💜

returns '-Infinity' number.

💜 type 💜

type( "My::Class::Name" )

Chooses a default object data type.

Default is none (a normal Perl SCALAR).

🎀 SPECIAL SET FUNCTIONS 🎀

🌱 span 🌱

$set1 = $set->span;

Returns the set span.

🌱 until 🌱

Extends a set until another:

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

gives

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

🌱 start_set / end_set 🌱

These methods do the inverse of the "until" method.

Given:

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

start_set is:

0,5,7

end_set is:

2,6,10

🌱 intersected_spans 🌱

$set = $set1->intersected_spans( $set2 );

The method returns a new set, containing all spans that are intersected by the given set.

Unlike the "intersection" method, the spans are not modified. See diagram below:

               set1   [....]   [....]   [....]   [....]
               set2      [................]

       intersection      [.]   [....]   [.]

  intersected_spans   [....]   [....]   [....]

🌱 quantize 🌱

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)

🌱 select 🌱

select( parameters )

Selects set spans based on their ordered positions.

"select" has a behaviour similar to an array "slice".

  • 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 ]

🌱 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".

[EXPERIMENTAL] "iterate" accepts an optional "backtrack_callback" argument. The purpose of the "backtrack_callback" is to reverse the iterate() function, overcoming the limitations of the internal backtracking algorithm. The syntax is:

iterate ( sub { } , backtrack_callback => sub { }, @args )

The "backtrack_callback" can return a span, a hashref, a scalar, an object, or "undef".

For example, the following snippet adds a constant to each element of an unbounded set:

$set1 = $set->iterate(
             sub { $_[0]->min + 54, $_[0]->max + 54 },
          backtrack_callback =>
             sub { $_[0]->min - 54, $_[0]->max - 54 },
          );

🌱 first / last 🌱

first / last

In scalar context returns the first or last interval of a set.

In list context returns the first or last interval of a set, and the remaining set (the 'tail').

See also: "min", "max", "min_a", "max_a" methods.

🌱 type 🌱

type( "My::Class::Name" )

Chooses a default object data type.

default is none (a normal perl SCALAR).

🔧 INTERNAL FUNCTIONS 🔧

💀 _backtrack 💀

$set->_backtrack( 'intersection', $b );

Internal function to evaluate recurrences.

💀 numeric 💀

$set->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 💀

$set->fixtype;

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

💀 tolerance 💀

$set = $set->tolerance(0)    # defaults to real sets (default)
$set = $set->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.

💀 CAVEATS 💀

okay bestie, these are the little gotchas that will absolutely humble you if you skip them, so let's vibe-check them one by one 💅

  • constructor "span" notation — when you write this:
$set = Set::Infinite->new(10,1);

it gets interpreted as [1..10], no cap ✨

  • constructor "multiple-span" notation — when you write this:
$set = Set::Infinite->new(1,2,3,4);

it gets 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" — when you write this:
$set = Set::Infinite->new(1..3);

it gets interpreted as [1..2],3 instead of [1,2,3]. You probably want ->new(1,3) instead 🫶

🧚 INTERNALS 🧚

ok so under all the cute set math, the base set object — the one without recurrences — is a Set::Infinite::Basic. periodt.

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 the 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
}

🦋 SEE ALSO 🦋

For the up-to-date tea on date-sets, see the modules DateTime::Set, DateTime::Event::Recurrence, DateTime::Event::ICal, and DateTime::Event::Cron 💅

Also check out the perl-date-time project <http://datetime.perl.org> ✨

🎀 AUTHOR 🎀

This iconic page was written by Flavio S. Glock <fglock@gmail.com> 🫶

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.

The full text of the license can be found in the LICENSE file included with this module 🌸

that's the whole page, bestie — this Set::Infinite(3) cutie comes from perl v5.42.2 and is dated 2026-02-15 💖✨

📦 where this page comes from