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 
 
Wed Apr  5 17:54:41 2017