Segments

Segments — Support for passing segment lists through GObject properties.

Functions

Types and Values

Includes

#include <gstlal/gstlal_segments.h>

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.

Reviewed: fd83b7bb2e8c918577ab7b06b5c358fbef14310f 2014-08-13 K. Cannon, J. Creighton, B. Sathyaprakash.

Functions

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()

Parameters

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()

Parameters

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()

Parameters

segmentlist

the struct gstlal_segment_list to free

 

gstlal_segment_list_length ()

gint
gstlal_segment_list_length (const struct gstlal_segment_list *segmentlist);

Parameters

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 (even if the append operation fails).

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.

Parameters

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 or NULL on failure.


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 for which t < stop.

Parameters

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);

Parameters

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

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

seglist

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

 

Returns

the newly-allocated GValueArray

Types and Values

struct gstlal_segment

struct gstlal_segment {
	guint64 start;
	guint64 stop;
};


struct gstlal_segment_list

struct gstlal_segment_list {
};