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

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_STPOOL retrieves the 'nth' string from the kernel pool variable
   'item' , where the string may be continued across several components
   of the kernel pool variable.

I/O


   Given:

      item     the name of a kernel pool variable for which the caller
               wants to retrieve a full (potentially continued) string.

               [1,c1] = size(item); char = class(item)

                  or

               [1,1] = size(item); cell = class(item)

      nth      the index of the string to retrieve from the kernel pool
               variable 'item' (index array base 1).

               [1,1]   = size(nth); int32 = class(nth)

      contin   a sequence of characters which (if they appear as the
               last non-blank sequence of characters in a component of a
               value of a kernel pool variable) act as a continuation
               marker:  the marker indicates that the string associated
               with the component containing it is continued into the
               next literal component of the kernel pool variable

               [1,c2] = size(contin); char = class(contin)

                  or

               [1,1] = size(contin); cell = class(contin)

               If 'contin' is a blank, all of the components of 'item'
               will return as a single string.

   the call:

      [string, found] = cspice_stpool( item, nth, contin )

   returns:

      string   the 'nth' scalar string value corresponding to
               the kernel pool variable specified by 'item'

               [1,c3] = size(string); char = class(string)

      found    a boolean indicating true if the request
               to retrieve the 'nth' string associated with 'item'
               succeeds, false, if not.

               [1,1] = size(found); logical = class(found)

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.

      %
      % Load a kernel containing the variable assignment:
      %
      % LONG_VAL = ( 'This is part of the first component //'
      %             'that needs more than one line when //'
      %             'inserting it into the kernel pool.'
      %             'This is the second string that is split //'
      %             'up as several components of a kernel pool //'
      %             'variable.' )
      %
      cspice_furnsh( 'pool_t.ker' )

      %
      % Retrieve the 'nth' entry for kernel pool variable
      % 'LONG_VAL' to 'string'.
      %
      ITEM   = 'LONG_VAL';
      CONTIN = '//';

      for nth=1:3

         [string, found] = cspice_stpool( ITEM, nth, CONTIN );

         if ( found )

            fprintf( ['Found index = %d component of kernel variable %s ' ...
                     'in the kernel pool.\n\n'], nth, ITEM)

            fprintf( 'String = ``%s``\n\n', string )

         else

            fprintf( ['No index = %d component of kernel variable %s ' ...
                      'found in the kernel pool.\n'], nth, ITEM)

         end

      end

      %
      % It's always good form to unload kernels after use,
      % particularly in MATLAB due to data persistence.
      %
      cspice_kclear

   MATLAB outputs (approximately):

      Found index = 1 component of kernel variable LONG_VAL in the
      kernel pool.

      String = ``This is part of the first component that needs more
      than one line when inserting it into the kernel pool.``

      Found index = 2 component of kernel variable LONG_VAL in the
      kernel pool.

      String = ``This is the second string that is split up as several
      components of a kernel pool variable.``

      No index = 3 component of kernel variable LONG_VAL found in the
      kernel pool.

Particulars


   None.

Required Reading


   For important details concerning this module's function, please refer to
   the CSPICE routine stpool_c.

   MICE.REQ
   KERNEL.REQ

Version


   -Mice Version 1.1.1, 12-MAR-2015, EDW (JPL)

      Edited I/O section to conform to NAIF standard for Mice documentation.

   -Mice Version 1.1.0, 10-MAY-2011, EDW (JPL)

      "logical" call replaced with "zzmice_logical."

   -Mice Version 1.0.0, 26-SEP-2007, EDW (JPL)

Index_Entries


   Retrieve a continued string value from the kernel pool


Wed Apr  5 18:00:35 2017