 
Symbol Tables
===========================================================================
 
   Last revised on 2008 JAN 17 by B. V. Semenov.
 
 
Abstract
--------------------------------------------------------
 
   Symbol tables are SPICE data structures used to associate variable names
   with sets of values.
 
 
Note on FORTRAN and C Versions
--------------------------------------------------------
 
   This document covers the FORTRAN version of the interfaces of this
   subsystem. CSPICE provides f2c translated equivalents for all, and
   native C wrappers for some of them. If you wish to use the C versions of
   the interfaces described in this document, refer to the CSPICE Required
   Reading, cspice.req, for more information on naming conventions,
   locations, and usage of the f2c'ed routines and native C wrappers.
 
 
Revisions
--------------------------------------------------------
 
   June 15, 1992
 
            The document differs from the previous version of December 2,
            1989 in that a number of typographical errors were corrected
            and a paragraph in the section on Symbol Table Initialization
            was modified to improve its clarity.
 
 
What are Symbol Tables?
--------------------------------------------------------
 
   Symbol tables are storage structures used to associate multiple values
   with one variable name called a symbol. This storage structure consists
   of three arrays. The first array, called the name table, contains the
   names of the symbols. The second array, called the pointer table,
   contains the pointers which associate the symbol name with its values.
   The third array, called the value table, contains values associated with
   the symbol names in the name table.
 
   As implemented in SPICELIB, there are three types of symbol tables:
   character, double precision, and integer. While the symbol names are
   always character strings, the type of the symbol table is determined by
   the data type of the values. For example, an integer symbol table has
   integer values associated with its symbol names.
 
 
Illustration of Symbol Table Representation
--------------------------------------------------------
 
   This is an illustration of how the contents of a symbol table are
   represented in the SPICELIB documentation. This symbol table is a double
   precision symbol table.
 
      symbol name          associated values
      --------------       -----------------
      BODY4_GM        -->   4.282628654899D4
      BODY4_POLE_DEC  -->   5.2886D1
                           -6.1D-2
                            0.0D0
      BODY4_POLE_RA   -->   3.17681D2
                           -1.08D-1
                            0.0D0
 
   This symbol table contains three symbols. One of the symbols, BODY4 GM,
   points to a single value. The other two symbols each point to three
   values.
 
 
