Add documentation for the iterator macros.

This commit is contained in:
Nev3r 2020-11-14 20:25:00 +01:00
parent 072e1889e2
commit cc98be4d23

View file

@ -61,14 +61,68 @@ INT32 Tag_Iterate_Things (const mtag_t tag, const size_t p);
INT32 Tag_FindLineSpecial(const INT16 special, const mtag_t tag);
INT32 P_FindSpecialLineFromTag(INT16 special, INT16 tag, INT32 start);
// Use this macro to declare the iterator position variable.
// Use this macro to declare an iterator position variable.
#define TAG_ITER_DECLARECOUNTER(level) size_t ICNT_##level
#define TAG_ITER(level, fn, tag, id) for(ICNT_##level = 0; (id = fn(tag, ICNT_##level)) >= 0; ICNT_##level++)
#define TAG_ITER(level, fn, tag, return_varname) for(ICNT_##level = 0; (return_varname = fn(tag, ICNT_##level)) >= 0; ICNT_##level++)
// Use these macros as wrappers for the taglist iterations.
#define TAG_ITER_SECTORS(level, tag, id) TAG_ITER(level, Tag_Iterate_Sectors, tag, id)
#define TAG_ITER_LINES(level, tag, id) TAG_ITER(level, Tag_Iterate_Lines, tag, id)
#define TAG_ITER_THINGS(level, tag, id) TAG_ITER(level, Tag_Iterate_Things, tag, id)
// Use these macros as wrappers for a taglist iteration.
#define TAG_ITER_SECTORS(level, tag, return_varname) TAG_ITER(level, Tag_Iterate_Sectors, tag, return_varname)
#define TAG_ITER_LINES(level, tag, return_varname) TAG_ITER(level, Tag_Iterate_Lines, tag, return_varname)
#define TAG_ITER_THINGS(level, tag, return_varname) TAG_ITER(level, Tag_Iterate_Things, tag, return_varname)
/* ITERATION MACROS
TAG_ITER_DECLARECOUNTER must be used before using the iterators.
'level':
For each nested iteration, an additional TAG_ITER_DECLARECOUNTER
must be used with a different level number to avoid conflict with
the outer iterations.
Most cases don't have nested iterations and thus the level is just 0.
'tag':
Pretty much the elements' tag to iterate through.
'return_varname':
Target variable's name to return the iteration results to.
EXAMPLE:
{
TAG_ITER_DECLARECOUNTER(0);
TAG_ITER_DECLARECOUNTER(1); // For the nested iteration.
size_t li;
size_t sec;
INT32 tag1 = 4;
...
TAG_ITER_LINES(0, tag1, li)
{
line_t *line = lines + li;
...
if (something)
{
mtag_t tag2 = 8;
// Nested iteration; just make sure the level is higher
// and that it has its own counter declared in scope.
TAG_ITER_SECTORS(1, tag2, sec)
{
sector_t *sector = sectors + sec;
...
}
}
}
}
Notes:
If no elements are found for a given tag, the loop inside won't be executed.
*/
#endif //__R_TAGLIST__