Index Page pos_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
       SpiceInt pos_c ( ConstSpiceChar     * str,
                         ConstSpiceChar    * substr,
                         SpiceInt            start  )
#### Abstract
       Find the first occurrence in a string of a substring, starting at
       a specified location, searching forward.
#### Required_Reading
       SCANNING
#### Keywords
       CHARACTER
       SEARCH
       UTILITY
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       str        I   Any character string.
       substr     I   Substring to locate in the character string.
       start      I   Position to begin looking for substr in str.

       The function returns the index of the first occurrence of substr in
       str at or following index start.
#### Detailed_Input
       str        is any character string.

       substr     is a substring to look for in str.  Spaces in substr are
                  significant, including trailing blanks.

       start      is the position in str to begin looking for substr. start
                  may range from 0 to n-1, where n is the number of
                  characters in str.
#### Detailed_Output
       The function returns the index of the beginning of the first
       substring of str that begins on or after index start and is equal
       to substr. If the substring cannot be found after start, the
       function is returns -1.
#### Parameters
       None.
#### Exceptions
       1) The error SPICE(NULLPOINTER) is signaled if either of
          the input string pointers is null.

       2) If start is less than 0, the search begins at the first
          character of the string.

       3) If start is greater than or equal to the length of the string,
          pos_c returns -1.

       4) The function returns -1 if either of the input strings is empty.
#### Files
       None.
#### Particulars
       pos_c is case sensitive.

       An entire family of related CSPICE routines

          cpos_c
          cposr_c
          ncpos_c
          ncposr_c
          pos_c
          posr_c

       is described in the Required Reading.
#### Examples
       Let string == "AN ANT AND AN ELEPHANT        "
                      012345678901234567890123456789

       Normal (Sequential) Searching:
       ------------------------------

          pos_c ( string, "AN",  0 ) ==  0
          pos_c ( string, "AN",  2 ) ==  3
          pos_c ( string, "AN",  5 ) ==  7
          pos_c ( string, "AN",  9 ) == 11
          pos_c ( string, "AN", 13 ) == 19
          pos_c ( string, "AN", 21 ) == -1

       start out of bounds:
       --------------------

          pos_c ( string, "AN", -6 ) ==  0
          pos_c ( string, "AN", -1 ) ==  0
          pos_c ( string, "AN", 30 ) == -1
          pos_c ( string, "AN", 43 ) == -1

       Significance of Spaces:
       -----------------------

          pos_c ( string, "AN",    0 ) ==  0
          pos_c ( string, " AN",   0 ) ==  2
          pos_c ( string, " AN ",  0 ) == 10
          pos_c ( string, " AN  ", 0 ) == -1
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       W.L. Taber      (JPL)
#### Version
       -CSPICE Version 1.0.0, 15-AUG-2002 (NJB) (WLT)
#### Index_Entries
       position of substring
#### Link to routine pos_c source file pos_c.c

    Wed Jun  9 13:05:27 2010