* make a Recurrence::Set class - elements can be sets

    * compare
    * size - accept a function; use as_list
    * as_list
    * contains( $set )
    * stringify 
    * set_start / set_end
   
    * remove "difference()" method ?
    
    * cleanup extra "is copy"
    
    * remove "arbitrary_limit" if possible

    * iterator / map / grep 

----------- not implemented or tested ------------------

- `new( closure_next => sub {...} )`

Creates a recurrence set where only methods `start()` and `next($x)` are enabled.

XXX - add tests

- `new( closure_previous => sub {...} )`

Creates a recurrence set where only methods `end()`, `previous($x)` are enabled.

XXX - add tests

- `new( closure_next => sub {...}, universe => $universal_set )` - `new( closure_previous => sub {...}, universe => $universal_set )`

Create a recurrence set with full bidirectional functionality.

The complementary functions are emulated using iterations.

See also the section "UNIVERSAL SET CONSTRUCTOR".

XXX - add tests

- `new( closure_next => sub {...}, closure_previous => sub {...} )`

Creates a bidirectional recurrence set.

These methods are disabled: complement(), difference($set)

XXX - add tests

---------------- end TODO -------------------

= NAME

Recurrence - An object representing an infinite recurrence set

= SYNOPSIS

    use Recurrence;

    # all integer numbers
    $universe = Recurrence.new( 
        closure_next =>     sub { $_ + 1 },
        closure_previous => sub { $_ - 1 },
        :is_universe(1) );

    # all even integers
    $even_numbers = Recurrence.new( 
        closure_next =>     sub { 2 * int( $_ / 2 ) + 2     },
        closure_previous => sub { 2 * int( ( $_ - 1 ) / 2 ) },
        universe => $universe );

    # all odd integers
    $odd_numbers = $even_numbers.complement;

    # all non-zero integers
    $non_zero = Recurrence.new( 
        closure_next =>        sub ($x) { $x == -1 ??  1 :: $x + 1 },
        closure_previous =>    sub ($x) { $x ==  1 ?? -1 :: $x - 1 },
        complement_next =>     sub ($x) { $x < 0   ??  0 ::    Inf },
        complement_previous => sub ($x) { $x > 0   ??  0 ::   -Inf },
    );

= DESCRIPTION

This class handles an infinite recurrence set, defined with closures.

A recurrence set is defined by a "successor" function and a "predecessor" function.

Recurrence sets can be combined with union, intersection, difference, and a few other operations.

This class also provides methods for iterating through the set, and for querying set properties.

Note that all set functions may end up being calculated using iterations, which can be slow. Set functions might also fail and emit warnings in some cases.

= CONSTRUCTORS

- `new( closure_next => sub {...}, closure_previous => sub {...}, universe => $universe )`

Creates a recurrence set.

The complementary functions are emulated using iterations.

See also the section "UNIVERSAL SET CONSTRUCTOR".

- `new( closure_next => sub {...}, closure_previous => sub {...}, complement_next => sub {...}, complement_previous => sub {...} )`

Creates a recurrence set. The complement set is specified with a recurrence.

= UNIVERSAL SET CONSTRUCTOR

- `new( closure_next => sub {...}, closure_previous => sub {...}, :is_universe(1) )`

Creates a "universal set".

The complement set of the universe is an empty set.

`:is_universe` must be set if this recurrence is a "universal set". Otherwise the program will emit warnings during the execution of some methods, because it will try to iterate to find a "complement set" that is empty.

= SET FUNCTIONS

- `get_universe()`

Returns the "universal set" recurrence object.

- `complement()`

Returns everything (from the universal set) that is not in this recurrence.

- `union( $recurrence )`

Returns all elements both from this recurrence and from the given recurrence.

- `intersection( $recurrence )`

Returns only the elements in this recurrence that are also in the given recurrence.

- `difference( $recurrence )`

Returns only the elements in this recurrence that are not in the given recurrence.

- `intersects( $recurrence )`

Returns true if this recurrence intersects (has any element in common) with the given recurrence.

= SCALAR FUNCTIONS

- `next( $x )`

Returns the element in the recurrence that is right after the parameter.

- `previous( $x )`

Returns the element in the recurrence that is right before the parameter.

- `current( $x )`

Returns the parameter value if the parameter is a member of the recurrence. Otherwise, returns the previous element in the recurrence.

- `contains( $x )`

Returns true if the parameter is a member of the recurrence set.

- `closest( $x )`

Returns the element in the recurrence that is closest to the parameter. If both previous and next elements are at the same distance, returns the previous one.

- `is_empty()`

Returns true if the recurrence is an empty set.

- `is_infinite()`

Returns true if the recurrence is infinite.

- `start()`

Returns the start element in the recurrence.

Returns negative infinite if the recurrence is infinite. Returns positive infinite if the recurrence is an empty set.

- `end()`

Returns the last element in the recurrence.

Returns positive infinite if the recurrence is infinite. Returns negative infinite if the recurrence is an empty set.

= ARITHMETIC FUNCTIONS

- `negate`

Negates all elements in the recurrence ( $x = -$x )

= SEE ALSO

    Span
    
    Set::Infinite

= AUTHOR

Flavio S. Glock, <fglock@pucrs.br>

= 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