javafx.util.Duration Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of javafx-base Show documentation
There is a newer version: 24-ea+15
/*
 * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javafx.util;

import java.io.Serializable;
import javafx.beans.NamedArg;

/**
 * 
 *     A class that defines a duration of time. Duration instances are immutable,
 *     and are therefore replaced rather than modified, similar to {@link java.math.BigDecimal}.
 *     Durations can be created using the constructor, or one of the static construction
 *     methods such as {@link #seconds} or {@link #minutes}.
 * 
 * @since JavaFX 2.0
 */
public class Duration implements Comparable, Serializable {
    /**
     * A Duration of 0 (no time).
     */
    public static final Duration ZERO = new Duration(0);

    /**
     * A Duration of 1 millisecond.
     */
    public static final Duration ONE = new Duration(1);

    /**
     * An Infinite Duration.
     */
    public static final Duration INDEFINITE = new Duration(Double.POSITIVE_INFINITY);

    /**
     * A Duration of some unknown amount of time.
     */
    public static final Duration UNKNOWN = new Duration(Double.NaN);

    /**
     * Factory method that returns a Duration instance for a specified
     * amount of time. The syntax is "[number][ms|s|m|h]".
     *
     * @param time A non-null string properly formatted. Leading or trailing
     * spaces will not parse correctly. Throws a NullPointerException if
     * time is null.
     * @return a Duration which is represented by the time
     */
    public static Duration valueOf(String time) {
        int index = -1;
        for (int i=0; iDuration.millis(50).negate() returns
     * a Duration of -50 milliseconds.
     * If the called Duration instance is INDEFINITE, return INDEFINITE.
     * This function does not change the value of the called Duration instance.
     *
     * @return the result of negating this duration. This is
     *         the same as -millis using double arithmetic
     */
    public Duration negate() {
        return millis(-millis);
    }

    /**
     * Gets whether this Duration instance is Indefinite. A Duration is Indefinite
     * if it equals Duration.INDEFINITE.
     * @return true if this Duration is equivalent to Duration.INDEFINITE or Double.POSITIVE_INFINITY.
     */
    public boolean isIndefinite() {
        return millis == Double.POSITIVE_INFINITY;
    }

    /**
     * Gets whether this Duration instance is Unknown. A Duration is Unknown
     * if it equals Duration.UNKNOWN.
     * @return true if this Duration is equivalent to Duration.UNKNOWN or Double.isNaN(millis)
     */
    public boolean isUnknown() {
        return Double.isNaN(millis);
    }

    /**
     * Returns true if the specified duration is less than (<) this instance.
     * INDEFINITE is treated as if it were positive infinity.
     *
     * @param other cannot be null
     * @return true if millis < other.millis using double arithmetic
     */
    public boolean lessThan(Duration other) {
        return millis < other.millis;
    }

    /**
     * Returns true if the specified duration is less than or equal to (<=) this instance.
     * INDEFINITE is treated as if it were positive infinity.
     *
     * @param other cannot be null
     * @return true if millis <= other.millis using double arithmetic
     */
    public boolean lessThanOrEqualTo(Duration other) {
        return millis <= other.millis;
    }

    /**
     * Returns true if the specified duration is greater than (>) this instance.
     * INDEFINITE is treated as if it were positive infinity.
     *
     * @param other cannot be null
     * @return true if millis > other.millis using double arithmetic
     */
    public boolean greaterThan(Duration other) {
        return millis > other.millis;
    }

    /**
     * Returns true if the specified duration is greater than or equal to (>=) this instance.
     * INDEFINITE is treated as if it were positive infinity.
     *
     * @param other cannot be null
     * @return true if millis >= other.millis using double arithmetic
     */
    public boolean greaterThanOrEqualTo(Duration other) {
        return millis >= other.millis;
    }

    /**
     * Returns a string representation of this {@code Duration} object.
     * @return a string representation of this {@code Duration} object.
     */
    @Override public String toString() {
        return isIndefinite() ? "INDEFINITE" : (isUnknown() ? "UNKNOWN" : millis + " ms");
    }

    /**
     * Compares durations represented by this object and the specified object.
     * Returns a negative integer, zero, or a positive integer as this duration
     * is less than, equal to, or greater than the specified duration.
     * @param d the duration to be compared.
     * @return a negative integer, zero, or a positive integer as this duration
     * is less than, equal to, or greater than the specified duration.
     */
    @Override public int compareTo(Duration d) {
        // Reuse the Double.compare implementation
        return Double.compare(millis, d.millis);
    }

    /**
     * Indicates whether some other object is "equal to" this one.
     * @param obj the reference object with which to compare.
     * @return {@code true} if this object is equal to the {@code obj} argument; {@code false} otherwise.
     */
    @Override public boolean equals(Object obj) {
        // Rely on Java's handling of double == double
        return obj == this || obj instanceof Duration && millis == ((Duration) obj).millis;
    }

    /**
     * Returns a hash code for this {@code Duration} object.
     * @return a hash code for this {@code Duration} object.
     */
    @Override public int hashCode() {
        // Uses the same implementation as Double.hashCode
        long bits = Double.doubleToLongBits(millis);
        return (int)(bits ^ (bits >>> 32));
    }
}