Segments

Segments — Support for passing segment lists through GObject properties.

Synopsis

#include <gstlal/gstlal_segments.h>

GValueArray *       g_value_array_from_gstlal_segment   (struct gstlal_segment seg);
GValueArray *       g_value_array_from_gstlal_segment_list
                                                        (struct gstlal_segment_list *seglist);
void                gstlal_segment_free                 (struct gstlal_segment *segment);
struct gstlal_segment * gstlal_segment_from_g_value_array
                                                        (GValueArray *va);
struct gstlal_segment_list * gstlal_segment_list_append (struct gstlal_segment_list *segmentlist,
                                                         struct gstlal_segment *segment);
void                gstlal_segment_list_free            (struct gstlal_segment_list *segmentlist);
struct gstlal_segment_list * gstlal_segment_list_from_g_value_array
                                                        (GValueArray *va);
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);
gint                gstlal_segment_list_index           (const struct gstlal_segment_list *segmentlist,
                                                         guint64 t);
gint                gstlal_segment_list_length          (const struct gstlal_segment_list *segmentlist);
struct gstlal_segment_list * gstlal_segment_list_new    (void);
struct gstlal_segment * gstlal_segment_new              (guint64 start,
                                                         guint64 stop);

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.

Details

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

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

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.

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

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_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_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_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.
Generated by GTK-Doc V1.18