Why use Symbol Tables?
--------------------------------------------------------
 
   The primary use of symbol tables is to implement associative arrays:
   that is, arrays which are indexed by character strings rather than by
   indices. For example, you may wish to store the masses for several
   planets and satellites, without knowing ahead of time which ones you
   will be using. You might use a double precision symbol table for this,
   storing the mass of Jupiter as element `JUPITER', the mass of Europa as
   element `EUROPA', and so on.
 
   The fact that more than one value may be stored under a single name
   (symbol) allows you to store polynomials, vectors, matrices, or any set
   of associated values under one name. Examples from the SPICELIB kernel
   pool include: three axes for one body under the name `BODYxxx AXES';
   polynomials for the right ascension and declination of the pole of a
   body (three terms each) under the name `BODYxxx POLE RA' and `BODYxxx
   POLE DEC'. Other examples might be to list the names of active
   satellites under the name of the parent planet; to list one or more
   vidicom matrices under the name `K-MATRIX'; and to store scalar, vector,
   and matrix values in a simulated desk calculator.
 
   In short, any time you need to store something and look it up later, you
   can use symbol tables. The advantages come into play mostly when the
   things to be stored are not known until run-time, or when a program is
   undergoing development and the things to be stored are subject to rapid
   change.
 
 
Symbol Subroutine Naming Conventions
--------------------------------------------------------
 
   The names of the symbol table subroutines in SPICELIB are assigned as
   follows. Each name is of the form SYfffx.
 
         SY    indicates that the subroutine belongs to the symbol table
               family of subroutines.
 
         fff   is a three letter mnemonic code indicating the function of
               the subroutine.
 
         x     indicates the data type of the values associated with the
               symbols in the name table. The data types are: C for
               character, D for double precision, and I for integer.
 
   In the descriptive text that follows, the generic routines are referred
   to by their mnemonic codes, and specific routines are referred to by
   their full names. For example, the notation DEL refers to the generic
   routine, DEL, for deleting a symbol. The notation SYDELC refers to the
   particular routine that deletes a symbol from a character symbol table.
 
 
Symbol Table Initialization
--------------------------------------------------------
 
   Symbol tables are implemented using cells, another SPICELIB data
   structure. Hence, the restrictions that apply to cells also apply to
   symbol tables. The size and cardinality of the components of a symbol
   table must be initialized before the symbol table can be used properly.
   The cell routines SSIZEx should be used for this initialization. Consult
   the Required Reading for the family of cell routines (cells.req) if you
   are not familiar with their use.
 
   Before using the symbol tables, you must initialize the name table,
   pointer table, and value table. This initialization sets the size and
   cardinality of the component tables.
 
   The size of the name table must equal the size of the pointer table. In
   other words, both must contain the same number of elements. Also, the
   size of the value table should be large enough to accommodate the
   maximum number of values anticipated. If the size of any of the
   component tables of a symbol table is too small, it is treated as an
   error by the symbol table routines.
 
   The cardinality of the component tables should be set to zero before
   using a symbol table.
 
   The following piece of code demonstrates the easiest way to initialize a
   symbol table. Using the cell routines SSIZEx to create a symbol table
   containing up to thirty symbols and up to one hundred-fifty values, the
   initialization looks like this:
 
   Initialize the name table:
 
      CALL SSIZEC ( 30,   TABSYM )
 
   Initialize the pointer table:
 
      CALL SSIZEI ( 30,   TABPTR )
 
   Initialize the value table:
 
      CALL SSIZEC ( 150,  TABVAL )
 
   The name table always contains character values and is initialized with
   SSIZEC. Likewise, the pointer table always contains integer values and
   is thus initialized with SSIZEI. The initialization of the value table
   is different for each of the types of symbol tables. In the example
   above the routine SSIZEC was used to initialize the value table for a
   character symbol table. A double precision value table should be
   initialized using SSIZED, and an integer values table should be
   initialized using SSIZEI.
 
 
A Comprehensive Example
--------------------------------------------------------
 
   The following examples illustrate how each symbol table routine is used.
   The first five examples illustrate how to create a symbol, delete a
   symbol, duplicate a symbol, rename a symbol, and fetch the name of a
   symbol. The next four examples demonstrate how to add a value, delete a
   value, obtain the values, and reorder the values associated with an
   existing symbol. The final example illustrates how to determine the
   number of values associated with a symbol.
 
 
Creating a symbol
 
   Suppose that you want to create a symbol table of famous scientists and
   their fields of study. First, you must create a symbol and give it one
   or more associated values. SET and PUT create symbols. If you want to
   create a symbol with one value, use the SET routine. Otherwise, use the
   PUT routine. The routine used depends on the initial number of values
   associated with the symbol. The call below demonstrates how to create
   the symbol `EINSTEIN' with the associated value `BROWNIAN MOTION'.
   Because this symbol has one value, the SET routine should be used.
 
   The call,
 
      CALL SYSETC
      ( 'EINSTEIN', 'BROWNIAN MOTION', TABSYM, TABPTR, TABVAL )
 
   creates the symbol table:
 
      EINSTEIN   -->  BROWNIAN MOTION
 
   To create a symbol giving it more than one value, use the PUT routine.
 
   If the VALUES array contains the elements,
 
      ELECTRIC CHARGE
      PHOTOELECTRIC EFFECT
 
   N is 2 (the number of elements in the VALUES array), and the symbol you
   want to create is named `MILLIKAN', the call,
 
      CALL SYPUTC
      ( 'MILLIKAN', VALUES, N, TABSYM, TABPTR, TABVAL )
 
   creates a new symbol in the symbol table. The symbol table now looks
   like this:
 
      EINSTEIN   -->  BROWNIAN MOTION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
 
   Imagine now that the symbol table has several symbols.
 
      BARDEEN    -->  TRANSISTOR EFFECT
                      SUPERCONDUCTIVITY
      EINSTEIN   -->  BROWNIAN MOTION
      HAHN       -->  NUCLEAR FISSION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
      PLANCK     -->  ELEMENTARY QUANTA
 
 
Deleting a symbol
 
   The routine DEL deletes a symbol from the symbol table.
 
   The call,
 
      CALL SYDELC ( 'PLANCK', TABSYM, TABPTR, TABVAL )
 
   deletes the scientist PLANCK from the table. The symbol table now looks
   like this:
 
      BARDEEN    -->  TRANSISTOR EFFECT
                      SUPERCONDUCTIVITY
      EINSTEIN   -->  BROWNIAN MOTION
      HAHN       -->  NUCLEAR FISSION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
 
 
Duplicating a symbol
 
   Perhaps after doing some research, you find that the scientist STRASSMAN
   also worked on NUCLEAR FISSION. You'd like to add him to the symbol
   table. Well, you can do this in two ways. You could create a symbol
   `STRASSMAN', or you could duplicate the symbol `HAHN' and give it the
   name `STRASSMAN' since their associated values are the same. The routine
   DUP duplicates a symbol.
 
   Using the DUP routine,
 
      CALL SYDUPC ( 'HAHN', 'STRASSMAN', TABSYM, TABPTR, TABVAL )
 
   changes the symbol table contents to:
 
      BARDEEN    -->  TRANSISTOR EFFECT
                      SUPERCONDUCTIVITY
      EINSTEIN   -->  BROWNIAN MOTION
      HAHN       -->  NUCLEAR FISSION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
      STRASSMAN  -->  NUCLEAR FISSION
 
   The same results could have been achieved using the SET routine to
   create a symbol with one associated value, or the PUT routine if the
   symbol you wanted to create had more than one associated value. The call
   for creating the symbol `STRASSMAN' with the value `NUCLEAR FISSION'
   would look like this:
 
      CALL SYSETC
      ( 'STRASSMAN', 'NUCLEAR FISSION', TABSYM, TABPRT, TABVAL )
 
 
