Compares two binary timestamps or two relative binary timestamps.

    Format

      #include <utc.h>

      int utc_cmpintervaltime(*relation, *utc1, *utc2)

         enum utc_cmptype *relation;
         const utc_t *utc1;
         const utc_t *utc2;

1 - Parameters

    Input

 utc1

    Binary timestamp or relative binary timestamp.

 utc2

    Binary timestamp or relative binary timestamp.

    Output

 relation

    Receives the result of the comparison of utc1:utc2, where the
    result is an enumerated type with one of the following values:

    o  utc_equalTo

    o  utc_lessThan

    o  utc_greaterThan

    o  utc_indeterminate

2 - Description

    The Compare Interval Time routine compares two binary timestamps
    and returns a flag indicating that the first time is greater
    than, less than, equal to, or overlapping with the second time.
    Two times overlap if the intervals (time - inaccuracy, time +
    inaccuracy) of the two times intersect.

    The input binary timestamps express two absolute or two relative
    times. Do not compare relative binary timestamps and binary
    timestamps. If you do, no meaningful results and no errors are
    returned.

    This routine does a temporal ordering of the time intervals.

    utc1 is utc_lessThan utc2 iff
            utc1.time + utc1.inacc < utc2.time - utc2.inacc

    utc1 is utc_greaterThan utc2 iff
            utc1.time - utc1.inacc > utc2.time + utc2.inacc

    utc1 utc_equalTo utc2 iff
            utc1.time == utc2.time and
            utc1.inacc == 0 and
            utc2.inacc == 0

    utc1 is utc_indeterminate with respect to utc2 if the intervals
    overlap.

3 - Returns

     0   Indicates that the routine executed successfully.
    -1   Indicates an invalid time argument.

4 - Example

    The following example checks to see if the current time is
    definitely after 1:00 P.M. today GMT.

    struct tm           tmtime, tmzero;
    enum utc_cmptype    relation;
    utc_t               testtime;

    /*
     *   Zero the tm structure for inaccuracy...
     */

    memset(&tmzero, 0, sizeof(tmzero));

    /*
     *   Get the current time, mapped to a tm structure...
     *
     *        NOTE: The NULL argument is used to get the current time.
     */

    utc_gmtime(&tmtime,      /* Out: Current GMT time in tm struct   */
             (long *)0,      /* Out: Nanoseconds of time             */
             (struct tm *)0, /* Out: Current inaccuracy in tm struct */
             (long *)0,      /* Out: Nanoseconds of inaccuracy       */
             (utc_t *)0);    /* In:  Current timestamp               */

    /*
     *   Construct a tm structure that corresponds to 1:00 PM...
     */

    tmtime.tm_hour = 13;
    tmtime.tm_min = 0;
    tmtime.tm_sec = 0;

    /*
     *   Convert to a binary timestamp...
     */

    utc_mkgmtime(&testtime,  /* Out: Binary timestamp of 1:00 PM  */
                 &tmtime,    /* In:  1:00 PM in tm struct         */
                 0,          /* In:  Nanoseconds of time          */
                 &tmzero,    /* In:  Zero inaccuracy in tm struct */
                 0);         /* In:  Nanoseconds of inaccuracy    */

    /*
     *   Compare to the current time, noting the use of the
     *   NULL argument...
     */

    utc_cmpintervaltime(&relation,    /* Out: Comparison relation */
                        (utc_t *)0,   /* In:  Current timestamp   */
                        &testtime);   /* In:  1:00 PM timestamp   */

    /*
     *   If it is not later - wait, print a message, etc.
     */

    if (relation != utc_greaterThan) {

    /*
     *     Note: It could be earlier than 1:00 PM or it could be
     *           indeterminate. If indeterminate, for some applications
     *           it might be worth waiting.
     */
    }

5 - Related Functions

    utc_cmpmidtime