/*

  Copyright 2004-2008 Paul R. Holser, Jr.  All rights reserved.

  Licensed under the Academic Free License version 3.0

  */

 package jaggregate;

 import java.io.Serializable;

 import java.util.NoSuchElementException;

 import jaggregate.internal.Casting;

 import jaggregate.internal.ReadOnlySequences;

 import jaggregate.internal.number.OperableNumber;

 import static jaggregate.OrderedCollection.*;

 import static jaggregate.internal.ArgumentChecks.*;

 import static jaggregate.internal.Casting.*;

 import static jaggregate.internal.number.OperableNumberFactory.*;

 /**

  * Represents a collection whose <dfn>elements</dfn> form an arithmetic progression.

  * <p/>

  * Currently, all the derivatives of {@link Number} in JDK 5 that override

  * {@link Object#equals(Object) equals} for value equality are supported as type

  * arguments for this class.  This excludes the new {@link

  * java.util.concurrent.atomic.AtomicInteger AtomicInteger} and

  * {@link java.util.concurrent.atomic.AtomicLong AtomicLong}.

  * <p/>

  * This class does nothing to compensate for the inexact representation of primitive

  * floating-point values; keep this in mind when using intervals of {@code float} or

  * {@code double}.

  *

  * @param <E> a restriction on the kinds of numbers that can be in the interval

  * @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>

  * @version $Id: Interval.java,v 1.7 2008/10/03 19:01:23 pholser Exp $

  */

 public class Interval<E extends Number> extends AbstractCollection<E>

     implements ReadOnlySequence<E>, Serializable {

     private static final long serialVersionUID = -1L;

     private final OperableNumber<E> begin;

     private final OperableNumber<E> end;

     private final OperableNumber<E> step;

     private final int size;

     /**

      * Creates an interval representing an arithmetic progression from one number to

      * another, in increments of 1.

      * <p/>

      * The interval will be {@linkplain #isEmpty() empty} if {@code from > to}.

      *

      * @param from the {@linkplain #first() first} element in the interval

      * @param to the {@linkplain #last() last} element of the interval

      * @throws NullPointerException if either {@code from} or {@code to}

      * is {@code null}

      */

     public Interval( E from, E to ) {

         this( from, to, null );

     }

     /**

      * Creates an interval representing an arithmetic progression from one number to

      * another, with the given increment.

      * <p/>

      * {@code by} can be negative.

      * <p/>

      * Note that {@code to} is not necessarily an element in the interval.

      * The {@linkplain #last() last element} is given by:

      * <blockquote>

      *     {@code ( to - from ) / by * by + from}

      * </blockquote>

      * The interval will be {@linkplain #isEmpty() empty} if {@code from < to} and

      * {@code by < 0}, or if {@code from > to} and {@code by > 0}.

      *

      * @param from the {@linkplain #first() first} element in the interval

      * @param to the termination of the interval

      * @param by the increment to use to compute successive interval values.  If this is

      * {@code null}, it will be treated as 1.

      * @throws NullPointerException if either {@code from} or {@code to}

      * is {@code null}

      * @throws IllegalArgumentException if {@code by == 0}

      */

     public Interval( E from, E to, E by ) {

         ensureNotNull( from, "lower bound" );

         ensureNotNull( to, "upper bound" );

         OperableNumber<E> opFrom = cast( wrap( from ) );

         OperableNumber<E> opTo = cast( wrap( to ) );

         OperableNumber<E> opBy = by == null

             ? opTo.one()

             : Casting.<OperableNumber<E>>cast( wrap( by ) );

         if ( opBy.isZero() )

             throw new IllegalArgumentException( "zero step" );

         begin = opFrom;

         if ( isEmptyIntervalSpecified( opFrom, opTo, opBy ) )

             end = opTo;

         else

             end = opTo.minus( from ).dividedBy( opBy ).times( opBy ).plus( opFrom );

         step = opBy;

         size = computeSize();

     }

     /**

      * Creates an interval representing an arithmetic progression from one number to

      * another, in increments of 1.

      * <p/>

      * The interval will be {@linkplain #isEmpty() empty} if {@code from > to}.

      *

      * @param <T> the type of numbers in the interval

      * @param from the {@linkplain #first() first} element in the interval

      * @param to the {@linkplain #last() last} element of the interval

      * @return the new interval

      * @throws NullPointerException if either {@code from} or {@code to}

      * is {@code null}

      */

     public static <T extends Number> Interval<T> fromTo( T from, T to ) {

         return new Interval<T>( from, to );

     }

     /**

      * Creates an interval representing an arithmetic progression from one number to

      * another, with the given increment.

      * <p/>

      * {@code by} can be negative.

      * <p/>

      * Note that {@code to} is not necessarily an element in the interval.

      * The {@linkplain #last() last element} is given by:

      * {@code ( to - from ) / by * by + from}

      * <p/>

      * The interval will be {@linkplain #isEmpty() empty} if {@code from < to} and

      * {@code by < 0}, or if {@code from > to} and {@code by > 0}.

      *

      * @param <T> the type of numbers in the interval

      * @param from the {@linkplain #first() first} element in the interval

      * @param to the termination of the interval

      * @param by the increment to use to compute successive interval values.  If this is

      * {@code null}, it will be treated as 1.

      * @return the new interval

      * @throws NullPointerException if {@code from}, {@code to}, or {@code by} is

      * {@code null}

      * @throws IllegalArgumentException if {@code by == 0}

      */

     public static <T extends Number> Interval<T> fromToBy( T from, T to, T by ) {

         return new Interval<T>( from, to, by );

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public <R> ReadOnlySequence<R> collect(

         UnaryFunctor<? super E, ? extends R> transformer ) {

         return (ReadOnlySequence<R>) super.collect( transformer );

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public ReadOnlySequence<E> reject( UnaryCondition<? super E> discriminator ) {

         return (ReadOnlySequence<E>) super.reject( discriminator );

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public ReadOnlySequence<E> select( UnaryCondition<? super E> discriminator ) {

         return (ReadOnlySequence<E>) super.select( discriminator );

     }

     /**

      * {@inheritDoc}

      */

     public ReadOnlySequence<E> concat( ReadOnlySequence<? extends E> otherSequence ) {

         return ReadOnlySequences.concat( this, otherSequence );

     }

     /**

      * {@inheritDoc}

      */

     public E after( E target ) {

         if ( !includes( target ) )

             throw new NoSuchElementException();

         if ( step.isPositive() ) {

             if ( begin.greaterThan( target ) || end.lessThanOrEqualTo( target ) )

                 throw new NoSuchElementException();

         }

         else {

             if ( begin.lessThan( target ) || end.greaterThanOrEqualTo( target ) )

                 throw new NoSuchElementException();

         }

         return step.plus( target ).unwrapped();

     }

     /**

      * {@inheritDoc}

      */

     public E at( int index ) {

         OperableNumber<E> result = step.times( index ).plus( begin );

         if ( step.isPositive() ) {

             if ( begin.greaterThan( result ) || end.lessThan( result ) )

                 throw new IndexOutOfBoundsException();

         }

         else {

             if ( begin.lessThan( result ) || end.greaterThan( result ) )

                 throw new IndexOutOfBoundsException();

         }

         return result.unwrapped();

     }

     /**

      * {@inheritDoc}

      */

     public E before( E target ) {

         if ( !includes( target ) )

             throw new NoSuchElementException();

         if ( step.isPositive() ) {

             if ( begin.greaterThanOrEqualTo( target ) || end.lessThan( target ) )

                 throw new NoSuchElementException();

         }

         else {

             if ( begin.lessThanOrEqualTo( target ) || end.greaterThan( target ) )

                 throw new NoSuchElementException();

         }

         return step.negated().plus( target ).unwrapped();

     }

     /**

      * {@inheritDoc}

      */

     public ReadOnlySequence<E> copyRange( int start, int stop ) {

         return ReadOnlySequences.copyRange( this, start, stop );

     }

     /**

      * {@inheritDoc}

      */

     public ReadOnlySequence<E> copyWith( E newElement ) {

         return ReadOnlySequences.copyWith( this, newElement );

     }

     /**

      * {@inheritDoc}

      */

     public ReadOnlySequence<E> copyWithout( E oldElement ) {

         return ReadOnlySequences.copyWithout( this, oldElement );

     }

     /**

      * {@inheritDoc}

      */

     public int findFirst( UnaryCondition<? super E> discriminator ) {

         return ReadOnlySequences.findFirst( this, discriminator );

     }

     /**

      * {@inheritDoc}

      */

     public int findLast( UnaryCondition<? super E> discriminator ) {

         return ReadOnlySequences.findLast( this, discriminator );

     }

     /**

      * {@inheritDoc}

      */

     public void forEachInReverseDo( UnaryFunctor<? super E, ?> operation ) {

         ReadOnlySequences.forEachInReverseDo( this, operation );

     }

     /**

      * {@inheritDoc}

      */

     public E first() {

         if ( isEmpty() )

             throw new NoSuchElementException();

         return begin.unwrapped();

     }

     /**

      * {@inheritDoc}

      */

     public void forEachInRangeDo( int start, int stop,

         UnaryFunctor<? super E, ?> operation ) {

         ReadOnlySequences.forEachInRangeDo( this, start, stop, operation );

     }

     /**

      * {@inheritDoc}

      */

     public void forEachInRangeDoWithIndex( int start, int stop,

         BinaryFunctor<? super Integer, ? super E, ?> operation ) {

         ReadOnlySequences.forEachInRangeDoWithIndex( this, start, stop, operation );

     }

     /**

      * {@inheritDoc}

      */

     public int indexOf( E target ) {

         return ReadOnlySequences.indexOf( this, target );

     }

     /**

      * {@inheritDoc}

      */

     public int indexOf( ReadOnlySequence<? extends E> targetSequence, int start ) {

         return ReadOnlySequences.indexOf( this, targetSequence, start );

     }

     /**

      * {@inheritDoc}

      */

     public void doWithIndex( BinaryFunctor<? super Integer, ? super E, ?> operation ) {

         ReadOnlySequences.doWithIndex( this, operation );

     }

     /**

      * {@inheritDoc}

      */

     public E last() {

         if ( isEmpty() )

             throw new NoSuchElementException();

         return end.unwrapped();

     }

     /**

      * {@inheritDoc}

      */

     public ReadOnlySequence<E> reverse() {

         return ReadOnlySequences.reverse( this );

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public boolean equals( Object that ) {

         return ReadOnlySequences.areSequencesEqual( this, that );

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public int hashCode() {

         return ReadOnlySequences.hashCode( this );

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public String toString() {

         return ReadOnlySequences.toString( this );

     }

     /**

      * {@inheritDoc}

      */

     public <T> void doWithOthers( ReadOnlySequence<? extends T> otherSequence,

         BinaryFunctor<? super E, ? super T, ?> operation ) {

         ReadOnlySequences.doWithOthers( this, otherSequence, operation );

     }

     /**

      * {@inheritDoc}

      */

     public void forEachDo( UnaryFunctor<? super E, ?> operation ) {

         if ( step.isPositive() )

             forEachDoPositiveStep( operation );

         else

             forEachDoNegativeStep( operation );

     }

     private void forEachDoPositiveStep( UnaryFunctor<? super E, ?> operation ) {

         for ( OperableNumber<E> i = cast( wrap( begin.unwrapped() ) );

             i.lessThanOrEqualTo( end );

             i.incrementBy( step ) ) {

             operation.evaluate( i.unwrapped() );

         }

     }

     private void forEachDoNegativeStep( UnaryFunctor<? super E, ?> operation ) {

         for ( OperableNumber<E> i = cast( wrap( begin.unwrapped() ) );

             i.greaterThanOrEqualTo( end );

             i.incrementBy( step ) ) {

             operation.evaluate( i.unwrapped() );

         }

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public boolean includes( E target ) {

         if ( target == null )

             return false;

         boolean belowMinimumPositive =

             step.isPositive() && begin.greaterThan( target );

         boolean belowMinimumNegative =

             step.isNegative() && end.greaterThan( target );

         if ( belowMinimumPositive || belowMinimumNegative )

             return false;

         return begin.negated().plus( target ).modulo( step ).isZero();

     }

     /**

      * {@inheritDoc}

      */

     public int size() {

         return size;

     }

     /**

      * {@inheritDoc}

      */

     @Override

     protected ExtensibleCollection<E> newEmptyExtensibleCollection() {

         return newEmptyExtensibleResultCollection();

     }

     /**

      * {@inheritDoc}

      */

     @Override

     protected <R> ExtensibleCollection<R> newEmptyExtensibleResultCollection() {

         return emptyOrderedCollection();

     }

     private boolean isEmptyIntervalSpecified( OperableNumber<E> from,

         OperableNumber<E> to, OperableNumber<E> by ) {

         boolean emptyDescending = from.lessThan( to ) && by.isNegative();

         boolean emptyAscending = from.greaterThan( to ) && by.isPositive();

         return emptyDescending || emptyAscending;

     }

     private int computeSize() {

         if ( step.isPositive() && begin.greaterThan( end ) )

             return 0;

         if ( step.isNegative() && begin.lessThan( end ) )

             return 0;

         return end.minus( begin ).dividedBy( step ).plus( 1 ).unwrapped().intValue();

     }

 }