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
042package 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 */
064public 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}