tpictr_c

Index Page tpictr_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void tpictr_c ( ConstSpiceChar * sample,
                       SpiceInt         lenout,
                       SpiceInt         lenerr,
                       SpiceChar      * pictur,
                       SpiceBoolean   * ok,
                       SpiceChar      * errmsg )
#### Abstract
       Given a sample time string, create a time format picture
       suitable for use by the routine timout_c.
#### Required_Reading
        None.
#### Keywords
        TIME
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       sample     I   A sample time string.
       lenout     I   The length for the output picture string.
       lenerr     I   The length for the output error string.
       pictur     O   A format picture that describes sample.
       ok         O   Flag indicating whether sample parsed successfully.
       errmsg     O   Diagnostic returned if sample cannot be parsed.
#### Detailed_Input
       sample     is a representative time string to use as a model to
                  format time strings.

       lenout     is the allowed length for the output picture.  This length
                  must large enough to hold the output string plus the null
                  terminator.  If the output string is expected to have x
                  characters, lenout needs to be x + 1.  80 is a reasonable
                  value for lenout (79 characters plus the null
                  terminator).

       lenerr     is the allowed length for the output error string.
#### Detailed_Output
       pictur     is a format picture suitable for use with the SPICE
                  routine timout_c.  This picture, when used to format an
                  epoch via timout_c, will yield the same time components in
                  the same order as the components in sample.

       ok         is a logical flag indicating whether the input format
                  sample could be parsed. If all of the components of
                  sample are recognizable, ok will be returned with the
                  value SPICEFALSE.  If some part of pictur cannot be
                  parsed, ok will be returned with the value SPICEFALSE.

       errmsg     is a diagnostic message that indicates what part of
                  sample was not recognizable.  If sample was successfully
                  parsed, ok will be SPICEFALSE and errmsg will be
                  returned as an empty string.
#### Parameters
       None.
#### Exceptions
       Error free.

       1) All problems with the inputs are diagnosed via ok and errmsg.

       2) If a format picture can not be created from the sample
          time string, pictur is returned as a blank string.
#### Files
       None.
#### Particulars
       Although the routine timout_c provides CSPICE users with a great
       deal of flexibility in formatting time strings, users must
       master the means by which a time picture is constructed
       suitable for use by timout_c.

       This routine allows CSPICE users to supply a sample time string
       from which a corresponding time format picture can be created,
       freeing users from the task of mastering the intricacies of
       the routine timout_c.

       Note that timout_c can produce many time strings whose patterns
       can not be discerned by this routine.  When such outputs are
       called for, the user must consult timout_c and construct the
       appropriate format picture "by hand."  However, these exceptional
       formats are not widely used and are not generally recognizable
       to an uninitiated reader.
#### Examples
       Suppose you need to print epochs corresponding to some events and
       you wish the epochs to have the same arrangement of components as in
       the string "10:23 P.M. PDT January 3, 1993".

       The following subroutine call will construct the appropriate format
       picture for use with timout_c.

       tpictr_c ( "10:23 P.M. PDT January 3, 1993",
                   lenout, lenerr, pictur, &ok, errmsg );

       The resulting picture is:

          "AP:MN AMPM PDT Month DD, YYYY ::UTC-7"

       This picture can be used with timout_c to format a sequence
       of epochs, et[0],...,et[n-1] (given as ephemeris seconds past J2000)
       as shown in the loop below:

          #include "SpiceUsr.h"
              .
              .
              .
          for ( i = 0; i < n; i++ )
          {
             timout_c ( et[i], pictur, string );
             printf ( "Epoch: %d --- %s\n", i, string );
          }
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       W.L. Taber      (JPL)
       E.D. Wright     (JPL)
#### Version
       -CSPICE Version 1.0.0, 23-JUL-1999   (EDW) (WLT)
#### Index_Entries
       Use a sample time string to produce a time format picture
#### Link to routine tpictr_c source file tpictr_c.c

    Thu Apr 16 08:59:23 2009