/*

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

  Licensed under the Academic Free License version 3.0

  */

 package jaggregate;

 import java.io.IOException;

 import java.io.ObjectInputStream;

 import java.io.ObjectOutputStream;

 import jaggregate.internal.Casting;

 import static jaggregate.internal.ArgumentChecks.*;

 /**

  * Represents an unordered, variable-sized collection whose <dfn>elements</dfn> can be

  * added or removed, but cannot be individually accessed by external <dfn>keys</dfn>.

  * <p/>

  * A bag is similar to a {@linkplain Set set} but can contain duplicate elements.

  * Elements are duplicates if they are <dfn>equivalent</dfn>.

  *

  * @param <E> a restriction on the types of elements that may be contained in the bag

  *

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

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

  */

 public abstract class AbstractBag<E> extends AbstractExtensibleCollection<E> {

     private transient AbstractDictionary<E, Integer> storage;

     private transient int numberOfElements;

     /**

      * Creates an empty bag.

      */

     protected AbstractBag() {

         initialize( 0 );

     }

     /**

      * Creates a bag containing the elements in the given collection.

      *

      * @param elements elements to add to the new bag

      * @throws NullPointerException if {@code elements} is {@code null}

      */

     protected AbstractBag( Collection<? extends E> elements ) {

         this();

         addAll( elements );

     }

     /**

      * Creates a bag containing the elements in the given array.

      *

      * @param elements elements to add to the new bag

      * @throws NullPointerException if {@code elements} is {@code null}

      */

     protected AbstractBag( E... elements ) {

         this();

         addAll( elements );

     }

     /**

      * Creates a bag containing the elements in the given iterable object.

      *

      * @param elements elements to add to the new bag

      * @throws NullPointerException if {@code elements} is {@code null}

      */

     protected AbstractBag( Iterable<? extends E> elements ) {

         this();

         addAll( elements );

     }

     /**

      * {@inheritDoc}

      *

      * @return a bag of results

      */

     @Override

     public <R> AbstractBag<R> collect(

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

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

     }

     /**

      * {@inheritDoc}

      */

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

         ensureNotNull( operation, OPERATION );

         storage.keysAndValuesDo( new BinaryFunctor<E, Integer, Void>() {

             public Void evaluate( E first, Integer second ) {

                 for ( int i = 0; i < second; ++i )

                     operation.evaluate( first );

                 return null;

             }

         } );

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public boolean includes( E target ) {

         return storage.includesKey( target );

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public int occurrencesOf( E target ) {

         Integer occurrences = storage.at( target );

         return occurrences == null ? 0 : occurrences;

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public void rehash() {

         storage.rehash();

     }

     /**

      * {@inheritDoc}

      *

      * @return a bag of rejects

      */

     @Override

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

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

     }

     /**

      * {@inheritDoc}

      *

      * @return a bag of selections

      */

     @Override

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

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

     }

     /**

      * {@inheritDoc}

      */

     public int size() {

         return numberOfElements;

     }

     /**

      * {@inheritDoc}

      */

     public void add( E newElement ) {

         add( newElement, 1 );

     }

     /**

      * Adds the given element to this bag a given number of times.

      *

      * @see #add(Object)

      * @param newElement the element to add

      * @param occurrences number of times to add {@code newElement}

      * @throws IllegalArgumentException if {@code occurrences} is negative

      */

     public void add( E newElement, int occurrences ) {

         if ( occurrences < 0 )

             throw new IllegalArgumentException(

                 "illegal non-negative oldOccurrences: " + occurrences );

         Integer oldOccurrences = storage.at( newElement );

         storage.putAt( newElement,

             oldOccurrences == null ? occurrences : oldOccurrences + occurrences );

         numberOfElements += occurrences;

     }

     /**

      * {@inheritDoc}

      */

     public boolean remove( E oldElement ) {

         Integer occurrences = storage.at( oldElement );

         if ( occurrences != null ) {

             if ( occurrences == 1 )

                 storage.removeKey( oldElement );

             else

                 storage.putAt( oldElement, occurrences - 1 );

             --numberOfElements;

             return true;

         }

         return false;

     }

     /**

      * {@inheritDoc}

      * <p/>

      * An object is considered equivalent to this bag if the object is assignable to

      * this bag's class and has equivalent contents, as defined by this bag's notion of

      * equivalence.

      */

     @Override

     public boolean equals( Object that ) {

         if ( this == that )

             return true;

         if ( !getImplementationClass().isInstance( that ) )

             return false;

         AbstractBag<?> other = (AbstractBag<?>) that;

         return storage.equals( other.storage );

     }

     /**

      * Subclasses implement this method to answer the root of its true runtime class,

      * for purposes of determining {@linkplain #equals(Object) equivalence}.

      *

      * @return this bag's implementation class

      */

     protected abstract Class<? extends AbstractBag> getImplementationClass();

     /**

      * {@inheritDoc}

      */

     @Override

     public int hashCode() {

         return storage.hashCode();

     }

     /**

      * {@inheritDoc}

      */

     @Override

     public String toString() {

         final StringBuilder buffer = new StringBuilder( "[" );

         if ( !isEmpty() ) {

             forEachDo( new UnaryFunctor<E, Void>() {

                 public Void evaluate( E argument ) {

                     buffer.append( asString( argument ) ).append( ',' );

                     return null;

                 }

             } );

             buffer.deleteCharAt( buffer.length() - 1 );

         }

         buffer.append( ']' );

         return buffer.toString();

     }

     /**

      * Answers a new, empty storage for the bag.

      *

      * @return a new, empty dictionary

      */

     protected abstract AbstractDictionary<E, Integer> newEmptyStorage();

     /**

      * Tells how the given element will show up in this bag's string representation.

      *

      * @param anElement an element of this collection

      * @return a string representation of {@code anElement} to be used in this bag's

      * string representation

      */

     protected abstract String asString( E anElement );

     /**

      * Serialization helper method.

      *

      * @param output stream to write object state to

      * @throws IOException if an I/O problem occurs during serialization

      */

     protected final void serializeTo( ObjectOutputStream output ) throws IOException {

         output.defaultWriteObject();

         output.writeInt( numberOfElements );

         output.writeObject( storage );

     }

     /**

      * De-serialization helper method.

      *

      * @param input stream to read object state from

      * @throws IOException if an I/O problem occurs during de-serialization

      * @throws ClassNotFoundException if a class that is necessary for de-serialization

      * cannot be found

      */

     protected final void deserializeFrom( ObjectInputStream input )

         throws IOException, ClassNotFoundException {

         input.defaultReadObject();

         initialize( input.readInt(),

             Casting.<AbstractDictionary<E, Integer>>cast( input.readObject() ) );

     }

     private void initialize( int size ) {

         initialize( size, newEmptyStorage() );

     }

     private void initialize( int size, AbstractDictionary<E, Integer> backingStore ) {

         numberOfElements = size;

         storage = backingStore;

     }

 }