Renaming a symbol
 
   The routine REN exists for renaming a symbol.
 
   Using the REN routine,
 
      CALL SYRENC ( 'HAHN', 'FERMI', TABSYM, TABPTR, TABVAL )
 
   the symbol `HAHN' is renamed to `FERMI'.
 
   The symbol table now looks like this:
 
      BARDEEN    -->  TRANSISTOR EFFECT
                      SUPERCONDUCTIVITY
      EINSTEIN   -->  BROWNIAN MOTION
      FERMI      -->  NUCLEAR FISSION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
      STRASSMAN  -->  NUCLEAR FISSION
 
 
Obtaining the name of a symbol
 
   The routine FET allows you to obtain the name of a particular symbol in
   the symbol table. Perhaps you want to know the names of the first four
   symbols in the symbol table. (Note that the FET routine does not modify
   the contents of the symbol table.)
 
   The following code will `fetch' and write to the screen the names of the
   first four symbols in the symbol table.
 
      DO I = 1, 4
         CALL SYFETC ( I, TABSYM, TABPTR, TABVAL, NAME, FOUND )
         WRITE (6,*) NAME
      END DO
 
 
Adding a new value to a symbol
 
   Suppose that you want to add a value to a symbol. This can be done by
   either `pushing' or `enqueueing' a value onto the symbol. Pushing a
   value onto a symbol means that the value becomes the first value
   associated with the symbol. Enqueueing the value onto the symbol means
   that the value becomes the last value associated with the symbol. The
   routines PSH or ENQ are used to add a value to the values already
   associated with a symbol.
 
   If the call is,
 
      CALL SYPSHC
      ( 'EINSTEIN', 'GENERAL RELATIVITY', TABSYM, TABPTR, TABVAL )
 
   the contents of the symbol table are now:
 
      BARDEEN    -->  TRANSISTOR EFFECT
                      SUPERCONDUCTIVITY
      EINSTEIN   -->  GENERAL RELATIVITY
                      BROWNIAN MOTION
      FERMI      -->  NUCLEAR FISSION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
      STRASSMAN  -->  NUCLEAR FISSION
 
   Let the next call be:
 
      CALL SYENQC
      ( 'EINSTEIN', 'PHOTOELECTRIC EFFECT', TABSYM, TABPTR, TABVAL )
 
   The contents of the symbol table are modified to be:
 
      BARDEEN    -->  TRANSISTOR EFFECT
                      SUPERCONDUCTIVITY
      EINSTEIN   -->  GENERAL RELATIVITY
                      BROWNIAN MOTION
                      PHOTOELECTRIC EFFECT
      FERMI      -->  NUCLEAR FISSION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
      STRASSMAN  -->  NUCLEAR FISSION
 
 
