[cairo] cairo 1.5.8 API Changes and bindings

[Alp Toker]

Jonathon Jongsma wrote:
> I had a brief chat with Behdad about this on IRC and he suggested to
> bring it up on the mailing list.  As far as I know, most bindings do
> not actually expose the cairo_status_t data type: the manual
> recommends that bindings check status and throw an exception of the
> appropriate type.  In this case, if bindings followed this advice,
> they'd be throwing exceptions on cases that previously didn't throw
> exceptions, which could potentially break existing applications.
> Behdad suggested possibly adding something like has_current_point() to
> work around this.  Anybody have any other thoughts about how to handle
> this in bindings?

Agreed.

I believe the original proposal over a year ago was a boolean return 
value. has_current_point() or cairo_path_is_empty() may be an even 
better idea than either a boolean return or an error return.

An error return isn't technically wrong, but it's likely to lead to 
wrong interpretation in bindings.

For the C# Cairo binding, we would have to special case this error so it 
doesn't raise an exception, since exceptions are intended for truly 
exceptional conditions and carry some overhead that you don't want to 
incur when simply checking for an empty path.

The benefit of has_current_point()/is_empty() over changing the return 
type is that a newly added symbol is easier to document and support.

The build failure mode of a change in return value is somewhat subtle 
compared to simply introducing cairo_path_is_empty().