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