repmot_c

Index Page repmot_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 repmot_c ( ConstSpiceChar   * in,
                       ConstSpiceChar   * marker,
                       SpiceInt           value,
                       SpiceChar          repcase,
                       SpiceInt           lenout,
                       SpiceChar        * out      )
#### Abstract
       Replace a marker with the text representation of an ordinal 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.
       MAXLON     P   Maximum length of an ordinal 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 the text representation of
                      the ordinal 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 ordinal number value for
                      the first occurrence of marker in the input string.

                      out and in must be identical or disjoint.
#### Parameters
       MAXLON         is the maximum expected length of any ordinal
                      text. 147 characters are sufficient to hold the
                      text representing any ordinal value whose
                      corresponding ordinal value is in the range

                        ( -10**12, 10**12 )

                      An example of a number whose ordinal 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 to construct messages that
       are partly fixed, and partly determined at run time. For example,
       a message like

          "The fifty-first picture was found in directory [USER.DATA]."

       might be constructed from the variable string

          "The #1 picture was found in directory #2."

       by the calls

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

       which substitute the ordinal text "fifty-first" 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 repmot_c to
       replace a marker within a string with the ordinal text
       corresponding to an integer.

       Uppercase
       ---------

          Let

             marker = "#"
             in     = "Invalid command.  The # word was not recognized."

          Then following the call,
                  .
                  .
                  .
             #define   LENOUT                  201
                  .
                  .
                  .
             repmot_c ( in, "#", 5, 'U', LENOUT, in );

          in is

             "Invalid command.  The FIFTH word was not recognized."

       Lowercase
       ---------

          Let

             marker = " XX "
             in     = "The XX word of the XX sentence was misspelled."

          Then following the call,

             repmot_c ( in, "  XX  ", 5, 'L', LENOUT, out );

          OUT is

             "The fifth word 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:  First."
#### Restrictions
       1) value must be in the range accepted by subroutine intord_.
          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 ordinal text
#### Link to routine repmot_c source file repmot_c.c

    Thu Apr 16 08:59:00 2009