LV2  1.0.13
Data Structures | Functions
util.h File Reference

Helper functions for the LV2 Atom extension. More...

Data Structures

struct  LV2_Atom_Object_Query
 A single entry in an Object query. More...
 

Functions

static uint32_t lv2_atom_pad_size (uint32_t size)
 Pad a size to 64 bits. More...
 
static uint32_t lv2_atom_total_size (const LV2_Atom *atom)
 Return the total size of atom, including the header. More...
 
static bool lv2_atom_is_null (const LV2_Atom *atom)
 Return true iff atom is null. More...
 
static bool lv2_atom_equals (const LV2_Atom *a, const LV2_Atom *b)
 Return true iff a is equal to b. More...
 

Sequence Iterator

#define LV2_ATOM_SEQUENCE_FOREACH(seq, iter)
 A macro for iterating over all events in a Sequence. More...
 
#define LV2_ATOM_SEQUENCE_BODY_FOREACH(body, size, iter)
 Like LV2_ATOM_SEQUENCE_FOREACH but for a headerless sequence body. More...
 
static LV2_Atom_Eventlv2_atom_sequence_begin (const LV2_Atom_Sequence_Body *body)
 Get an iterator pointing to the first event in a Sequence body. More...
 
static LV2_Atom_Eventlv2_atom_sequence_end (const LV2_Atom_Sequence_Body *body, uint32_t size)
 Get an iterator pointing to the end of a Sequence body. More...
 
static bool lv2_atom_sequence_is_end (const LV2_Atom_Sequence_Body *body, uint32_t size, LV2_Atom_Event *i)
 Return true iff i has reached the end of body. More...
 
static LV2_Atom_Eventlv2_atom_sequence_next (const LV2_Atom_Event *i)
 Return an iterator to the element following i. More...
 

Tuple Iterator

#define LV2_ATOM_TUPLE_FOREACH(tuple, iter)
 A macro for iterating over all properties of a Tuple. More...
 
#define LV2_ATOM_TUPLE_BODY_FOREACH(body, size, iter)
 Like LV2_ATOM_TUPLE_FOREACH but for a headerless tuple body. More...
 
static LV2_Atomlv2_atom_tuple_begin (const LV2_Atom_Tuple *tup)
 Get an iterator pointing to the first element in tup. More...
 
static bool lv2_atom_tuple_is_end (const void *body, uint32_t size, LV2_Atom *i)
 Return true iff i has reached the end of body. More...
 
static LV2_Atomlv2_atom_tuple_next (const LV2_Atom *i)
 Return an iterator to the element following i. More...
 

Object Iterator

#define LV2_ATOM_OBJECT_FOREACH(obj, iter)
 A macro for iterating over all properties of an Object. More...
 
#define LV2_ATOM_OBJECT_BODY_FOREACH(body, size, iter)
 Like LV2_ATOM_OBJECT_FOREACH but for a headerless object body. More...
 
static LV2_Atom_Property_Bodylv2_atom_object_begin (const LV2_Atom_Object_Body *body)
 Return a pointer to the first property in body. More...
 
static bool lv2_atom_object_is_end (const LV2_Atom_Object_Body *body, uint32_t size, LV2_Atom_Property_Body *i)
 Return true iff i has reached the end of obj. More...
 
static LV2_Atom_Property_Bodylv2_atom_object_next (const LV2_Atom_Property_Body *i)
 Return an iterator to the property following i. More...
 

Object Query

static const LV2_Atom_Object_Query LV2_ATOM_OBJECT_QUERY_END = { 0, NULL }
 
static int lv2_atom_object_query (const LV2_Atom_Object *object, LV2_Atom_Object_Query *query)
 Get an object's values for various keys. More...
 
static int lv2_atom_object_body_get (uint32_t size, const LV2_Atom_Object_Body *body,...)
 Body only version of lv2_atom_object_get(). More...
 
static int lv2_atom_object_get (const LV2_Atom_Object *object,...)
 Variable argument version of lv2_atom_object_query(). More...
 

Detailed Description

Helper functions for the LV2 Atom extension.

Note these functions are all static inline, do not take their address.

This header is non-normative, it is provided for convenience.

Macro Definition Documentation

#define LV2_ATOM_SEQUENCE_FOREACH (   seq,
  iter 
)
Value:
for (LV2_Atom_Event* (iter) = lv2_atom_sequence_begin(&(seq)->body); \
!lv2_atom_sequence_is_end(&(seq)->body, (seq)->atom.size, (iter)); \
(iter) = lv2_atom_sequence_next(iter))
static bool lv2_atom_sequence_is_end(const LV2_Atom_Sequence_Body *body, uint32_t size, LV2_Atom_Event *i)
Return true iff i has reached the end of body.
Definition: util.h:91
The header of an atom:Event.
Definition: atom.h:204
static LV2_Atom_Event * lv2_atom_sequence_next(const LV2_Atom_Event *i)
Return an iterator to the element following i.
Definition: util.h:100
static LV2_Atom_Event * lv2_atom_sequence_begin(const LV2_Atom_Sequence_Body *body)
Get an iterator pointing to the first event in a Sequence body.
Definition: util.h:77

