I've added an annotation. Let me know if it doesn't work.

I don't think these annotation changes have the desired effect.  Instead of simply letting you omit the length argument as in

  $p->load_from_data ("GtkButton {...}");

they force you to provide an array of integers.  In Perl, you can get by with this workaround:

  $p->load_from_data ([map ord, split //, "GtkButton {...}"])

I don't think there's currently a way to associate a string with a length argument (right, Colin?).  So the best we can do is to revert this patch and make language bindings add overrides to provide a default length argument.  I can do the revert if everyone agrees.

(In reply to comment #2)
> I don't think these annotation changes have the desired effect.  Instead of
> simply letting you omit the length argument as in
> 
>   $p->load_from_data ("GtkButton {...}");
> 
> they force you to provide an array of integers.  

Looks like the new API is an array of bytes, which should be handled by bindings cleanly.

> I don't think there's currently a way to associate a string with a length
> argument (right, Colin?).  

Strings as in utf8 ideally shouldn't have a length (in bytes), since then one could be truncating the buffer in the middle.

Take g_utf8_validate() - if we were adding this API today, I'd have it take a GBytes or a (guint8* data, int length).  The latter would force C users (at least on x86) to cast, but conceptually the function operates on binary data - it's valid to pass it non-UTF-8.  Thus it shouldn't take a char *, which the default assumption is for it to be UTF-8.

That's the ideal - of course, we have a number of APIs which take char * (utf8) with length.  Binding consistency here may be weaker.

> So the best we can do is to revert this patch and
> make language bindings add overrides to provide a default length argument.  I
> can do the revert if everyone agrees.

But this patch has been released in GTK+ 3.2; we'd be changing the API *again* if we reverted.

It seems to me the least-bad thing to do at this point is to leave the function as-is.  If really desired, we could add a new function which took a utf8 (i.e. char* without length), but regardless, I also think the Perl bindings should make conversion between Perl-native string types and array-of-guint8 convenient.

I'm not sure how perl handles Unicode, but IIRC its basic string type *is* an array of bytes in an undefined encoding.  Converting that to a guint8-array should Just Work.

(In reply to comment #3)
> (In reply to comment #2)
> > So the best we can do is to revert this patch and
> > make language bindings add overrides to provide a default length argument.  I
> > can do the revert if everyone agrees.
> 
> But this patch has been released in GTK+ 3.2; we'd be changing the API *again*
> if we reverted.
> 
> It seems to me the least-bad thing to do at this point is to leave the function
> as-is.  If really desired, we could add a new function which took a utf8 (i.e.
> char* without length), but regardless, I also think the Perl bindings should
> make conversion between Perl-native string types and array-of-guint8
> convenient.

Supporting this case in the bindings has not occurred to me, and should indeed be doable.  It does feel strange, though, to handle guint8 arrays specially: "treat all arrays like this, *except* when their element type is guint8, in which case treat them like this instead".

Also, I worry about the inconsistency between this way of representing strings as byte arrays and the default way that an un-annotated gchar* argument is handled by gobject-introspection.  In particular, what about gtk_builder_add_from_string and gtk_ui_manager_add_ui_from_string?  They don't have an (array) annotation yet.

(In reply to comment #4)

> Supporting this case in the bindings has not occurred to me, and should indeed
> be doable.  It does feel strange, though, to handle guint8 arrays specially:
> "treat all arrays like this, *except* when their element type is guint8, in
> which case treat them like this instead".

Byte arrays really are a very common special case, and again for both Perl and Python, their "strings" really are byte arrays, so there should be an implicit conversion available on input.

What your return on output is more interesting; I'm not sure what pygobject returns by default at the moment.  Gjs has its own ByteArray type because it's just too inefficient to represent a binary array as either a JavaScript UCS-16 string or (even worse) an array of doubles.

> Also, I worry about the inconsistency between this way of representing strings
> as byte arrays and the default way that an un-annotated gchar* argument is
> handled by gobject-introspection.  In particular, what about
> gtk_builder_add_from_string and gtk_ui_manager_add_ui_from_string?  They don't
> have an (array) annotation yet.

In the current system, it will work for authors to pass -1.  While that's slightly lame, it's not really a serious problem.

But it is *really* important for APIs to be extremely clear about whether they accept UTF-8 or binary data.  For historical reasons not all APIs in GLib/GTK+ do this, but new ones should.

While we could add an annotation (array length=len) (element-type gchar) to the APIs you mentioned, this would actually break IABI because bindings would then expect the the length parameter to be omitted.  So we should probably just leave things as is.

OK, I handle this in the bindings now.