NAME

   utc_spantime - Given two (possibly unordered) binary timestamps,
                  returns a single UTC time interval whose inaccuracy
                  spans the two input binary timestamps

 SYNOPSIS

   #include <dce/utc.h>

   int utc_spantime( utc_t *result,
                     utc_t *utc1,
                     utc_t *utc2 );

 PARAMETERS

   Input

   utc1
       Binary timestamp. Use NULL if you want this routine to use the
       current time for this parameter.

   utc2
       Binary timestamp. Use NULL if you want this routine to use the
       current time for this parameter.

   Output

   result
       Spanning timestamp.

 DESCRIPTION

   Given two binary timestamps, the utc_spantime() routine returns a
   single UTC time interval whose inaccuracy spans the two input
   timestamps (that is, the interval resulting from the earliest
   possible time of either timestamp to the latest possible time of
   either timestamp).

 NOTES

   The tdf parameter in the output UTC value is copied from the utc2
   input. If either input binary timestamp has an unspecified
   inaccuracy, an error is returned.

 RETURN VALUES

    0    Indicates that the routine executed successfully.

   -1    Indicates an invalid time argument.

 EXAMPLES

   The following example computes the earliest and latest times for
   an array of 10 timestamps.

        utc_t               time_array[10], testtime, earliest, latest;
        int                 i;

        /*   Set the running timestamp to the first entry...        */
        testtime = time_array[0];

        for (i=1; i<10; i++) {

           /*   Compute the minimum and the maximum against the next
            *   element...
            */
      utc_spantime(&testtime,       /* Out: Resultant interval        */
                   &testtime,       /* In:  Largest previous interval */
                   &time_array[i]); /* In:  Element under test        */
      }

      /*   Compute the earliest and latest possible times            */
      utc_pointtime(&earliest,   /* Out: Earliest poss time in array */
                   (utc_t *)0,   /* Out: Midpoint                    */
                   &latest,      /* Out: Latest poss time in array   */
                   &testtime);   /* In:  Spanning interval           */

 RELATED INFORMATION

   Functions: utc_boundtime
              utc_gettime
              utc_pointtime