LAL  7.1.7.1-56c71ae

Detailed Description

Provides data types and functions for manipulating lists of ``segments'' (GPS time intervals).

Functions for handling segments

Author
Peter Shawhan

Synopsis

#include <lal/Segments.h>

This header defines data structures for segments and lists of segments, as well as prototypes for functions that manipulate them.

A segment is a time interval with a start time and an end time. The end time must be equal to or later than the start time. If the end time is equal to the start time, then the segment represents a point in time. If the end time is later than the start time, then the segment represents a half-open time interval, inclusive of its starting point and exclusive of its ending point.

All of the segment list manipulation functions are XLAL functions. They handle error conditions by invoking the current XLAL error handler and setting xlalErrno to a nonzero value.

Error conditions

xlalErrnodescription
XLAL_EFAULTNull pointer passed for some argument
XLAL_EINVALAttempted to use an uninitialized segment list structure
XLAL_EDOMPair of GPS times does not represent a valid segment

Notes

A LALSegList must be initialized before it is used. Initialization leaves it in an ``empty'' state, containing no segments. They also must be ''cleared'' after using XLALSegListClear(), and freed with LALFree() if it was dynamically allocated. Segments can then be added to the list through an ``append'' operation. The information about each segment appended is copied to a memory location managed by the LALSegList object. In fact, the segments are stored in the form of an array of LALSeg structures, with the segs field of the segment list structure being the base address of the array. This allows the segments to be accessed directly using a pointer as an iterator, as in the following example code:

LALSegList mylist;
LALSeg *segp;
...
/\* (Append segments to the segment list 'mylist' here) *\/
...
for ( segp=mylist.segs; segp<mylist.segs+mylist.length; segp++ ) {
printf( "The end time of the segment is GPS %d.%09d\n", segp->end.gpsSeconds, segp->end.gpsNanoSeconds );
}

... or by using an integer array index, as in the following example code:

LALSegList mylist;
LALSeg *segp;
INT4 iseg;
LIGOTimeGPS startgps;
...
/\* (Append segments to the segment list 'mylist' here) *\/
...
for ( iseg=0; iseg<mylist.length; iseg++ ) {
/\* One way to access the segment... *\/
startgps = mylist.segs[iseg].start;
printf( "The start time of the segment is GPS %d.%09d\n", startgps.gpsSeconds, startgps.gpsNanoSeconds );
/\* Another way to access the segment... *\/
segp = mylist.segs + iseg;
printf( "The end time of the segment is GPS %d.%09d\n", segp->end.gpsSeconds, segp->end.gpsNanoSeconds );
}

Note that if the segment list is empty, then the segs field will be NULL and the length field will be \(0\). So be careful not to dereference the segs pointer unless you know that the length is nonzero.

A segment list is considered ``sorted'' if the segments are in ascending (or at least non-descending) order according to the comparison done by the XLALSegCmp() function. A segment list is considered ``disjoint'' if no two segments in the list overlap, although they may touch at an endpoint due to the half-open nature of the time intervals represented by segments. The LALSegList structure includes fields which record whether the segment list is sorted and/or disjoint, and these are used to search the segment list more efficiently when possible. Note that a segment list could in principle be disjoint but not sorted, but that case is not of interest for the code; the disjoint field in the structure specifically means that the list is sorted and disjoint.

Also all segments in a segment list can be time-shifted using XLALSegListShift().

The first few functions listed deal with segments:

XLALSegSet(), XLALSegCreate(), XLALGPSInSeg(), XLALSegCmp()

Functions for handling segment lists

The rest of the functions listed deal with segment lists:

XLALSegListInit(), XLALSegListClear(), XLALSegListAppend(), XLALSegListSort() XLALSegListCoalesce(), XLALSegListSearch()

Error codes and return values

Each XLAL function listed above, if it fails invokes the current XLAL error handler, sets xlalErrno to the appropriate XLAL error code, and returns a particular value as noted below:

Prototypes

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. More...
 
