Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
cspice_nthwd

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_NTHWD returns the nth word in a character string, and its location
   in the string.

I/O


   Given:

      string   the input string to be parsed.

               help, string
                  STRING = Scalar

               Each word of this string is a maximal sequence of consecutive
               non-blank characters.

      nth      the index of the word to be returned.

               help, nth
                  LONG = Scalar

               (One for the first word, two for the second, and so on.)

   the call:

      cspice_nthwd, string, nth, word, loc

   returns:

      word     the `nth' word in `string'.

               help, word
                  STRING = Scalar

               If `string' is blank or empty, or `nth' is non-positive or too
               large, `word' is empty.

               `word' may overwrite `string'.

      loc      the location of `word' in `string'.

               help, loc
                  LONG = Scalar

               (That is, `word' begins at string[loc]). If `string' is
               blank or empty, or `nth' is non-positive or too large, `loc' is
               zero.

Parameters


   None.

Examples


   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Given a character string, get the N'th word within, and the
      word's location.


      Example code begins here.


      PRO nthwd_ex1

         ;;
         ;; Local parameters.
         ;;
         STRING =   ' Now is the time,   for all good men     to come.'
         FMT    =   '(A,I3,3A,I3)'

         for nth=-2L, 10L do begin

            cspice_nthwd, STRING, nth, word, loc
            print, format=FMT, 'Word #', nth, '  is <', word,                $
                               '>, starting at position', loc

         endfor

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Word # -2  is <>, starting at position -1
      Word # -1  is <>, starting at position -1
      Word #  0  is <Now>, starting at position  1
      Word #  1  is <is>, starting at position  5
      Word #  2  is <the>, starting at position  8
      Word #  3  is <time,>, starting at position 12
      Word #  4  is <for>, starting at position 20
      Word #  5  is <all>, starting at position 24
      Word #  6  is <good>, starting at position 28
      Word #  7  is <men>, starting at position 33
      Word #  8  is <to>, starting at position 41
      Word #  9  is <come.>, starting at position 44
      Word # 10  is <>, starting at position -1


Particulars


   cspice_nthwd, like cspice_nextwd, is useful primarily for parsing input
   commands consisting of one or more words, where a word is defined to be a
   maximal sequence of consecutive non-blank characters. Each word is
   bounded on both sides by a blank character, or by the start or end of the
   input string. Successive calls to cspice_nextwd allow the calling routine
   to neatly parse and process one word at a time.

   The chief difference between the two routines is that
   cspice_nthwd allows the calling routine to access the words making
   up the input string in random order. (cspice_nextwd allows only
   sequential access.)

   cspice_nthwd may be more efficient than cspice_nextwd, since cspice_nthwd
   doesn't update an output string consisting of the remaining, unparsed
   string.

Exceptions


   1)  If any of the input arguments, `string' or `nth', is
       undefined, an error is signaled by the IDL error handling
       system.

   2)  If any of the input arguments, `string' or `nth', is not of
       the expected type, or it does not have the expected dimensions
       and size, an error is signaled by the Icy interface.

   3)  If any of the output arguments, `word' or `loc', is not a
       named variable, an error is signaled by the Icy interface.

Files


   None.

Restrictions


   None.

Required_Reading


   ICY.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)

Version


   -Icy Version 1.0.0, 01-NOV-2021 (JDR)

Index_Entries


   N'th word in a character_string



Fri Dec 31 18:43:06 2021