Overloading and optional arguments: Cairo: A Vector Graphics Library

## 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);