Re: gtk_label_get_text() string duping

[Darin Adler <darin eazel com>]

I decided I should contribute a little to this discussion (Maciej urged me
to), but I wanted to contribute more than just my opinion. So here is a
quick recent war story:

    The gnome_vfs_uri_get_basename function returned a pointer to a string.
This was possible because the basename happened to be at the end of the URI
string. For efficiency, it just returned a pointer to that. Then we
discovered that this was not the desired behavior of basename for URIs that
end in "/". But we could not change what basename did without changing the
interface. We had coded into the API the fact that the format we stored a
URI in included the basename. After reading all the client code, we found
that every caller (about 10 different places, maybe 20) would have been
happy with our new "correct" basename, and we wanted to change the behavior
without changing the function otherwise, but we couldn't without adding a
second copy of the string that we could return for this case. Exposing the
way a URI was stored in the class by exposing the fact that you can return
an internal string caused trouble when we wanted to fix the bug.

Calling the thing "dup" is kind of silly. If the thing returned is really
just a "dup", then the "dup" call shouldn't exist. If the thing is computed
then I think "dup" is a strange way to say that.

One reason a call that returns a copy is safer than a peek-tpye call is that
a peek-type call needs to document how long the returned value is good. This
is simple for a "get widget" call, where the widget's lifetime is tied to
the lifetime of the object you get it from. But for string calls it can be
subtle. An example of this is old version of gtk_entry_get_text in the gnome
1.2 branch which has to manage a special variable for the returned text. How
long is the text returned good for? In practice it can be a real bug if
someone tries to use this returned text as a key for a hash table, for
example. The caller knows that you don't need to free the text but doesn't
know what its lifetime is.

For the simplest code the "peek"-type calls are way handier, but they are
poorer at encapsulation, which is why I prefer "get" to be the default and
have the most straightforward name.

    -- Darin