org.chocosolver.util.iterators.RangeIterator 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
Open-source constraint solver.
The newest version!
/*
 * This file is part of choco-solver, http://choco-solver.org/
 *
 * Copyright (c) 2024, 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 range iterator.
 * 
 * A range 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.
 * 

 * 
 * RangeIterator rit = ...;
 * rit.bottomUpInit();
 * while (rit.hasNext()) {
 *     int from = rit.min();
 *     int to = rit.max();
 *     // operate on range [from,to] here
 *     rit.next();
 * }
 *
 * OR
 *
 *  * DisposableRangeIterator rit = ...;
 * rit.topDownInit();
 * while (rit.hasPrevious()) {
 *     int from = rit.min();
 *     int to = rit.max();
 *     // operate on range [from,to] here
 *     rit.previous();
 * }
 *
 * 

 * Based on 
"Views and Iterators for Generic Constraint Implementations" 

 * C. Shulte and G. Tack.

 * Eleventh International Conference on Principles and Practice of Constraint Programming
 * 

 *
 * @author Charles Prud'homme
 * @since 05/10/11
 */
public interface RangeIterator {

    void bottomUpInit();

    void topDownInit();

    /**
     * Returns true if the iteration has more ranges. (In other
     * words, returns true if next would return a valid range.)
     *
     * @return true if the getIterator has more ranges.
     */
    boolean hasNext();

    /**
     * Returns true if the iteration has more ranges. (In other
     * words, returns true if previous would return a valid range.)
     *
     * @return true if the getIterator has more ranges.
     */
    boolean hasPrevious();

    /**
     * Compute the next range.
     */
    void next();

    /**
     * Compute the previous range.
     */
    void previous();

    /**
     * Return the lower bound of the current range (inclusive)
     *
     * @return lower bound of the current range
     */
    int min();

    /**
     * Return the upper bound of the current range (inclusive)
     *
     * @return upper bound of the current range
     */
    int max();
}