Bugs:
    * Lazy lists are not implemented
    * Constructors should emit error messages if there are unknown parameters

  Tests:
    * unicode, overloading - ~ <=> 
    * compare - depends on finishing Set::Infinite::Functional.compare() 
      and Span::Code.compare()
    * contains
    * size
   
  Constructor:
    * new() from Array
   
  Methods:
    * set_start_open / set_start_closed
    * set_end_open / set_end_closed - better names ?
    * is_singleton
    * first_span/last_span; span_iterator
    * see also: Span.pm TODO

  Optimizations:
    * create a store for single elements (Span::Singleton)
    * use binary search instead of linear search

  From Perl5 version of Set::Infinite:
    * "backtracking"  
    * map / grep / intersected_spans / span 
    * recurrence of spans

  From "Set" API:
    * equal/not_equal
    * symmetric_difference
    * proper_subset
    * proper_superset
    * subset
    * superset
    * includes/member/has

= NAME

Set::Infinite - An object representing an ordered set of spans

= SYNOPSIS

  use Set::Infinite;

  my $set = Set::Infinite.new( spans => $span );

= DESCRIPTION

This class represents an ordered set of spans.

The problem this class solves is when you need do perform "set" operations on Span objects, that return lists of spans.

In this example, @span may contain zero, one, two, or three spans, depending on the contents of $span1 and $span2:

  @span = $span1.union( $span2 );
  say @span.map:{ .stringify }.join(",");

On the other hand, a Set::Infinite object is more practical to work with:

  $set = $set1.union( $set2 );
  say $set.stringify;

= CONSTRUCTORS

- `new()`

Without any parameters, returns an empty span.

- `new( objects => ( 1, 3, 9 ) )`

Creates a `Set::Infinite` object with a few elements.

- `new( spans => ( $span1, $span2 ) )`

Creates a `Set::Infinite` object using existing Span objects.

- `new( recurrence => $recurr )`

Creates a `Set::Infinite` object using an existing Recurrence object.

- `universal_set()`

Creates an object with a continuous span (-Inf..Inf).

- `empty_set()`

Creates an empty set.

= OBJECT METHODS

The following methods are available for Set::Infinite objects:

- `start()` / `end()`

Return the start or end value of the set.

These methods may return nothing if the set is empty.

- `start_is_open()` / `end_is_open()` / `start_is_closed()` / `end_is_closed()`

Return a logical value, whether the `start` or `end` values belong to the set ("closed") or not ("open").

- `size()`

Return the "size" of the set.

For example: if `start` and `end` are times, then `size` will be a duration.

If the set contains lazy recurrences, it may not be possible to calculate the set size.

- `contains( $object )` / `intersects( $object )`

These methods return a logical value.

The argument can be a Set::Infinite, a Span object, a Recurrence object, or a scalar value.

- `union( $object )` / `intersection( $span )` / `difference( $object )`

Returns a Set::Infinite.

The argument can be a Set::Infinite, a Span object, a Recurrence object, or a scalar value.

- `complement()`

Returns a Set::Infinite.

- `stringify()`

Return a string representation of the set.

- `compare( $object )`

Compares the sets numerically. Returns -1, 0, or 1.

The argument can be a Set::Infinite, a Span object, a Recurrence object, or a scalar value.

- `is_empty()`

Returns `true` if the set is empty.

- `is_infinite()`

Returns true if the start or the end of the set are Infinite.

= ITERATORS AND LIST OPERATIONS

- `spans()`

Returns a list of `Span` objects.

- `iterator()`

Returns an iterator:

    $iter = $set.iterator;
    say $i while $i = $iter.next;

The iterator has `next()`, `previous()`, `current()`, and `reset()` methods.

If the set is "continuous", this method emits a warning and returns undef.

- `lazy()`

Makes a lazy iterator:

    say $a while $a = $set.lazy;

= MUTATOR METHODS

- `add( $set )`

Includes new elements in the set

- `remove( $set )`

Removes elements from the set

= SEE ALSO

    Span
    
    Recurrence

= AUTHOR

Flavio S. Glock, <fglock@gmail.com>

= COPYRIGHT

Copyright (c) 2005, Flavio S. Glock. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Perl6::Pugs

perl -MCPAN -e shell
install Perl6::Pugs