001/*
002 * Units of Measurement Reference Implementation
003 * Copyright (c) 2005-2024, Jean-Marie Dautelle, Werner Keil, Otavio Santana.
004 *
005 * All rights reserved.
006 *
007 * Redistribution and use in source and binary forms, with or without modification,
008 * are permitted provided that the following conditions are met:
009 *
010 * 1. Redistributions of source code must retain the above copyright notice,
011 *    this list of conditions and the following disclaimer.
012 *
013 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions
014 *    and the following disclaimer in the documentation and/or other materials provided with the distribution.
015 *
016 * 3. Neither the name of JSR-385, Indriya nor the names of their contributors may be used to endorse or promote products
017 *    derived from this software without specific prior written permission.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
022 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
023 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
026 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package tech.units.indriya.spi;
031
032import tech.uom.lib.common.function.MaximumSupplier;
033import tech.uom.lib.common.function.MinimumSupplier;
034
035/**
036 * A Range is a pair of <code>T</code> items that represent a range of values.
037 * <p>
038 * 
039 * <dl>
040 * <dt><span class="strong">API Note:</span></dt><dd>This interface places no restrictions on the mutability of
041 *          implementations, however immutability is strongly recommended. All
042 *          implementations should be {@link Comparable}.</dd>
043 * </dl>
044 * 
045 * @param <T>
046 *          The value of the range.
047 * 
048 * @author <a href="mailto:werner@units.tech">Werner Keil</a>
049 * @version 2.0, August 23, 2023
050 * @since 1.0
051 * @see <a href="http://en.wikipedia.org/wiki/Range">Wikipedia: Range</a>
052 */
053public interface Range<T> extends MinimumSupplier<T>, MaximumSupplier<T> {
054  // XXX do we keep null for min and max to represent infinity?
055
056  /**
057   * Returns the smallest value of the range. The value is the same as that given as the constructor parameter for the smallest value.
058   * 
059   * @return the minimum value
060   */
061  public T getMinimum();
062
063  /**
064   * Returns the largest value of the range. The value is the same as that given as the constructor parameter for the largest value.
065   * 
066   * @return the maximum value
067   */
068  public T getMaximum();
069
070  /**
071   * Returns the resolution of the range. The value is the same as that given as the constructor parameter for the largest value.
072   * 
073   * @return resolution of the range, the value is the same as that given as the constructor parameter for the resolution
074   */
075  public T getResolution();
076
077  /**
078   * Method to easily check if {@link #getMinimum()} is not {@code null}.
079   * 
080   * @return {@code true} if {@link #getMinimum()} is not {@code null} .
081   */
082  public boolean hasMinimum();
083
084  /**
085   * Method to easily check if {@link #getMaximum()} is not {@code null}.
086   * 
087   * @return {@code true} if {@link #getMaximum()} is not {@code null}.
088   */
089  public boolean hasMaximum();
090
091  /**
092   * Checks whether the given <code>T</code> is within this range
093   * 
094   * @param t
095   * @return true if the value is within the range
096   */
097  public abstract boolean contains(T t);
098}