Re: Usability of GSequence API

[Soeren Sandmann <sandmann daimi au dk>]

Behdad Esfahbod <behdad behdad org> writes:

> The main issues I see with it are (other than just the large number of
> functions for something as simple as a sequence):
> 
>   - GSequenceIter is used both as a "node" reference and as an iterator.
> For example, the way to get/set the value of a node is to do that using
> an iterator pointing at the node.

The concept of "node" simply doesn't exist in the public API. The

   typedef struct GSequenceNode GSequenceIter;

should just be considered an implementation detail. We can change it
to "struct _GSequenceIter" and then have the c file do

struct _GSequenceIter
{
    GSequenceNode node;
};

and add the necessary casting, but I don't think that's really worth
the effort.

I'm not sure what you mean by "node", so below I'll assume you mean
"item" which is the thing a users inserts in the sequence and
generally in the implementation stored in a GSequenceNode (but they
are not the same thing; for example the end node does not store any
item).

>   - There are several methods that take a GSequenceIter but are not
> prefixed with g_sequence_iter.

The intention is that those methods correspond to an operation on the
sequence, whereas g_sequence_iter methods operate on the iterator
itself.

>   - Some methods names hardly suggest the semantics of the operation.
> For example:
> 
> void           g_sequence_move               (GSequenceIter            *src,
>                                               GSequenceIter            *dest);
> 
> What does it mean to move a iterator to another one?  It's still not
> clear even if you s/GSequenceIter/GSequenceNode/.

It moves the item pointed to by src to the position given by dest. I'd
agree that it's unclear that 'src' and 'dest' are not really equals
here, but I don't see any good alternative names.

>   - Unlike the common idiom, iterators are not allocated and freed.
> They are really just pointers to nodes.

That they are not allocated and freed is a feature, not a bug, and
there is prior art in GtkTreeIter and GtkTextIter, so that's far from
a common idiom. (The only place we have allocated iterators is in
Pango as far as I know).

And no, they are really iterators, not pointers to items. If they were
pointers you would always be able to dereference them, but you can't
dereference the end iterator. Even an empty sequence has an iterator. 

> Note that I did not read the docs, just the header, and did that on
> purpose.

I have attempted to explain the concepts in the overview section of
the docs. Once someone understands those I think the function names in
the header file will make more sense.

> I totally agree that we need a higher level datastructure than GList in
> glib.  Just that the GSequence API is too different from other glib
> datastructures that I know that is confusing to me.

Well, I am open to suggestions, but keep in mind that an important
usecase is being able to implement GtkTreeModel and in particular
GtkListStore.


Soren