Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 4057) +++ trunk/doc/pslib/psLibSDRS.tex (revision 4061) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.238 2005-05-31 21:55:39 jhoblitt Exp $ +%%% $Id: psLibSDRS.tex,v 1.239 2005-06-01 01:33:39 jhoblitt Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -335,7 +335,7 @@ psFreeFcn freeFcn; ///< deallocator. If NULL, use generic deallocation. size_t userMemorySize; ///< the size of the user-portion of the memory block - const psMemoryId id; ///< a unique ID for this allocation + const psMemId id; ///< a unique ID for this allocation const char* file; ///< set from __FILE__ in e.g. p_psAlloc - const int lineno; ///< set from __LINE__ in e.g. p_psAlloc + const unsigned int lineno; ///< set from __LINE__ in e.g. p_psAlloc pthread_mutex_t refCounterMutex; ///< mutex to ensure exclusive access to reference counter psReferenceCount refCounter; ///< how many times pointer is referenced @@ -345,5 +345,5 @@ typedef void (*psFreeFcn)(void* ptr); -typedef unsigned long psMemoryId; +typedef unsigned long psMemId; typedef unsigned long psReferenceCount; \end{datatype} @@ -434,7 +434,7 @@ % \begin{prototype} -psPtr p_psAlloc(size_t size, const char *file, int lineno); -psPtr p_psRealloc(psPtr ptr, size_t size, const char *file, int lineno); -void p_psFree(psPtr ptr, const char *file, int lineno); +psPtr p_psAlloc(size_t size, const char *filename, unsigned int lineno); +psPtr p_psRealloc(psPtr ptr, size_t size, const char *filename, unsigned int lineno); +void p_psFree(psPtr ptr, const char *filename, unsigned int lineno); \end{prototype} % @@ -481,6 +481,6 @@ \begin{prototype} -void psMemSetDeallocator(void* ptr, psFreeFcn freeFcn); -psFreeFcn psMemGetDeallocator(void* ptr); +void psMemSetDeallocator(psPtr ptr, psFreeFcn freeFcn); +psFreeFcn psMemGetDeallocator(const psPtr ptr); \end{prototype} @@ -526,5 +526,5 @@ \item \code{psMemExhaustedCallbackDefault} \item \code{psMemProblemCallbackDefault} -\item \code{psMemAllocateCallbackDefault} +\item \code{psMemAllocCallbackDefault} \item \code{psMemFreeCallbackDefault} \end{itemize} @@ -573,5 +573,5 @@ % \begin{datatype} -typedef void (*psMemProblemCallback)(psMemBlock *ptr, char *file, int lineno); +typedef void (*psMemProblemCallback)(psMemBlock *ptr, char *filename, unsigned int lineno); \end{datatype} @@ -588,9 +588,9 @@ detected by checking \code{psMemBlock.refCounter}. -\subsubsubsection{\tt psMemAllocateCallback \& psMemFreeCallback} - -Two private variables, \code{p_psMemAllocateID} and +\subsubsubsection{\tt psMemAllocCallback \& psMemFreeCallback} + +Two private variables, \code{p_psMemAllocID} and \code{p_psMemFreeID}, can be used to trace the allocation and freeing -of specific memory blocks. If the first (\code{p_psMemAllocateID}) is +of specific memory blocks. If the first (\code{p_psMemAllocID}) is set and a memory block with that ID is allocated, the corresponding callback is called just before memory is returned to the calling @@ -602,6 +602,6 @@ % \begin{prototype} -psMemoryId psMemAllocateCallbackSetID(psMemoryId id); -psMemoryId psMemFreeCallbackSetID(psMemoryId id); +psMemId psMemAllocCallbackSetID(psMemId id); +psMemId psMemFreeCallbackSetID(psMemId id); \end{prototype} % @@ -609,26 +609,26 @@ % \begin{datatype} -typedef psMemoryId (*psMemAllocateCallback)(const psMemBlock *ptr); -\end{datatype} - -\begin{prototype} -psMemAllocateCallback psMemAllocateCallbackSet(psMemAllocateCallback func); -\end{prototype} - -\begin{datatype} -typedef psMemoryId (*psMemFreeCallback)(const psMemBlock *ptr); +typedef psMemId (*psMemAllocCallback)(const psMemBlock *ptr); +\end{datatype} + +\begin{prototype} +psMemAllocCallback psMemAllocCallbackSet(psMemAllocCallback func); +\end{prototype} + +\begin{datatype} +typedef psMemId (*psMemFreeCallback)(const psMemBlock *ptr); \end{datatype} \begin{prototype} psMemFreeCallback psMemFreeCallbackSet(psMemFreeCallback func); -psMemoryId psMemGetId(void); +psMemId psMemGetId(void); \end{prototype} % The callback functions are called with a pointer to the corresponding memory block. The routines \code{psMemFreeCallbackIDSet} and -\code{psMemAllocateCallbackIDSet} accept the desired ID value and return the +\code{psMemAllocCallbackIDSet} accept the desired ID value and return the old value to the user. The return values of the handlers installed by -\code{psMemAllocateCallbackSet} and \code{psMemFreeCallbackSet} are -used to increment the values of \code{p_psMemAllocateID} and +\code{psMemAllocCallbackSet} and \code{psMemFreeCallbackSet} are +used to increment the values of \code{p_psMemAllocID} and \code{p_psMemFreeID} respectively. For example, a return value of \code{0} implies that the value is unchanged; if the value is \code{2} @@ -649,5 +649,5 @@ % \begin{prototype} -int psMemCheckLeaks(psMemoryId id0, psMemBlock ***array, FILE *fd, bool persistence); +int psMemCheckLeaks(psMemId id0, psMemBlock ***array, FILE *fd, bool persistence); int psMemCheckCorruption(bool abort_on_error); \end{prototype} @@ -828,5 +828,5 @@ % \begin{prototype} -void psTrace(const char *facil, int myLevel,...); +void psTrace(const char *facil, int level,...); \end{prototype} % @@ -835,5 +835,5 @@ \code{vprintf} functions. This command specifies the name of the facility to which the message belongs (\code{facil}), the trace level -for this message in that facility (\code{myLevel}) and the message +for this message in that facility (\code{level}) and the message itself. @@ -857,5 +857,5 @@ \code{psTrace}) must be printed if and only if \code{psTraceGetLevel(facil)} returns a value greater than or equal to -the value of \code{myLevel} for that message. That is, a larger +the value of \code{level} for that message. That is, a larger number for the trace level corresponds to lower-level statements, and hence is more verbose. @@ -956,9 +956,9 @@ % \begin{prototype} -void psLogMsg(const char *name, int myLevel, const char *fmt, ...); -void psLogMsgV(const char *name, int myLevel, const char *fmt, va_list ap); +void psLogMsg(const char *name, int level, const char *fmt, ...); +void psLogMsgV(const char *name, int level, const char *fmt, va_list ap); \end{prototype} where \code{name} is a word to describe the source of the message, -\code{myLevel} is the severity level of this message, and \code{fmt} +\code{level} is the severity level of this message, and \code{fmt} is a printf-style formatting statement defining the actual message, and is followed by the arguments to the formatting code. The second @@ -983,5 +983,5 @@ This function returns the previous log level. A specific message invoked with \code{psLogMsg} is only printed if its value of -\code{myLevel} is less than the current value set by +\code{level} is less than the current value set by \code{psLogSetLevel}. The default log level is set to \code{PS_LOG_INFO}. @@ -1059,5 +1059,5 @@ returns the error code. \begin{prototype} -psErrorCode p_psError(const char *file, int lineno, const char *func, psErrorCode code, bool new, +psErrorCode p_psError(const char *filename, unsigned int lineno, const char *func, psErrorCode code, bool new, const char *fmt, ...); \end{prototype} @@ -1340,9 +1340,9 @@ In addition, we specify two functions for working with \code{psScalar} data: \begin{prototype} -psScalar *psScalarAlloc(psC64 value, psElemType dataType); +psScalar *psScalarAlloc(complex double value, psElemType type); psScalar *psScalarCopy(const psScalar *value); \end{prototype} The first creates a \code{psType}-ed structure from a constant value, -casting it as appropriate based on the \code{dataType}. The second +casting it as appropriate based on the \code{type}. The second copies the provided \code{psScalar} value. This latter function is necessary to keep a copy of an existing \code{psScalar} value, since @@ -1605,6 +1605,13 @@ specified \code{position}. -\begin{prototype} -psArray *psArraySort(psArray *array, int (*compare)(const void **a, const void **b) ); +\begin{datatype} +typedef int (*psComparePtrFunc) ( + const void **a, ///< first comparison target + const void **b ///< second comparison target +); +\end{datatype} + +\begin{prototype} +psArray *psArraySort(psArray *array, psComparePtrFunc func); \end{prototype} An array may be sorted using \code{psArraySort}, which requires the @@ -1652,5 +1659,5 @@ \begin{prototype} -psList *psListAlloc(const void *data); +psList *psListAlloc(psPtr data); \end{prototype} Create a list. This function may take a pointer to a data item, or it @@ -1724,7 +1731,7 @@ \begin{prototype} -bool psListAdd(psList *list, int location, const void *data); -bool psListAddAfter(psListIterator *iterator, const void *data); -bool psListAddBefore(psListIterator *iterator, const void *data); +bool psListAdd(psList *list, int location, psPtr data); +bool psListAddAfter(psListIterator *iterator, psPtr data); +bool psListAddBefore(psListIterator *iterator, psPtr data); \end{prototype} the first function, \code{psListAdd}, adds an entry to the \code{list} @@ -1742,7 +1749,7 @@ \begin{prototype} -void *psListGet(psList *list, int location); -void *psListGetAndIncrement(psListIterator *iterator); -void *psListGetAndDecrement(psListIterator *iterator); +psPtr psListGet(psList *list, int location); +psPtr psListGetAndIncrement(psListIterator *iterator); +psPtr psListGetAndDecrement(psListIterator *iterator); \end{prototype} A data item may be retrieved from the list with these functions. The @@ -1773,5 +1780,5 @@ \begin{prototype} bool psListRemove(psList *list, int location) -bool psListRemoveData(psList *list, const void *data); +bool psListRemoveData(psList *list, psPtr data); \end{prototype} A data item may be removed from the list with these functions. For @@ -1800,5 +1807,5 @@ \begin{prototype} -psList *psListSort(psList *list, int (*compare)(const void **a, const void **b) ); +psList *psListSort(psList *list, psComparePtrFunc func); \end{prototype} A list may be sorted using \code{psListSort}, which requires the @@ -1855,5 +1862,5 @@ A hash table is created with the following function: \begin{prototype} -psHash *psHashAlloc(psS32 nbuckets); +psHash *psHashAlloc(psU32 nalloc); \end{prototype} which allocates the space for the hash table, creating and @@ -1864,5 +1871,5 @@ A data item may be added to the hash table with the function: \begin{prototype} -bool psHashAdd(psHash *table, const char *key, psPtr data); +bool psHashAdd(psHash *hash, const char *key, psPtr data); \end{prototype} In this function, the value of the string \code{key} is used to @@ -1875,5 +1882,5 @@ The data associated with a given key may be found with the function: \begin{prototype} -void *psHashLookup(const psHash *table, const char *key); +psPtr psHashLookup(const psHash *hash, const char *key); \end{prototype} which returns the data value pointed to by the element associated with @@ -1881,5 +1888,5 @@ a specific key may be removed (deleted) with the function: \begin{prototype} -bool psHashRemove(psHash *table, const char *key); +bool psHashRemove(psHash *hash, const char *key); \end{prototype} The function returns a value of \code{true} if the operation was @@ -1888,5 +1895,5 @@ The function \begin{prototype} -psList *psHashKeyList(const psHash *table); +psList *psHashKeyList(const psHash *hash); \end{prototype} returns the complete list of defined keys associated with the @@ -1894,5 +1901,5 @@ \begin{prototype} -psArray *psHashToArray(const psHash *table); +psArray *psHashToArray(const psHash *hash); \end{prototype} This function places the data in a \code{psHash} into a \code{psArray} @@ -1956,5 +1963,5 @@ \begin{prototype} psLookupTable *psLookupTableAlloc(const char *filename, ///< File from which to read - const char *format ///< scanf-like format string + const char *format, ///< scanf-like format string int indexCol ///< Column of the index vector (starting at zero) ); @@ -2000,6 +2007,6 @@ functions: \begin{prototype} -psF64 psLookupTableInterpolate(const psLookupTable *table, psF64 index, int column, psLookupStatusType *status); -psVector *psLookupTableInterpolateAll(const psLookupTable *table, psF64 index, psVector *stats); +double psLookupTableInterpolate(const psLookupTable *table, double index, int column, psLookupStatusType *status); +psVector *psLookupTableInterpolateAll(const psLookupTable *table, double index, psVector *stats); \end{prototype} Both functions shall interpolate the \code{table} at the provided @@ -2054,5 +2061,5 @@ We also require the corresponding constructor and destructor: \begin{prototype} -psBitSet *psBitSetAlloc(psS32 n); +psBitSet *psBitSetAlloc(psU32 nalloc); \end{prototype} where \code{n} is the requested number of bits. @@ -2068,9 +2075,9 @@ \begin{prototype} -psBitSet *psBitSetSet(psBitSet *bitSet, psS32 bit); -psBitSet* psBitSetClear(psBitSet *bitSet, psS32 bit); +psBitSet *psBitSetSet(psBitSet *bitSet, psU32 bit); +psBitSet* psBitSetClear(psBitSet *bitSet, psU32 bit); psBitSet *psBitSetOp(psBitSet *outBitSet, const psBitSet *inBitSet1, const char *operator, const psBitSet *inBitSet2); psBitSet *psBitSetNot(psBitSet *outBitSet, const psBitSet *inBitSet); -bool psBitSetTest(const psBitSet *bitSet, psS32 bit); +bool psBitSetTest(const psBitSet *bitSet, psU32 bit); char *psBitSetToString(const psBitSet* bitSet); \end{prototype} @@ -2418,14 +2425,14 @@ To evaluate the polynomials at specific coordinates, we define: \begin{prototype} -psF64 psPolynomial1DEval(const psPolynomial2D *myPoly, +psF64 psPolynomial1DEval(const psPolynomial2D *poly, psF64 x); -psF64 psPolynomial2DEval(const psPolynomial2D *myPoly, +psF64 psPolynomial2DEval(const psPolynomial2D *poly, psF64 x, psF64 y); -psF64 psPolynomial3DEval(const psPolynomial2D *myPoly, +psF64 psPolynomial3DEval(const psPolynomial2D *poly, psF64 x, psF64 y, psF64 z); -psF64 psPolynomial4DEval(const psPolynomial2D *myPoly, +psF64 psPolynomial4DEval(const psPolynomial2D *poly, psF64 x, psF64 y, @@ -2436,14 +2443,14 @@ In the event that several evaluations are required, we also define: \begin{prototype} -psVector *psPolynomial1DEvalVector(const psPolynomial2D *myPoly, +psVector *psPolynomial1DEvalVector(const psPolynomial2D *poly, const psVector *x); -psVector *psPolynomial2DEvalVector(const psPolynomial2D *myPoly, +psVector *psPolynomial2DEvalVector(const psPolynomial2D *poly, const psVector *x, const psVector *y); -psVector *psPolynomial3DEvalVector(const psPolynomial2D *myPoly, +psVector *psPolynomial3DEvalVector(const psPolynomial2D *poly, const psVector *x, const psVector *y, const psVector *z); -psVector *psPolynomial4DEvalVector(const psPolynomial2D *myPoly, +psVector *psPolynomial4DEvalVector(const psPolynomial2D *poly, const psVector *x, const psVector *y, @@ -2716,5 +2723,5 @@ \begin{prototype} -psPolynomial1D *psVectorFitPolynomial1D(psPolynomial1D *myPoly, +psPolynomial1D *psVectorFitPolynomial1D(psPolynomial1D *poly, const psVector *mask, unsigned int maskValue @@ -2722,5 +2729,5 @@ const psVector *fErr const psVector *x); -psPolynomial2D *psVectorFitPolynomial2D(psPolynomial1D *myPoly, +psPolynomial2D *psVectorFitPolynomial2D(psPolynomial1D *poly, const psVector *mask, unsigned int maskValue @@ -2729,5 +2736,5 @@ const psVector *x, const psVector *y); -psPolynomial3D *psVectorFitPolynomial3D(psPolynomial1D *myPoly, +psPolynomial3D *psVectorFitPolynomial3D(psPolynomial1D *poly, const psVector *mask, unsigned int maskValue @@ -2737,5 +2744,5 @@ const psVector *y, const psVector *z); -psPolynomial4D *psVectorFitPolynomial4D(psPolynomial1D *myPoly, +psPolynomial4D *psVectorFitPolynomial4D(psPolynomial1D *poly, const psVector *mask, unsigned int maskValue @@ -2748,5 +2755,5 @@ \end{prototype} These functions return the polynomial that best fits the input data. -The provided polynomial, \code{myPoly}, specifies the fit order, and +The provided polynomial, \code{poly}, specifies the fit order, and will be returnd with the best-fit coefficients. The dependent variable and its error (\code{f, fErr}) are provided along with the @@ -2762,5 +2769,5 @@ \begin{prototype} -psPolynomial1D *psVectorClipFitPolynomial1D(psPolynomial1D *myPoly, +psPolynomial1D *psVectorClipFitPolynomial1D(psPolynomial1D *poly, psStats *stats, const psVector *mask, @@ -2769,5 +2776,5 @@ const psVector *fErr const psVector *x); -psPolynomial2D *psVectorClipFitPolynomial2D(psPolynomial1D *myPoly, +psPolynomial2D *psVectorClipFitPolynomial2D(psPolynomial1D *poly, psStats *stats, const psVector *mask, @@ -2777,5 +2784,5 @@ const psVector *x, const psVector *y); -psPolynomial3D *psVectorClipFitPolynomial3D(psPolynomial1D *myPoly, +psPolynomial3D *psVectorClipFitPolynomial3D(psPolynomial1D *poly, psStats *stats, const psVector *mask, @@ -2786,5 +2793,5 @@ const psVector *y, const psVector *z); -psPolynomial4D *psVectorClipFitPolynomial4D(psPolynomial1D *myPoly, +psPolynomial4D *psVectorClipFitPolynomial4D(psPolynomial1D *poly, psStats *stats, const psVector *mask, @@ -3075,5 +3082,5 @@ \begin{prototype} psImage *psImageRotate(psImage *out, const psImage *input, float angle, - psC64 exposed, psImageInterpolateMode mode); + complex double exposed, psImageInterpolateMode mode); \end{prototype} Rotate the input image by given angle, specified in radians. The @@ -3089,5 +3096,5 @@ \begin{prototype} psImage *psImageShift(psImage *out, const psImage *input, - float dx, float dy, psC64 exposed, psImageInterpolateMode mode); + float dx, float dy, complex double exposed, psImageInterpolateMode mode); \end{prototype} Shift image by an arbitrary number of pixels (\code{dx,dy}) in either @@ -3198,7 +3205,7 @@ \begin{prototype} -psC64 psImagePixelInterpolate(const psImage *input, float x, float y, +complex double psImagePixelInterpolate(const psImage *input, float x, float y, const psImage *mask, unsigned int maskVal, - psC64 unexposedValue, psImageInterpolateMode mode); + complex double unexposedValue, psImageInterpolateMode mode); \end{prototype} Perform interpolation of image pixel values to the given fractional @@ -3318,6 +3325,6 @@ typedef struct { - int n; // Number in use - const int nalloc; // Number allocated + psU32 n; // Number in use + const psU32 nalloc; // Number allocated psPixelCoord *data; // The pixel coordinates } psPixels; @@ -3325,6 +3332,6 @@ \begin{prototype} -psPixels *psPixelsAlloc(int nalloc); -psPixels *psPixelsRealloc(psPixels *pixels, int nalloc); +psPixels *psPixelsAlloc(psU32 nalloc); +psPixels *psPixelsRealloc(psPixels *pixels, psU32 nalloc); \end{prototype} @@ -3971,5 +3978,5 @@ typedef struct { psList *list; ///< list of psMetadataItem - psHash *table; ///< hash table of the same metadata + psHash *hash; ///< hash table of the same metadata } psMetadata; \end{datatype} @@ -4039,5 +4046,5 @@ \begin{prototype} -bool psMetadataAddItem(psMetadata *md, const psMetadataItem *item, int location, int mode); +bool psMetadataAddItem(psMetadata *md, const psMetadataItem *item, psS32 location, psS32 flags); bool psMetadataAdd(psMetadata *md, int location, const char *name, int format, const char *comment, ...); bool psMetadataAddV(psMetadata *md, int location, const char *name, int format, const char *comment, @@ -4247,5 +4254,5 @@ data type, printing is not allowed. \begin{prototype} -bool psMetadataItemPrint(FILE *fd, const char *format, const psMetadataItem *md); +bool psMetadataItemPrint(FILE *fd, const char *format, const psMetadataItem *item); \end{prototype} @@ -4503,5 +4510,5 @@ to a complete \code{psXMLDoc} (in memory) and vice versa: \begin{prototype} -psXMLDoc *psMetadataToXMLDoc(const psMetadata *metadata); +psXMLDoc *psMetadataToXMLDoc(const psMetadata *md); psMetadata *psXMLDocToMetadata(const psXMLDoc *doc); \end{prototype} @@ -4518,6 +4525,6 @@ into a complete \code{psXMLDoc} (also in memory), and vice versa: \begin{prototype} -psXMLDoc *psXMLParseMemory(const char *buffer, int size); -int psXMLDocToMemory(const psXMLDoc *doc, char *buffer); +psXMLDoc *psXMLParseMem(const char *buffer, int size); +int psXMLDocToMem(const psXMLDoc *doc, char *buffer); \end{prototype} @@ -4891,10 +4898,10 @@ \begin{prototype} -void *psFitsReadTableRowRaw(const int *nBytes, const psFits *fits, int row); +void *psFitsReadTableRowRaw(size_t *size, const psFits *fits, int row); \end{prototype} This function reads a single row of the table in the extension pointed at by the \code{psFits} file pointer. The row number to be read is given by \code{row}. The result is returned as collection of -\code{nBytes} bytes allocated by the function. The function must +\code{size} bytes allocated by the function. The function must apply the needed byte-swapping on the data in the row based on the description of the table data in the table header. \tbr{we may need @@ -4923,9 +4930,9 @@ \begin{prototype} -psArray *psFitsReadTableRaw(int *nBytes, const psFits *fits); +psArray *psFitsReadTableRaw(size_t *size, const psFits *fits); \end{prototype} This function reads the entire data block from a table into the a \code{psArray}, with one element of the array per row. The number of -bytes per row is returned in \code{nBytes}. The function must apply +bytes per row is returned in \code{size}. The function must apply the needed byte-swapping on the data in each row based on the description of the table data in the table header. @@ -5044,5 +5051,5 @@ \begin{prototype} -psF64 *psTimeToLMST(psTime *time, psF64 longitude); +double psTimeToLMST(psTime *time, double longitude); \end{prototype} @@ -5109,7 +5116,7 @@ \begin{prototype} -psTime *psTimeFromJD(double input); -psTime *psTimeFromMJD(double input); -psTime *psTimeFromISO(const char *input, psTimeType timeSystem); +psTime *psTimeFromJD(double jd); +psTime *psTimeFromMJD(double mjd); +psTime *psTimeFromISO(const char *input, psTimeType type); psTime *psTimeFromTimeval(const timeval *input); psTime *psTimeFromUTC(psS64 sec, psU32 nsec, bool leapsecond); @@ -5124,6 +5131,6 @@ \begin{prototype} -psTime *psTimeMath(const psTime *time, psF64 delta); -psF64 psTimeDelta(const psTime *time1, const psTime *time2); +psTime *psTimeMath(const psTime *time, double delta); +double psTimeDelta(const psTime *time1, const psTime *time2); \end{prototype}