Index: /trunk/doc/pslib/ChangeLogSDRS.tex =================================================================== --- /trunk/doc/pslib/ChangeLogSDRS.tex (revision 3314) +++ /trunk/doc/pslib/ChangeLogSDRS.tex (revision 3315) @@ -1,3 +1,3 @@ -%%% $Id: ChangeLogSDRS.tex,v 1.70 2005-02-17 02:34:52 price Exp $ +%%% $Id: ChangeLogSDRS.tex,v 1.71 2005-02-24 01:30:58 price Exp $ \subsection{Changes from version 00 to version 01} @@ -472,6 +472,11 @@ \item fix typo in psVector typedef \item add limit param to psDBSelectRows() -\item change psDBUpdateRows() & psDBDeleteRows() to return signed values +\item change psDBUpdateRows() and psDBDeleteRows() to return signed values \item Made \code{psMemSetDeallocator} and \code{psMemGetDeallocator} public functions, and cleaned up description. -\end{itemize} +\item Reworked \code{psLookupTable} functions so that the number of + columns and their types are defined by a \code{scanf}-like format + string. Added \code{psVectorsReadFromFile} and + \code{psLookupTableImport} to generalise the reading of tabular data + from a file. +\end{itemize} Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 3314) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 3315) @@ -1,3 +1,3 @@ -%%% $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,58 +1787,98 @@ 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,8 +1891,4 @@ and \code{psLookupTableInterpolateAll} shall return \code{NULL} --- that is, no attempt is made at extrapolation. - - - - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%