This library provides a medium-level interface for accessing and manipulating file contents in memory. Its purpose is to allow code parts developed independently from each other to use the same memory representation of objects while being able to rely on some invariants. In particular, it should be possible to access and manipulate objects without knowledge of the other modules' object system or metadata.

In practice, this means:

An object is represented by exactly the information which is required to describe it. Information which is only meaningful to some code parts is not managed by the library, such as pointers to shared data or weak references. For example, the data structure representing a schematic net is:
struct xornsch_net {

struct xorn_double2d pos;

struct xorn_double2d size;

int color;

bool is_bus;

bool is_pin;

bool is_inverted;

};
File contents are referred to by revisions which are basically copy-on-write smart pointers. Once a revision is marked as “final”, it is not possible make further changes to it by means of the library's functions. (But it is of course possible to create a copy of the revision and modify that.) This allows to keep tabs on a certain state of a file, making it easy to implement an undo/redo functionality.
The actual data an object has in a revision is looked up and changed using a xorn_object_t or xorn_selection_t key which describes the “identity” of one or multiple objects, respectively.

The library's interface is designed to anticipate the operations which an application will typically perform on the file's contents and provide abstract functions which express these intentions to allow the library to do some optimization. For example, to delete all circles and arcs with radius zero, instead of

xorn_object_t *objects;
size_t count;
unsigned int i;
xorn_get_objects(rev, &objects, &count);
for (i = 0; i < count; i++) {
    xorn_obtype_t type = xorn_get_object_type(rev, objects[i]);
    if (type == xornsch_obtype_circle &&
        xornsch_get_circle_data(rev, objects[i])->radius == 0.)
        xorn_delete_object(rev, objects[i]);
    if (type == xornsch_obtype_arc &&
        xornsch_get_arc_data(rev, objects[i])->radius == 0.)
        xorn_delete_object(rev, objects[i]);
}
free(objects);

you would write:

xorn_selection_t sel = xornsch_select_by_radius(rev, 0.);
xorn_delete_selected_objects(rev, sel);
xorn_free_selection(sel);

The implementation could now, for example, choose to express the selection as a filter which can be applied to individual objects rather than as a list of object pointers, if this should prove more efficient. This way, the application doesn't have to know about but can still benefit from optimizations to the potentially messy detail of how the data is internally stored and accessed.

See also: xornstorage.h; How to use the storage library

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.