Deleting a value from a symbol
 
   The only value that can be deleted is the first value associated with a
   symbol. The first value associated with the symbol is deleted using the
   POP routine. The call below demonstrates how to `pop' a value associated
   with the symbol `BARDEEN'.
 
   The call,
 
      CALL SYPOPC ( 'BARDEEN', TABSYM, TABPTR, TABVAL, VALUE, FOUND )
 
   results in the symbol table:
 
      BARDEEN    -->  SUPERCONDUCTIVITY
      EINSTEIN   -->  GENERAL RELATIVITY
                      BROWNIAN MOTION
                      PHOTOELECTRIC EFFECT
      FERMI      -->  NUCLEAR FISSION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
      STRASSMAN  -->  NUCLEAR FISSION
 
   If there are no remaining values associated with the symbol after VALUE
   has been popped, the symbol is removed from the symbol table.
 
 
Obtaining values associated with a symbol
 
   Some symbol table routines exist to obtain values associated with a
   particular symbol. All of the values can be obtained, a subset of the
   values, or just a particular value associated with a symbol. The
   routines to do this are GET, SEL, and NTH respectively. These routines
   do not modify the symbol tables. To obtain all the values associated
   with the symbol `EINSTEIN' use the GET routine.
 
   Calling the GET routine,
 
      CALL SYGETC
      ( 'EINSTEIN', TABSYM, TABPTR, TABVAL, N, VALUES, FOUND )
 
   returns the following information about the symbol:
 
         N        the number of values returned
 
         VALUES   an array containing the symbol's values
 
         FOUND    indicates whether or not the symbol was found in the
                  symbol table
 
   The following information is returned for the symbol `EINSTEIN':
 
      N        3
 
      VALUES   GENERAL RELATIVITY
               BROWNIAN MOTION
               PHOTOELECTRIC EFFECT
 
      FOUND    TRUE
 
 