A macro for iterating over all events in a Sequence.

Parameters
seqThe sequence to iterate over
iterThe name of the iterator

This macro is used similarly to a for loop (which it expands to), e.g.:

// Do something with ev (an LV2_Atom_Event*) here...
}
#define LV2_ATOM_SEQUENCE_BODY_FOREACH (   body,
  size,
  iter 
)
Value:
for (LV2_Atom_Event* (iter) = lv2_atom_sequence_begin(body); \
!lv2_atom_sequence_is_end(body, size, (iter)); \
(iter) = lv2_atom_sequence_next(iter))
static bool lv2_atom_sequence_is_end(const LV2_Atom_Sequence_Body *body, uint32_t size, LV2_Atom_Event *i)
Return true iff i has reached the end of body.
Definition: util.h:91
The header of an atom:Event.
Definition: atom.h:204
static LV2_Atom_Event * lv2_atom_sequence_next(const LV2_Atom_Event *i)
Return an iterator to the element following i.
Definition: util.h:100
static LV2_Atom_Event * lv2_atom_sequence_begin(const LV2_Atom_Sequence_Body *body)
Get an iterator pointing to the first event in a Sequence body.
Definition: util.h:77

Like LV2_ATOM_SEQUENCE_FOREACH but for a headerless sequence body.

#define LV2_ATOM_TUPLE_FOREACH (   tuple,
  iter 
)
Value:
for (LV2_Atom* (iter) = lv2_atom_tuple_begin(tuple); \
!lv2_atom_tuple_is_end(LV2_ATOM_BODY(tuple), (tuple)->size, (iter)); \
(iter) = lv2_atom_tuple_next(iter))
static bool lv2_atom_tuple_is_end(const void *body, uint32_t size, LV2_Atom *i)
Return true iff i has reached the end of body.
Definition: util.h:145
static LV2_Atom * lv2_atom_tuple_next(const LV2_Atom *i)
Return an iterator to the element following i.
Definition: util.h:152
static LV2_Atom * lv2_atom_tuple_begin(const LV2_Atom_Tuple *tup)
Get an iterator pointing to the first element in tup.
Definition: util.h:138
#define LV2_ATOM_BODY(atom)
Return a pointer to the body of an Atom.
Definition: atom.h:92
The header of an atom:Atom.
Definition: atom.h:100

A macro for iterating over all properties of a Tuple.

Parameters
tupleThe tuple to iterate over
iterThe name of the iterator

This macro is used similarly to a for loop (which it expands to), e.g.:

LV2_ATOMO_TUPLE_FOREACH(tuple, elem) {
// Do something with elem (an LV2_Atom*) here...
}
#define LV2_ATOM_TUPLE_BODY_FOREACH (   body,
  size,
  iter 
)
Value:
for (LV2_Atom* (iter) = (LV2_Atom*)body; \
!lv2_atom_tuple_is_end(body, size, (iter)); \
(iter) = lv2_atom_tuple_next(iter))
static bool lv2_atom_tuple_is_end(const void *body, uint32_t size, LV2_Atom *i)
Return true iff i has reached the end of body.
Definition: util.h:145
static LV2_Atom * lv2_atom_tuple_next(const LV2_Atom *i)
Return an iterator to the element following i.
Definition: util.h:152
The header of an atom:Atom.
Definition: atom.h:100

Like LV2_ATOM_TUPLE_FOREACH but for a headerless tuple body.

