net.openhft.koloboke.collect.ObjCollection Maven / Gradle / Ivy

/*
 * Copyright 2014 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package net.openhft.koloboke.collect;

import java.util.function.Consumer;
import java.util.function.Predicate;
import javax.annotation.Nonnull;

import java.util.Collection;


/**
 * A collection of objects, the library's extension of the classic {@link Collection} interface.
 *
 * All methods of {@link Collection} interface defined in terms of elements equality and
 * referring to {@link Object#equals(Object)} method are supposed to use {@link #equivalence()}
 * in this interface. Thus in some sense {@code ObjCollection} violates general {@link Collection}
 * contract, but this approach provides a great flexibility. If you need strict {@link Collection}
 * implementation, you can always construct an {@code ObjCollection} with default equality,
 * i. e. {@code equivalence() == }{@link Equivalence#defaultEquality()}.
 *
 * 
See {@code Collection}
 * mutability matrix for methods which are supported by {@code ObjCollections} with the specific
 * mutability. All methods defined in this interface directly are supported
 * by {@code ObjCollections} with any mutability profile.
 *
 * @param  the type of elements in this collection
 */
public interface ObjCollection extends Collection, Container {

    /**
     * Returns the equivalence strategy for elements in this collection. All methods
     * in {@link Collection} interface which defined in terms of {@link Object#equals(Object)}
     * equality of elements, for example, {@link #contains(Object)} and {@link #remove(Object)},
     * are supposed to use this equivalence instead.
     *
     * @return the equivalence strategy for elements in this collection
     */
    @Nonnull
    Equivalence equivalence();


    /**
     * Checks the given {@code predicate} on each element of this collection until all element
     * have been processed or the predicate returns {@code false} for some element,
     * or throws an {@code Exception}. Exceptions thrown by the predicate are relayed to the caller.
     *
     * 
Unless otherwise specified by the implementing class, elements are checked
     * by the predicate in the order of iteration (if an iteration order is specified).
     *
     * If this collection is empty, this method returns {@code true} immediately.
     *
     * @return {@code true} if the predicate returned {@code true} for all elements of this
     *         collection, {@code false} if it returned {@code false} for the element
     * @param predicate the predicate to be checked for each element of this collection
     * @see 
     *     Comparison of iteration options in the library
     */
    boolean forEachWhile(@Nonnull Predicate predicate);

    /**
     * Returns a new cursor over this collection's elements. Cursor iteration order is always
     * corresponds to the {@linkplain #iterator() iterator}'s order.
     *
     * @return a new cursor over this collection's elements
     * @see 
     *     Comparison of iteration options in the library
     */
    @Nonnull
    ObjCursor cursor();

    /**
     * Returns a new iterator over this collection's elements.
     *
     * @return a new iterator over this collection's elements
     * @see 
     *     Comparison of iteration options in the library
     */
    @Override
    @Nonnull
    ObjIterator iterator();

}