Index Page
cspice_timout
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_TIMOUT converts an input epoch represented in TDB seconds
   past the TDB epoch of J2000 to a character string formatted to
   the specifications of a user's format picture.

   For important details concerning this module's function, please refer to
   the CSPICE routine timout_c.

I/O


   This routine uses as input the time picture string created
   by a cspice_tpictr call.

   Given:

      et       a double precision scalar or N-vector representation
               of time in seconds past the ephemeris epoch J2000.

      pictur   a scalar string that specifies how the output should be
               presented.  The string is made up of various markers
               that stand for various components associated with
               a time.

      lenout   the length in characters of 'output' (this
               argument should have a value of 1 plus the
               assumed output string length to accommodate the C
               null terminator).

   the call:

      cspice_timout, et, pictur, lenout, output

   returns:

      output   the scalar or string N-vector representation
               of 'et' in the format defined by 'pictur'.

               'output' returns with the same measure of
               vectorization (N) as 'et'.

Examples


   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

      ;;
      ;; Given a sample with the format of the UNIX date string
      ;; local to California, create a SPICE time picture for use
      ;; in cspice_timout. Use the minimum safe length, 'lenout'
      ;; for the output time string (+1 for the C null terminator
      ;; used in CSPICE).
      ;;
      sample = 'Thu Oct 1 11:11:11 PDT 1111'
      SIZE   = 5
      lenout = strlen(sample) + 1

      ;;
      ;; Load a leapseconds kernel file.
      ;;
      cspice_furnsh, 'standard.tm'

      ;;
      ;; Create the pic string.
      ;;
      cspice_tpictr, sample, 64, pic, ok, err

      ;;
      ;; Check the error flag, 'ok', for problems.
      ;;
      if ( ~ok ) then begin
         print, err
         stop
      endif

      ;;
      ;; Convert an ephemeris time to the 'pic' format.
      ;;
      ;; Using the ET representation for: Dec 25 2005, 1:15:00 AM UTC
      ;;
      et = 188745364.d

      cspice_timout, et, pic, lenout, output
      print, 'Scalar: '
      print, 'ET              : ', et
      print, 'Converted output: ', output
      print

      ;;
      ;; Create an array of ephemeris times beginning
      ;; at 188745364.d with graduations of 10000.0
      ;; ephemeris seconds.
      ;;
      et = 10000.d * dindgen( SIZE ) + 188745364.d

      ;;
      ;; Convert the array of ephemeris times 'et' to an
      ;; array of time strings, 'output', in 'pic' format.
      ;;
      cspice_timout, et, pic, lenout, output

      print, 'Vector:'
      for i=0, (SIZE-1) do begin
         print, 'ET              : ', et[i]
         print, 'Converted output: ', output[i]
         print
      endfor

   IDL outputs:

      Scalar:
      ET              :    1.8874536e+08
      Converted output: Sat Dec 24 18:14:59 PDT 2005

      Vector:
      ET              :    1.8874536e+08
      Converted output: Sat Dec 24 18:14:59 PDT 2005

      ET              :    1.8875536e+08
      Converted output: Sat Dec 24 21:01:39 PDT 2005

      ET              :    1.8876536e+08
      Converted output: Sat Dec 24 23:48:19 PDT 2005

      ET              :    1.8877536e+08
      Converted output: Sun Dec 25 02:34:59 PDT 2005

      ET              :    1.8878536e+08
      Converted output: Sun Dec 25 05:21:39 PDT 2005

