[Xcb] about api changes

[Christoph Pfister]

2007/6/9, Thomas Hunger <hto at arcor.de>:
> > - For elements which occupy adjacent memory positions you have two
> > functions - for example "xcb_visualtype_t *xcb_depth_visuals(...)"
> > and "int xcb_depth_visuals_length(...)". To get to the next element
> > you simply increment the pointer.
>
> As you wrote the functions are:
>
>   xcb_visualtype_t *
>   xcb_depth_visuals (const xcb_depth_t *R);
>
> and
>
>   xcb_visualtype_iterator_t
>   xcb_depth_visuals_iterator (const xcb_depth_t *R);
>
> If I understand you correctly then you would remove the last function.

Yes, for this kind of list.

> The last function is needed internally though, so it cannot be
> removed but could be made private.

It's used internally - for the depth iterator (memory layout:
xcb_screen_t - depth[0] - visuals[variable size] - depth[1] -
visuals[variable size] etc). This could be simplified of course (to
jump from one depth to next you increment the pointer by
"sizeof(depth) + sizeof(visual) * number_of_visuals_for_this_depth"
bytes).

> I am not so sure anymore that this
> is sensible. First, if it is documented properly that there are two
> ways to access there should be no confusion.

There are in fact three ways with the current api:
a) get a pointer to the first element + advance yourself
b) get an iterater + advance yourself
c) get an iterator + use the _next() function

a + b are possible for the continuous lists (where elements occupy
adjacent memory positions); b + c are possible for the non-continuous
lists (but b is in this case _horribly_ wrong).

> Second, it makes the API more consistent. Every list with a type that
> has an iterator can be asked for that iterator.

An iterator is possible for every list. Just that there are two types
of lists so there are also different ways you have to treat an
iterator ...

> Removing the last function would remove that feature and the user would need to know if
> the type is memory-adjacent or not.

He has to know that _anyway_. If he doesn't care he may write garbage
(using possibilty b for non-continuous lists; this looks fine and
there's no simple way to detect this case - and guess it also takes
some annoying time till he finds out what he does wrongly).

> So I believe we should keep the current API.

Christoph