Segments

Segments — Support for passing segment lists through GObject properties.

Synopsis

#include <gstlal/gstlal_segments.h>

struct gstlal_segment * gstlal_segment_new              (guint64 start,
                                                         guint64 stop);
void                gstlal_segment_free                 (struct gstlal_segment *segment);
struct gstlal_segment_list * gstlal_segment_list_new    (void);
void                gstlal_segment_list_free            (struct gstlal_segment_list *segmentlist);
gint                gstlal_segment_list_length          (const struct gstlal_segment_list *segmentlist);
struct gstlal_segment_list * gstlal_segment_list_append (struct gstlal_segment_list *segmentlist,
                                                         struct gstlal_segment *segment);
gint                gstlal_segment_list_index           (const struct gstlal_segment_list *segmentlist,
                                                         guint64 t);
struct gstlal_segment * gstlal_segment_list_get         (struct gstlal_segment_list *segmentlist,
                                                         gint index);
struct gstlal_segment_list * gstlal_segment_list_get_range
                                                        (const struct gstlal_segment_list *segmentlist,
                                                         guint64 start,
                                                         guint64 stop);
struct gstlal_segment_list * gstlal_segment_list_from_g_value_array
                                                        (GValueArray *va);
struct gstlal_segment * gstlal_segment_from_g_value_array
                                                        (GValueArray *va);
GValueArray *       g_value_array_from_gstlal_segment   (struct gstlal_segment seg);
GValueArray *       g_value_array_from_gstlal_segment_list
                                                        (struct gstlal_segment_list *seglist);

Description

Here is defined a structure for storing a start/stop pair (a "segment") and a structure for storing a list of such structures (a "segment list"). Unlike other libraries, like the segments library provided by the Python glue package, this library does not implement high-level segment arithmetic or other logical operations, only the most basic storage and retrieval functions are provided here. The purpose of this code is to support passing segment lists through GObject properties as GValueArrays, not to implement a segment arithmetic library.

Details

gstlal_segment_new ()

struct gstlal_segment * gstlal_segment_new              (guint64 start,
                                                         guint64 stop);

Allocate and initialize a struct gstlal_segment. The segment represents an interval (e.g., of time) and spans [start, stop).

See also: gstlal_segment_free()

start :

the segment start

stop :

the segment stop

Returns :

a newly-allocated segment or NULL on failure.

gstlal_segment_free ()

void                gstlal_segment_free                 (struct gstlal_segment *segment);

Frees all memory associated with a struct gstlal_segment.

See also: gstlal_segment_new()

segment :

the struct gstlal_segment to free

gstlal_segment_list_new ()

struct gstlal_segment_list * gstlal_segment_list_new    (void);

Allocate a new struct gstlal_segment_list.

See also: gstlal_segment_list_free()

Returns :

the newly-allocated struct gstlal_segment_list or NULL on failure.

gstlal_segment_list_free ()

void                gstlal_segment_list_free            (struct gstlal_segment_list *segmentlist);

Frees all memory associated with a struct gstlal_segment_list including any segments within it.

See also: gstlal_segment_list_new()

segmentlist :

the struct gstlal_segment_list to free

gstlal_segment_list_length ()

gint                gstlal_segment_list_length          (const struct gstlal_segment_list *segmentlist);

segmentlist :

the struct gstlal_segment_list whose length is to be reported

Returns :

the length of the struct gstlal_segment_list.

gstlal_segment_list_append ()

struct gstlal_segment_list * gstlal_segment_list_append (struct gstlal_segment_list *segmentlist,
                                                         struct gstlal_segment *segment);

Append a struct gstlal_segment to a struct gstlal_segment_list. This function takes ownership of the struct gstlal_segment, and the calling code must not access it after invoking this function.

Note that no check is made to ensure the segments in the list are in order and disjoint. Any conditions such as those must be enforced by the application.

segmentlist :

the struct gstlal_segment_list to which to append the struct gstlal_segment

segment :

the struct gstlal_segment to append

Returns :

the struct gstlal_segment_list.

gstlal_segment_list_index ()

gint                gstlal_segment_list_index           (const struct gstlal_segment_list *segmentlist,
                                                         guint64 t);

Search for the first struct gstlal_segment in segmentlist that contains the value t, that is for which stop <= t < stop.

segmentlist :

the struct gstlal_segment_list to search

t :

the value to search for

Returns :

the index of the first matching struct gstlal_segment or the length of the list if no struct gstlal_segments match.

gstlal_segment_list_get ()

struct gstlal_segment * gstlal_segment_list_get         (struct gstlal_segment_list *segmentlist,
                                                         gint index);

segmentlist :

a struct gstlal_segment_list

index :

the index of the segment to retrieve

Returns :

the struct gstlal_segment at the requested position in the list. The address is a pointer into the list, it cannot be free'ed.

gstlal_segment_list_get_range ()

struct gstlal_segment_list * gstlal_segment_list_get_range
                                                        (const struct gstlal_segment_list *segmentlist,
                                                         guint64 start,
                                                         guint64 stop);

Constructs a new struct gstlal_segment_list containing the intersection of segmentlist and the segment [start, stop).

segmentlist :

a segment list

start :

the start of the range to retrieve

stop :

the end of the range to retrieve

Returns :

a newly-allocated struct gstlal_segment_list.

gstlal_segment_list_from_g_value_array ()

struct gstlal_segment_list * gstlal_segment_list_from_g_value_array
                                                        (GValueArray *va);

Creates a new struct gstlal_segment_list from a GValueArray of two-element GValueArrays. Each two-element GValueArray is converted to a struct gstlal_segment using gstlal_segment_from_g_value_array(), and the struct gstlal_segment_list populated with the results in order. This function borrows a reference to the GValueArray.

See also: g_value_array_from_gstlal_segment_list()

va :

a GValueArray of two-element GValueArrays

Returns :

the newly-allocated struct gstlal_segment_list.

gstlal_segment_from_g_value_array ()

struct gstlal_segment * gstlal_segment_from_g_value_array
                                                        (GValueArray *va);

Creates a new struct gstlal_segment from a two-element GValueArray. The start and stop of the segment are set to the 0th and 1st elements of the array, respectively. This function borrows a reference to the GValueArray. NOTE: very little error checking is done!

See also: g_value_array_from_gstlal_segment()

va :

a two-element GValueArray

Returns :

the newly-allocated struct gstlal_segment.

g_value_array_from_gstlal_segment ()

GValueArray *       g_value_array_from_gstlal_segment   (struct gstlal_segment seg);

Create a two-element GValueArray containing the start and stop of a struct gstlal_segment.

See also: gstlal_segment_from_g_value_array()

seg :

the struct gstlal_segment to convert to a GValueArray

Returns :

the newly-allocated two-element GValueArray

g_value_array_from_gstlal_segment_list ()

GValueArray *       g_value_array_from_gstlal_segment_list
                                                        (struct gstlal_segment_list *seglist);

Create a GValueArray of two-element GValueArrays containing the contents of a struct gstlal_segment_list.

See also: gstlal_segment_list_from_g_value_array()

seglist :

the struct gstlal_segment_list to convert to a GValueArray of two-element GValueArrays

Returns :

the newly-allocated GValueArray