Particulars


   A format picture is simply a string of letters that lets
   cspice_timout know where various components of a time representation
   should be placed during creation of the time string.
   Here's an example of such a picture:

      MON DD,YYYY  HR:MN:SC.#### (TDB) ::TDB

   Here is a sample of the times that would be created by
   using this format.

      JAN 12,1992  12:28:18.2772 (TDB)
      FEB 13,1994  23:18:25.2882 (TDB)
      AUG 21,1995  00:02:00.1881 (TDB)

   As you can see from the samples above, the format picture
   specifies that every time string created should begin
   with a three-letter abbreviation for the month, followed
   by a space and the day of the month. The day of month is
   followed immediately by a comma and the year. The year
   component is followed by two spaces. Next are the output hours,
   represented as a two digit integer, a colon, minutes as
   a two digit integer, another colon, and seconds rounded
   to 4 decimal places and having a two digit integer part.
   This is followed by a space and the string '(TDB)'. The
   special marker '::TDB' in the time picture is an
   ``invisible'' marker. It is used to specify the time
   system that should be used in creating the time string
   (in this case Barycentric Dynamical Time).

   cspice_timout does not recognize all of the parts
   of the time format picture in the example above. The list
   of recognized parts and unrecognized parts are listed in
   the table below.

     Recognized       Unrecognized
     ----------       ------------
     'MON'            ' '
     'DD'             ','
     'YYYY'           '  '
     'HR'             ':'
     'MN'             '(TDB)'
     'SC'
     '.####'
     '::TDB'

   The unrecognized parts are called literal markers.  They are
   copied exactly as they appear in pictur into the output string.
   The recognized parts of the picture are replaced by a
   component of time or, as in the case of `::TDB' are used
   as instructions about the overall properties of the time
   string.

   The full list of recognized markers, their classification
   and meaning are given below.

   MARKER       CLASS     MEANING
   -----------  --------  -----------------------------------------
   '.##...'     modifier  represent a numeric component that
                          immediately precedes this in a decimal
                          format.  Number of decimal places
                          equals the number of '#' characters
   '::GCAL'     meta      dates are reported in Gregorian Calendar
   '::JCAL'     meta      dates are reported in Julian Calendar
   '::MCAL'     meta      dates after 15 October, 1582 are reported
                          in Gregorian Calendar, before that
                          dates are reported in Julian Calendar

   '::RND'      meta      round output to places specified by
                          least significant component

   '::TDB'      meta      all components should be TDB

   '::TDT'      meta      all components should be TDT

   '::TRNC'     meta      truncate all output components (default)
   '::UTC'      meta      all components should be UTC (default)
   '::UTC+h:m'  meta      all components in UTC offset by +h (hours)
                          and +m (minutes) so as to allow time zones.
   '::UTC-h:m'  meta      all components in UTC offset by -h (hours)
                          and -m (minutes) so as to allow time zones.
   'AMPM'       string    String (either 'A.M.'  or 'P.M.')
                          indicating whether hours are before
                          or after noon.
   'ampm'       string    String (either 'a.m.'  or 'p.m.')
                          indicating whether hours are before
                          or after noon.
   'AP'         numeric   AM/PM equivalents of the hour component
                          of a time.
   'DD'         numeric   Day of month
   'DOY'        numeric   Day of year
   'ERA'        string    String (either 'B.C.'  or 'A.D.') giving
                          era associated with an epoch.
   'era'        string    String (either 'b.c.'  or 'a.d.') giving
                          era associated with an epoch.
   'HR'         numeric   hour component of time
   'JULIAND'    numeric   julian date component of time
   'MM'         numeric   numeric representation of month component
   'MN'         numeric   minute component of time
   'MON'        string    upper case three letter abbreviation for
                          month
   'Mon'        string    capitalized three letter abbreviation for
                          month
   'mon'        string    lower case three letter abbreviation for
                          month
   'MONTH'      string    upper case full name of month
   'Month'      string    capitalized full name of month
   'month'      string    lower case full name of month
   'SC'         numeric   seconds component of time
   'SP1950'     numeric   seconds past 1950 component of time
   'SP2000'     numeric   seconds past 2000 component of time
   'YR'         numeric   last two digits of year component of time
   'YYYY'       numeric   year component of time
   'WEEKDAY'    string    upper case day of week
   'Weekday'    string    capitalized day of week
   'weekday'    string    lower case day of week
   'WKD'        string    upper case three letter abbreviation for
                          day of week.
   'Wkd'        string    capitalized three letter abbreviation for
                          day of week.
   'wkd'        string    lower case three letter abbreviation for
                          day of week.

   String Markers

      String markers are portions of the format picture that
      will be replaced with a character string representing the
      corresponding component of a time.

   Numeric Markers

      Numeric markers are portions of the format picture that
      will be replaced with a decimal string that represents
      the corresponding component of a time.

   Meta Markers

      Meta markers (listed under the class ``meta'' in the
      table above) are used to indicate `global' properties of
      your time string. You may specify time scale and how
      rounding should be performed on the components of time
      in your output string. Meta markers may be placed anywhere
      in your format picture. They do not contribute to placement
      of characters in output time strings. Also there are no
      restrictions on how many meta markers you may place in
      the format picture. However, if you supply conflicting
      `meta' markers (for example ::TDT and ::TDB) in your
      picture the first marker listed (in left to right order)
      overrules the conflicting marker that appears later in
      the picture.

   Modifier Markers

      The numeric markers listed in the table above stand
      for integers unless they are modified through use of a
      modifier marker. The strings

         .#
         .##
         .###
         .####

      are used to this end. When a numeric marker is followed
      immediately by one of these modifiers, the corresponding
      time component will be written with the number of decimal
      places indicated by number of successive occurrences of
      the character '#'. Any numeric token may be modified.

   Rounding vs. Truncation

      The meta markers ::TRNC and ::RND allow you to control
      how the output time picture is rounded. If you specify
      ::TRNC all components of time are simply truncated to
      the precision specified by the marker and any modifier.
      If you specify ::RND the output time is rounded to the
      least significant component of the format picture. The
      default action is truncation.

      Whether an output time string should be rounded or
      truncated depends upon what you plan to do with the
      string. For example suppose you simply want to get the
      calendar date associated with a time and not the time of
      day. Then you probably do not want round your output.
      Rounding 1992 Dec 31, 13:12:00 to the nearest day
      produces 1993 Jan 1. Thus in this case rounding is probably
      not appropriate.

      However, if you are producing output for plotting using
      Julian Date, seconds past an 1950 or or seconds past
      2000, you will probably want your output rounded so as
      to produce a smoother plot.

   Time Zones

      The meta markers ::UTC+h:m  and ::UTC-h:m  allow you
      offset UTC times so that you may represent times in
      a time zone other than GMT.  For example you can
      output times in Pacific Standard time by placing the
      meta-marker ::UTC-8 in your format picture.

      For example if you use the picture

         YYYY Mon DD, HR:MN:SC ::UTC

      You will get output strings such as:

         1995 Jan 03, 12:00:00

      If you use the picture


         YYYY Mon DD, HR:MN:SC ::UTC-8

      You will get output strings such as:

         1995 Jan 03, 04:00:00

      Finally, if you use the picture

         YYYY Mon DD, HR:MN:SC ::UTC-8:15

      You will get output string

         1995 Jan 03, 03:45:00

      Note that the minutes are always added or subtracted
      based on the sign present in the time zone specifier.
      In the case of ::UTC+h:m, minutes are added. In the
      case ::UTC-h:m, minutes are subtracted.

      The unsigned part of the hours component can be no more
      than 12.  The unsigned part of the minutes can be no more
      than 59.

   Calendars

      The calendar currently used by western countries is the
      Gregorian Calendar.  This calendar begins on Oct 15, 1582.
      Prior to Gregorian Calendar the Julian calendar was used
      The last Julian calendar date prior to the beginning
      of the Gregorian Calendar is Oct 5, 1582.

      The primary difference between the Julian and Gregorian
      calendars is in the determination of leap years.
      Nevertheless both can be formally extended backward and
      forward in time indefinitely.

      By default cspice_timout uses the Gregorian Calendar (::GCAL) in the
      determination of the output string.  However, you may
      specify that cspice_timout use the Julian Calendar (::JCAL) or a
      mixture of both (::MCAL).  If you specify ::MCAL, epochs
      that occur after the beginning of the Gregorian Calendar
      will be represented using the Gregorian Calendar, epochs
      prior to the beginning of the Gregorian calendar will
      be represented using the Julian Calendar.

   Getting Software to Construct Pictures for You

      Although it is not difficult to construct time format
      pictures, you do need to be aware of the various markers
      that may appear in a format picture.

      There is an alternative means for getting a format picture.
      The routine cspice_tpictr constructs format pictures from a sample
      time string.  For example suppose you would like your
      time strings to look like the basic pattern of the string
      below.

         'Fri Jul 26 12:22:09 PDT 1996'

      You can call cspice_tpictr with this string, and it will create
      the appropriate pictur for use with cspice_timout.

         cspice_tpictr, 'Fri Jul 26 12:22:09 PDT 1996', $
                        lenout, pictur, ok, errmsg

      The result will be:

         'Wkd Mon DD HR:MN:SC (PDT) ::UTC-7'

      Note: not every date that you can read is interpretable
      by cspice_tpictr.  For example, you might be able to understand
      that 19960212121116 is Feb 12 1996, 12:11:16.  However,
      cspice_tpictr cannot recognize this string.  Thus it is important
      to check the logical OK to make sure that cspice_tpictr was able
      to understand the time picture you provided.

      Even thought cspice_tpictr can not recognize every time pattern
      that has been used by various people, it does recognize
      nearly all patterns that you use when you want to communicate
      outside your particular circle of colleagues.

Required Reading


   ICY.REQ
   TIME.REQ

Version


   -Icy Version 1.1.3, 13-APR-2015, EDW (JPL)

      Added Particulars section corresponding to version in CSPICE
      timout_c wrapper.

   -Icy Version 1.1.2, 19-SEP-2011, EDW (JPL)

      Corrected error in example code. cspice_tpictr
      call used 'lenout' variable for 'pic' length instead
      of value 64.

   -Icy Version 1.1.1, 05-FEB-2008, EDW (JPL)

      Edited I/O section, replaced comment

         "returns with the same order"

      with

         "returns with the same measure of vectorization"

   -Icy Version 1.1.0, 12-SEP-2004, EDW (JPL)

       Added capability to process vector 'et' input
       returning an array of time strings 'output'.

   -Icy Version 1.0.0, 16-JUN-2003, EDW (JPL)

Index_Entries


   Convert and format d.p. seconds past J2000 as a string




Wed Apr  5 17:58:04 2017