repmc_c

Index Page repmc_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 repmc_c ( ConstSpiceChar    * in,
                      ConstSpiceChar    * marker,
                      ConstSpiceChar    * value,
                      SpiceInt            lenout,
                      SpiceChar         * out    )
#### Abstract
       Replace a marker with a character string.
#### 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.
       lenout     I   Available space in output string.
       out        O   Output string.
#### Detailed_Input
       in             is a character string.

       marker         is character string indicating where a substring
                      replacement is to be made. 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 a replacement character string.

                      Leading and trailing blanks in value are NOT
                      significant: the portion of value that is substituted
                      for marker extends from its first non-blank character
                      to its last non-blank character.

                      However, if value is blank or empty, a single blank
                      is substituted for the first occurrence of marker.

      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 value
                      (leading and trailing blanks excepted) for
                      the first occurrence of marker in the input
                      string.

                      out and in must be identical or disjoint.
#### Parameters
       None.
#### Exceptions
       1) If either the input or output string pointers are null, the
          error SPICE(NULLPOINTER) is signaled.

       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 value is blank or empty, a single blank is substituted
          for the first occurrence of marker.
#### 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

          #include "SpiceUsr.h"
               .
               .
               .
          #define   LENOUT                  81
               .
               .
               .
          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

             marker == "#"
             in     == "Invalid operation value.  The value was:  <#>."

          Then following the call,

             #include "SpiceUsr.h"
                  .
                  .
                  .
             #define   LENOUT                  201
                  .
                  .
                  .

             repmc_c ( in, "#", "append", LENOUT, in  )

          in is

             "Invalid operation value.  The value was:  <append>."

       2. Let

             marker == " XX "
             in     == "A syntax error occurred.  The token XX was not "
                       "recognized.  Did you mean to say XX?"

          Then following the call,

             #include "SpiceUsr.h"
                  .
                  .
                  .
             #define   LENOUT                  201
                  .
                  .
                  .

             repmc_c ( in, "  XX  ", "  FND  ", LENOUT, out );

          out is

             "A syntax error occurred.  The token FND was not "
             "recognized.  Did you mean to say XX?"

          Making the additional call

             repmc_c ( out, "  XX  ", "  found  ", LENOUT, out );

          yields the string

             "A syntax error occurred.  The token FND was not
              recognized.  Did you mean to say found?"

       3. 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
       None.
#### 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 character_string
#### Link to routine repmc_c source file repmc_c.c

    Thu Apr 16 08:58:58 2009