Index Page
repmct_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 repmct_c ( ConstSpiceChar   * in,
                   ConstSpiceChar   * marker,
                   SpiceInt           value,
                   SpiceChar          repcase,
                   SpiceInt           lenout,
                   SpiceChar        * out      ) 

Abstract

 
   Replace a marker with the text representation of a 
   cardinal number. 
 

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.
   repcase    I   Case of replacement text. 
   lenout     I   Available space in output string.
   out        O   Output string. 
   MAXLCN     P   is the maximum expected length of any cardinal text.

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 the text representation of 
                  the cardinal number value. 
 
                  Leading and trailing blanks in marker are not 
                  significant. In particular, no substitution is 
                  performed if marker is blank or empty. 
 
   value          is an arbitrary integer. 
 
   repcase        indicates the case of the replacement text. 
                  repcase may be any of the following: 
 
                     repcase   Meaning       Example 
                     -------   -----------   ----------------------- 
                     U, u      Uppercase     ONE HUNDRED FIFTY-THREE 
 
                     L, l      Lowercase     one hundred fifty-three 
 
                     C, c      Capitalized   One hundred fifty-three 
 
   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 the cardinal number value for 
                  the first occurrence of marker in the input string. 
 
                  out and in must be identical or disjoint. 
 

Parameters

 
   MAXLCN         is the maximum expected length of any cardinal 
                  text. 145 characters are sufficient to hold the 
                  text representing any value in the range 
 
                    ( -10**12, 10**12 ) 
 
                  An example of a number whose text representation 
                  is of maximum length is 
 
                     - 777 777 777 777 
 

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 value of repcase is not recognized, the error 
      will be diagnosed by routines in the call tree of this 
      routine.  out is not changed. 
 

Files

 
   None. 
 

Particulars

 
   This is one of a family of related routines for inserting values 
   into strings. They are typically used 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

 
   The following examples illustrate the use of repmct_c to 
   replace a marker within a string with the cardinal text 
   corresponding to an integer. 
 
   Uppercase 
   --------- 
 
      Let 
 
         marker == "#" 
         in     == "Invalid command.  Word # was not recognized." 
 
      Then following the call, 
 
        #include "SpiceUsr.h"
              .
              .
              .
         #define   LENOUT                  201
              .
              .
              .
         repmct_c ( in, "#", 5, 'U', LENOUT, in );
 
      in is 
 
         "Invalid command.  Word FIVE was not recognized." 
 
   Lowercase 
   --------- 
 
      Let 
 
         marker == " XX " 
         in     == "Word XX of the XX sentence was misspelled." 
 
      Then following the call, 
 
        #include "SpiceUsr.h"
              .
              .
              .
         #define   LENOUT                  201
              .
              .
              .
         repmct_c ( in, "  XX  ", 5, 'L', LENOUT, out );
 
      out is 
 
         "Word five of the XX sentence was misspelled." 
 
 
   Capitalized 
   ----------- 
 
      Let 
 
         marker == " XX " 
         in     == "Name:  YY.  Rank:  XX." 
 
      Then following the calls, 
 
        #include "SpiceUsr.h"
              .
              .
              .
         #define   LENOUT                  201
              .
              .
              .
         repmc_c  ( in,  "YY", "Moriarty", LENOUT, out );
         repmct_c ( out, "XX",  1,  'C',   LENOUT, out );
 
      out is 
 
         "Name:  Moriarty.  Rank:  One." 
 

Restrictions

 
   1) value must be in the range accepted by subroutine inttxt_. 
      This range is currently 
 
         ( -10**12, 10**12 ) 
 
      Note that the endpoints of the interval are excluded. 
 

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