[Xcb] question about iterator/length generation

[Jamey Sharp]

Hi Thomas!

On Fri, May 11, 2007 at 08:18:35PM +0200, Thomas Hunger wrote:
> I have (hopefully) simple question which I cannot figure out: What are 
> the rules for generating iterator access and _length functions?

This ought to be answered here:
	http://xcb.freedesktop.org/wiki/ProtocolStubApi
but unfortunately I now see that documentation is not as useful as I
thought it was when I wrote it. sigh. Also it says obsolete things.

Each type declared with <struct> or <xidtype> has a corresponding
iterator type and functions for walking that iterator. For example:

	typedef struct xcb_screen_iterator_t {
		xcb_screen_t *data;
		int           rem;
		int           index;
	} xcb_screen_iterator_t;

	void
	xcb_screen_next (xcb_screen_iterator_t *i);

	xcb_generic_iterator_t
	xcb_screen_end (xcb_screen_iterator_t i);

Then, each <list> (whether in <struct> or <reply>) has functions to get
access to the list. A _length function is always present.

- If the list element type is variable-length (it contains lists with a
  non-constant number of elements) then an array accessor cannot be
  generated. 

- If the list element type was not declared with <struct> or <xidtype>,
  then an iterator accessor cannot be generated. This is for types like
  CARD8 that are built-in to the code generator.

These conditions are mutually exclusive, so at least one type of
accessor will be generated, and often both will.

For example, xcb_screen is variable-length, so xcb_setup generates these
functions:

	int
	xcb_setup_roots_length (const xcb_setup_t *R);

	xcb_screen_iterator_t
	xcb_setup_roots_iterator (const xcb_setup_t *R);

There's some rule for <list>s also generating _end functions sometimes,
but honestly I'm not quite sure what it is at the moment. Offhand it
looks like it happens for all but the last <list> in a <struct> or
<reply>. Also it looks like those should have been kept 'static'...

I hope that helps!
--Jamey
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20070512/5825ae5e/attachment.pgp