IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Jun 13, 2005, 4:19:36 PM (21 years ago)
Author:
Paul Price
Message:

Changes to psMetadataType --> psDataType

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/pslib/psLibSDRS.tex

    r4239 r4242  
    1 %%% $Id: psLibSDRS.tex,v 1.275 2005-06-13 22:41:59 price Exp $
     1%%% $Id: psLibSDRS.tex,v 1.276 2005-06-14 02:19:36 price Exp $
    22\documentclass[panstarrs,spec]{panstarrs}
    33
    … …  
    790790\subsubsection{Type information}
    791791
     792We need to be able to specify two different sorts of types.
     793
     794The first, for use with math structures (\S\ref{sec:mathStructures}),
     795defines a numerical type; e.g., short integer, double-precision
     796floating point, etc:
     797
     798\begin{datatype}
     799typedef enum {
     800    PS_TYPE_S8,                        ///< Character
     801    PS_TYPE_S16,                       ///< Short integer
     802    PS_TYPE_S32,                       ///< Integer
     803    PS_TYPE_S64,                       ///< Long integer
     804    PS_TYPE_U8,                        ///< Unsigned character
     805    PS_TYPE_U16,                       ///< Unsigned short integer
     806    PS_TYPE_U32,                       ///< Unsigned integer
     807    PS_TYPE_U64,                       ///< Unsigned long integer
     808    PS_TYPE_F32,                       ///< Floating point
     809    PS_TYPE_F64,                       ///< Double-precision floating point
     810    PS_TYPE_C32,                       ///< Complex numbers consisting of floats
     811    PS_TYPE_C64,                       ///< Complex numbers consisting of doubles
     812    PS_TYPE_BOOL                       ///< Boolean value
     813} psElemType;
     814\end{datatype}
     815
     816
     817The second, primarily for use with the metadata
     818(\S\ref{sec:metadata}), defines a data structure; e.g., list, array,
     819FITS file:
     820
     821\begin{datatype}
     822typedef enum {                         ///< type of item.data is:
     823    PS_DATA_S32  = PS_TYPE_S32,        ///< psS32
     824    PS_DATA_F32  = PS_TYPE_F32,        ///< psF32
     825    PS_DATA_F64  = PS_TYPE_F64,        ///< psF64
     826    PS_DATA_BOOL = PS_TYPE_BOOL,       ///< psBool
     827    PS_DATA_STRING = 0x10000,          ///< String (char *)
     828    PS_DATA_ARRAY,                     ///< psArray
     829    PS_DATA_BITSET,                    ///< psBitSet
     830    PS_DATA_CELL,                      ///< psCell
     831    PS_DATA_CHIP,                      ///< psChip
     832    PS_DATA_CUBE,                      ///< psCube
     833    PS_DATA_FITS,                      ///< psFits
     834    PS_DATA_HASH,                      ///< psHash
     835    PS_DATA_HISTOGRAM,                 ///< psHistogram
     836    PS_DATA_IMAGE,                     ///< psImage
     837    PS_DATA_KERNEL,                    ///< psKernel
     838    PS_DATA_LIST,                      ///< psList
     839    PS_DATA_LOOKUPTABLE,               ///< psLookupTable
     840    PS_DATA_METADATA,                  ///< psMetadata
     841    PS_DATA_METADATAITEM,              ///< psMetadataItem
     842    PS_DATA_MINIMIZATION,              ///< psMinimization
     843    PS_DATA_PIXELS,                    ///< psPixels
     844    PS_DATA_PLANE,                     ///< psPlane
     845    PS_DATA_PLANEDISTORT,              ///< psPlaneDistort
     846    PS_DATA_PLANETRANSFORM,            ///< psPlaneTransform
     847    PS_DATA_POLYNOMIAL1D,              ///< psPolynomial1D
     848    PS_DATA_POLYNOMIAL2D,              ///< psPolynomial2D
     849    PS_DATA_POLYNOMIAL3D,              ///< psPolynomial3D
     850    PS_DATA_POLYNOMIAL4D,              ///< psPolynomial4D
     851    PS_DATA_PROJECTION,                ///< psProjection
     852    PS_DATA_READOUT,                   ///< psReadout
     853    PS_DATA_REGION,                    ///< psRegion
     854    PS_DATA_SCALAR,                    ///< psScalar
     855    PS_DATA_SPHERE,                    ///< psSphere
     856    PS_DATA_SPHERETRANSFORM,           ///< psSphereTransform
     857    PS_DATA_SPLINE1D,                  ///< psSpline1D
     858    PS_DATA_STATS,                     ///< psStats
     859    PS_DATA_TIME,                      ///< psTime
     860    PS_DATA_VECTOR,                    ///< psVector
     861    PS_DATA_UNKNOWN,                   ///< Other data of an unknown type
     862    PS_DATA_METADATA_MULTI             ///< Used internally for metadata; not a 'real' type
     863} psDataType;
     864\end{datatype}
     865
     866Here we have not included every type of structure used in PSLib, but
     867only those we expect will be frequently carried around in containers.
     868We include \code{PS_DATA_S32, PS_DATA_F32, PS_DATA_F64} and
     869\code{PS_DATA_BOOL} since the metadata use these, and we set them to
     870the same values as in \code{psElemType}.
     871
     872The other values are offset from these ``primitive'' types so that
     873they can be identified easily.  A macro,
     874\code{PS_DATA_IS_PRIMITIVE(type)}, shall return \code{true} if the
     875type is one of the numerical data types (S32, F32, F64, bool).  In
     876such a case, the data value is directly available from the metadata.
     877Otherwise, a pointer to the data is available.
     878
     879\code{PS_DATA_METADATA_MULTI} is used by the metadata, so the user
     880should not use this type.
     881
     882\subsubsection{Type checking}
     883
    792884Several of the collections contain data using a \code{void*} pointer.
    793885This makes it difficult to ensure that data coming off a collection is
    … …  
    802894
    803895\begin{prototype}
     896psDataType psMemGetType(psPtr ptr);
     897\end{prototype}
     898
    804899bool psMemCheckArray(psPtr ptr);
    805900bool psMemCheckBitSet(psPtr ptr);
    … …  
    842937
    843938\begin{prototype}
    844 bool psMemCheckType(psType type, psPtr ptr);
    845 \end{prototype}
    846 
    847 \tbd{Need to define psType.}
     939bool psMemCheckType(psDataType type, psPtr ptr);
     940\end{prototype}
     941
     942The reason for having functions that check the type instead of
     943returning the type is that the check is quick and the result is clean,
     944while returning the type involves descending through a case statement.
    848945
    849946%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    … …  
    20722169    const psS32 id;                     ///< unique ID for this item
    20732170    char *name;                         ///< Name of item
    2074     psMetadataType type;                ///< type of this item
     2171    psDataType type;                    ///< type of this item
    20752172    const union {
    20762173        psS32 S32;                      ///< integer data
    … …  
    20942191\code{comment}. The \code{type} entry specifies how to interpret the
    20952192type of the data being represented, given by the enumerated type
    2096 \code{psMetadataType}:
    2097 %
    2098 \filbreak
    2099 \begin{datatype}
    2100 typedef enum {                         ///< type of item.data is:
    2101     PS_META_S32  = PS_TYPE_S32,        ///< psS32 primitive data.
    2102     PS_META_F32  = PS_TYPE_F32,        ///< psF32 primitive data.
    2103     PS_META_F64  = PS_TYPE_F64,        ///< psF64 primitive data.
    2104     PS_META_BOOL = PS_TYPE_BOOL,       ///< psBool primitive data.
    2105     PS_META_LIST = 0x10000,            ///< List data (Stored as item.data.list).
    2106     PS_META_STR,                       ///< String data (Stored as item.data.V).
    2107     PS_META_META,                      ///< Metadata (Stored as item.data.md).
    2108     PS_META_VEC,                       ///< Vector data (Stored as item.data.V).
    2109     PS_META_IMG,                       ///< Image data (Stored as item.data.V).
    2110     PS_META_HASH,                      ///< Hash data (Stored as item.data.V).
    2111     PS_META_LOOKUPTABLE,               ///< Lookup table data (Stored as item.data.V).
    2112     PS_META_JPEG,                      ///< JPEG data (Stored as item.data.V).
    2113     PS_META_PNG,                       ///< PNG data (Stored as item.data.V).
    2114     PS_META_ASTROM,                    ///< Astrometric coefficients (Stored as item.data.V).
    2115     PS_META_TIME,                      ///< psTime object (Stored as item.data.V).
    2116     PS_META_UNKNOWN,                   ///< Other data (Stored as item.data.V).
    2117     PS_META_MULTI                      ///< Used internally, do not create a metadata item of this type.
    2118 } psMetadataType;
    2119 \end{datatype}
    2120 The macro \code{PS_META_IS_PRIMITIVE(psMetadataType.type)} returns
    2121 true if the type is one of the primitive data types (S32, F64, etc).
    2122 In such a case, the data value is directly available.  Otherwise, a
    2123 pointer to the data is available.
     2193\code{psDataType}.
    21242194
    21252195A collection of metadata is represented by the \code{psMetadata} structure:
    … …  
    21462216\code{psMetadata.hash} entries, which are required to have unique
    21472217keys, would have a single entry with the keyword of the repeated key,
    2148 with the value of \code{psMetadataType} set to \code{PS_META_MULTI},
     2218with the value of \code{psDataType} set to \code{PS_DATA_METADATA_MULTI},
    21492219and the \code{psMetadataItem.data} element pointing to a \code{psList}
    21502220containing the actual entries.  If \code{psMetadataItemAlloc} is
    2151 called with the type set to \code{PS_META_MULTI}, such a repeated key
     2221called with the type set to \code{PS_DATA_METADATA_MULTI}, such a repeated key
    21522222is created.  In this case, the data value passed to
    21532223\code{psMetadataItemAlloc} (the quantity in ellipsis) must be
    … …  
    21632233psMetadataItem* psMetadataItemAllocS32(const char* name, const char* comment, psS32 value);
    21642234psMetadataItem* psMetadataItemAllocBool(const char* name, const char* comment, bool value);
    2165 psMetadataItem* psMetadataItemAllocPtr(const char* name, psMetadataType type, const char* comment, psPtr value);
     2235psMetadataItem* psMetadataItemAllocPtr(const char* name, psDataType type, const char* comment, psPtr value);
    21662236\end{prototype}
    21672237
    … …  
    21782248
    21792249\begin{prototype}
    2180 psMetadataItem *psMetadataItemAlloc(const char *name, psMetadataType type, const char *comment, ...);
    2181 psMetadataItem *psMetadataItemAllocV(const char *name, psMetadataType type, const char *comment, va_list list);
     2250psMetadataItem *psMetadataItemAlloc(const char *name, psDataType type, const char *comment, ...);
     2251psMetadataItem *psMetadataItemAllocV(const char *name, psDataType type, const char *comment, va_list list);
    21822252\end{prototype}
    21832253
    … …  
    22152285the \code{psList}.  The entry \code{mode} for \code{psMetadataAddItem}
    22162286is a bit mask constructed by OR-ing the allowed option flags (eg,
    2217 \code{PS_META_REPLACE}) which specify minor variations on the
     2287\code{PS_DATA_REPLACE}) which specify minor variations on the
    22182288behavior.  The \code{format} entry, which specifies both the metadata
    22192289type and the optional flags, is constructed by bit-wise OR-ing the
    2220 appropriate \code{psMetadataType} and allowed option flags.  Care
     2290appropriate \code{psDataType} and allowed option flags.  Care
    22212291should be taken not to leak memory when appending an item for which
    22222292the key already exists in the metadata (and is not
    2223 \code{PS_META_MULTI}).
     2293\code{PS_DATA_METADATA_MULTI}).
    22242294%
    22252295
    … …  
    22352305The functions above take option flags which modify the behavior when
    22362306metadata items are added to the metadata list.  These flags must be
    2237 bit-exclusive of those used above for the \code{psMetadataTypes}.  The
     2307bit-exclusive of those used above for the \code{psDataTypes}.  The
    22382308flags have the following meanings:
    22392309
    22402310\code{PS_META_DEFAULT}: This is the zero bit mask, to allow the
    22412311default behavior for \code{psMetadataAddItem} above.  If this is OR-ed
    2242 with a \code{psMetadataType}, the result is as if no OR-ing took
     2312with a \code{psDataType}, the result is as if no OR-ing took
    22432313place.
    22442314
    … …  
    22482318
    22492319\code{PS_META_DUPLICATE_OK}: Allow the new metadata item key to be a
    2250 duplicate (ie, \code{PS_META_MULTI}).  If an existing item with the
    2251 same key is already \code{PS_META_MULTI}, the new item is added to the
    2252 \code{PS_META_MULTI} list.  If the existing item is not
    2253 \code{PS_META_MULTI}, a \code{PS_META_MULTI} list is created to
    2254 contain both the existing item and the new item.  The original entry's
    2255 location on the psMetadata.list must be maintained.
    2256 
    2257 \code{PS_META_NULL}:  Indicates that \code{psMetadataItem.data} should be
    2258 ignored and that the the current value is ``NULL'' or undefined.  The
    2259 \code{psMetadataItem} must have a proper \code{type} set and it's \code{data}
    2260 field shall have a valid value.  e.g. A \code{type} of \code{PS_META_STR} would
    2261 require that 's \code{data} is set to \code{NULL}.
     2320duplicate (ie, \code{PS_DATA_METADATA_MULTI}).  If an existing item
     2321with the same key is already \code{PS_DATA_METADATA_MULTI}, the new
     2322item is added to the \code{PS_DATA_METADATA_MULTI} list.  If the
     2323existing item is not \code{PS_DATA_METADATA_MULTI}, a
     2324\code{PS_DATA_METADATA_MULTI} list is created to contain both the
     2325existing item and the new item.  The original entry's location on the
     2326psMetadata.list must be maintained.
     2327
     2328\code{PS_META_NULL}: Indicates that \code{psMetadataItem.data} should
     2329be ignored and that the the current value is ``NULL'' or undefined.
     2330The \code{psMetadataItem} must have a proper \code{type} set and it's
     2331\code{data} field shall have a valid value.  e.g. A \code{type} of
     2332\code{PS_DATA_STR} would require that its \code{data} is set to
     2333\code{NULL}.
    22622334
    22632335There are several of cases to handle for duplication of an existing
    … …  
    22652337must also be handled:
    22662338
    2267 If the new key already exists, but is not \code{PS_META_MULTI}, and
    2268 the new item is not flagged as either \code{PS_META_DUPLICATE_OK} or
    2269 \code{PS_META_REPLACE}, an error is raised. 
     2339If the new key already exists, but is not
     2340\code{PS_DATA_METADATA_MULTI}, and the new item is not flagged as
     2341either \code{PS_META_DUPLICATE_OK} or \code{PS_META_REPLACE}, an error
     2342is raised.
    22702343
    22712344If the new key already exists, and the existing item is
    2272 \code{PS_META_MULTI}, the new item is added to the MULTI list.  Note
    2273 that if the new item is also of type \code{PS_META_MULTI}, no action
    2274 is taken, but a successful exit status is returned (the action of
    2275 adding a \code{PS_META_MULTI} item to the metadata is equivalent to
    2276 setting that key to be tagged as \code{PS_META_MULTI}.  If it is
    2277 {\em already} \code{PS_META_MULTI}, this effect has already been
    2278 achieved). 
     2345\code{PS_DATA_METADATA_MULTI}, the new item is added to the MULTI
     2346list.  Note that if the new item is also of type
     2347\code{PS_DATA_METADATA_MULTI}, no action is taken, but a successful
     2348exit status is returned (the action of adding a
     2349\code{PS_DATA_METADATA_MULTI} item to the metadata is equivalent to
     2350setting that key to be tagged as \code{PS_DATA_METADATA_MULTI}.  If it
     2351is {\em already} \code{PS_DATA_METADATA_MULTI}, this effect has
     2352already been achieved).
    22792353
    22802354An example of code to use these metadata APIs to generate the
    … …  
    22842358md = psMetadataAlloc();
    22852359
    2286 psMetadataAdd(md, PS_LIST_TAIL, "SIMPLE",   PS_META_BOOL, "basic fits",            TRUE);
    2287 psMetadataAdd(md, PS_LIST_TAIL, "BLANK",    PS_META_S32,  "invalid pixel data",    -32768);
    2288 psMetadataAdd(md, PS_LIST_TAIL, "DATE-OBS", PS_META_STR,  "observing date UT", "   2004-6-16");
    2289 psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_META_LIST, "head of comment block", NULL);
    2290 psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_META_STR,  "",                      "DATA");
    2291 psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_META_STR,  "",                      "PARAMS");
    2292 psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME",  PS_META_F32,  "exposure time (sec)",   1.05);
    2293 psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_META_STR,  "",                      "FOO");
     2360psMetadataAdd(md, PS_LIST_TAIL, "SIMPLE",   PS_DATA_BOOL, "basic fits",            TRUE);
     2361psMetadataAdd(md, PS_LIST_TAIL, "BLANK",    PS_DATA_S32,  "invalid pixel data",    -32768);
     2362psMetadataAdd(md, PS_LIST_TAIL, "DATE-OBS", PS_DATA_STR,  "observing date UT", "   2004-6-16");
     2363psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_DATA_LIST, "head of comment block", NULL);
     2364psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_DATA_STR,  "",                      "DATA");
     2365psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_DATA_STR,  "",                      "PARAMS");
     2366psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME",  PS_DATA_F32,  "exposure time (sec)",   1.05);
     2367psMetadataAdd(md, PS_LIST_TAIL, "COMMENT",  PS_DATA_STR,  "",                      "FOO");
    22942368
    22952369cell = psMetadataAlloc();
    2296 psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME",  PS_META_STR,  "",                    "CCD00");
    2297 psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_META_STR,  "",                    "BSEC-00");
    2298 psMetadataAdd(cell, PS_LIST_TAIL, "CHIP",     PS_META_STR,  "",                    "CHIP.00");
    2299 psMetadataAdd(md,   PS_LIST_TAIL, "CELL.00",  PS_META_META, "",                    cell);
     2370psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME",  PS_DATA_STR,  "",                    "CCD00");
     2371psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_DATA_STR,  "",                    "BSEC-00");
     2372psMetadataAdd(cell, PS_LIST_TAIL, "CHIP",     PS_DATA_STR,  "",                    "CHIP.00");
     2373psMetadataAdd(md,   PS_LIST_TAIL, "CELL.00",  PS_DATA_META, "",                    cell);
    23002374
    23012375cell = psMetadataAlloc();
    2302 psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME",  PS_META_STR,  "",                    "CCD01");
    2303 psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_META_STR,  "",                    "BSEC-01");
    2304 psMetadataAdd(cell, PS_LIST_TAIL, "CHIP",     PS_META_STR,  "",                    "CHIP.01");
    2305 psMetadataAdd(md,   PS_LIST_TAIL, "CELL.01",  PS_META_META, "",                    cell);
     2376psMetadataAdd(cell, PS_LIST_TAIL, "EXTNAME",  PS_DATA_STR,  "",                    "CCD01");
     2377psMetadataAdd(cell, PS_LIST_TAIL, "BIASNAME", PS_DATA_STR,  "",                    "BSEC-01");
     2378psMetadataAdd(cell, PS_LIST_TAIL, "CHIP",     PS_DATA_STR,  "",                    "CHIP.01");
     2379psMetadataAdd(md,   PS_LIST_TAIL, "CELL.01",  PS_DATA_META, "",                    cell);
    23062380\end{verbatim}
    23072381
    23082382The following code shows how to use the APIs to replace one of these values:
    23092383\begin{verbatim}
    2310 psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME",  PS_META_F32 | PS_REPLACE,  "new exposure time (sec)",   2.05);
     2384psMetadataAdd(md, PS_LIST_TAIL, "EXPTIME",  PS_DATA_F32 | PS_REPLACE,  "new exposure time (sec)",   2.05);
    23112385\end{verbatim}
    23122386
    … …  
    23202394bool psMetadataAddF64(psMetadata* md, psS32 location, const char* name, const char* comment, psF64 value);
    23212395bool psMetadataAddBool(psMetadata* md, psS32 location, const char* name, const char* comment, bool value);
    2322 bool psMetadataAddPtr(psMetadata* md, psS32 location, const char* name, psMetadataType type,
     2396bool psMetadataAddPtr(psMetadata* md, psS32 location, const char* name, psDataType type,
    23232397                        const char* comment, psPtr value);
    23242398\end{prototype}
    … …  
    23832457with \code{IPP.machines.detector}.  The iterator should iterate over
    23842458every item in the metadata list, even those that are contained in a
    2385 \code{PS_META_LIST}.  The value \code{iterator} specifies the iterator
     2459\code{PS_DATA_LIST}.  The value \code{iterator} specifies the iterator
    23862460to be used.  In setting the iterator, the position of the iterator is
    23872461defined by \code{location}, which follows the conventions of the
    … …  
    25862660should construct a \code{psMetadata} container and fill it with
    25872661\code{psMetadataItems} having the names \code{EXTNAME, BIASSEC, CHIP},
    2588 with type \code{PS_META_STR}, but data allocated.  When it next
     2662with type \code{PS_DATA_STR}, but data allocated.  When it next
    25892663encounters an entry of type \code{CELL}, it should then use the given
    25902664name (e.g., \code{CELL.00}) for the \code{psMetadataItem}, and copy
    … …  
    27662840
    27672841\section{Mathematical Structures}
     2842\label{sec:mathStructures}
    27682843
    27692844Throughout PSLib, we require a variety of structures which correspond
    … …  
    27982873determine the type of the data on the basis of the data. 
    27992874Supported data types must be defined by a structure in which
    2800 the first element is always of type \code{psType}:
     2875the first element is always of type \code{psMathType}:
    28012876\begin{datatype}
    28022877typedef struct {
    28032878    psDimen dimen;                      ///< The dimensionality
    2804     psElemType type;                    ///< The type
    2805 } psType;
    2806 \end{datatype}
    2807 where \code{psDimen dimen} defines the dimensionality of the data and
    2808 \code{psElemType type} defines the data type of each element.  These
    2809 two variable types are defined as:
     2879    psElemType type;                ///< The type
     2880} psMathType;
     2881\end{datatype}
     2882where \code{psDimen dimen} defines the dimensionality of the data:
    28102883\begin{datatype}
    28112884typedef enum {
    … …  
    28172890} psDimen;
    28182891\end{datatype}
    2819 and
    2820 \begin{datatype}
    2821 typedef enum {
    2822     PS_TYPE_S8,                         ///< Character
    2823     PS_TYPE_S16,                        ///< Short integer
    2824     PS_TYPE_S32,                        ///< Integer
    2825     PS_TYPE_S64,                        ///< Long integer
    2826     PS_TYPE_U8,                         ///< Unsigned character
    2827     PS_TYPE_U16,                        ///< Unsigned short integer
    2828     PS_TYPE_U32,                        ///< Unsigned integer
    2829     PS_TYPE_U64,                        ///< Unsigned long integer
    2830     PS_TYPE_F32,                        ///< Floating point
    2831     PS_TYPE_F64,                        ///< Double-precision floating point
    2832     PS_TYPE_C32,                        ///< Complex numbers consisting of floats
    2833     PS_TYPE_C64,                        ///< Complex numbers consisting of doubles
    2834     PS_TYPE_BOOL                        ///< Boolean value
    2835 } psElemType;
    2836 \end{datatype}
    2837 We discuss the application of \code{psType} in more detail in
     2892\code{psElemType type}, which defines the data type of each element, has
     2893already been defined
     2894
     2895We discuss the application of \code{psMathType} in more detail in
    28382896section~\ref{sec:arithmetic}. 
    28392897
    … …  
    28492907\begin{datatype}
    28502908typedef struct {
    2851     psType type;                        ///< data type information
     2909    psMathType type;                    ///< data type information
    28522910} psMath;
    28532911\end{datatype}
    … …  
    28632921\begin{datatype}
    28642922typedef struct {
    2865     psType type;                        ///< data type information
     2923    psMathType type;                    ///< data type information
    28662924    union {                           
    28672925        psS8   S8;                      ///< bye value entry
    … …  
    28822940psScalar *psScalarCopy(const psScalar *value);
    28832941\end{prototype}
    2884 The first creates a \code{psType}-ed structure from a constant value,
    2885 casting it as appropriate based on the \code{type}.  The second
     2942The first creates a \code{psMathType}-ed structure from a constant
     2943value, casting it as appropriate based on the \code{type}.  The second
    28862944copies the provided \code{psScalar} value.  This latter function is
    28872945necessary to keep a copy of an existing \code{psScalar} value, since
    … …  
    29002958\begin{datatype}
    29012959typedef struct {
    2902     psType type;                        ///< vector data type and dimension
     2960    psMathType type;                    ///< vector data type and dimension
    29032961    long n;                             ///< size of vector
    29042962    const long nalloc;                  ///< allocated data block
    … …  
    29262984union \code{data} which consists of pointers to each of the defined
    29272985primitive data types.  Note the parallelism in the names of the types,
    2928 union elements, and the psElemType names.  This parallelism allows us
    2929 to use automatic construction mechanisms effectively.  The data type
    2930 is defined by the first element, \code{psType}.  The structure is
    2931 associated with a constructor and reallocator:
     2986union elements, and the \code{psElemType} names.  This parallelism
     2987allows us to use automatic construction mechanisms effectively.  The
     2988data type is defined by the first element, \code{psMathType}.  The
     2989structure is associated with a constructor and reallocator:
    29322990%
    29332991\begin{prototype}
    … …  
    30123070\begin{datatype}
    30133071typedef struct psImage {
    3014     psType type;                        ///< image data type and dimension
     3072    psMathType type;                    ///< image data type and dimension
    30153073    const psU32 numCols;                ///< Number of columns in image
    30163074    const psU32 numRows;                ///< Number of rows in image.
    … …  
    30393097
    30403098This structure represents an image consisting of a 2-D array of
    3041 pixels.  The size of this array is given by the elements \code{(numRows,
    3042 numCols)}.  The data type of the pixel is defined in the \code{psType
    3043 type} entry (specifically, the \code{psElemType} member, \code{type};
    3044 see \ref{sec:arithmetic}).  (n.b. that for FITS images, these values
    3045 are restricted to the datatypes equivalent to the valid BITPIX values
    3046 8, 16, 32, -32, -64).  The image represented in the data structure may
    3047 represent a subset of the pixels in a complete array, in which case
    3048 the image is considered to be the child of that parent array.  The
    3049 offset of the \code{(0,0)} pixel in this array relative to the parent
    3050 array is given by the elements \code{(col0,row0)}: \code{col0} is the
    3051 starting column number in the parent image while \code{row0} is the
    3052 starting row number.  The structure may include references to
    3053 subrasters (\code{children}) and/or to a containing array
    3054 (\code{parent}).  Unless this image is a child of another image
    3055 (represents a subset of the pixels of another image), the image data
    3056 is allocated in a contiguous block.  We define the following
    3057 supporting functions, which are valid for data types \code{psS8,
    3058 psS16, psU8, psU16, psF32, psF64, psC32, psC64}.
     3099pixels.  The size of this array is given by the elements
     3100\code{(numRows, numCols)}.  The data type of the pixel is defined in
     3101the \code{psMathType type} entry (specifically, the
     3102\code{psElemType} member, \code{type}; see \ref{sec:arithmetic}).
     3103(n.b. that for FITS images, these values are restricted to the
     3104datatypes equivalent to the valid BITPIX values 8, 16, 32, -32, -64).
     3105The image represented in the data structure may represent a subset of
     3106the pixels in a complete array, in which case the image is considered
     3107to be the child of that parent array.  The offset of the \code{(0,0)}
     3108pixel in this array relative to the parent array is given by the
     3109elements \code{(col0,row0)}: \code{col0} is the starting column number
     3110in the parent image while \code{row0} is the starting row number.  The
     3111structure may include references to subrasters (\code{children})
     3112and/or to a containing array (\code{parent}).  Unless this image is a
     3113child of another image (represents a subset of the pixels of another
     3114image), the image data is allocated in a contiguous block.  We define
     3115the following supporting functions, which are valid for data types
     3116\code{psS8, psS16, psU8, psU16, psF32, psF64, psC32, psC64}.
    30593117
    30603118\begin{prototype}
    … …  
    30733131    psU32 numCols,                      ///< the desired number of columns in image
    30743132    psU32 numRows,                      ///< the desired number of rows in image
    3075     const psElemType type               ///< the desired datatype of the image
     3133    const psElemType type           ///< the desired datatype of the image
    30763134);
    30773135\end{prototype}
    … …  
    32393297
    32403298\begin{datatype}
    3241     typedef struct {
    3242         MYSQL *mysql;
    3243     } psDB;
     3299typedef struct {
     3300    MYSQL *mysql;
     3301} psDB;
    32443302\end{datatype}
    32453303
    … …  
    32473305
    32483306\begin{prototype}
    3249     // wraps mysql_init() & mysql_real_connect()
    3250     psDB *psDBInit(const char *host, const char *user, const char *passwd, const char *dbname);
    3251 
    3252     // wraps mysql_close()
    3253     void psDBCleanup(psDB *dbh);
    3254 
    3255     // wraps mysql_create_db()
    3256     bool psDBCreate(psDB *dbh, const char *dbname);
    3257 
    3258     // wraps mysql_select_db()
    3259     bool psDBChange(psDB *dbh, const char *dbname);
    3260 
    3261     // wraps mysql_drop_db()
    3262     bool psDBDrop(psDB *dbh, const char *dbname);
    3263 \end{prototype}
    3264 
    3265 For MySQL support, \code{psDBInit()} wraps \code{mysql_init()} and
    3266 \code{mysql_real_connect()} in order to initialize a psDB structure and
     3307psDB *psDBInit(const char *host, const char *user, const char *passwd, const char *dbname);
     3308void psDBCleanup(psDB *dbh);
     3309bool psDBCreate(psDB *dbh, const char *dbname);
     3310bool psDBChange(psDB *dbh, const char *dbname);
     3311bool psDBDrop(psDB *dbh, const char *dbname);
     3312\end{prototype}
     3313
     3314For MySQL support, \code{psDBInit} wraps \code{mysql_init} and
     3315\code{mysql_real_connect} in order to initialize a psDB structure and
    32673316establish a database connection.  A null pointer should be returned on
    32683317failure.
    … …  
    32723321would be ignored while \code{dbname} would specify the path to the
    32733322SQLite db file.
     3323
     3324\code{psDBCleanup} shall wrap \code{mysql_close}.  \code{psDBCreate}
     3325shall wrap \code{mysql_create_db}.  \code{psDBChange} shall wrap
     3326\code{mysql_select_db}.  \code{psDBDrop} shall wrap
     3327\code{mysql_drop_db}.
    32743328
    32753329\subsubsection{Interacting with Database Tables}
    … …  
    32873341
    32883342\begin{prototype}
    3289     bool psDBCreateTable(psDB *dbh, const char *tableName, const psMetadata *md);
     3343bool psDBCreateTable(psDB *dbh, const char *tableName, const psMetadata *md);
    32903344\end{prototype}
    32913345
    … …  
    32973351given by the \code{psMetadataItem.type} entry.  A lookup table should
    32983352be used to convert from PSLib types into MySQL compatible SQL data
    3299 types.  For example, a \code{PS_META_STR} would map to an SQL99
    3300 varchar.  If the value of \code{type} is \code{PS_META_STR} then the
     3353types.  For example, a \code{PS_DATA_STR} would map to an SQL99
     3354varchar.  If the value of \code{type} is \code{PS_DATA_STR} then the
    33013355\code{psMetadataItem.data} element is set to a string with the length
    33023356for the field written as a text string.  The value of the
    33033357\code{psMetadataItem.data} element is unused for the
    3304 \code{PS_META_PRIMITIVE} types.  Other metadata types beyond
    3305 \code{PS_META_STR} and \code{PS_META_PRIMITIVE} are not allowed in a
     3358\code{PS_DATA_PRIMITIVE} types.  Other metadata types beyond
     3359\code{PS_DATA_STR} and \code{PS_DATA_PRIMITIVE} are not allowed in a
    33063360table definition metadata collection.
    33073361
    … …  
    33143368
    33153369\begin{prototype}
    3316     bool psDBDropTable(psDB *dbh, const char *tableName);
     3370bool psDBDropTable(psDB *dbh, const char *tableName);
    33173371\end{prototype}
    33183372
    … …  
    33203374
    33213375\begin{prototype}
    3322     bool p_psDBRunQuery(psDB *dbh, const char *query);
     3376bool p_psDBRunQuery(psDB *dbh, const char *query);
    33233377\end{prototype}
    33243378
    … …  
    33283382
    33293383\begin{prototype}
    3330     psArray *psDBSelectColumn(psDB *dbh, const char *tableName, const char *col, unsigned long limit);
    3331     psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col, psElemType type, unsigned long limit);
     3384psArray *psDBSelectColumn(psDB *dbh, const char *tableName, const char *col, unsigned long limit);
     3385psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col,
     3386                              psElemType type, unsigned long limit);
    33323387\end{prototype}
    33333388
    … …  
    33403395
    33413396\begin{prototype}
    3342     psArray *psDBSelectRows(psDB *dbh, const char *tableName, const psMetadata *where, unsigned long limit);
     3397psArray *psDBSelectRows(psDB *dbh, const char *tableName, const psMetadata *where, unsigned long limit);
    33433398\end{prototype}
    33443399
    … …  
    33533408
    33543409\begin{prototype}
    3355     bool psDBInsertOneRow(psDB *dbh, const char *tableName, const psMetadata *row);
     3410bool psDBInsertOneRow(psDB *dbh, const char *tableName, const psMetadata *row);
    33563411\end{prototype}
    33573412
    … …  
    33613416
    33623417\begin{prototype}
    3363     bool psDBInsertRows(psDB *dbh, const char *tableName, const psArray *rowSet);
     3418bool psDBInsertRows(psDB *dbh, const char *tableName, const psArray *rowSet);
    33643419\end{prototype}
    33653420
    … …  
    33683423
    33693424\begin{prototype}
    3370     psArray *psDBDumpRows(psDB *dbh, const char *tableName);
     3425psArray *psDBDumpRows(psDB *dbh, const char *tableName);
    33713426\end{prototype}
    33723427
    … …  
    33743429
    33753430\begin{prototype}
    3376     psMetadata *psDBDumpCols(psDB *dbh, const char *tableName);
     3431psMetadata *psDBDumpCols(psDB *dbh, const char *tableName);
    33773432\end{prototype}
    33783433
    … …  
    33823437
    33833438\begin{prototype}
    3384 psS64 psDBUpdateRows(psDB *dbh, const char *tableName, const psMetadata *where, const psMetadata *values);
     3439psS64 psDBUpdateRows(psDB *dbh, const char *tableName, const psMetadata *where,
     3440                     const psMetadata *values);
    33853441\end{prototype}
    33863442
    … …  
    33933449
    33943450\begin{prototype}
    3395     psS64 psDBDeleteRows(psDB *dbh, const char *tableName, const psMetadata *where);
     3451psS64 psDBDeleteRows(psDB *dbh, const char *tableName, const psMetadata *where);
    33963452\end{prototype}
    33973453
    … …  
    39223978typedef struct {
    39233979    psPolynomialType type;              ///< Polynomial type
    3924     psElemType       ctype;             ///< Polynomial precision
     3980    psElemType ctype;               ///< Polynomial precision
    39253981    int n;                              ///< Number of terms
    39263982    union {
    … …  
    39403996typedef struct {
    39413997    psPolynomialType type;              ///< Polynomial type
    3942     psElemType       ctype;             ///< Polynomial precision
     3998    psElemType ctype;               ///< Polynomial precision
    39433999    int nX, nY;                         ///< Number of terms in x and y
    39444000    union {
    3945       psF32 **F32;                       ///< Coefficients
    3946       psF64 **F64;                       ///< Coefficients
     4001      psF32 **F32;                      ///< Coefficients
     4002      psF64 **F64;                      ///< Coefficients
    39474003    } coeff;
    39484004    union {
    3949       psF32 **F32;                       ///< Error in coefficients
    3950       psF64 **F64;                       ///< Error in coefficients
     4005      psF32 **F32;                      ///< Error in coefficients
     4006      psF64 **F64;                      ///< Error in coefficients
    39514007    } coeffErr;
    39524008    char *mask;                         ///< Coefficient mask
    … …  
    48874943
    48884944\begin{prototype}
    4889 psType *psBinaryOp(psPtr out, const psPtr in1, const char *op, const psPtr in2);
    4890 psType *psUnaryOp(psPtr out, const psPtr in, const char *op);
     4945psMathType *psBinaryOp(psPtr out, const psPtr in1, const char *op, const psPtr in2);
     4946psMathType *psUnaryOp(psPtr out, const psPtr in, const char *op);
    48914947\end{prototype}
    48924948These functions determine the type of the operands on the basis of
    4893 their \code{psType} elements, which always are the first elements.
     4949their \code{psMathType} elements, which always are the first elements.
    48944950Note that these functions return a pointer to the appropriate type for
    4895 the operation.  Since the result may be cast to \code{psType}, the
     4951the operation.  Since the result may be cast to \code{psMathType}, the
    48964952resulting type may be determined by examining the return value.  It is
    48974953expected that the implementation of these functions will employ
Note: See TracChangeset for help on using the changeset viewer.