Changeset 3315 for trunk/doc/pslib/psLibSDRS.tex

Timestamp:

Feb 23, 2005, 3:31:03 PM (21 years ago)

Author:

Paul Price

Message:

Reworked psLookupTable functions so that the number of columns and
their types are defined by a scanf-like format string. Added
psVectorsReadFromFile and psLookupTableImport to generalise the
reading of tabular data from a file.

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (3 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.182 2005-02-17 02:34:56 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.183 2005-02-24 01:31:03 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -1787 +1787 @@
 polar motion vector as a function of date.
 
+One of the key functionalities of a lookup table is to read data from
+an ordinary text file into an array of vectors.  This functionality is
+generally useful, and so we specify a separate function that may be
+called independently:
+\begin{verbatim}
+psArray *psVectorsReadFromFile(const char *filename, const char *format);
+\end{verbatim}
+\code{psVectorsReadFromFile} shall return an array of
+\code{psVector}s, read from the specified \code{filename}.  The file
+shall be plain text, consisting of an identical number of columns on
+each line, with the values separated by whitespace.  Lines commencing
+with a comment character (the pound sign, \code{#}) and blank lines
+shall be ignored.  The \code{format} is a \code{scanf}-like format
+which specifies the number of columns in the file, as well as their
+types.  The following formats shall be defined: \code{\%d} for psS32,
+\code{\%ld} for psS64, \code{\%f} for psF32, and \code{\%lf} for
+psF64.  A star (\code{*}) in the format shall indicate that the column
+is to be skipped.
+
+
 \begin{verbatim}
 typedef struct {
+    const char *filename;               ///< File from which data is to be read
+    const char *format;                 ///< scanf-like format string for file
+    unsigned int indexCol;              ///< Column of the index vector (starting at zero)
     psVector *index;                    ///< Index values
     psArray *values;                    ///< Corresponding values: an array of vectors
-    const char *filename;               ///< File from which table was read
     const psF64 validFrom, validTo;     ///< Range of validity
 } psLookupTable;
 \end{verbatim}
 
-\code{index} shall contain the index values, which shall be sorted in
-increasing order.  The \code{values} shall consist of an array of
-vectors, each of the same length as the \code{index} vector.  The
-vectors (including the \code{index} and all vectors in the
-\code{values} array) may be any numerical type except complex types.
-The \code{filename} shall specify the file from which the table is to
-be read.  The \code{validFrom} and \code{validTo} shall specify the
-range of valid values for the index; in most cases, these will simply
-be the first and last indices.
+\code{filename} shall specify the file from which the lookup table
+data is to be read.  \code{format} shall contain a \code{scanf}-like
+format string specifying how the columns are to be interpreted (see
+\code{psVectorsReadFromFile}).  \code{indexCol} shall specify the
+index of the column (with the first column having an index of zero)
+that will form the index values.  \code{index} shall contain the index
+values, which shall be sorted in increasing order.  The \code{values}
+shall consist of an array of vectors, each of the same length as the
+\code{index} vector.  The vectors (including the \code{index} and all
+vectors in the \code{values} array) may be any numerical type except
+complex types.  The \code{validFrom} and \code{validTo} shall specify
+the range of valid values for the index; in most cases, these will
+simply be the first and last indices.
 
 The constructor shall be:
 \begin{verbatim}
-psLookupTable *psLookupTableAlloc(const char *filename, int numValues);
-\end{verbatim}
-Here the \code{filename} indicates the file from which the table
-shall be read when \code{psLookupTableRead} is
-called. \code{numValues} indicates the number of vectors in the
-\code{values} array.
-
-The destructor shall also free the components.
+psLookupTable *psLookupTableAlloc(const char *filename, ///< File from which to read
+                                  const char *format ///< scanf-like format string
+                                  int indexCol ///< Column of the index vector (starting at zero)
+                                  );
+\end{verbatim}
+This function shall allocate a \code{psLookupTable}, and set the
+appropriate values, but it shall not read the lookup table.  This is
+so that the lookup table can be specified at the initialisation of a
+program, but not read unless required.
+
+The destructor shall free all the components.
+
+\begin{verbatim}
+psLookupTable *psLookupTableImport(psLookupTable *table, ///< Lookup table into which to import
+                                   const psArray *vectors, ///< Array of vectors
+                                   int indexCol ///< Index of the index vector in the array of vectors
+                                   );
+\end{verbatim}
+\code{psLookupTableImport} shall import an array of vectors into a
+\code{table}.  If \code{table} is \code{NULL}, a new
+\code{psLookupTable} shall be allocated and returned.  The array of
+\code{vectors}, which was likely generated by
+\code{psVectorsReadFromFile}, are imported by setting the
+\code{table->index} to the vector specified by the \code{indexCol},
+and pointing the \code{table->values} array data to the remaining
+vectors in \code{vectors}.  Reference counters for the vectors shall
+be incremented as appropriate.  The \code{validFrom} and
+\code{validTo} members of the \code{table} shall be set to the first
+and last values in the index vector.  If the \code{index} vector is
+not sorted in the file, the lookup table shall be sorted prior to the
+function returning.
 
 \begin{verbatim}
 int psLookupTableRead(psLookupTable *table);
 \end{verbatim}
-\code{psLookupTableRead} shall read the \code{table} from the
-appropriate file and import the data into the \code{table}, and set
-the \code{validFrom} and \code{validTo} on the basis of the first and
-last values in the \code{table}.  Sufficient memory shall be allocated
-to hold all the data in the specified file.  The file shall be plain
-text, with index and values on separate lines, separated by
-whitespace.  Lines commencing with a comment character (the pound
-sign, \code{#}) and blank lines shall be ignored.
-\code{table->values->n} in addition to the index shall be read on each
-line.  If the \code{index} vector is not sorted in the file, the
-lookup table shall be sorted prior to the function returning, but no
-sort shall be performed if the indices were sorted in the file.  If
-the input \code{table} has already been read from a file, the file
-shall be re-read, and the contents replaced.  The function shall
-return the number of lines read (not including ignored lines).
+\code{psLookupTableRead} combines \code{psVectorsReadFromFile} and
+\code{psLookupTableImport} to read the appropriate file and import the
+data into the extant \code{table}.  If the input \code{table} has
+already been read from a file, the file shall be re-read, and the
+contents replaced.  The function shall return the number of lines read
+(not including ignored lines).
 
 Interpolation on a lookup table is performed by the following
 functions:
 \begin{verbatim}
-psF64 psLookupTableInterpolate(psLookupTable *table, psF64 index, int column);
-psVector *psLookupTableInterpolateAll(psLookupTable *table, psF64 index);
+psF64 psLookupTableInterpolate(const psLookupTable *table, psF64 index, int column);
+psVector *psLookupTableInterpolateAll(const psLookupTable *table, psF64 index);
 \end{verbatim}
 Both functions shall interpolate the \code{table} at the provided
@@ -1851 +1891 @@
 and \code{psLookupTableInterpolateAll} shall return \code{NULL} ---
 that is, no attempt is made at extrapolation.
-
-
-
-
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%