001    // --- BEGIN LICENSE BLOCK ---
002    /* 
003     * Copyright (c) 2009, Mikio L. Braun
004     * All rights reserved.
005     * 
006     * Redistribution and use in source and binary forms, with or without
007     * modification, are permitted provided that the following conditions are
008     * met:
009     * 
010     *     * Redistributions of source code must retain the above copyright
011     *       notice, this list of conditions and the following disclaimer.
012     * 
013     *     * Redistributions in binary form must reproduce the above
014     *       copyright notice, this list of conditions and the following
015     *       disclaimer in the documentation and/or other materials provided
016     *       with the distribution.
017     * 
018     *     * Neither the name of the Technische Universit?t Berlin nor the
019     *       names of its contributors may be used to endorse or promote
020     *       products derived from this software without specific prior
021     *       written permission.
022     * 
023     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
024     * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
025     * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
026     * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
027     * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
028     * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
029     * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
030     * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
031     * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
032     * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
033     * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
034     */
035    // --- END LICENSE BLOCK ---
036    
037    /*
038     * To change this template, choose Tools | Templates
039     * and open the template in the editor.
040     */
041    
042    package org.jblas.ranges;
043    
044    /**
045     * <p>The Range interface represents basically a set of indices. Before using a range
046     * you have to call init() with the actually available lower and upper bounds, such 
047     * that you can also have an "AllRange" which contains all possible indices.</p>
048     * 
049     * <p>Further operations include:</p>
050     * 
051     * <ul>
052     * <li> length() - returns total number of elements.
053     * <li> next() - increase counter (use value()) to retrieve the value.
054     * <li> index() - get the index of the current value.
055     * <li> value() - get the current value.
056     * <li> hasMore() - more indices available.
057     * </ul>
058     * 
059     * <p>Typical uses look like this:</p>
060     * <pre>    for (r.init(lower, upper); r.hasMore(); r.next()) {
061     *       System.out.printf("Value number %d is %d%n", index(), value());
062     *    }</pre>
063     */
064    public interface Range {
065        /** Initialize Range to available indices */
066        public void init(int lower, int upper);
067        /** Total number of indices. */
068        public int length();
069        /** Increase counter. */
070        public void next();
071        /** Consecutive numbering of current index. */
072        public int index();
073        /** Get current index. */
074        public int value();
075        /** More indices available? */
076        public boolean hasMore();
077    }