From 4b0d8831c29fde017869ac7e77fdf7871bbc4b10 Mon Sep 17 00:00:00 2001 From: Adrien Destugues Date: Tue, 24 May 2022 09:06:36 +0200 Subject: [PATCH] HaikuBook: better doc and example for BList::DoForEach The description of the callback function was still quite confusing. The main usage for the return argument from the callback function is not handling failures, but knowing wether the function did something in the list or not, and stopping the iteration if only one item was looked for. Add an example use of the function return value to implement a linear search in the list and remove the note about the function "failing", which is not what this parameter was meant to do (and I think that lead to the initial inversion of "true" and "false" values. Change-Id: If8cae8b8ee21ced2c899aef6033a89ab8dbf1621 Reviewed-on: https://review.haiku-os.org/c/haiku/+/5339 Reviewed-by: waddlesplash Tested-by: Commit checker robot --- docs/user/support/List.dox | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/docs/user/support/List.dox b/docs/user/support/List.dox index b77642ce04..60397c0472 100644 --- a/docs/user/support/List.dox +++ b/docs/user/support/List.dox @@ -545,11 +545,11 @@ A C D E F G B H I J \fn void BList::DoForEach(bool (*func)(void* item)) \brief Perform an action on every item in the list. - If one of the actions on the items fails it means that the \a func function - returned \c true and the processing of the list will be stopped. + Iterates over all items in the list, and calls the \a func function on each of them, + until the function returns \c true. - \param func A pointer to a function that takes a \c void* argument and - returns a bool. + \param func A pointer to a function that takes a \c void* list item, and + returns a bool indicating if the iteration should stop. \see DoForEach(bool (*func)(void*, void*), void*) @@ -561,12 +561,29 @@ A C D E F G B H I J \fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void* arg2) \brief Perform an action on every item in the list with an argument. - If one of the actions on the items fails it means that the \a func function - returned \c true and the processing of the list will be stopped. + The iteration stops when the \a func function returns \c true. + This can be used to implement a linear search of the list, for example: + + \code{.cpp} + bool compareFunc(void* _item, void* arg2) { + Item* item = (Item*)_item; + Args* args = (Args*)arg2; + if (item->Matches(args->pattern)) { + args->result = item; + return true; + } + return false; + } + + Args args = {0}; + list.DoForEach(compareFunc, &args); + if (args->result != NULL) { + // Found it! + } + \endcode \param func A function with the first \c void* argument being the item - and the second \c void* being the argument that you supply. It - should return a boolean value on whether it succeeded or not. + and the second \c void* being the argument that you supply. \param arg2 An argument to supply to \a func. \see DoForEach(bool (*func)(void*))