From cc98be4d232323ccb989a9792f3382df366535fe Mon Sep 17 00:00:00 2001 From: Nev3r Date: Sat, 14 Nov 2020 20:25:00 +0100 Subject: [PATCH] Add documentation for the iterator macros. --- src/taglist.h | 66 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 6 deletions(-) diff --git a/src/taglist.h b/src/taglist.h index 3a724aef3..a1dfe479e 100644 --- a/src/taglist.h +++ b/src/taglist.h @@ -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__