001/*
002 * Copyright (C) 2009 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.collect;
018
019import com.google.common.annotations.Beta;
020import com.google.common.annotations.GwtCompatible;
021
022import java.util.NoSuchElementException;
023
024/**
025 * Static methods pertaining to {@link Range} instances.  Each of the
026 * {@link Range nine types of ranges} can be constructed with a corresponding
027 * factory method:
028 *
029 * <dl>
030 * <dt>{@code (a..b)}
031 * <dd>{@link #open}
032 * <dt>{@code [a..b]}
033 * <dd>{@link #closed}
034 * <dt>{@code [a..b)}
035 * <dd>{@link #closedOpen}
036 * <dt>{@code (a..b]}
037 * <dd>{@link #openClosed}
038 * <dt>{@code (a..+∞)}
039 * <dd>{@link #greaterThan}
040 * <dt>{@code [a..+∞)}
041 * <dd>{@link #atLeast}
042 * <dt>{@code (-∞..b)}
043 * <dd>{@link #lessThan}
044 * <dt>{@code (-∞..b]}
045 * <dd>{@link #atMost}
046 * <dt>{@code (-∞..+∞)}
047 * <dd>{@link #all}
048 * </dl>
049 *
050 * <p>Additionally, {@link Range} instances can be constructed by passing the
051 * {@link BoundType bound types} explicitly.
052 *
053 * <dl>
054 * <dt>Bounded on both ends
055 * <dd>{@link #range}
056 * <dt>Unbounded on top ({@code (a..+∞)} or {@code (a..+∞)})
057 * <dd>{@link #downTo}
058 * <dt>Unbounded on bottom ({@code (-∞..b)} or {@code (-∞..b]})
059 * <dd>{@link #upTo}
060 * </dl>
061 *
062 * <p>See the Guava User Guide article on <a href=
063 * "http://code.google.com/p/guava-libraries/wiki/RangesExplained">
064 * {@code Range}</a>.
065 *
066 * @author Kevin Bourrillion
067 * @author Gregory Kick
068 * @since 10.0
069 * @deprecated Use the corresponding method in {@link Range}.
070 */
071@Deprecated
072@GwtCompatible
073@Beta
074public final class Ranges {
075  private Ranges() {}
076
077  /**
078   * Returns a range that contains all values strictly greater than {@code
079   * lower} and strictly less than {@code upper}.
080   *
081   * @throws IllegalArgumentException if {@code lower} is greater than <i>or
082   *     equal to</i> {@code upper}
083   */
084  public static <C extends Comparable<?>> Range<C> open(C lower, C upper) {
085    return Range.open(lower, upper);
086  }
087
088  /**
089   * Returns a range that contains all values greater than or equal to
090   * {@code lower} and less than or equal to {@code upper}.
091   *
092   * @throws IllegalArgumentException if {@code lower} is greater than {@code
093   *     upper}
094   */
095  public static <C extends Comparable<?>> Range<C> closed(C lower, C upper) {
096    return Range.closed(lower, upper);
097  }
098
099  /**
100   * Returns a range that contains all values greater than or equal to
101   * {@code lower} and strictly less than {@code upper}.
102   *
103   * @throws IllegalArgumentException if {@code lower} is greater than {@code
104   *     upper}
105   */
106  public static <C extends Comparable<?>> Range<C> closedOpen(
107      C lower, C upper) {
108    return Range.closedOpen(lower, upper);
109  }
110
111  /**
112   * Returns a range that contains all values strictly greater than {@code
113   * lower} and less than or equal to {@code upper}.
114   *
115   * @throws IllegalArgumentException if {@code lower} is greater than {@code
116   *     upper}
117   */
118  public static <C extends Comparable<?>> Range<C> openClosed(
119      C lower, C upper) {
120    return Range.openClosed(lower, upper);
121  }
122
123  /**
124   * Returns a range that contains any value from {@code lower} to {@code
125   * upper}, where each endpoint may be either inclusive (closed) or exclusive
126   * (open).
127   *
128   * @throws IllegalArgumentException if {@code lower} is greater than {@code
129   *     upper}
130   */
131  public static <C extends Comparable<?>> Range<C> range(
132      C lower, BoundType lowerType, C upper, BoundType upperType) {
133    return Range.range(lower, lowerType, upper, upperType);
134  }
135
136  /**
137   * Returns a range that contains all values strictly less than {@code
138   * endpoint}.
139   */
140  public static <C extends Comparable<?>> Range<C> lessThan(C endpoint) {
141    return Range.lessThan(endpoint);
142  }
143
144  /**
145   * Returns a range that contains all values less than or equal to
146   * {@code endpoint}.
147   */
148  public static <C extends Comparable<?>> Range<C> atMost(C endpoint) {
149    return Range.atMost(endpoint);
150  }
151
152  /**
153   * Returns a range with no lower bound up to the given endpoint, which may be
154   * either inclusive (closed) or exclusive (open).
155   */
156  public static <C extends Comparable<?>> Range<C> upTo(
157      C endpoint, BoundType boundType) {
158    return Range.upTo(endpoint, boundType);
159  }
160
161  /**
162   * Returns a range that contains all values strictly greater than {@code
163   * endpoint}.
164   */
165  public static <C extends Comparable<?>> Range<C> greaterThan(C endpoint) {
166    return Range.greaterThan(endpoint);
167  }
168
169  /**
170   * Returns a range that contains all values greater than or equal to
171   * {@code endpoint}.
172   */
173  public static <C extends Comparable<?>> Range<C> atLeast(C endpoint) {
174    return Range.atLeast(endpoint);
175  }
176
177  /**
178   * Returns a range from the given endpoint, which may be either inclusive
179   * (closed) or exclusive (open), with no upper bound.
180   */
181  public static <C extends Comparable<?>> Range<C> downTo(
182      C endpoint, BoundType boundType) {
183    return Range.downTo(endpoint, boundType);
184  }
185
186  /** Returns a range that contains every value of type {@code C}. */
187  public static <C extends Comparable<?>> Range<C> all() {
188    return Range.all();
189  }
190
191  /**
192   * Returns a range that {@linkplain Range#contains(Comparable) contains} only
193   * the given value. The returned range is {@linkplain BoundType#CLOSED closed}
194   * on both ends.
195   */
196  public static <C extends Comparable<?>> Range<C> singleton(C value) {
197    return Range.singleton(value);
198  }
199
200  /**
201   * Returns the minimal range that
202   * {@linkplain Range#contains(Comparable) contains} all of the given values.
203   * The returned range is {@linkplain BoundType#CLOSED closed} on both ends.
204   *
205   * @throws ClassCastException if the parameters are not <i>mutually
206   *     comparable</i>
207   * @throws NoSuchElementException if {@code values} is empty
208   * @throws NullPointerException if any of {@code values} is null
209   */
210  public static <C extends Comparable<?>> Range<C> encloseAll(
211      Iterable<C> values) {
212    return Range.encloseAll(values);
213  }
214}