cairo_path_t

The cairo_path_t type is one
area in which most language bindings will differ significantly
from the C API. The C API for cairo_path_t is
designed for efficiency and to avoid auxiliary objects that
would be have to be manually memory managed by the
application. However,
a language binding should not present cairo_path_t as an
array, but rather as an opaque that can be iterated
over. Different languages have quite different conventions for
how iterators work, so it is impossible to give an exact
specification for how this API should work, but the type names
and methods should be similar to the language's mapping of the following:

The above is written using the Java conventions for
iterators. To illustrate how the API for PathIterator might
depend on the native iteration conventions of the API, examine
three versions of the loop, first written in a hypothetical Java
binding:

While many of the API elements stay the same in the three
examples, the exact iteration mechanism is quite different, to
match how users of the language would expect to iterate over
a container.

You should not present an API for mutating or for creating new
cairo_path_t objects. In the future, these
guidelines may be extended to present an API for creating a
cairo_path_t from scratch for use with
cairo_append_path()
but the current expectation is that cairo_append_path() will
mostly be used with paths from
cairo_copy_path().