LALAtomicDatatypes.h 12.2 KB
Newer Older
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's avatar
jolien committed
20
21
22
/** \file
 * \ingroup std
 * \brief The primative LAL datatypes.
23
24
25
 * \authors J. D. E. Creighton
 * \authors T. D. Creighton
 * \authors K. Wette
jolien's avatar
jolien committed
26
 *
Adam Mercer's avatar
Adam Mercer committed
27
 * This header defines the primative LAL datatypes.  These datatypes
jolien's avatar
jolien committed
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 <em>atomic</em>
 * 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 <tt>int32_t</tt>. While the size of types such as <tt>int</tt> and
 * <tt>long int</tt> are platform dependent, the sizes of INT4 and INT8
 * is always 4- and 8-bytes respectively (platform independent).
 * REAL4 and REAL8 are always type <tt>float</tt> and <tt>double</tt>
 * 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 <tt>long int</tt> rather than type
 * <tt>long long int</tt>.
 */

jolien's avatar
jolien committed
55
/*************************** <lalVerbatim file="LALAtomicDatatypesHV">
jolien's avatar
jolien committed
56
Author: J. D. E. Creighton, T. D. Creighton
jolien's avatar
jolien committed
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
**************************** </lalVerbatim> */

/* <lalLaTeX>

\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.

</lalLaTeX> */
148

jolien's avatar
jolien committed
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 <tt>long int</tt> instead.
 */
/** \var typedef long long UINT8
 * \brief Eight-byte unsigned integer.
 *
 * On some platforms this is equivalent to <tt>unsigned long int</tt> 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
 */

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;

213
#include <stdint.h>
214
215
216
217
218
219
220
221
222

#ifndef LAL_USE_OLD_COMPLEX_STRUCTS
#if defined(__cplusplus)
#include <complex>
#else
#include <complex.h>
#endif
#endif /* LAL_USE_OLD_COMPLEX_STRUCTS */

223
224
#include <lal/LALConfig.h>

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


240
/* Integer types */
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 */
249
250
#define LAL_INT8_C INT64_C
#define LAL_UINT8_C UINT64_C
251
252

/* Real types */
253
254
typedef float REAL4;
typedef double REAL8;
255

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<float> COMPLEX8;
typedef std::complex<double> COMPLEX16;
#else
typedef float complex COMPLEX8;
typedef double complex COMPLEX16;
#endif

/* Complex type constructors */
#if defined(__cplusplus)
#define CX8rect(re, im)  std::complex<float>( re, im )
#define CX16rect(re, im) std::complex<float>( 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's avatar
jolien committed
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
/* <lalLaTeX>

\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}

</lalLaTeX> */
351

jolien's avatar
jolien committed
352
/** Single-precision floating-point complex number (8 bytes total) */
353
354
355
typedef struct
tagCOMPLEX8
{
jolien's avatar
jolien committed
356
357
  REAL4 re; /**< The real part. */
  REAL4 im; /**< The imaginary part. */
358
359
360
}
COMPLEX8;

jolien's avatar
jolien committed
361
/** Double-precision floating-point complex number (16 bytes total) */
362
363
364
typedef struct
tagCOMPLEX16
{
jolien's avatar
jolien committed
365
366
  REAL8 re; /**< The real part. */
  REAL8 im; /**< The imaginary part. */
367
368
369
}
COMPLEX16;

jolien's avatar
jolien committed
370
371
372
373
374

/* <lalLaTeX>
\vfill{\footnotesize\input{LALAtomicDatatypesHV}}
</lalLaTeX> */

375
376
377
378
379
/** \endcond */

#endif /* LAL_USE_OLD_COMPLEX_STRUCTS */

#endif /* SWIG */
jolien's avatar
jolien committed
380

381
382
383
384
385
#ifdef  __cplusplus
}
#endif

#endif /* _LALATOMICDATATYPES_H */