org.chocosolver.util.iterators.ValueIterator Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of choco-solver Show documentation
There is a newer version: 4.10.17
/*
 * This file is part of choco-solver, http://choco-solver.org/
 *
 * Copyright (c) 2022, IMT Atlantique. All rights reserved.
 *
 * Licensed under the BSD 4-clause license.
 *
 * See LICENSE file in the project root for full license information.
 */
package org.chocosolver.util.iterators;

/**
 * An interface to declare values iterator.
 * 
 * A value iterator can be iterated in 2 ways: bottom-up (from lower bound to upper bound) 

 * and top-down (from upper bound to lower bound).

 * To iterate in bottom-up way, first call bottomUpInit(), then hasNext() and next().

 * To iterate in bottom-up way, first call topDownInit(), then hasPrevious() and previous().

 * 

 * Once a way is selected, using the wrong methods can lead to unexpected behaviour.
 * 

 * 
 * ValueIterator vit = ...;
 * vit.bottomUpInit();
 * while(vit.hasNext()){
 *    int v = vit.next();
 *    // operate on value v here
 * }
 * OR
 *  * ValueIterator vit = ...;
 * vit.topDownInit();
 * while(vit.hasPrevious()){
 *    int v = vit.previous();
 *    // operate on value v here
 * }
 *
 * @author Charles Prud'homme
 * @since 05/10/11
 */
public interface ValueIterator {

    /**
     * Prepare iteration from smallest value to highest value (using {@link #hasNext()} / {@link #next()})
     *      * ValueIterator vit = ...;
     * vit.bottomUpInit();
     * while(vit.hasNext()){
     *    int v = vit.next();
     *    // operate on value v here
     * }
     * OR
     *      */
    void bottomUpInit();

    /**
     * Prepare iteration from highest value to smallest value (using {@link #hasPrevious()} / {@link #previous()})
     *      * ValueIterator vit = ...;
     * vit.topDownInit();
     * while(vit.hasPrevious()){
     *    int v = vit.previous();
     *    // operate on value v here
     * }
     */
    void topDownInit();

    /**
     * Returns true if the iteration has more values. (In other
     * words, returns true if next would return valid value.)
     *      * ValueIterator vit = ...;
     * vit.bottomUpInit();
     * while(vit.hasNext()){
     *    int v = vit.next();
     *    // operate on value v here
     * }
     * OR
     *      *
     * @beware incompatible with {@link #hasPrevious()}
     *
     * @return true if the getIterator has more values.
     */
    boolean hasNext();

    /**
     * Returns true if the iteration has more ranges. (In other
     * words, returns true if previous would return a valid value.)
     *      * ValueIterator vit = ...;
     * vit.topDownInit();
     * while(vit.hasPrevious()){
     *    int v = vit.previous();
     *    // operate on value v here
     * }
     *
     * @beware incompatible with {@link #hasNext()}
     *
     * @return true if the getIterator has more values.
     */
    boolean hasPrevious();

    /**
     * Compute and return the next value.
     *      * ValueIterator vit = ...;
     * vit.bottomUpInit();
     * while(vit.hasNext()){
     *    int v = vit.next();
     *    // operate on value v here
     * }
     * OR
     *      *
     * @beware incompatible with {@link #previous()}
     *
     * @return the next element in the iteration.
     */
    int next();

    /**
     * Compute and return the previous value.
     *      * ValueIterator vit = ...;
     * vit.topDownInit();
     * while(vit.hasPrevious()){
     *    int v = vit.previous();
     *    // operate on value v here
     * }
     *
     * @beware incompatible with {@link #next()}
     *
     * @return the previous element in the iteration.
     */
    int previous();
}