Re: Structures thought question

["Havoc Pennington" <hp pobox com>]

Hi,

On Sat, Nov 15, 2008 at 7:06 AM, Owen Taylor <otaylor redhat com> wrote:
>
> void clutter_color_from_pixel (ClutterColor *dest,
>                               guint32       pixel);
>

If this is a method, I guess it raises the issue that the ClutterColor
"this" has to end up modified ... I'm not sure what gjs does here at
the moment. I guess we need to treat all "this" as "inout" ?

color.from_pixel(0xffffff)

(though when answering the in/out/inout question, I don't know the
answer to the "how many *" part, i.e. is an out param ClutterColor* or
ClutterColor**)

> void gdk_region_union (GdkRegion       *source1,
>                       const GdkRegion *source2);

I would expect "inout source1" as "this" and "in source2"

source1.union(source2);

> void gdk_region_get_clipbox (const GdkRegion *region,
>                             GdkRectangle    *rectangle);

Hmm... const methods treat "this" as "in" not "inout" I guess.

Not clear to me if the rectangle is "out" or "inout" - does the "in"
mean "GdkRectangle* not GdkRectangle**" or does it mean "nobody cares
about the initial value"

This one maps to gjs I guess as:

 rect = region.get_clipbox();

> void gtk_text_buffer_insert (GtkTextBuffer *buffer,
>                             GtkTextIter   *iter,
>                             const gchar   *text,
>                             gint           len);

Would "inout" imply GtkTextIter** vs. GtkTextIter*, or does it just
imply that the iter has to be copied back over the original iter after
the call.

iter is either "in" (if "in" already implies we copy back and "out"
just adds the ** indirection), or "inout" (if "out" means to copy back
to the orignal iter).

My guess is that the extra * needs to be a separate flag from the in/out/inout

So "out" means "we need to update the original value" aka "the arg is
not const", while some separate flag would mean "add an extra pointer
indirection"

I could also see doing it with a "const" flag which indicated whether
to update the original value, and "out" would mean "add an extra
pointer indirection," but I don't know if that really works or not,
plus it just doesn't seem right.

This one could map to gjs as either of:

   buffer.insert(iter, text);  // iter is modified
or
   newIter = buffer.insert(iter, text); // iter is not modified,
"inout" means one in arg and one return value

Is the rule that "out" and "inout" are both returned, or that only
plain "out" is returned? I think perhaps "only out is returned" makes
more sense, but I don't know what the code does right now.

> gboolean clutter_color_parse (const gchar  *color,
>                             ClutterColor *dest);

This one should maybe be "in color, out dest" i.e. no "in" on the
dest. Which might ideally map to gjs as:
  [success, color] = Clutter.color_parse("blue");

Though, if you were hand-writing the binding, you might be tempted to
make it a method on ClutterColor, since it's bizarre that the C
function's args are backward ...

Anyway, what makes sense to me after working through the examples is:
 - "in" means no need to update the original value after the call
because the arg is const
 - "inout" means an arg to JS function, which has the post-call value
assigned back to it
 - "out" means a return value from the JS function, and no arg to the
JS function
 - "this" args can be either "in" or "inout"
 - there is some extra flag to deal with return by pointer (an extra
indirection)

I don't really remember what gjs does right now in all these cases,
I'd look but I'm sure whatever it does is more accidental than
well-thought-out anyway ;-)

Havoc