001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.functor.range;
018
019import java.util.Collection;
020
021/**
022 * Represent an interval of elements that varies from the <b>left limit</b>
023 * to the <b>right limit</b>. Each limit in this range is an {@link Endpoint
024 * Endpoint}. The left and the right limits can be <b>inclusive</b>
025 * (<b>bounded</b>, <b>closed</b>) or <b>exclusive</b> (<b>unbounded</b>,
026 * <b>open</b>).
027 * <p>
028 * The difference between each element within this range is called <b>step</b>.
029 * The step can be positive or negative, displaying whether the range elements
030 * are ascending or descending.
031 *
032 * @param <T> the type of elements held by this range.
033 * @param <S> the type of the step of this range.
034 * @see org.apache.commons.functor.range.Endpoint
035 * @since 1.0
036 * @version $Revision$ $Date$
037 */
038public interface Range<T extends Comparable<?>, S> extends Iterable<T> {
039
040    /**
041     * Default left bound type.
042     */
043    BoundType DEFAULT_LEFT_BOUND_TYPE = BoundType.CLOSED;
044
045    /**
046     * Default right bound type.
047     */
048    BoundType DEFAULT_RIGHT_BOUND_TYPE = BoundType.OPEN;
049
050    /**
051     * Get the left limit of this range.
052     *
053     * @return Endpoint
054     */
055    Endpoint<T> getLeftEndpoint();
056
057    /**
058     * Get the right limit of this range.
059     *
060     * @return Endpoint
061     */
062    Endpoint<T> getRightEndpoint();
063
064    /**
065     * Get the step between elements of this range.
066     *
067     * @return Number
068     */
069    S getStep();
070
071    /**
072     * Returns <code>true</code> if this range is empty.
073     *
074     * @return <code>true</code> if this range is empty
075     */
076    boolean isEmpty();
077
078    /**
079     * Returns <code>true</code> if this range contains the specified element.
080     *
081     * @param obj element whose presence is being tested in this range
082     * @return <code>true</code> if this range contains the specified element
083     */
084    boolean contains(T obj);
085
086    /**
087     * Returns <code>true</code> is this range contains all of the elements in
088     * the specified collection.
089     *
090     * @param col collection to be checked for the containment in this range
091     * @return <code>true</code> if this range contains all of the elements in
092     * the specified collection
093     */
094    boolean containsAll(Collection<T> col);
095}