LAL  7.2.0.1-a5e7375
Segments.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2007 Alexander Dietz, Jolien Creighton, Peter Shawhan
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with with program; see the file COPYING. If not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17 * MA 02110-1301 USA
18 */
19 
20 #ifndef _SEGMENTS_H
21 #define _SEGMENTS_H
22 
23 #include <lal/LALDatatypes.h>
24 #include <lal/XLALError.h>
25 
26 #if defined(__cplusplus)
27 extern "C" {
28 #elif 0
29 } /* so that editors will match preceding brace */
30 #endif
31 
32 /**
33  * \defgroup Segments_h Header Segments.h
34  * \ingroup lal_tools
35  * \author Peter Shawhan
36  *
37  * \brief Provides data types and functions for manipulating lists of ``segments'' (GPS time intervals).
38  *
39  * ### Synopsis ###
40  *
41  * \code
42  * #include <lal/Segments.h>
43  * \endcode
44  *
45  * This header defines data structures for segments and lists of
46  * segments, as well as prototypes for functions that manipulate them.
47  *
48  * A segment is a time interval with a start time and an end time. The end time
49  * must be equal to or later than the start time. If the end time is equal to
50  * the start time, then the segment represents a point in time. If the end time
51  * is later than the start time, then the segment represents a half-open time
52  * interval, inclusive of its starting point and exclusive of its ending point.
53  *
54  * All of the segment list manipulation functions are XLAL functions.
55  * They handle error conditions by invoking the current XLAL error handler
56  * and setting \c xlalErrno to a nonzero value.
57  *
58  * ### Error conditions ###
59  *
60  * <table><tr><th>xlalErrno</th><th>description</th></tr>
61  * <tr><td> XLAL_EFAULT</td><td>Null pointer passed for some argument</td></tr>
62  * <tr><td> XLAL_EINVAL</td><td>Attempted to use an uninitialized segment list structure</td></tr>
63  * <tr><td> XLAL_EDOM</td><td>Pair of GPS times does not represent a valid segment</td></tr>
64  * </table>
65  *
66  * ### Notes ###
67  *
68  * A \c LALSegList must be initialized before it is used. Initialization
69  * leaves it in an ``empty'' state, containing no segments. They also must be ''cleared''
70  * after using \c XLALSegListClear(), and freed with \c LALFree() if it was dynamically allocated.
71  * Segments can then be added to the list through an ``append'' operation. The information about
72  * each segment appended is copied to a memory location managed by the
73  * \c LALSegList object. In fact, the segments are stored in the form of
74  * an array of \c LALSeg structures, with the \c segs field of
75  * the segment list structure being the base address of the array.
76  * This allows the segments to be accessed directly using a pointer as an
77  * iterator, as in the following example code:
78  *
79  * \code
80  * LALSegList mylist;
81  * LALSeg *segp;
82  * ...
83  * /\* (Append segments to the segment list 'mylist' here) *\/
84  * ...
85  * for ( segp=mylist.segs; segp<mylist.segs+mylist.length; segp++ ) {
86  *
87  * printf( "The end time of the segment is GPS %d.%09d\n", segp->end.gpsSeconds, segp->end.gpsNanoSeconds );
88  *
89  * }
90  * \endcode
91  *
92  * ... or by using an integer array index, as in the following example code:
93  *
94  * \code
95  * LALSegList mylist;
96  * LALSeg *segp;
97  * INT4 iseg;
98  * LIGOTimeGPS startgps;
99  * ...
100  * /\* (Append segments to the segment list 'mylist' here) *\/
101  * ...
102  * for ( iseg=0; iseg<mylist.length; iseg++ ) {
103  *
104  * /\* One way to access the segment... *\/
105  * startgps = mylist.segs[iseg].start;
106  * printf( "The start time of the segment is GPS %d.%09d\n", startgps.gpsSeconds, startgps.gpsNanoSeconds );
107  *
108  * /\* Another way to access the segment... *\/
109  * segp = mylist.segs + iseg;
110  * printf( "The end time of the segment is GPS %d.%09d\n", segp->end.gpsSeconds, segp->end.gpsNanoSeconds );
111  *
112  * }
113  * \endcode
114  *
115  * Note that if the segment list is empty, then the \c segs field will
116  * be NULL and the \c length field will be \f$0\f$. So be careful not to
117  * dereference the \c segs pointer unless you know that the length is
118  * nonzero.
119  *
120  * A segment list is considered ``sorted'' if the segments are in ascending
121  * (or at least non-descending) order according to the comparison done by
122  * the \c XLALSegCmp() function. A segment list is considered ``disjoint''
123  * if no two segments in the list overlap, although they
124  * may touch at an endpoint due to the half-open nature of the time intervals
125  * represented by segments. The \c LALSegList structure includes fields
126  * which record whether the segment list is sorted and/or disjoint, and these
127  * are used to search the segment list more efficiently when possible. Note
128  * that a segment list could in principle be disjoint but not sorted, but that
129  * case is not of interest for the code; the \c disjoint field in the
130  * structure specifically means that the list is sorted \e and disjoint.
131  *
132  * Also all segments in a segment list can be time-shifted using \c XLALSegListShift().
133  *
134  */
135 /** @{ */
136 
137 /*------------------- Compile-time parameters -------------------*/
138 
139 #ifndef SWIG /* exclude from SWIG interface */
140 
141 #define SEGMENTSH_ALLOCBLOCK 64 /**< Initial number of LALSeg spaces to
142  * allocate in memory at one time; this is
143  * intended to reduce the number of memory
144  * reallocation calls needing to be made to
145  * build up a segment list. For a large
146  * segment list, the reallocation size
147  * switches over to a multiplicative factor.
148  */
149 
150 #define SEGMENTSH_INITMAGICVAL 729415386 /**< Distinctive value set in the
151  * 'initMagic' field to provide a
152  * check that the structure was
153  * properly initialized. */
154 
155 #endif /* SWIG */
156 
157 /*------------------- Data structure definitions -------------------*/
158 
159 /** Struct holding a single segment */
160 typedef struct
161 tagLALSeg
162 {
163  LIGOTimeGPS start; /**< Beginning time of the segment */
164  LIGOTimeGPS end; /**< Ending time of the segment */
165  INT4 id; /**< Identifier (segment ID, array index, etc.) for user */
166 }
167 LALSeg;
168 
169 /** Struct holding a segment list */
170 #ifdef SWIG /* SWIG interface directives */
171 SWIGLAL(IGNORE_MEMBERS(tagLALSegList, arraySize, dplaces, sorted, disjoint, initMagic, lastFound));
172 #endif // SWIG
173 typedef struct
174 tagLALSegList
175 {
176 #ifdef SWIG /* SWIG interface directives */
177  SWIGLAL(ARRAY_1D(LALSegList, LALSeg, segs, UINT4, length));
178 #endif
179  LALSeg *segs; /**< Pointer to array of segments (LALSeg structures) */
180  size_t arraySize; /**< Size of array for which memory is allocated */
181  UINT4 length; /**< Number of segments in this segment list */
182  UINT4 dplaces; /**< Decimal places (0,3,6,9) to format GPS times */
183  UINT4 sorted; /**< Flag to indicate whether segment list is sorted */
184  UINT4 disjoint; /**< Flag to indicate whether segment list is disjoint */
185  UINT4 initMagic; /**< Internal value to help ensure list was initialized */
186  LALSeg *lastFound; /**< Internal record of last segment found by a search */
187 }
188 LALSegList;
190 /*----------------------- Function prototypes ----------------------*/
191 int
192 XLALSegSet( LALSeg *seg, const LIGOTimeGPS *start, const LIGOTimeGPS *end,
193  const INT4 id );
196 XLALSegCreate( const LIGOTimeGPS *start, const LIGOTimeGPS *end,
197  const INT4 id );
198 
199 int
200 XLALGPSInSeg( const void *gps, const void *seg );
201 
202 int
203 XLALSegCmp( const void *seg0, const void *seg1 );
204 
205 LALSegList *
206 XLALSegListCreate( void );
207 
208 int
209 XLALSegListInit( LALSegList *seglist );
210 
211 int
212 XLALSegListClear( LALSegList *seglist );
213 
214 int
215 XLALSegListFree( LALSegList *seglist );
216 
217 int
218 XLALSegListAppend( LALSegList *seglist, const LALSeg *seg );
219 
220 int
221 XLALSegListSort( LALSegList *seglist );
222 
223 int
224 XLALSegListCoalesce( LALSegList *seglist );
225 
226 int
227 XLALSegListRange( const LALSegList *seglist, LIGOTimeGPS *start, LIGOTimeGPS *end );
228 
229 LALSeg *
230 XLALSegListSearch( LALSegList *seglist, const LIGOTimeGPS *gps );
231 
232 int
233 XLALSegListShift( LALSegList *seglist, const LIGOTimeGPS *shift );
234 
235 int
236 XLALSegListKeep( LALSegList *seglist, const LIGOTimeGPS *start, const LIGOTimeGPS *end );
237 
238 LALSeg *
239 XLALSegListGet( LALSegList *seglist, UINT4 indx );
240 
241 
242 int XLALSegListIsInitialized ( const LALSegList *seglist );
243 int XLALSegListInitSimpleSegments ( LALSegList *seglist, LIGOTimeGPS startTime, UINT4 Nseg, REAL8 Tseg );
244 char *XLALSegList2String ( const LALSegList *seglist );
245 
246 /** @} */
247 
248 #if 0
249 { /* so that editors will match succeeding brace */
250 #elif defined(__cplusplus)
251 }
252 #endif /* C++ protection. */
253 #endif /* Double-include protection. */
int XLALSegListCoalesce(LALSegList *seglist)
The function XLALSegListCoalesce() first sorts the segments in a segment list (if not already sorted)...
Definition: Segments.c:544
int XLALSegListRange(const LALSegList *seglist, LIGOTimeGPS *start, LIGOTimeGPS *end)
The function XLALSegListRange() returns the start and end GPS times of the segment list...
Definition: Segments.c:625
int XLALSegListShift(LALSegList *seglist, const LIGOTimeGPS *shift)
UNDOCUMENTED.
Definition: Segments.c:940
int XLALSegSet(LALSeg *seg, const LIGOTimeGPS *start, const LIGOTimeGPS *end, const INT4 id)
This function sets the start time, the end time, and the id of a segment.
Definition: Segments.c:87
int XLALSegListInitSimpleSegments(LALSegList *seglist, LIGOTimeGPS startTime, UINT4 Nseg, REAL8 Tseg)
(Re-)Initialize a segment list with Nseg &#39;simple&#39; segments of length &#39;Tseg&#39;, starting at t0 = startTi...
Definition: Segments.c:1074
int XLALSegListInit(LALSegList *seglist)
This function must be called to initialize a segment list structure before that structure can be used...
Definition: Segments.c:255
Epoch relative to GPS epoch, see LIGOTimeGPS type for more details.
Definition: LALDatatypes.h:458
LALSeg * XLALSegCreate(const LIGOTimeGPS *start, const LIGOTimeGPS *end, const INT4 id)
This function is similar to XLALSegSet() except that it allocates memory for a new segment structure ...
Definition: Segments.c:131
char * XLALSegList2String(const LALSegList *seglist)
Output an (octave) formatting of &#39;seglist&#39; as a string.
Definition: Segments.c:1108
int XLALSegListIsInitialized(const LALSegList *seglist)
Simple method to check whether a LALSegList is in an initialized state.
Definition: Segments.c:1055
Struct holding a single segment.
Definition: Segments.h:170
int XLALGPSInSeg(const void *gps, const void *seg)
This is designed to be usable as a comparison function for bsearch() and therefore returns a negative...
Definition: Segments.c:182
int XLALSegListSort(LALSegList *seglist)
This function sorts the segments in a segment list into forward time order.
Definition: Segments.c:491
int XLALSegListAppend(LALSegList *seglist, const LALSeg *seg)
This function appends a segment to a segment list.
Definition: Segments.c:375
Struct holding a segment list.
Definition: Segments.h:183
LALSegList * XLALSegListCreate(void)
This function allocates memory for a new segment list structure, initializes the segment list...
Definition: Segments.c:239
LALSeg * XLALSegListGet(LALSegList *seglist, UINT4 indx)
Get a copy of the segment at indx in the internal array.
Definition: Segments.c:1143
LALSeg * XLALSegListSearch(LALSegList *seglist, const LIGOTimeGPS *gps)
The function XLALSegListSearch() determines which segment in the list, if any, contains the GPS time ...
Definition: Segments.c:714
int XLALSegListKeep(LALSegList *seglist, const LIGOTimeGPS *start, const LIGOTimeGPS *end)
UNDOCUMENTED.
Definition: Segments.c:977
double REAL8
Double precision real floating-point number (8 bytes).
int XLALSegCmp(const void *seg0, const void *seg1)
This is designed to be usable as a comparison function for qsort() and therefore returns a negative v...
Definition: Segments.c:213
int XLALSegListFree(LALSegList *seglist)
This function frees a segment list created with XLALSegListCreate().
Definition: Segments.c:348
uint32_t UINT4
Four-byte unsigned integer.
int32_t INT4
Four-byte signed integer.
int XLALSegListClear(LALSegList *seglist)
This function must be called when you are done with a segment list, in order to free memory that was ...
Definition: Segments.c:303