repmf_c

Index Page repmf_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 repmf_c ( ConstSpiceChar     * in,
                      ConstSpiceChar     * marker,
                      SpiceDouble          value,
                      SpiceInt             sigdig,
                      SpiceChar            format,
                      SpiceInt             lenout,
                      SpiceChar          * out )
#### Abstract
       Replace a marker in a string with a formatted double precision
       value.
#### Required_Reading
       None.
#### Keywords
       CHARACTER
       CONVERSION
       STRING
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       in         I   Input string.
       marker     I   Marker to be replaced.
       value      I   Replacement value.
       sigdig     I   Significant digits in replacement text.
       format     I   Format: 'E' or 'F'.
       lenout     I   Available space in output string.
       out        O   Output string.
       MAXLFD     P   Maximum length of a formatted DP number.
#### Detailed_Input
       in             is an arbitrary character string.

       marker         is an arbitrary character string. The first occurrence
                      of marker in the input string is to be replaced by value.

                      Leading and trailing blanks in marker are NOT significant.
                      In particular, no substitution is performed if marker
                      is blank.

       value          is an arbitrary double precision number.

       sigdig         is the number of significant digits with which value
                      is to be represented. sigdig must be greater than
                      zero and less than 15.

       format         is the format in which value is to be represented.
                      format may be any of the following:

                         format  Meaning      Example
                         ------  -----------  ----------------
                         E, e    Scientific   3.14159E+03
                                 (exponent)
                                 notation

                         F, f    Fixed-point  3141.59
                                 notation

       lenout         is the allowed length of the output string.  This length
                      must large enough to hold the output string plus the
                      terminator.  If the output string is expected to have x
                      characters, lenout should be at least x + 1.
#### Detailed_Output
       out            is the string obtained by substituting the text
                      representation of value for the first occurrence
                      of marker in the input string.

                      The text representation of value is in scientific
                      (exponent) or fixed-point notation, depending on
                      having the value of format, and having the number
                      of significant digits specified by sigdig.
                      The representation of value is produced by the
                      routine dpstrf_; see that routine for details
                      concerning the representation of double precision
                      numbers.

                      out and in must be identical or disjoint.
#### Parameters
       MAXLFD         is the maximum expected length of the text
                      representation of a formatted double precision
                      number. 56 characters are sufficient to hold any
                      result returned by dpstrf_. (See $Restrictions.)
#### Exceptions
       1) The error SPICE(NULLPOINTER) is signaled if any of
          the input or output string pointers is null.

       2) If the marker string is blank or empty, this routine leaves
          the input string unchanged, except that trailing blanks
          will be trimmed.  This case is not considered an error.

       3) If the output string is too short to accommodate a terminating
          null character, the error SPICE(STRINGTOOSHORT) is signaled.

       4) If out does not have sufficient length to accommodate the
          result of the substitution, the result will be truncated on
          the right.

       5) If the requested format is not supported, the error MAY be
          diagnosed by routines in the call tree of this routine.
          The current Fortran implementation defaults to F format
          if the format is anything other than 'E'.
#### Files
       None.
#### Particulars
       This is one of a family of related routines for inserting values
       into strings. They are typically to construct messages that
       are partly fixed, and partly determined at run time. For example,
       a message like

          "Fifty-one pictures were found in directory [USER.DATA]."

       might be constructed from the fixed string

          "#1 pictures were found in directory #2."

       by the calls

          repmct_c ( string, "#1",  51,  'c',      LENOUT, string );
          repmc_c  ( string, "#2", "[USER.DATA]",  LENOUT, string );

       which substitute the cardinal text "Fifty-one" and the character
       string "[USER.DATA]" for the markers "#1" and "#2" respectively.

       The complete list of routines is shown below.

          repmc_c  ( Replace marker with character string value )
          repmd_c  ( Replace marker with double precision value )
          repmf_c  ( Replace marker with formatted d.p. value   )
          repmi_c  ( Replace marker with integer value          )
          repmct_c ( Replace marker with cardinal text          )
          repmot_c ( Replace marker with ordinal text           )
#### Examples
       1. Let

             in == "Invalid duration value.  The value was #."

          Then following the call,

             #include "SpiceUsr.h"
                  .
                  .
                  .
             #define   LENOUT                  201
                  .
                  .
                  .
             repmf_c ( in, "#", 5.0e3, 5, 'f', LENOUT, in );

          in is

             "Invalid duration value.  The value was 5000.0."

       2. Let

             in == "Left endpoint exceeded right endpoint.  The left "
                   "endpoint was: XX.  The right endpoint was: XX."

          Then following the call,

             #include "SpiceUsr.h"
                  .
                  .
                  .
             #define   LENOUT                  201
                  .
                  .
                  .
             repmf_c ( in, "  XX  ",  -5.2d-9, 3, 'e', lenout, out );

          out is

             "Left endpoint exceeded right endpoint.  The left "
             "endpoint was: -5.20E-09.  The right endpoint was: XX."

       3. Let

             in == "Invalid quantity.  The value was # units."

          Then following the call,

             #include "SpiceUsr.h"
                  .
                  .
                  .
             #define   LENOUT                  201
                  .
                  .
                  .
             repmf_c ( in, "#", 5.0e1, 3, 'f', LENOUT, in );

          in is

             "Invalid quantity.  The value was 50.0 units."

       4. In the above example, if sigdig is 1 instead of 3, in becomes

             "Invalid quantity.  The value was 50. units."

       5. Let

             in == "Invalid duration value.  The value was #."

          Then following the call,

             #include "SpiceUsr.h"
                  .
                  .
                  .
             #define   LENOUT                  201
                  .
                  .
                  .
             repmf_c ( in, "#", 5.0e1, 100, 'e', LENOUT, in );

          in is

             "Invalid duration value.  The value was "
             "5.0000000000000E+01."

          Note that even though 100 digits of precision were requested,
          only 14 were returned.

       6. Let

             marker == "&"
             num    == 23
             chance == "fair"
             score  == 4.665

          Then following the sequence of calls,

             #include "SpiceUsr.h"
                  .
                  .
                  .
             #define   LENOUT                  201
                  .
                  .
                  .
             repmi_c ( "There are & routines that have a "
                       "& chance of meeting your needs.  "
                       "The maximum score was &.",
                       marker,
                       num,
                       LENOUT,
                       msg                                  );

             repmc_c ( msg, marker, chance,        LENOUT, msg );

             repmf_c ( msg, marker, score, 4, 'f', LENOUT, msg );

          msg is

             "There are 23 routines that have a fair chance of "
             "meeting your needs.  The maximum score was 4.665."
#### Restrictions
       1) The maximum number of significant digits returned is 14.

       2) This routine makes explicit use of the format of the string
          returned by dpstrf_; should that routine change, substantial
          work may be required to bring this routine back up to snuff.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
       I.M. Underwood (JPL)
#### Version
       -CSPICE Version 1.0.0, 14-AUG-2002 (NJB) (IMU)
#### Index_Entries
       replace marker with formatted d.p. value
#### Link to routine repmf_c source file repmf_c.c

    Thu Apr 16 08:59:00 2009