Storing file contents in memory. More...
#include <stddef.h>
#include <stdbool.h>
Go to the source code of this file.
Classes | |
struct | xorn_string |
Sequence of bytes. More... | |
struct | xorn_double2d |
Pair of double values indicating a coordinate or offset. More... | |
struct | xorn_pointer |
Arbitrary reference-counted pointer. More... | |
struct | xornsch_line_attr |
Schematic line style. More... | |
struct | xornsch_fill_attr |
Schematic fill style. More... | |
struct | xornsch_arc |
Schematic arc. More... | |
struct | xornsch_box |
Schematic box. More... | |
struct | xornsch_circle |
Schematic circle. More... | |
struct | xornsch_component |
Schematic component. More... | |
struct | xornsch_line |
Schematic line. More... | |
struct | xornsch_net |
Schematic net segment, bus segment, or pin. More... | |
struct | xornsch_path |
Schematic path. More... | |
struct | xornsch_picture |
Schematic picture. More... | |
struct | xornsch_text |
Schematic text or attribute. More... | |
Typedefs | |
typedef struct xorn_revision * | xorn_revision_t |
Opaque type representing the contents of a file. More... | |
typedef struct xorn_object * | xorn_object_t |
Opaque type representing the identity of an object. More... | |
typedef struct xorn_selection * | xorn_selection_t |
Opaque type representing the identity of a set of objects. More... | |
Enumerations | |
enum | xorn_obtype_t { xorn_obtype_none, xornsch_obtype_arc, xornsch_obtype_box, xornsch_obtype_circle, xornsch_obtype_component, xornsch_obtype_line, xornsch_obtype_net, xornsch_obtype_path, xornsch_obtype_picture, xornsch_obtype_text } |
Object types, each corresponding to a data structure. More... | |
enum | xorn_attst_t { xorn_attst_na, xorn_attst_consistent, xorn_attst_inconsistent } |
Attribute status across multiple objects. More... | |
Functions | |
xorn_revision_t | xorn_new_revision (xorn_revision_t rev) |
Create a new revision, either from scratch or by copying an existing one. More... | |
bool | xorn_revision_is_transient (xorn_revision_t rev) |
Return whether a revision can be changed. More... | |
void | xorn_finalize_revision (xorn_revision_t rev) |
Prevent further changes to a revision. More... | |
void | xorn_free_revision (xorn_revision_t rev) |
Free the memory associated with a revision. More... | |
bool | xorn_object_exists_in_revision (xorn_revision_t rev, xorn_object_t ob) |
Return whether an object exists in a revision. More... | |
xorn_obtype_t | xorn_get_object_type (xorn_revision_t rev, xorn_object_t ob) |
Get the type of an object in a given revision. More... | |
const void * | xorn_get_object_data (xorn_revision_t rev, xorn_object_t ob, xorn_obtype_t type) |
Get a pointer to an object's data in a given revision. More... | |
int | xorn_get_object_location (xorn_revision_t rev, xorn_object_t ob, xorn_object_t *attached_to_return, unsigned int *position_return) |
Get the location of an object in the object structure. More... | |
int | xorn_get_objects (xorn_revision_t rev, xorn_object_t **objects_return, size_t *count_return) |
Return a list of all objects in a revision. More... | |
int | xorn_get_objects_attached_to (xorn_revision_t rev, xorn_object_t ob, xorn_object_t **objects_return, size_t *count_return) |
Return a list of objects in a revision which are attached to a certain object. More... | |
int | xorn_get_selected_objects (xorn_revision_t rev, xorn_selection_t sel, xorn_object_t **objects_return, size_t *count_return) |
Return a list of objects which are in a revision as well as in a selection. More... | |
int | xorn_get_added_objects (xorn_revision_t from_rev, xorn_revision_t to_rev, xorn_object_t **objects_return, size_t *count_return) |
Return a list of objects which are in a revision but not in another. More... | |
int | xorn_get_removed_objects (xorn_revision_t from_rev, xorn_revision_t to_rev, xorn_object_t **objects_return, size_t *count_return) |
Return a list of objects which are in a revision but not in another. More... | |
int | xorn_get_modified_objects (xorn_revision_t from_rev, xorn_revision_t to_rev, xorn_object_t **objects_return, size_t *count_return) |
Return a list of objects which exist in two revisions but have different type or data. More... | |
xorn_selection_t | xorn_select_none () |
Create an empty selection. More... | |
xorn_selection_t | xorn_select_object (xorn_object_t ob) |
Create a selection containing a single object. More... | |
xorn_selection_t | xorn_select_attached_to (xorn_revision_t rev, xorn_object_t ob) |
Create a selection containing all objects in a revision attached to a given object. More... | |
xorn_selection_t | xorn_select_all (xorn_revision_t rev) |
Create a selection containing all objects in a revision. More... | |
xorn_selection_t | xorn_select_all_except (xorn_revision_t rev, xorn_selection_t sel) |
Create a selection containing all objects in a revision except those in a given selection. More... | |
xorn_selection_t | xorn_select_including (xorn_selection_t sel, xorn_object_t ob) |
Create a selection which contains all the objects in an existing selection plus a given object. More... | |
xorn_selection_t | xorn_select_excluding (xorn_selection_t sel, xorn_object_t ob) |
Create a selection which contains all the objects in an existing selection minus a given object. More... | |
xorn_selection_t | xorn_select_union (xorn_selection_t sel0, xorn_selection_t sel1) |
Create a selection containing the objects in either given selection. More... | |
xorn_selection_t | xorn_select_intersection (xorn_selection_t sel0, xorn_selection_t sel1) |
Create a selection containing the objects in both given selections. More... | |
xorn_selection_t | xorn_select_difference (xorn_selection_t sel0, xorn_selection_t sel1) |
Create a selection containing the objects contained in one given selection, but not the other. More... | |
bool | xorn_selection_is_empty (xorn_revision_t rev, xorn_selection_t sel) |
Return whether a selection is empty in a given revision. More... | |
bool | xorn_object_is_selected (xorn_revision_t rev, xorn_selection_t sel, xorn_object_t ob) |
Return whether an object exists in a revision and is selected in a selection. More... | |
void | xorn_free_selection (xorn_selection_t sel) |
Free the memory used for storing a selection. More... | |
xorn_object_t | xorn_add_object (xorn_revision_t rev, xorn_obtype_t type, const void *data) |
Add a new object to a transient revision. More... | |
int | xorn_set_object_data (xorn_revision_t rev, xorn_object_t ob, xorn_obtype_t type, const void *data) |
Set an object in a transient revision to the given object type and data. More... | |
int | xorn_relocate_object (xorn_revision_t rev, xorn_object_t ob, xorn_object_t attach_to, xorn_object_t insert_before) |
Change the location of an object in the object structure of a transient revision. More... | |
void | xorn_delete_object (xorn_revision_t rev, xorn_object_t ob) |
Delete an object from a transient revision. More... | |
void | xorn_delete_selected_objects (xorn_revision_t rev, xorn_selection_t sel) |
Delete some objects from a transient revision. More... | |
xorn_object_t | xorn_copy_object (xorn_revision_t dest, xorn_revision_t src, xorn_object_t ob) |
Copy an object to a transient revision. More... | |
xorn_selection_t | xorn_copy_objects (xorn_revision_t dest, xorn_revision_t src, xorn_selection_t sel) |
Copy some objects to a transient revision. More... | |
Storing file contents in memory.
See here for an overview of the storage library.
Definition in file xornstorage.h.
typedef struct xorn_object * xorn_object_t |
Opaque type representing the identity of an object.
A value of this type is used as a key to look up and change the state of an object in a revision. It is created by xorn_add_object, xorn_copy_object, or (indirectly) xorn_copy_objects and doesn't need to be freed explicitly; it loses its meaning once the last revision in which it is valid has been freed.
Definition at line 55 of file xornstorage.h.
typedef struct xorn_revision * xorn_revision_t |
Opaque type representing the contents of a file.
A revision points to a particular state of the contents of a file, sharing memory parts between revisions where possible. It is created by xorn_new_revision and needs to be freed explicitly by calling xorn_free_revision.
A revision can be “finalized” by calling xorn_finalize_revision which prevents further changes to it by means of the library's functions. It is of course still possible to create a copy of the revision and modify that.
Definition at line 54 of file xornstorage.h.
typedef struct xorn_selection * xorn_selection_t |
Opaque type representing the identity of a set of objects.
A value of this type is used as an set of keys for mass object inspection or manipulation not designating any specific order. It can be created using one of the xorn_select_something
class of functions and needs to be freed explicitly by calling xorn_free_selection.
Definition at line 56 of file xornstorage.h.
enum xorn_attst_t |
Attribute status across multiple objects.
Returned by the xornsch_get_attribute
class of functions.
Definition at line 40 of file xornstorage.h.
enum xorn_obtype_t |
Object types, each corresponding to a data structure.
The type of an object indicates which data structure is used to encode its parameters. It can be read using xorn_get_object_type. Depending on the object type, the object's data can be read using the appropriate type-safe function, e.g. xornsch_get_line_data
for a line object.
Enumerator | |
---|---|
xorn_obtype_none |
The object does not exist. |
xornsch_obtype_arc |
See xornsch_arc. |
xornsch_obtype_box |
See xornsch_box. |
xornsch_obtype_circle |
See xornsch_circle. |
xornsch_obtype_component |
See xornsch_component. |
xornsch_obtype_line |
See xornsch_line. |
xornsch_obtype_net |
See xornsch_net. |
xornsch_obtype_path |
See xornsch_path. |
xornsch_obtype_picture |
See xornsch_picture. |
xornsch_obtype_text |
See xornsch_text. |
Definition at line 27 of file xornstorage.h.
xorn_object_t xorn_add_object | ( | xorn_revision_t | rev, |
xorn_obtype_t | type, | ||
void const * | data | ||
) |
Add a new object to a transient revision.
The object is appended to the end of the object list.
data must point to a data structure matching the object type indicated by type (e.g., if type is xornsch_obtype_net
, then data must point to a xornsch_net
structure). The data structure (including referenced strings) will not be accessed after this function has returned.
NULL
.Example:
xornsch_add_net
etc.) which offer the same functionality but are type-safe. Definition at line 60 of file manipulate.cc.
xorn_object_t xorn_copy_object | ( | xorn_revision_t | dest, |
xorn_revision_t | src, | ||
xorn_object_t | ob | ||
) |
Copy an object to a transient revision.
Any objects attached to ob are copied as well, their copies being attached to the copy of ob, which is appended to the end of the object list.
dest | Destination revision (must be transient) |
src | Source revision (does not need to be transient) |
ob | Object in the source revision which should be copied |
NULL
. Definition at line 392 of file manipulate.cc.
xorn_selection_t xorn_copy_objects | ( | xorn_revision_t | dest, |
xorn_revision_t | src, | ||
xorn_selection_t | sel | ||
) |
Copy some objects to a transient revision.
Any objects attached to the objects are copied as well and attached to the corresponding new object. The copied objects are appended to the end of the object list in an unspecified order.
dest | Destination revision (must be transient) |
src | Source revision (does not need to be transient) |
sel | Objects in the source revision which should be copied |
NULL
.Definition at line 433 of file manipulate.cc.
void xorn_delete_object | ( | xorn_revision_t | rev, |
xorn_object_t | ob | ||
) |
Delete an object from a transient revision.
Any objects attached to ob are deleted as well.
The deleted object(s) stay valid and can later be re-added using xorn_set_object_data or its type-safe equivalents.
If the revision isn't transient or the object doesn't exist in the revision, nothing is changed.
Definition at line 301 of file manipulate.cc.
void xorn_delete_selected_objects | ( | xorn_revision_t | rev, |
xorn_selection_t | sel | ||
) |
Delete some objects from a transient revision.
Any objects attached to a deleted object are deleted as well.
The deleted objects stay valid and can later be re-added using xorn_set_object_data or its type-safe equivalents.
Objects that don't exist in the revision are ignored. If the revision isn't transient, nothing is changed.
Definition at line 328 of file manipulate.cc.
void xorn_finalize_revision | ( | xorn_revision_t | rev | ) |
Prevent further changes to a revision.
When a revision is created, it is initially transient, i.e. changeable. However, it is typically not desired for a revision to change once it is in its desired state. Using this function, you can prevent further changes to the revision by means of the Xorn functions (though nobody can prevent you from poking into memory and messing things up). It will still be possible to create a copy of the revision and change that.
Definition at line 91 of file revision.cc.
void xorn_free_revision | ( | xorn_revision_t | rev | ) |
Free the memory associated with a revision.
Some memory may be shared between revisions. This memory will be released once all revisions using it have been freed.
Definition at line 103 of file revision.cc.
void xorn_free_selection | ( | xorn_selection_t | sel | ) |
Free the memory used for storing a selection.
Definition at line 277 of file selection.cc.
int xorn_get_added_objects | ( | xorn_revision_t | from_rev, |
xorn_revision_t | to_rev, | ||
xorn_object_t ** | objects_return, | ||
size_t * | count_return | ||
) |
Return a list of objects which are in a revision but not in another.
The returned list contains all objects in to_rev which are not in from_rev. They are not necessarily returned in a meaningful order.
The same semantics apply as in xorn_get_objects. See there for a more detailed description.
int xorn_get_modified_objects | ( | xorn_revision_t | from_rev, |
xorn_revision_t | to_rev, | ||
xorn_object_t ** | objects_return, | ||
size_t * | count_return | ||
) |
Return a list of objects which exist in two revisions but have different type or data.
The objects are not necessarily returned in a meaningful order.
The same semantics apply as in xorn_get_objects. See there for a more detailed description.
const void* xorn_get_object_data | ( | xorn_revision_t | rev, |
xorn_object_t | ob, | ||
xorn_obtype_t | type | ||
) |
Get a pointer to an object's data in a given revision.
The returned data structure (including referenced strings) must not be changed by the caller; use xorn_set_object_data or its type-safe equivalents to change the object.
xornsch_obtype_net
, returns a pointer to a xornsch_net
structure). If the object doesn't exist in rev, or type doesn't match its type, returns NULL
.Example:
xornsch_get_net_data
etc.) which offer the same functionality but are type-safe. int xorn_get_object_location | ( | xorn_revision_t | rev, |
xorn_object_t | ob, | ||
xorn_object_t * | attached_to_return, | ||
unsigned int * | position_return | ||
) |
Get the location of an object in the object structure.
rev | Revision to examine |
ob | Object whose location to return |
attached_to_return | Pointer to a variable where to write the object to which ob is attached |
position_return | Pointer to a variable where to write the index of ob relative to its sibling objects |
Both pointer arguments may be NULL
to indicate that the caller isn't interested in the return value.
0
and writes the appropriate values to attached_to_return and position_return if ob exists in rev. Otherwise, doesn't touch the values and returns -1
. xorn_obtype_t xorn_get_object_type | ( | xorn_revision_t | rev, |
xorn_object_t | ob | ||
) |
Get the type of an object in a given revision.
Returns xorn_obtype_none if the object doesn't exist in the revision.
int xorn_get_objects | ( | xorn_revision_t | rev, |
xorn_object_t ** | objects_return, | ||
size_t * | count_return | ||
) |
Return a list of all objects in a revision.
A list of xorn_object_t values is allocated and written to, and its location is written to the variable pointed to by objects_return. The number of objects is written to the variable pointed to by count_return. If the list is empty or there is not enough memory, *objects_return may be set to NULL
.
The objects are returned in their actual order. Attached objects are listed after the object they are attached to.
0
on success and -1
if there is not enough memory.free(3)
.Example:
int xorn_get_objects_attached_to | ( | xorn_revision_t | rev, |
xorn_object_t | ob, | ||
xorn_object_t ** | objects_return, | ||
size_t * | count_return | ||
) |
Return a list of objects in a revision which are attached to a certain object.
If ob is NULL
, return all objects in the revision which are not attached. The objects are returned in their actual order. Objects attached to the returned objects are not returned.
objects_return may be NULL
to indicate that the caller is only interested in the object count. In this case, the object list isn't created, and the function cannot run out of memory. Otherwise, the same semantics apply as in xorn_get_objects. See there for a more detailed description.
int xorn_get_removed_objects | ( | xorn_revision_t | from_rev, |
xorn_revision_t | to_rev, | ||
xorn_object_t ** | objects_return, | ||
size_t * | count_return | ||
) |
Return a list of objects which are in a revision but not in another.
The returned list contains all objects in from_rev which are not in to_rev. They are not necessarily returned in a meaningful order.
The same semantics apply as in xorn_get_objects. See there for a more detailed description.
int xorn_get_selected_objects | ( | xorn_revision_t | rev, |
xorn_selection_t | sel, | ||
xorn_object_t ** | objects_return, | ||
size_t * | count_return | ||
) |
Return a list of objects which are in a revision as well as in a selection.
The objects are not necessarily returned in a meaningful order.
The same semantics apply as in xorn_get_objects. See there for a more detailed description.
xorn_revision_t xorn_new_revision | ( | xorn_revision_t | rev | ) |
Create a new revision, either from scratch or by copying an existing one.
You should free the revision using xorn_free_revision once it isn't used any more.
rev | Revision to copy, or NULL . |
There is a slight difference between creating two empty revisions and copying an empty one: only in the second case, objects of one revision will be valid in the other.
Definition at line 56 of file revision.cc.
bool xorn_object_exists_in_revision | ( | xorn_revision_t | rev, |
xorn_object_t | ob | ||
) |
bool xorn_object_is_selected | ( | xorn_revision_t | rev, |
xorn_selection_t | sel, | ||
xorn_object_t | ob | ||
) |
Return whether an object exists in a revision and is selected in a selection.
Definition at line 266 of file selection.cc.
int xorn_relocate_object | ( | xorn_revision_t | rev, |
xorn_object_t | ob, | ||
xorn_object_t | attach_to, | ||
xorn_object_t | insert_before | ||
) |
Change the location of an object in the object structure of a transient revision.
This function performs two distinct operations:
If attach_to is NULL
, the object becomes un-attached. If ob and insert_before are identical and ob is already attached to attach_to, the revision is left unchanged.
rev | Revision to modify (must be transient) |
ob | The object which should be reordered and/or attached (must be xornsch_text if attach_to is not NULL ) |
attach_to | The object to which ob should be attached (must be xornsch_net or xornsch_component, or NULL ) |
insert_before | An object already attached to attach_to before which ob should be inserted, or NULL to append it at the end. |
0
on success. Returns -1
ifNULL
) attach_to or insert_before don't exist in the revision,NULL
andNULL
and not attached to attach_to, orExample:
Definition at line 219 of file manipulate.cc.
bool xorn_revision_is_transient | ( | xorn_revision_t | rev | ) |
Return whether a revision can be changed.
When a revision is created, it is initially transient, i.e. changeable. This can be changed by calling xorn_finalize_revision. After that, it can't be changed directly any more—you will have to create a transient copy if you want to change it again.
Definition at line 76 of file revision.cc.
xorn_selection_t xorn_select_all | ( | xorn_revision_t | rev | ) |
Create a selection containing all objects in a revision.
Definition at line 90 of file selection.cc.
xorn_selection_t xorn_select_all_except | ( | xorn_revision_t | rev, |
xorn_selection_t | sel | ||
) |
Create a selection containing all objects in a revision except those in a given selection.
Definition at line 112 of file selection.cc.
xorn_selection_t xorn_select_attached_to | ( | xorn_revision_t | rev, |
xorn_object_t | ob | ||
) |
Create a selection containing all objects in a revision attached to a given object.
The object may be NULL
, in which case the selection contains all objects which are not attached.
NULL
if ob does not exist in rev or there is not enough memory. Definition at line 61 of file selection.cc.
xorn_selection_t xorn_select_difference | ( | xorn_selection_t | sel0, |
xorn_selection_t | sel1 | ||
) |
Create a selection containing the objects contained in one given selection, but not the other.
Definition at line 224 of file selection.cc.
xorn_selection_t xorn_select_excluding | ( | xorn_selection_t | sel, |
xorn_object_t | ob | ||
) |
Create a selection which contains all the objects in an existing selection minus a given object.
Definition at line 156 of file selection.cc.
xorn_selection_t xorn_select_including | ( | xorn_selection_t | sel, |
xorn_object_t | ob | ||
) |
Create a selection which contains all the objects in an existing selection plus a given object.
Definition at line 136 of file selection.cc.
xorn_selection_t xorn_select_intersection | ( | xorn_selection_t | sel0, |
xorn_selection_t | sel1 | ||
) |
Create a selection containing the objects in both given selections.
Definition at line 201 of file selection.cc.
xorn_selection_t xorn_select_none | ( | ) |
Create an empty selection.
Definition at line 24 of file selection.cc.
xorn_selection_t xorn_select_object | ( | xorn_object_t | ob | ) |
Create a selection containing a single object.
Definition at line 35 of file selection.cc.
xorn_selection_t xorn_select_union | ( | xorn_selection_t | sel0, |
xorn_selection_t | sel1 | ||
) |
Create a selection containing the objects in either given selection.
Definition at line 178 of file selection.cc.
bool xorn_selection_is_empty | ( | xorn_revision_t | rev, |
xorn_selection_t | sel | ||
) |
Return whether a selection is empty in a given revision.
Definition at line 246 of file selection.cc.
int xorn_set_object_data | ( | xorn_revision_t | rev, |
xorn_object_t | ob, | ||
xorn_obtype_t | type, | ||
void const * | data | ||
) |
Set an object in a transient revision to the given object type and data.
If the object does not exist in the revision, it is created and appended to the end of the object list.
rev | Revision to be changed (must be transient) |
ob | An object which has previously been returned by a Xorn function for either this revision, one of its ancestors, or a revision which has a common ancestor with it. |
type | New object type (may be different from previous one, but must be xornsch_obtype_net or xornsch_obtype_component if there are objects attached to ob, and must be xornsch_obtype_text if ob itself is attached to an object) |
data | Pointer to a data structure matching the object type indicated by type (e.g., if type is xornsch_obtype_net , a pointer to a xornsch_net structure). The data structure (including referenced strings) will not be accessed after this function has returned. |
0
if the object has been changed. Returns -1
ifExample:
xornsch_set_net_data
etc.) which offer the same functionality but are type-safe. Definition at line 131 of file manipulate.cc.