[cairo] API Shakeup: cairo_current_path -> cairo_copy_path_data

[mental at rydia.net]

Quoting Carl Worth <cworth at cworth.org>:

> First, the convention would be to name it something like:
>
> 	cairo_path_data_destroy (cairo_path_data_t *data);
>
> but then we'd have an unconventional "destroy" function with no
> matching "create", (nor "reference").

That doesn't seem quite so bad, though given this is non-refcounted
POD, it might make sense to employ a different convention like
_free instead of _destroy to underscore the distinction.

> Second, the cairo_copy_path_data function returns an array, so we
> open the possibility for the user to call the "destroy" function
> with something besides the address of the first element. There are
> no other allocated array objecte in cairo so far, so there would
> be nothing to indicate to the user that this destroy function must
> only be called on the first element. Meanwhile, the semantics of
> free are well-enough understood to not suffer from this problem.

Hmm.  That would seem to suggest either:

 1) call it cairo_free()

 2) use a structure with an array/pointer element rather than
    a raw array, avoiding ambiguity about what to pass the
    destroy/free fuction

The latter has the advantage that you could also have a "length"
member[1], avoiding all the grief and pain that has been wrought
upon the world by value-terminated C arrays over the years.

-mental

---

[1] i.e. (this would be allocated to size):

  typedef struct {
    unsigned length;
    cairo_path_data_t data[1];
  } cairo_path_t;

 or (if you don't like "magic" array members):

  typedef struct {
    unsigned length;
    cairo_path_data_t *data;
  } cairo_path_t;