LALAtomicDatatypes.h 12.2 KB
 bema committed Jun 08, 2007 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 /* * Copyright (C) 2007 Jolien Creighton * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with with program; see the file COPYING. If not, write to the * Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, * MA 02111-1307 USA */  jolien committed Aug 25, 2005 20 21 22 /** \file * \ingroup std * \brief The primative LAL datatypes.  Karl Wette committed Feb 27, 2012 23 24 25  * \authors J. D. E. Creighton * \authors T. D. Creighton * \authors K. Wette  jolien committed Aug 25, 2005 26  *  Adam Mercer committed Apr 29, 2009 27  * This header defines the primative LAL datatypes. These datatypes  jolien committed Aug 25, 2005 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54  * are: CHAR, INT2, INT4, INT8 (signed integer types); UCHAR, UINT2 * UINT4, UINT8 (unsigned integer types); REAL4, REAL8 (single- and * double-precision floating point types); and COMPLEX8 and COMPLEX16 * (single- and double-precision floating point complex types). * Note that the complex types are implemented as structures. This is * because LAL conforms to the C89 standard rather than the C99 * standard. The non-complex datatypes are known as atomic * datatypes: these may be passed directly to functions or used as * the return value of XLAL functions. * * The number in the name of each of these types (other than * CHAR and UCHAR) is the number of 8-bit bytes that the datatype * occupies. E.g., INT4 is a four-byte integer. In C99 it would be * called int32_t. While the size of types such as int and * long int are platform dependent, the sizes of INT4 and INT8 * is always 4- and 8-bytes respectively (platform independent). * REAL4 and REAL8 are always type float and double * but LAL is only supported on platforms in which these types conform * to the IEEE 754 standard. * * This documentation shows how the datatypes are defined on today's * most common (32-bit) platform. Be careful in particular about * the integer type INT8. On 64-bit platforms it will usually be * equivalent to type long int rather than type * long long int. */  jolien committed Jun 03, 2000 55 /***************************  jolien committed Dec 01, 2001 56 Author: J. D. E. Creighton, T. D. Creighton  jolien committed Jun 03, 2000 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 **************************** */ /* \subsection{Primitive datatypes} \label{ss:LALAtomicDatatypes.h} The primitive datatypes are defined in a separate header \verb@LALAtomicDatatypes.h@, which is included by \verb@LALDatatypes.h@. This is done in order to facilitate the interface between LAL and non-LAL modules. By including just \verb@LALAtomicDatatypes.h@, a non-LAL module can ensure that it is using the same arithmetic standard as LAL, without being burdened by LAL's more specialized structures. Primitive datatypes are those that conceptually store a single number or quantity. They include both the \emph{atomic} datatypes and the complex datatypes. \subsubsection*{Atomic datatypes} Atomic LAL datatypes are platform-independent datatypes corresponding to the basic types in the C/C++ language. However, since the C/C++ types are not necessarily the same across platforms, the actual mapping between LAL and C/C++ datatypes may be different on different platforms. The following table lists the LAL atomic datatypes, their size and range, and the C/C++ datatype to which they \emph{usually} correspond. \begin{center} \begin{tabular}{|lccc|} \hline Type & Bytes & Range & Usual C/C++ type \\ \hline \tt CHAR & 1 & \verb@'\0'@ to \verb@'\255'@ & \tt char \\ \tt UCHAR & 1 & \verb@'\0'@ to \verb@'\255'@ & \tt unsigned char \\ \tt BOOLEAN & 1 & 0 or positive & \tt unsigned char \\ \hline \tt INT2 & 2 & $-2^{-15}$ to $2^{15}-1$ & \tt short \\ \tt INT4 & 4 & $-2^{-31}$ to $2^{31}-1$ & {\tt int} or {\tt long} \\ \tt INT8 & 8 & $-2^{-63}$ to $2^{63}-1$ & \tt long long \\ \tt UINT2 & 2 & 0 to $2^{16}-1$ & \tt unsigned short \\ \tt UINT4 & 4 & 0 to $2^{32}-1$ & {\tt unsigned int} or {\tt long} \\ \tt UINT8 & 8 & 0 to $2^{64}-1$ & \tt unsigned long long \\ \hline \tt REAL4 & 4 & $-3.4\times10^{38}$ to $3.4\times10^{38}$ & \tt float \\ \tt REAL8 & 8 & $-1.8\times10^{308}$ to $1.8\times10^{308}$ & \tt double \\ \hline \end{tabular} \end{center} The unsigned character and integer datatypes store their values according to the usual binary system. For signed characters and integers, setting the most-significant bit indicates that the number formed from the remaining bits should be added to the lower value of the range. The \verb@REAL4@ and \verb@REAL8@ datatypes should store values according to the IEEE Standard 754 for Binary Floating-Point Arithmetic, which gives them the following precisions and dynamic ranges: \begin{center} \begin{tabular}{|l|cc|} \hline & \tt REAL4 & \tt REAL8 \\ \hline Minimum positive subnormal & $1.4\times10^{-45}$ & $4.9\times10^{-324}$ \\ Minimum positive normal & $1.2\times10^{-38}$ & $2.2\times10^{-308}$ \\ Maximum finite normal & $3.4\times10^{38}$ & $1.8\times10^{308}$ \\ Minimum fractional difference & $6.0\times10^{-8}$ & $1.1\times10^{-16}$ \\ Significant decimal digits & 6--9 & 15--17 \\ \hline \end{tabular} \end{center} The minimum positive subnormal is the smallest positive representable number. The minimum positive normal is the smallest positive number that can be represented with full precision; that is, one whose mantissa lies in the range [0.5,1). The maximum finite normal is the largest representable number other than the reserved code for $+\infty$. The minimum fractional difference is the smallest fractional difference between consecutive representable numbers, or \emph{half} the difference between 1 and the next representable number. Significant decimal digits gives the number of decimal digits used to represent the binary number in decimal notation: the first is the maximum number of digits that are guaranteed not to change upon conversion to binary, the second is the number of digits required to represent a unique binary quantity. */  jolien committed Apr 20, 2000 148   jolien committed Aug 25, 2005 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 /** \var typedef char CHAR * \brief One-byte signed integer. */ /** \var typedef unsigned char UCHAR * \brief One-byte unsigned integer. */ /** \var typedef short INT2 * \brief Two-byte signed integer. */ /** \var typedef short UINT2 * \brief Two-byte unsigned integer. */ /** \var typedef int INT4 * \brief Four-byte signed integer. */ /** \var typedef int UINT4 * \brief Four-byte unsigned integer. */ /** \var typedef long long INT8 * \brief Eight-byte signed integer. * * On some platforms this is equivalent to long int instead. */ /** \var typedef long long UINT8 * \brief Eight-byte unsigned integer. * * On some platforms this is equivalent to unsigned long int instead. */ /** \var typedef float REAL4 * \brief Single precision real floating-point number (4 bytes). */ /** \var typedef double REAL8 * \brief Double precision real floating-point number (8 bytes). */ /** \def LAL_INT8_C(v) (v ## LL) * \brief Macro for use in defining \a v as an INT8 constant. * * This macro affixes the appropriate qualifier to form an INT8 constant. * For example: * \code * const INT8 jan_1_2000_gps_nanosec = LAL_INT8_C(63072001300000000) * \endcode */ /** \def LAL_UINT8_C(v) (v ## ULL) * \brief Macro for use in defining \a v as an UINT8 constant. * * This macro affixes the appropriate qualifier to form an UINT8 constant. * For example: * \code * const UINT8 jan_1_2000_gps_nanosec = LAL_UINT8_C(63072001300000000) * \endcode */  jolien committed Apr 20, 2000 202 203 204 205 206 207 208 209 210 211 212 #ifndef _LALATOMICDATATYPES_H #define _LALATOMICDATATYPES_H #ifdef __cplusplus extern "C" { #endif typedef char CHAR; typedef unsigned char UCHAR; typedef unsigned char BOOLEAN;  Adam Mercer committed May 29, 2009 213 #include  Karl Wette committed Feb 27, 2012 214 215 216 217 218 219 220 221 222  #ifndef LAL_USE_OLD_COMPLEX_STRUCTS #if defined(__cplusplus) #include #else #include #endif #endif /* LAL_USE_OLD_COMPLEX_STRUCTS */  jolien committed Nov 09, 2000 223 224 #include  jolien committed Aug 11, 2005 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 /* If INT8 etc. are already defined, undefine them */ #undef CHAR #undef UCHAR #undef INT2 #undef INT4 #undef INT8 #undef UINT2 #undef UINT4 #undef UINT8 #undef REAL4 #undef REAL8 #undef COMPLEX8 #undef COMPLEX16  jolien committed Nov 09, 2000 240 /* Integer types */  jolien committed Aug 02, 2004 241 242 243 244 245 246 247 248 typedef int16_t INT2; typedef int32_t INT4; typedef int64_t INT8; typedef uint16_t UINT2; typedef uint32_t UINT4; typedef uint64_t UINT8; /* Macros for integer constants */  Adam Mercer committed May 29, 2009 249 250 #define LAL_INT8_C INT64_C #define LAL_UINT8_C UINT64_C  jolien committed Nov 09, 2000 251 252  /* Real types */  Adam Mercer committed Mar 08, 2010 253 254 typedef float REAL4; typedef double REAL8;  jolien committed Nov 09, 2000 255   Karl Wette committed Feb 27, 2012 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 #ifndef SWIG /* exclude from SWIG interface */ #ifndef LAL_USE_OLD_COMPLEX_STRUCTS /* Complex types */ #if defined(__cplusplus) typedef std::complex COMPLEX8; typedef std::complex COMPLEX16; #else typedef float complex COMPLEX8; typedef double complex COMPLEX16; #endif /* Complex type constructors */ #if defined(__cplusplus) #define CX8rect(re, im) std::complex( re, im ) #define CX16rect(re, im) std::complex( re, im ) #define CX8polar(r, th) ( (r) * exp( _Complex_I * (th) ) ) #define CX16polar(r, th) ( (r) * exp( _Complex_I * (th) ) ) #else #define CX8rect(re, im) ( (re) + _Complex_I * (im) ) #define CX16rect(re, im) ( (re) + _Complex_I * (im) ) #define CX8polar(r, th) ( (r) * cexpf( _Complex_I * (th) ) ) #define CX16polar(r, th) ( (r) * cexp ( _Complex_I * (th) ) ) #endif /* Real and imaginary part accessors */ #if defined(__cplusplus) #define CX8re(z) std::real(z) #define CX16re(z) std::real(z) #define CX8im(z) std::imag(z) #define CX16im(z) std::imag(z) #elif defined(__GNUC__) #define CX8re(z) __real__(z) #define CX16re(z) __real__(z) #define CX8im(z) __imag__(z) #define CX16im(z) __imag__(z) #else #define CX8re(z) crealf(z) #define CX16re(z) creal (z) #define CX8im(z) cimagf(z) #define CX16im(z) cimag (z) #endif /* Real and imaginary part assignment */ #if !defined(__cplusplus) && defined(__GNUC__) #define setCX8re(z, re) __real__(z) = (re) #define setCX16re(z, re) __real__(z) = (re) #define setCX8im(z, im) __imag__(z) = (im) #define setCX16im(z, im) __imag__(z) = (im) #else #define setCX8re(z, re) (z) = CX8rect ( re, CX8imag (z) ) #define setCX16re(z, re) (z) = CX16rect( re, CX16imag(z) ) #define setCX8im(z, im) (z) = CX8rect ( CX8re (z), im ) #define setCX16im(z, im) (z) = CX16rect( CX16re(z), im ) #endif #else /* LAL_USE_OLD_COMPLEX_STRUCTS */ /** \cond DONT_DOXYGEN */  jolien committed Jun 03, 2000 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 /* \subsubsection*{Complex datatypes} LAL represents complex numbers as structures with two floating-point fields, storing the real and imaginary parts. These are considered primitive datatypes (rather than aggregate or structured datatypes) because they conceptually represent a single number. Furthermore, atomic and complex datatypes are treated equivalently by LAL aggregate and structured datatypes. \vspace{1ex} \begin{verbatim} COMPLEX8 \end{verbatim} This structure stores a single-precision complex number in 8~bytes of memory. The fields are: \begin{description} \item[\texttt{REAL4 re}] The real part. \item[\texttt{REAL4 im}] The imaginary part. \end{description} \vspace{1ex} \begin{verbatim} COMPLEX16 \end{verbatim} This structure stores a double-precision complex number in 16~bytes of memory. The fields are: \begin{description} \item[\texttt{REAL8 re}] The real part. \item[\texttt{REAL8 im}] The imaginary part. \end{description} */  jolien committed Apr 20, 2000 351   jolien committed Aug 25, 2005 352 /** Single-precision floating-point complex number (8 bytes total) */  jolien committed Apr 20, 2000 353 354 355 typedef struct tagCOMPLEX8 {  jolien committed Aug 25, 2005 356 357  REAL4 re; /**< The real part. */ REAL4 im; /**< The imaginary part. */  jolien committed Apr 20, 2000 358 359 360 } COMPLEX8;  jolien committed Aug 25, 2005 361 /** Double-precision floating-point complex number (16 bytes total) */  jolien committed Apr 20, 2000 362 363 364 typedef struct tagCOMPLEX16 {  jolien committed Aug 25, 2005 365 366  REAL8 re; /**< The real part. */ REAL8 im; /**< The imaginary part. */  jolien committed Apr 20, 2000 367 368 369 } COMPLEX16;  jolien committed Jun 03, 2000 370 371 372 373 374  /* \vfill{\footnotesize\input{LALAtomicDatatypesHV}} */  Karl Wette committed Feb 27, 2012 375 376 377 378 379 /** \endcond */ #endif /* LAL_USE_OLD_COMPLEX_STRUCTS */ #endif /* SWIG */  jolien committed Jun 03, 2000 380   jolien committed Apr 20, 2000 381 382 383 384 385 #ifdef __cplusplus } #endif #endif /* _LALATOMICDATATYPES_H */