com.carrotsearch.hppcrt.ObjectContainer Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of hppcrt Show documentation

High Performance Primitive Collections Realtime (fork of HPPC from Carrotsearch) Fundamental data structures (maps, sets, lists, queues, heaps, sorts) generated for combinations of object and primitive types to conserve JVM memory and speed up execution. The Realtime fork intends to extend the existing collections, by tweaking to remove any dynamic allocations at runtime, and to obtain low variance execution times whatever the input nature.

There is a newer version: 0.7.5

Show newest version

package com.carrotsearch.hppcrt;

import java.util.Iterator;

import com.carrotsearch.hppcrt.cursors.ObjectCursor;
import com.carrotsearch.hppcrt.predicates.ObjectPredicate;
import com.carrotsearch.hppcrt.procedures.ObjectProcedure;

/**
 * A generic container holding Objects. An overview of interface relationships
 * is given in the figure below:
 * 
 * 
 */
 @javax.annotation.Generated(
    date = "2016-01-27T20:51:53+0100",
    value = "KTypeContainer.java") 
public interface ObjectContainer extends Iterable>
{
    /**
     * Returns an iterator to a cursor traversing the collection. The order of traversal
     * is not defined. More than one cursor may be active at a time. The behavior of
     * iterators is undefined if structural changes are made to the underlying collection.
     * 
     * The iterator is implemented as a
     * cursor and it returns the same cursor instance on every call to
     * {@link Iterator#next()} (to avoid boxing of primitive types). To read the current
     * list's value (or index in the list) use the cursor's public fields. An example is
     * shown below.
     * 
     *      * for (ObjectCursor<Object> c : container) {
     *   System.out.println("index=" + c.index + " value=" + c.value);
     * }
     * 
     */
    @Override
    Iterator> iterator();

    /**
     * Lookup a given element in the container. This operation has no speed
     * guarantees (may be linear with respect to the size of this container).
     * 
     * @return Returns true if this container has an element
     * equal to e.
     */
    boolean contains(KType e);

    /**
     * Return the current number of elements in this container. The time for calculating
     * the container's size may take O(n) time, although implementing classes
     * should try to maintain the current size and return in constant time.
     */
    int size();

    /**
     * Return the maximum number of elements this container is guaranteed to hold without reallocating.
     * The time for calculating the container's capacity may take O(n) time.
     */
    int capacity();

    /**
     * True if there is no elements in the container,
     * equivalent to size() == 0
     */
    boolean isEmpty();

    /**
     * Copies all elements from this container to an array.
     * The returned array is sized to match exactly
     * the number of elements of the container.
     * If you need an array of the type identical with this container's generic type, use {@link #toArray(Class)}.
     * 
     * @see #toArray(Class)
     */
      
    Object[] toArray();

      

      
    /**
     * Copies all elements of this container to a dynamically created array of the given
     * component type. An {@link ArrayStoreException} may be thrown if this container's elements
     * are not assignable to the array's component type.
     *
     * The returned array is always a copy, regardless of the storage used by the container.
     * 
     * @throws ArrayStoreException
     */
     T[] toArray(Class componentClass);

      

    /**
     * Copies all elements of this container to an existing array of the same type.
     * @param target The target array must be large enough to hold all elements, i.e >= {@link #size()}.
     * @return Returns the target argument for chaining.
     */
    KType[] toArray(KType[] target);

    /**
     * Applies a procedure to all container elements. Returns the argument (any
     * subclass of {@link ObjectProcedure}. This lets the caller to call methods of the argument
     * by chaining the call (even if the argument is an anonymous type) to retrieve computed values,
     * for example (IntContainer):
     *      * int count = container.forEach(new IntProcedure() {
     *      int count; // this is a field declaration in an anonymous class.
     *      public void apply(int value) { count++; }}).count;
     * 
     */
    > T forEach(T procedure);

    /**
     * Applies a predicate to container elements, as long as the predicate
     * returns true. The iteration is interrupted otherwise.
     */
    > T forEach(T predicate);
}