From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 869526DE02C3 for ; Sat, 3 Sep 2016 05:50:19 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org X-Spam-Flag: NO X-Spam-Score: -0.007 X-Spam-Level: X-Spam-Status: No, score=-0.007 tagged_above=-999 required=5 tests=[AWL=0.004, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01] autolearn=disabled Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id lTcH1yvoX6TN for ; Sat, 3 Sep 2016 05:50:19 -0700 (PDT) Received: from fethera.tethera.net (fethera.tethera.net [198.245.60.197]) by arlo.cworth.org (Postfix) with ESMTPS id D30886DE0243 for ; Sat, 3 Sep 2016 05:50:18 -0700 (PDT) Received: from remotemail by fethera.tethera.net with local (Exim 4.84_2) (envelope-from ) id 1bgAOg-0006SZ-T4; Sat, 03 Sep 2016 08:50:10 -0400 Received: (nullmailer pid 4746 invoked by uid 1000); Sat, 03 Sep 2016 12:50:13 -0000 From: David Bremner To: David Bremner , Franz Fellner , Lucas Hoffmann , notmuch@notmuchmail.org Subject: [PATCH] lib doc: group query functions, add disclaimer Date: Sat, 3 Sep 2016 09:50:08 -0300 Message-Id: <20160903125008.4704-1-david@tethera.net> X-Mailer: git-send-email 2.9.3 In-Reply-To: <87a8fsl8qs.fsf@zancas.localnet> References: <87a8fsl8qs.fsf@zancas.localnet> X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 03 Sep 2016 12:50:19 -0000 The destructiveness is somewhat surprising, so emphasize it with an extra remark in the docs. --- lib/notmuch.h | 144 +++++++++++++++++++++++++++++++--------------------------- 1 file changed, 78 insertions(+), 66 deletions(-) diff --git a/lib/notmuch.h b/lib/notmuch.h index 2faa146..954060d 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -686,6 +686,70 @@ notmuch_tags_t * notmuch_database_get_all_tags (notmuch_database_t *db); /** + * Is the given 'threads' iterator pointing at a valid thread. + * + * When this function returns TRUE, notmuch_threads_get will return a + * valid object. Whereas when this function returns FALSE, + * notmuch_threads_get will return NULL. + * + * If passed a NULL pointer, this function returns FALSE + * + * See the documentation of notmuch_query_search_threads for example + * code showing how to iterate over a notmuch_threads_t object. + */ +notmuch_bool_t +notmuch_threads_valid (notmuch_threads_t *threads); + +/** + * Get the current thread from 'threads' as a notmuch_thread_t. + * + * Note: The returned thread belongs to 'threads' and has a lifetime + * identical to it (and the query to which it belongs). + * + * See the documentation of notmuch_query_search_threads for example + * code showing how to iterate over a notmuch_threads_t object. + * + * If an out-of-memory situation occurs, this function will return + * NULL. + */ +notmuch_thread_t * +notmuch_threads_get (notmuch_threads_t *threads); + +/** + * Move the 'threads' iterator to the next thread. + * + * If 'threads' is already pointing at the last thread then the + * iterator will be moved to a point just beyond that last thread, + * (where notmuch_threads_valid will return FALSE and + * notmuch_threads_get will return NULL). + * + * See the documentation of notmuch_query_search_threads for example + * code showing how to iterate over a notmuch_threads_t object. + */ +void +notmuch_threads_move_to_next (notmuch_threads_t *threads); + +/** + * Destroy a notmuch_threads_t object. + * + * It's not strictly necessary to call this function. All memory from + * the notmuch_threads_t object will be reclaimed when the + * containing query object is destroyed. + */ +void +notmuch_threads_destroy (notmuch_threads_t *threads); + +/** + * @name Queries + * + * @remark The caller should assume that any notmuch_query_* function + * without an appropriate const declaration is destructive in its + * query argument. In particular calling + * notmuch_query_{count,search}_* on the same query may lead to + * surprising results. + */ +/**@{*/ +/** * Create a new query for 'database'. * * Here, 'database' should be an open database, (see @@ -736,6 +800,19 @@ typedef enum { NOTMUCH_SORT_UNSORTED } notmuch_sort_t; + +/** + * Destroy a notmuch_query_t along with any associated resources. + * + * This will in turn destroy any notmuch_threads_t and + * notmuch_messages_t objects generated by this query, (and in + * turn any notmuch_thread_t and notmuch_message_t objects generated + * from those results, etc.), if such objects haven't already been + * destroyed. + */ +void +notmuch_query_destroy (notmuch_query_t *query); + /** * Return the query_string of this query. See notmuch_query_create. */ @@ -927,72 +1004,6 @@ notmuch_messages_t * notmuch_query_search_messages (notmuch_query_t *query); /** - * Destroy a notmuch_query_t along with any associated resources. - * - * This will in turn destroy any notmuch_threads_t and - * notmuch_messages_t objects generated by this query, (and in - * turn any notmuch_thread_t and notmuch_message_t objects generated - * from those results, etc.), if such objects haven't already been - * destroyed. - */ -void -notmuch_query_destroy (notmuch_query_t *query); - -/** - * Is the given 'threads' iterator pointing at a valid thread. - * - * When this function returns TRUE, notmuch_threads_get will return a - * valid object. Whereas when this function returns FALSE, - * notmuch_threads_get will return NULL. - * - * If passed a NULL pointer, this function returns FALSE - * - * See the documentation of notmuch_query_search_threads for example - * code showing how to iterate over a notmuch_threads_t object. - */ -notmuch_bool_t -notmuch_threads_valid (notmuch_threads_t *threads); - -/** - * Get the current thread from 'threads' as a notmuch_thread_t. - * - * Note: The returned thread belongs to 'threads' and has a lifetime - * identical to it (and the query to which it belongs). - * - * See the documentation of notmuch_query_search_threads for example - * code showing how to iterate over a notmuch_threads_t object. - * - * If an out-of-memory situation occurs, this function will return - * NULL. - */ -notmuch_thread_t * -notmuch_threads_get (notmuch_threads_t *threads); - -/** - * Move the 'threads' iterator to the next thread. - * - * If 'threads' is already pointing at the last thread then the - * iterator will be moved to a point just beyond that last thread, - * (where notmuch_threads_valid will return FALSE and - * notmuch_threads_get will return NULL). - * - * See the documentation of notmuch_query_search_threads for example - * code showing how to iterate over a notmuch_threads_t object. - */ -void -notmuch_threads_move_to_next (notmuch_threads_t *threads); - -/** - * Destroy a notmuch_threads_t object. - * - * It's not strictly necessary to call this function. All memory from - * the notmuch_threads_t object will be reclaimed when the - * containing query object is destroyed. - */ -void -notmuch_threads_destroy (notmuch_threads_t *threads); - -/** * Return the number of messages matching a search. * * This function performs a search and returns the number of matching @@ -1059,6 +1070,7 @@ NOTMUCH_DEPRECATED(4,3) unsigned int notmuch_query_count_threads (notmuch_query_t *query); +/**@}*/ /** * Get the thread ID of 'thread'. * -- 2.9.3