Reordering the values associated with a symbol
 
   Two routines exist for reordering the values associated with a symbol.
   The routine ORD will order the values in increasing order from the first
   value to the last. Character values are ordered according to the ASCII
   collating sequence. The second routine, TRN, transposes two values
   associated with a symbol.
 
   Calling the ORD routine to order the values associated with the symbol
   `EINSTEIN',
 
      CALL SYORDC ( 'EINSTEIN', TABSYM, TABPTR, TABVAL )
 
   the contents of the symbol table are modified to be:
 
      BARDEEN    -->  SUPERCONDUCTIVITY
      EINSTEIN   -->  BROWNIAN MOTION
                      GENERAL RELATIVITY
                      PHOTOELECTRIC EFFECT
      FERMI      -->  NUCLEAR FISSION
      MILLIKAN   -->  ELECTRIC CHARGE
                      PHOTOELECTRIC EFFECT
      STRASSMAN  -->  NUCLEAR FISSION
 
   In order to transpose the first and second value associated with the
   symbol `MILLIKAN', use the TRN routine.
 
   The call,
 
      CALL SYTRNC ( 'MILLIKAN', 1, 2, TABSYM, TABPTR, TABVAL )
 
   Changes the symbol table to look like this:
 
      BARDEEN    -->  SUPERCONDUCTIVITY
      EINSTEIN   -->  BROWNIAN MOTION
                      GENERAL RELATIVITY
                      PHOTOELECTRIC EFFECT
      FERMI      -->  NUCLEAR FISSION
      MILLIKAN   -->  PHOTOELECTRIC EFFECT
                      ELECTRIC CHARGE
      STRASSMAN  -->  NUCLEAR FISSION
 
 
Determining the dimension of a symbol
 
   The integer function DIM exists for determining how many values are
   associated with a symbol. (Note that the DIM function does not modify
   the symbol table.)
 
   The code,
 
      NUMSUB = SYDIMC ( 'EINSTEIN', TABSYM, TABPTR, TABVAL )
 
   returns the value of 3 for NUMSUB.
 
 
Three Letter Mnemonics used in Subroutine Names
--------------------------------------------------------
 
   The following is a list of the three letter mnemonics and their related
   functions.
 
         DEL    delete a symbol
 
         DIM    return the dimension of a symbol (function)
 
         DUP    duplicate a symbol
 
         ENQ    enque a value onto an existing symbol
 
         FET    fetch the name of the Nth symbol
 
         GET    return all of the values associated with a symbol
 
         NTH    return the Nth value associated with a symbol
 
         ORD    order the values associated with a symbol
 
         POP    pop a value associated with a symbol
 
         PSH    push a value onto a symbol
 
         PUT    create a symbol with several associated values
 
         REN    rename an existing symbol
 
         SET    create a symbol with one associated value
 
         SEL    select a subset of values associated with a symbol
 
         TRN    transpose two values associated with a symbol
 
 
Calling Sequences
--------------------------------------------------------
 
   The following is a list of the calling sequences of the generic symbol
   table routines in SPICELIB.
 
   Subroutines:
 
      SYDELx  ( NAME, TABSYM, TABPTR, TABVAL )
 
      SYDUPx  ( NAME, COPY, TABSYM, TABPTR, TABVAL )
 
      SYENQx  ( NAME, VALUE, TABSYM, TABPTR, TABVAL )
 
      SYFETx  ( NTH, TABSYM, TABPTR, TABVAL, NAME, FOUND )
 
      SYGETx  ( NAME, TABSYM, TABPTR, TABVAL, N, VALUES, FOUND )
 
      SYNTHx  ( NAME, NTH, TABSYM, TABPTR, TABVAL, VALUE, FOUND )
 
      SYORDx  ( NAME, TABSYM, TABPTR, TABVAL )
 
      SYPOPx  ( NAME, TABSYM, TABPTR, TABVAL, VALUE, FOUND )
 
      SYPSHx  ( NAME, VALUE, TABSYM, TABPTR, TABVAL )
 
      SYPUTx  ( NAME, VALUES, N, TABSYM, TABPTR, TABVAL )
 
      SYRENx  ( OLD, NEW, TABSYM, TABPTR, TABVAL )
 
      SYSELx  ( NAME, BEGIN, END, TABSYM, TABPTR, TABVAL, VALUES, FOUND )
 
      SYSETx  ( NAME, VALUE, TABSYM, TABPTR, TABVAL )
 
      SYTRNx  ( NAME, I, J, TABSYM, TABPTR, TABVAL )
 
   Functions:
 
      SYDIMx  ( NAME, TABSYM, TABPTR, TABVAL )
 
