Overloading and optional arguments

Function overloading (having a several variants of a function with the same name and different arguments) is a language feature available in many languages but not in C.

In general, language binding authors should use restraint in combining functions in the cairo API via function overloading. What may seem like an obvious overload now may turn out to be strange with future additions to cairo. It might seem logical to make cairo_set_source_rgb() an overload of cairo_set_source(), but future plans to add cairo_set_source_rgb_premultiplied(), which will also take three doubles make this a bad idea. For this reason, only the following pairs of functions should be combined via overloading

void
cairo_set_source (cairo_t *cr, cairo_pattern_t *source);

void
cairo_set_source_surface (cairo_t          *cr,
                          cairo_surface_t  *source,
                          double            surface_x,
                          double            surface_y);
      
void
cairo_mask (cairo_t         *cr,
	    cairo_pattern_t *pattern);

void
cairo_mask_surface (cairo_t         *cr,
		    cairo_surface_t *surface,
		    double           surface_x,
		    double           surface_y);
      
cairo_surface_t *
cairo_image_surface_create (cairo_format_t	format,
			    int			width,
			    int			height);
cairo_surface_t *
cairo_image_surface_create_for_data (unsigned char	       *data,
				     cairo_format_t		format,
				     int			width,
				     int			height,
				     int			stride);

cairo_status_t
cairo_surface_write_to_png (cairo_surface_t	*surface,
			    const char		*filename);

cairo_status_t
cairo_surface_write_to_png_stream (cairo_surface_t	*surface,
				   cairo_write_func_t	write_func,
				   void			*closure);

cairo_surface_t *
cairo_image_surface_create_from_png (const char	*filename);

cairo_surface_t *
cairo_image_surface_create_from_png_stream (cairo_read_func_t	read_func,
					    void		*closure);
    

Note that there are cases where all constructors for a type aren't overloaded together. For example cairo_image_surface_create_from_png() should not be overloaded together with cairo_image_surface_create(). In such cases, the remaining constructors will typically need to be bound as static methods. In Java, for example, we might have:

Surface surface1 = ImageSurface(Format.RGB24, 100, 100);
Surface surface2 = ImageSurface.createFromPNG("camera.png");

Some other overloads that add combinations not found in C may be convenient for users for language bindings that provide cairo_point_t and cairo_rectangle_t types, for example:

void
cairo_move_to (cairo_t       *cr,
               cairo_point_t *point);
void
cairo_rectangle (cairo_t           *cr,
                 cairo_rectangle_t *rectangle);