Package uk.ac.rdg.resc.edal.util

Class TimeUtils

  • public class TimeUtils
extends Object

    Collection of static utility methods that are useful for dealing with time-related types.

    Author:
    Guy Griffiths, Jon Blower

    • Field Detail

      • TIME_POSITION_COMPARATOR

        public static final Comparator<org.joda.time.DateTime> TIME_POSITION_COMPARATOR

        A Comparator that compares DateTime objects based only on their millisecond instant values. This can be used for sorting or searching Lists of DateTime objects.

        The ordering defined by this Comparator is inconsistent with equals because it ignores the Chronology of the DateTime instants.

        (Note: The DateTime object inherits from Comparable, not Comparable<DateTime>, so we can't use the methods in Collections directly. However we can reuse the AbstractInstant.compareTo(java.lang.Object) method.)

    • Method Detail

      • dateTimeToISO8601

        public static String dateTimeToISO8601​(org.joda.time.DateTime dateTime)
        Converts a DateTime object into an ISO8601-formatted String.

      • iso8601ToDateTime

        public static org.joda.time.DateTime iso8601ToDateTime​(String isoDateTime,
                                                       org.joda.time.Chronology chronology)
                                                throws BadTimeFormatException
        Converts an ISO8601-formatted String into a DateTime object
        Throws:
        BadTimeFormatException - if the string is not a valid ISO8601 date (with optional time), or if it is not valid within the Chronology (e.g. 31st July in a 360-day calendar).

      • findTimeIndex

        public static int findTimeIndex​(List<org.joda.time.DateTime> dtList,
                                org.joda.time.DateTime target)
        Searches the given list of timesteps for the specified date-time using the binary search algorithm. Matches are found based only upon the millisecond instant of the target DateTime, not its Chronology.
        Parameters:
        target - The timestep to search for.
        Returns:
        the index of the search key, if it is contained in the list; otherwise, (-(insertion point) - 1). The insertion point is defined as the point at which the key would be inserted into the list: the index of the first element greater than the key, or list.size() if all elements in the list are less than the specified key. Note that this guarantees that the return value will be >= 0 if and only if the key is found. If this Layer does not have a time axis this method will return -1.

      • formatUtcIsoTimeOnly

        public static String formatUtcIsoTimeOnly​(org.joda.time.DateTime dateTime)
        Formats a DateTime as the time only in ISO format Time zone offset is zero (UTC).

      • formatUtcTimeOnly

        public static String formatUtcTimeOnly​(org.joda.time.DateTime dateTime)
        Formats a DateTime as the time only in the format "HH:mm:ss", e.g. "14:53:03". Time zone offset is zero (UTC).

      • formatUtcHumanReadableDateTime

        public static String formatUtcHumanReadableDateTime​(org.joda.time.DateTime dateTime)
        Formats a DateTime in a nice human-readable manner.

      • formatUtcDateOnly

        public static String formatUtcDateOnly​(org.joda.time.DateTime dateTime)
        Formats a DateTime as the date only in the format "yyyy-MM-dd", e.g. "2018-01-01". Time zone offset is zero (UTC).

      • getTimeStringForCapabilities

        public static String getTimeStringForCapabilities​(List<org.joda.time.DateTime> times)

        Returns a string representing the given List of DateTimes, suitable for inclusion in a Capabilities document. For regularly-spaced data, this will return a string of the form "start/stop/period". For irregularly-spaced data this will return the times as a comma-separated list. For lists with some regular and some irregular spacings, this will use a combination of both approaches.

        All DateTimes in the provided list are assumed to be in the same Chronology as the first element of the list. If this is not the case, undefined behaviour may result.

        Parameters:
        times - The List of DateTimes to convert to a String. If this List contains no entries, an empty string will be returned.
        Returns:
        a string representing the given List of DateTimes, suitable for inclusion in a Capabilities document.
        Throws:
        NullPointerException - if times == null

      • getPeriodString

        public static String getPeriodString​(long period)

        Gets a representation of the given period as an ISO8601 string, e.g. "P1D" for one day, "PT3.5S" for 3.5s.

        For safety, this will only express periods in days, hours, minutes and seconds. These are the only durations that are constant in their millisecond length across different Chronologies. (Years and months can be different lengths between and within Chronologies.)

        Parameters:
        period - The period in milliseconds
        Returns:
        a representation of the given period as an ISO8601 string

      • getTimeRangeForString

        public static Extent<org.joda.time.DateTime> getTimeRangeForString​(String timeString,
                                                                   org.joda.time.Chronology chronology)
                                                            throws BadTimeFormatException
        Converts a time string into time range.
        Parameters:
        timeString - A string contining comma-separated times/ranges of time
        chronology - The Chronology of the time string
        Returns:
        An Extent representing the range of times found
        Throws:
        BadTimeFormatException - If any of the individual times are incorrectly formatted for ISO8601

      • onSameDay

        public static boolean onSameDay​(org.joda.time.DateTime dt1,
                                org.joda.time.DateTime dt2)
        Tests if two DateTimes fall on the same day.
        Parameters:
        dt1 - The first DateTime. The second DateTime will be converted to have the same time zone as this one
        dt2 - The second DateTime.
        Returns:
        true if the two given DateTimes fall on the same day.

      • getUnitLengthSeconds

        public static int getUnitLengthSeconds​(String unit)
        Parameters:
        unit - A string representing the unit. This accepts seconds, minutes, hours and days, and should be constant across calendar systems.
        Returns:
        The length of the given unit in seconds.