Re: Consensus on getter conventions?

[Oskar Liljeblad <osk hem passagen se>]

On Thursday, August 24, 2000 at 14:02, Derek Simkowiak wrote:
> -> My personal preference is to have all get_* functions which return
> -> something be a pointer to a "static" piece of memory.  Those
> -> cases where deallocation is required should return by argument.
> -> 
> ->   /* this doesn't need to be freed because it was the return */
> ->   const gchar* gtk_widget_get_name(GtkWidget*);
> -> 
> ->   /* this one does need to be free and it is different for that reason */
> ->   void gtk_font_selection_dialog_get_font_name(
> ->         GtkFontSelectionDialog *fsd,  gchar**);
> ->                                       ^^^^^
> ->               notice it isn't const because we give it to the user.
> 
> 	I like Karl's idea.  Makes it clear as day.
> 
> 	Would this cause any problems for language bindings?

I can only speak for my GTK bindings for Java (Gnome-GCJ), and
it wouldn't cause any problems. As long as

  {existance of a return arg} + {number of return-by-pointer args} <= 1

In other words, it is hard to handle functions with multiple return/
output values, especially if the the values are of different types.

The main issue as I see it is figuring out whether a function returns
a static string or a dynamic. Why not just add a postfix '_s' to
methods which return static strings? And if compatibility with old
versions of GTK is to be kept, add a set of functions with '_d'
postfix as well. In the end, all you need to achieve consistency
is a set of #define's in the appropriate header files:

  #define gtk_accelerator_get_d		gtk_accelerator_get
  #define gtk_arg_name_strip_type_s	gtk_arg_name_strip_type
  #define gtk_clist_get_column_title_s	gtk_clist_get_column_title
  #define gtk_args_collect_d		gtk_args_collect
  #define gtk_entry_get_text_s		gtk_entry_get_text

(This along with a policy to recommend future functions that
return gchar*, gchar**, GList* and others to end with either _d
or _s.)

For functions that take return-by-pointer arguments, to me only
solution seems to be to document each argument name appropriately
in the header file. For example:

gint gtk_clist_get_text (GtkCList  *clist,
			 gint       row,
			 gint       column,
			 gchar    **text);

would become

gint gtk_clist_get_text (GtkCList  *clist,
			 gint       row,
			 gint       column,
			 gchar    **text_s);

Oskar Liljeblad (osk@hem.passagen.se)