org.rrd4j.core.timespec

## Class TimeSpec

- java.lang.Object
- - org.rrd4j.core.timespec.TimeSpec

-     public class TimeSpec
      extends Object

  Represents time specifications parsed from at-style date strings.

  This class stores the result of parsing time specifications in the format used by RRDTool and described in detail on the rrdfetch man page. It supports both absolute timestamps and relative time adjustments.

  Time specification types:
  - Absolute time: Specific date and time (e.g., "Jan 1 2023 12:00")
  - Relative time: Offsets from reference time (e.g., "now-2hours")
  - Start/End markers: Relative to another time spec (e.g., "start+1day")

  Common usage patterns:

       // Absolute time examples
       TimeParser p1 = new TimeParser("Jan 1 2023");
       TimeParser p2 = new TimeParser("12:30");
       TimeParser p3 = new TimeParser("2023/01/01 12:30:45");

       // Relative time examples
       TimeParser p4 = new TimeParser("now-1day");      // Yesterday
       TimeParser p5 = new TimeParser("now+2hours30min"); // 2.5 hours from now
       TimeParser p6 = new TimeParser("tomorrow");       // Tomorrow at midnight
       TimeParser p7 = new TimeParser("noon");           // Today at 12:00

       // Range examples
       TimeParser p8 = new TimeParser("start");           // Start of range
       TimeParser p9 = new TimeParser("end+1week");      // End of range + 1 week

  See `TimeParser` for complete syntax reference and parsing details.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) TimeSpec` | `context`
    `(package private) String` | `dateString`
    `(package private) int` | `day`
    `(package private) int` | `dday`
    `(package private) int` | `dhour`
    `(package private) int` | `dmin`
    `(package private) int` | `dmonth`
    `(package private) int` | `dsec`
    `(package private) int` | `dyear`
    `(package private) int` | `hour`
    `(package private) int` | `min`
    `(package private) int` | `month`
    `(package private) int` | `sec`
    `(package private) int` | `type`
    `(package private) static int` | `TYPE_ABSOLUTE`
    `(package private) static int` | `TYPE_END`
    `(package private) static int` | `TYPE_START`
    `(package private) int` | `wday`
    `(package private) int` | `year`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TimeSpec(String dateString)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) String` | `dump()` Returns a debug string representation of this TimeSpec.
    `(package private) GregorianCalendar` | `getTime()`
    `static Calendar[]` | `getTimes(TimeSpec spec1, TimeSpec spec2)` Use this static method to resolve relative time references and obtain the corresponding Calendar objects.
    `long` | `getTimestamp()` Returns the corresponding timestamp (seconds since Epoch).
    `static long[]` | `getTimestamps(TimeSpec spec1, TimeSpec spec2)` Use this static method to resolve relative time references and obtain the corresponding timestamps (seconds since epoch).
    `(package private) void` | `localtime(long timestamp)` Initializes this TimeSpec with local time components from a timestamp.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### context

          TimeSpec context

    - #### dateString

          final String dateString

    - #### day

          int day

    - #### dday

          int dday

    - #### dhour

          int dhour

    - #### dmin

          int dmin

    - #### dmonth

          int dmonth

    - #### dsec

          int dsec

    - #### dyear

          int dyear

    - #### hour

          int hour

    - #### min

          int min

    - #### month

          int month

    - #### sec

          int sec

    - #### type

          int type

    - #### TYPE_ABSOLUTE

          static final int TYPE_ABSOLUTE

      See Also:
        Constant Field Values

    - #### TYPE_END

          static final int TYPE_END

      See Also:
        Constant Field Values

    - #### TYPE_START

          static final int TYPE_START

      See Also:
        Constant Field Values

    - #### wday

          int wday

    - #### year

          int year

  - ### Constructor Detail

    - #### TimeSpec

          TimeSpec(String dateString)

  - ### Method Detail

    - #### dump

          String dump()

      Returns a debug string representation of this TimeSpec.

      This method formats the TimeSpec for debugging purposes, showing both the absolute time components and the relative delta components in a compact format.

      Returns:
        debug string showing type and all time components

    - #### getTime

          GregorianCalendar getTime()

    - #### getTimes

          public static Calendar[] getTimes(TimeSpec spec1,
                                            TimeSpec spec2)

      Use this static method to resolve relative time references and obtain the corresponding Calendar objects. Example:

           TimeParser pStart = new TimeParser("now-1month"); // starting time
           TimeParser pEnd = new TimeParser("start+1week");  // ending time
           TimeSpec specStart = pStart.parse();
           TimeSpec specEnd = pEnd.parse();
           GregorianCalendar[] gc = TimeSpec.getTimes(specStart, specEnd);

      Parameters:
        `spec1` - Starting time specification
        `spec2` - Ending time specification
      Returns:
        Two element array containing Calendar objects

    - #### getTimestamp

          public long getTimestamp()

      Returns the corresponding timestamp (seconds since Epoch). Example:

           TimeParser p = new TimeParser("now-1day");
           TimeSpec ts = p.parse();
           System.out.println("Timestamp was: " + ts.getTimestamp();

      Returns:
        Timestamp (in seconds, no milliseconds)

    - #### getTimestamps

          public static long[] getTimestamps(TimeSpec spec1,
                                             TimeSpec spec2)

      Use this static method to resolve relative time references and obtain the corresponding timestamps (seconds since epoch). Example:

           TimeParser pStart = new TimeParser("now-1month"); // starting time
           TimeParser pEnd = new TimeParser("start+1week");  // ending time
           TimeSpec specStart = pStart.parse();
           TimeSpec specEnd = pEnd.parse();
           long[] ts = TimeSpec.getTimestamps(specStart, specEnd);

      Parameters:
        `spec1` - Starting time specification
        `spec2` - Ending time specification
      Returns:
        array containing two timestamps (in seconds since epoch)

    - #### localtime

          void localtime(long timestamp)

      Initializes this TimeSpec with local time components from a timestamp.

      This helper method converts a Unix timestamp (seconds since epoch) into individual time components (year, month, day, hour, minute, second) and day of week. This is used to establish a baseline time for relative time calculations.

      Parameters:
        `timestamp` - Unix timestamp in seconds since epoch