#define LV2_ATOM_OBJECT_FOREACH (   obj,
  iter 
)
Value:
for (LV2_Atom_Property_Body* (iter) = lv2_atom_object_begin(&(obj)->body); \
!lv2_atom_object_is_end(&(obj)->body, (obj)->atom.size, (iter)); \
(iter) = lv2_atom_object_next(iter))
static LV2_Atom_Property_Body * lv2_atom_object_begin(const LV2_Atom_Object_Body *body)
Return a pointer to the first property in body.
Definition: util.h:189
static LV2_Atom_Property_Body * lv2_atom_object_next(const LV2_Atom_Property_Body *i)
Return an iterator to the property following i.
Definition: util.h:205
The body of an atom:Property (e.g.
Definition: atom.h:177
static bool lv2_atom_object_is_end(const LV2_Atom_Object_Body *body, uint32_t size, LV2_Atom_Property_Body *i)
Return true iff i has reached the end of obj.
Definition: util.h:196

A macro for iterating over all properties of an Object.

Parameters
objThe object to iterate over
iterThe name of the iterator

This macro is used similarly to a for loop (which it expands to), e.g.:

// Do something with prop (an LV2_Atom_Property_Body*) here...
}
#define LV2_ATOM_OBJECT_BODY_FOREACH (   body,
  size,
  iter 
)
Value:
!lv2_atom_object_is_end(body, size, (iter)); \
(iter) = lv2_atom_object_next(iter))
static LV2_Atom_Property_Body * lv2_atom_object_begin(const LV2_Atom_Object_Body *body)
Return a pointer to the first property in body.
Definition: util.h:189
static LV2_Atom_Property_Body * lv2_atom_object_next(const LV2_Atom_Property_Body *i)
Return an iterator to the property following i.
Definition: util.h:205
The body of an atom:Property (e.g.
Definition: atom.h:177
static bool lv2_atom_object_is_end(const LV2_Atom_Object_Body *body, uint32_t size, LV2_Atom_Property_Body *i)
Return true iff i has reached the end of obj.
Definition: util.h:196

Like LV2_ATOM_OBJECT_FOREACH but for a headerless object body.

Function Documentation

static uint32_t lv2_atom_pad_size ( uint32_t  size)
inlinestatic

Pad a size to 64 bits.

static uint32_t lv2_atom_total_size ( const LV2_Atom atom)
inlinestatic

Return the total size of atom, including the header.

static bool lv2_atom_is_null ( const LV2_Atom atom)
inlinestatic

Return true iff atom is null.

static bool lv2_atom_equals ( const LV2_Atom a,
const LV2_Atom b 
)
inlinestatic

Return true iff a is equal to b.

static LV2_Atom_Event* lv2_atom_sequence_begin ( const LV2_Atom_Sequence_Body body)
inlinestatic

Get an iterator pointing to the first event in a Sequence body.

static LV2_Atom_Event* lv2_atom_sequence_end ( const LV2_Atom_Sequence_Body body,
uint32_t  size 
)
inlinestatic

Get an iterator pointing to the end of a Sequence body.

static bool lv2_atom_sequence_is_end ( const LV2_Atom_Sequence_Body body,
uint32_t  size,
LV2_Atom_Event i 
)
inlinestatic

Return true iff i has reached the end of body.

static LV2_Atom_Event* lv2_atom_sequence_next ( const LV2_Atom_Event i)
inlinestatic

Return an iterator to the element following i.

static LV2_Atom* lv2_atom_tuple_begin ( const LV2_Atom_Tuple tup)
inlinestatic

Get an iterator pointing to the first element in tup.

static bool lv2_atom_tuple_is_end ( const void *  body,
uint32_t  size,
LV2_Atom i 
)
inlinestatic

Return true iff i has reached the end of body.

static LV2_Atom* lv2_atom_tuple_next ( const LV2_Atom i)
inlinestatic

Return an iterator to the element following i.

static LV2_Atom_Property_Body* lv2_atom_object_begin ( const LV2_Atom_Object_Body body)
inlinestatic

Return a pointer to the first property in body.

static bool lv2_atom_object_is_end ( const LV2_Atom_Object_Body body,
uint32_t  size,
LV2_Atom_Property_Body i 
)
inlinestatic

Return true iff i has reached the end of obj.

static LV2_Atom_Property_Body* lv2_atom_object_next ( const LV2_Atom_Property_Body i)
inlinestatic

Return an iterator to the property following i.

static int lv2_atom_object_query ( const LV2_Atom_Object object,
LV2_Atom_Object_Query query 
)
inlinestatic

Get an object's values for various keys.

The value pointer of each item in query will be set to the location of the corresponding value in object. Every value pointer in query MUST be initialised to NULL. This function reads object in a single linear sweep. By allocating query on the stack, objects can be "queried" quickly without allocating any memory. This function is realtime safe.

This function can only do "flat" queries, it is not smart enough to match variables in nested objects.

For example:

const LV2_Atom* name = NULL;
const LV2_Atom* age = NULL;
{ urids.eg_name, &name },
{ urids.eg_age, &age },
};
// name and age are now set to the appropriate values in obj, or NULL.
static int lv2_atom_object_body_get ( uint32_t  size,
const LV2_Atom_Object_Body body,
  ... 
)
inlinestatic

Body only version of lv2_atom_object_get().

static int lv2_atom_object_get ( const LV2_Atom_Object object,
  ... 
)
inlinestatic

Variable argument version of lv2_atom_object_query().

This is nicer-looking in code, but a bit more error-prone since it is not type safe and the argument list must be terminated.

The arguments should be a series of uint32_t key and const LV2_Atom** value pairs, terminated by a zero key. The value pointers MUST be initialized to NULL. For example:

const LV2_Atom* name = NULL;
const LV2_Atom* age = NULL;
uris.name_key, &name,
uris.age_key, &age,
0);

Variable Documentation

const LV2_Atom_Object_Query LV2_ATOM_OBJECT_QUERY_END = { 0, NULL }
static