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
#### Link to routine repmct_c source file repmct_c.c

    Wed Jun  9 13:05:28 2010