The cairo-path-data-t structure is used to represent the path data inside a cairo-path-t instance.

The data structure is designed to try to balance the demands of efficiency and ease-of-use. A path is represented as an array of cairo-path-data-t structures, which is a union of headers and points.

(defcstruct header-t
  (data-type cairo-path-data-type-t)
  (length :int))


(defcstruct point-t
  (x :double)
  (y :double))


(defcunion cairo-path-data-t
  (header (:pointer (:struct header-t)))
  (point (:pointer (:struct point-t))))  

Each portion of the path is represented by one or more elements in the array, (one header followed by 0 or more points). The length value of the header is the number of array elements for the current portion including the header, (i.e. length == 1 + # of points), and where the number of points for each element type is as follows:

%CAIRO_PATH_MOVE_TO:     1 point
%CAIRO_PATH_LINE_TO:     1 point
%CAIRO_PATH_CURVE_TO:    3 points
%CAIRO_PATH_CLOSE_PATH:  0 points  

The semantics and ordering of the coordinate values are consistent with the functions cairo-move-to, cairo-line-to, cairo-curve-to, and cairo-close-path.

Here is sample code for iterating through a cairo-path-t structure:

int i;
cairo_path_t *path;
cairo_path_data_t *data;


path = cairo_copy_path (cr);


for (i=0; i < path->num_data; i += path->data[i].header.length) {
    data = &path->data[i];
    switch (data->header.type) {
    case CAIRO_PATH_MOVE_TO:
        do_move_to_things (data[1].point.x, data[1].point.y);
        break;
    case CAIRO_PATH_LINE_TO:
        do_line_to_things (data[1].point.x, data[1].point.y);
        break;
    case CAIRO_PATH_CURVE_TO:
        do_curve_to_things (data[1].point.x, data[1].point.y,
                            data[2].point.x, data[2].point.y,
                            data[3].point.x, data[3].point.y);
        break;
    case CAIRO_PATH_CLOSE_PATH:
        do_close_path_things ();
        break;
    }
}
cairo_path_destroy (path);  

As of Cairo 1.4, Cairo does not mind if there are more elements in a portion of the path than needed. Such elements can be used by users of the Cairo API to hold extra values in the path data structure. For this reason, it is recommended that applications always use data->header.length to iterate over the path data, instead of hardcoding the number of elements for each element type.