LALSegXLALSegCreate (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 rather than setting the fields of an existing segment structure. More...
 
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 value, 0, or a positive value depending on whether the GPS time (the first argument) is before the beginning of, within, or after the end of the segment (the second argument). More...
 
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 value, 0, or a positive value depending on whether the first argument is less than, equal to, or greater than the second. More...
 
LALSegListXLALSegListCreate (void)
 This function allocates memory for a new segment list structure, initializes the segment list, and returns a pointer to it. More...
 
int XLALSegListInit (LALSegList *seglist)
 This function must be called to initialize a segment list structure before that structure can be used. More...
 
int XLALSegListClear (LALSegList *seglist)
 This function must be called when you are done with a segment list, in order to free memory that was allocated to store the segments in the list. More...
 
int XLALSegListFree (LALSegList *seglist)
 This function frees a segment list created with XLALSegListCreate(). More...
 
int XLALSegListAppend (LALSegList *seglist, const LALSeg *seg)
 This function appends a segment to a segment list. More...
 
int XLALSegListSort (LALSegList *seglist)
 This function sorts the segments in a segment list into forward time order. More...
 
int XLALSegListCoalesce (LALSegList *seglist)
 The function XLALSegListCoalesce() first sorts the segments in a segment list (if not already sorted) and then joins together segments which overlap or touch (i.e. More...
 
int XLALSegListRange (const LALSegList *seglist, LIGOTimeGPS *start, LIGOTimeGPS *end)
 The function XLALSegListRange() returns the start and end GPS times of the segment list. More...
 
LALSegXLALSegListSearch (LALSegList *seglist, const LIGOTimeGPS *gps)
 The function XLALSegListSearch() determines which segment in the list, if any, contains the GPS time passed to this function. More...
 
int XLALSegListShift (LALSegList *seglist, const LIGOTimeGPS *shift)
 UNDOCUMENTED. More...
 
int XLALSegListKeep (LALSegList *seglist, const LIGOTimeGPS *start, const LIGOTimeGPS *end)
 UNDOCUMENTED. More...
 
LALSegXLALSegListGet (LALSegList *seglist, UINT4 indx)
 Get a copy of the segment at indx in the internal array. More...
 
int XLALSegListIsInitialized (const LALSegList *seglist)
 Simple method to check whether a LALSegList is in an initialized state. More...
 
int XLALSegListInitSimpleSegments (LALSegList *seglist, LIGOTimeGPS startTime, UINT4 Nseg, REAL8 Tseg)
 (Re-)Initialize a segment list with Nseg 'simple' segments of length 'Tseg', starting at t0 = startTime, ie { [t0, t0+Tseg), [t0+Tseg, t0+2*Tseg), ... More...
 
char * XLALSegList2String (const LALSegList *seglist)
 Output an (octave) formatting of 'seglist' as a string. More...
 

Data Structures

struct  LALSeg
 Struct holding a single segment. More...
 
struct  LALSegList
 Struct holding a segment list. More...
 

Macros

#define SEGMENTSH_ALLOCBLOCK   64
 Initial number of LALSeg spaces to allocate in memory at one time; this is intended to reduce the number of memory reallocation calls needing to be made to build up a segment list. More...
 
#define SEGMENTSH_INITMAGICVAL   729415386
 Distinctive value set in the 'initMagic' field to provide a check that the structure was properly initialized. More...
 

Files

file  SegmentsTest.c
 Tests the segment and segment list manipulation functions.
 

Function Documentation

◆ XLALSegSet()

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.

The id can be any integer and is solely for the use of the user, e.g. to store a segment ID code or an index into some array containing additional information about the segment. XLALSegSet() checks to make sure the segment is valid, i.e. the end time is later than or equal to the start time; an error occurs if this condition is not true.

Definition at line 87 of file Segments.c.

◆ XLALSegCreate()

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 rather than setting the fields of an existing segment structure.

It returns a pointer to the new LALSeg structure. When the structure is no longer needed, its pointer should be passed to XLALFree().

Definition at line 131 of file Segments.c.

◆ XLALGPSInSeg()

int XLALGPSInSeg ( const void *  pgps,
const void *  pseg 
)

This is designed to be usable as a comparison function for bsearch() and therefore returns a negative value, 0, or a positive value depending on whether the GPS time (the first argument) is before the beginning of, within, or after the end of the segment (the second argument).

Note that a segment is a half-open interval, so the GPS time is considered to be within the segment if it is equal to the start time of the segment but not if it is equal to the end time of the segment.

Returns a comparison value (negative, 0, or positive).

Definition at line 182 of file Segments.c.

◆ XLALSegCmp()

int XLALSegCmp ( const void *  pseg0,
const void *  pseg1 
)

This is designed to be usable as a comparison function for qsort() and therefore returns a negative value, 0, or a positive value depending on whether the first argument is less than, equal to, or greater than the second.

The comparison is based on the start time of the segments, unless these are equal, in which case the end times are compared. Therefore, two segments are considered equal only if their start and end times are identical.

Returns a comparison value (negative, 0, or positive).

Definition at line 213 of file Segments.c.

◆ XLALSegListCreate()

LALSegList* XLALSegListCreate ( void  )

This function allocates memory for a new segment list structure, initializes the segment list, and returns a pointer to it.

Definition at line 239 of file Segments.c.

◆ XLALSegListInit()

int XLALSegListInit ( LALSegList seglist)

This function must be called to initialize a segment list structure before that structure can be used.

Definition at line 255 of file Segments.c.

◆ XLALSegListClear()

int XLALSegListClear ( LALSegList seglist)

This function must be called when you are done with a segment list, in order to free memory that was allocated to store the segments in the list.

(Strictly speaking, this is only necessary if the list contains one or more segments.) The function leaves the segment list in a valid state, but containing no segments. After calling XLALSegListClear(), it is OK to re-use the segment list structure (by using XLALSegListAppend() to add segments to it, etc.). You do not have to call XLALSegListInit() again before re-using it, but it is OK to do so. If you do call XLALSegListInit() again, you must do so after calling XLALSegListClear() !

Definition at line 303 of file Segments.c.

◆ XLALSegListFree()

int XLALSegListFree ( LALSegList seglist)

This function frees a segment list created with XLALSegListCreate().

Definition at line 348 of file Segments.c.

◆ XLALSegListAppend()

int XLALSegListAppend ( LALSegList seglist,
const LALSeg seg 
)

This function appends a segment to a segment list.

It first checks to make sure the segment is valid, i.e. the end time is later than or equal to the start time; an error occurs if this condition is not true. The input segment information is copied into an array of LALSeg structures maintained ``internally'' by the segment list. The function takes care of extending this array when necessary. It also checks whether the segment being appended preserves the sorted'' and/ordisjoint'' properties of the segment list. An empty segment list has the sorted'' anddisjoint'' properties to start with, and as long as segments are appended in ascending time order and do not overlap, it retains those properties.

Definition at line 375 of file Segments.c.

◆ XLALSegListSort()

int XLALSegListSort ( LALSegList seglist)

This function sorts the segments in a segment list into forward time order.

If the list is already sorted, then this function returns promptly.

Definition at line 491 of file Segments.c.

◆ XLALSegListCoalesce()

int XLALSegListCoalesce ( LALSegList seglist)

The function XLALSegListCoalesce() first sorts the segments in a segment list (if not already sorted) and then joins together segments which overlap or touch (i.e.

share endpoints). The result is a segment list which is sorted and is guaranteed to not have any overlapping segments; thus it is ``disjoint''. (Note, however, that a disjoint segment list is not necessarily coalesced, since segments which touch at an endpoint are considered disjoint but will be joined by XLALSegListCoalesce().) If the list has the ``disjoint'' property to begin with, then this function returns promptly. Each segment in the output list is assigned the id value taken from the first segment in the input list (after it has been sorted) among those which were joined to make it.

Definition at line 544 of file Segments.c.

◆ XLALSegListRange()

int XLALSegListRange ( const LALSegList seglist,
LIGOTimeGPS start,
LIGOTimeGPS end 
)

The function XLALSegListRange() returns the start and end GPS times of the segment list.

These may not be the first and last GPS times in the segment list, for example if the segment list is not sorted.

Definition at line 625 of file Segments.c.

◆ XLALSegListSearch()

LALSeg* XLALSegListSearch ( LALSegList seglist,
const LIGOTimeGPS gps 
)

The function XLALSegListSearch() determines which segment in the list, if any, contains the GPS time passed to this function.

It returns a pointer to a segment containing the time, if there is one, otherwise it returns NULL. If more than one segment in the list contains the time, then this function returns a pointer to one of the segments which contains it, not necessarily the first such segment in the list. (This is not an issue if the list is ``disjoint'', which guarantees that it has no overlapping segments.) The following code shows how the XLALSegListSearch() function might be used:

LALSegList mylist;
LIGOTimeGPS tgps, startgps;
LALSeg *segp;
...
/\* (Fill the segment list 'mylist' with segments here) *\/
/\* (Set the gps time, 'tgps', to search for) *\/
...
segp = XLALSegListSearch( &mylist, &tgps );
if ( segp ) {
startgps = segp->start;
printf( "That time is within a segment which starts at GPS time %d.%09d\n",
startgps.gpsSecconds, startgps.gpsNanoSeconds );
} else {
printf( "That time is not within any segment in the list\n" );
}

The search algorithm used by the XLALSegListSearch() function depends on whether the segment list is sorted'' and/ordisjoint''. If the segment list has both of these properties, then the function can use a binary search to locate the segment containing the time, or to determine that there is no such segment. (Therefore, it is a good idea to pass a segment list to XLALSegListCoalesce() before using it with XLALSegListSearch(), unless segment list ordering or distinct segments which touch/overlap are meaningful for what you are doing, which is sometimes the case.) Otherwise, it must use a linear search, although a ``sorted'' list can still be searched slightly more efficiently than an un-sorted list. In all cases, XLALSegListSearch() first checks whether the segment found by the last successful search contains the specified time, and returns that promptly if so.

Returns
a pointer to a segment in the list which contains the time being searched for, or NULL if there is no such segment. If more than one segment in the list contains the time, then this function returns a pointer to one of the segments which contains it, not necessarily the first such segment in the list. (This is not an issue if the list is ``disjoint'', which guarantees that it has no overlapping segments.) If no segment in the list contains the time, then this function returns NULL; however, this is not really an error, use xlalErrno to differentiate between failure and non-failure.

Definition at line 714 of file Segments.c.

◆ XLALSegListShift()

int XLALSegListShift ( LALSegList seglist,
const LIGOTimeGPS shift 
)

UNDOCUMENTED.

Definition at line 940 of file Segments.c.

◆ XLALSegListKeep()

int XLALSegListKeep ( LALSegList seglist,
const LIGOTimeGPS start,
const LIGOTimeGPS end 
)

UNDOCUMENTED.

Definition at line 977 of file Segments.c.

◆ XLALSegListGet()

LALSeg* XLALSegListGet ( LALSegList seglist,
UINT4  indx 
)

Get a copy of the segment at indx in the internal array.

If the segment is beyond the bounds of the array, return NULL.

Definition at line 1143 of file Segments.c.

◆ XLALSegListIsInitialized()

int XLALSegListIsInitialized ( const LALSegList seglist)

Simple method to check whether a LALSegList is in an initialized state.

Avoid the user having to deal with LALSegList internal 'magic'.

Definition at line 1055 of file Segments.c.

◆ XLALSegListInitSimpleSegments()

int XLALSegListInitSimpleSegments ( LALSegList seglist,
LIGOTimeGPS  startTime,
UINT4  Nseg,
REAL8  Tseg 
)

(Re-)Initialize a segment list with Nseg 'simple' segments of length 'Tseg', starting at t0 = startTime, ie { [t0, t0+Tseg), [t0+Tseg, t0+2*Tseg), ...

[t0+(N-1)*Tseg, t0+N*Tseg) }

Note: accepts un-initialized segments list, as well as existing segment-lists. The latter will be properly cleared before re-use.

The 'Id' field of segment k is set to 'k'

Definition at line 1074 of file Segments.c.

◆ XLALSegList2String()

char* XLALSegList2String ( const LALSegList seglist)

Output an (octave) formatting of 'seglist' as a string.

Definition at line 1108 of file Segments.c.

Macro Definition Documentation

◆ SEGMENTSH_ALLOCBLOCK

#define SEGMENTSH_ALLOCBLOCK   64

Initial number of LALSeg spaces to allocate in memory at one time; this is intended to reduce the number of memory reallocation calls needing to be made to build up a segment list.

For a large segment list, the reallocation size switches over to a multiplicative factor.

Definition at line 141 of file Segments.h.

◆ SEGMENTSH_INITMAGICVAL

#define SEGMENTSH_INITMAGICVAL   729415386

Distinctive value set in the 'initMagic' field to provide a check that the structure was properly initialized.

Definition at line 157 of file Segments.h.