feat: Autogenerate BFS and DFS callback closures with unified TRUE=stop convention

R/cliques.R

@@ -204,8 +204,8 @@ clique.number <- function(graph) {
 #' @param ... These dots are for future extensions and must be empty.
 #' @param callback Optional function to call for each clique found. If provided,
 #'   the function should accept one argument: `clique` (integer vector of vertex
-#'   IDs in the clique, 1-based indexing). The function should return `TRUE` to
-#'   continue the search or `FALSE` to stop it. If `NULL` (the default), all
+#'   IDs in the clique, 1-based indexing). The function should return `FALSE` to
+#'   continue the search or `TRUE` to stop it. If `NULL` (the default), all
 #'   cliques are collected and returned as a list.
 #'
 #'   **Important limitation:** Callback functions must NOT call any igraph

R/cycles.R

@@ -77,8 +77,8 @@ find_cycle <- function(graph, mode = c("out", "in", "all", "total")) {
 #' @param callback Optional function to call for each cycle found. If provided,
 #'   the function should accept two arguments: `vertices` (integer vector of vertex
 #'   IDs in the cycle) and `edges` (integer vector of edge IDs
-#'   in the cycle). The function should return `TRUE` to continue
-#'   the search or `FALSE` to stop it. If `NULL` (the default), all cycles are
+#'   in the cycle). The function should return `FALSE` to continue
+#'   the search or `TRUE` to stop it. If `NULL` (the default), all cycles are
 #'   collected and returned as a list.
 #'
 #'   **Important limitation:** Callback functions must NOT call any igraph
@@ -103,8 +103,8 @@ find_cycle <- function(graph, mode = c("out", "in", "all", "total")) {
 #' @param callback Optional function to call for each cycle found. If provided,
 #'   the function should accept two arguments: `vertices` (integer vector of vertex
 #'   IDs in the cycle) and `edges` (integer vector of edge IDs
-#'   in the cycle). The function should return `TRUE` to continue
-#'   the search or `FALSE` to stop it. If `NULL` (the default), all cycles are
+#'   in the cycle). The function should return `FALSE` to continue
+#'   the search or `TRUE` to stop it. If `NULL` (the default), all cycles are
 #'   collected and returned as a list.
 #'
 #'   **Important limitation:** Callback functions must NOT call any igraph

R/motifs.R

@@ -139,7 +139,7 @@ dyad.census <- function(graph) {
 #' @param callback Optional callback function to call for each motif found.
 #'   The function should accept two arguments: `vids` (integer vector of vertex IDs
 #'   in the motif) and `isoclass` (the isomorphism class of the motif).
-#'   The function should return `TRUE` to continue the search or `FALSE` to stop it.
+#'   The function should return `FALSE` to continue the search or `TRUE` to stop it.
 #'   If `NULL` (the default), motif counts are returned as a numeric vector.
 #'
 #'   **Important limitation:** Callback functions must NOT call any igraph

R/structural-properties.R

@@ -2633,7 +2633,8 @@ count_loops <- function(graph) {
 #' @param dist Logical scalar, whether to return the distance from the root of
 #'   the search tree.
 #' @param callback If not `NULL`, then it must be callback function. This
-#'   is called whenever a vertex is visited. See details below.
+#'   is called whenever a vertex is visited. The callback function should
+#'   return `FALSE` to continue the search or `TRUE` to stop it. See details below.
 #' @param extra Additional argument to supply to the callback function.
 #' @param rho The environment in which the callback function is evaluated.
 #' @param neimode `r lifecycle::badge("deprecated")` This argument is deprecated

R/topology.R

@@ -770,7 +770,7 @@ graph.count.subisomorphisms.vf2 <- function(
 #'   If provided, the function should accept two arguments: `map12` (integer vector
 #'   mapping vertex IDs from graph1 to graph2, 1-based indexing) and `map21`
 #'   (integer vector mapping vertex IDs from graph2 to graph1, 1-based indexing).
-#'   The function should return `TRUE` to continue the search or `FALSE` to stop it.
+#'   The function should return `FALSE` to continue the search or `TRUE` to stop it.
 #'   If `NULL` (the default), all isomorphisms are collected and returned as a list.
 #'   Only supported for `method = "vf2"`.
 #'
@@ -895,7 +895,7 @@ isomorphisms <- function(graph1, graph2, method = "vf2", ..., callback = NULL) {
 #'   If provided, the function should accept two arguments: `map12` (integer vector
 #'   mapping vertex IDs from pattern to target, 1-based indexing) and `map21`
 #'   (integer vector mapping vertex IDs from target to pattern, 1-based indexing).
-#'   The function should return `TRUE` to continue the search or `FALSE` to stop it.
+#'   The function should return `FALSE` to continue the search or `TRUE` to stop it.
 #'   If `NULL` (the default), all subisomorphisms are collected and returned as a list.
 #'   Only supported for `method = "vf2"`.
 #'

src/cpp11.cpp

@@ -52,6 +52,7 @@ extern SEXP R_igraph_barabasi_game(SEXP, SEXP, SEXP, SEXP, SEXP, SEXP, SEXP, SEX
 extern SEXP R_igraph_betweenness(SEXP, SEXP, SEXP, SEXP);
 extern SEXP R_igraph_betweenness_cutoff(SEXP, SEXP, SEXP, SEXP, SEXP);
 extern SEXP R_igraph_betweenness_subset(SEXP, SEXP, SEXP, SEXP, SEXP, SEXP);
+extern SEXP R_igraph_bfs_closure(SEXP, SEXP, SEXP, SEXP, SEXP, SEXP, SEXP);
 extern SEXP R_igraph_bfs_simple(SEXP, SEXP, SEXP);
 extern SEXP R_igraph_biadjacency(SEXP, SEXP, SEXP, SEXP);
 extern SEXP R_igraph_bibcoupling(SEXP, SEXP);
@@ -137,6 +138,7 @@ extern SEXP R_igraph_delete_vertices(SEXP, SEXP);
 extern SEXP R_igraph_delete_vertices_idx(SEXP, SEXP);
 extern SEXP R_igraph_density(SEXP, SEXP);
 extern SEXP R_igraph_deterministic_optimal_imitation(SEXP, SEXP, SEXP, SEXP, SEXP, SEXP);
+extern SEXP R_igraph_dfs_closure(SEXP, SEXP, SEXP, SEXP, SEXP, SEXP);
 extern SEXP R_igraph_diameter(SEXP, SEXP, SEXP);
 extern SEXP R_igraph_diameter_dijkstra(SEXP, SEXP, SEXP, SEXP);
 extern SEXP R_igraph_difference(SEXP, SEXP);
@@ -657,6 +659,7 @@ static const R_CallMethodDef CallEntries[] = {
     {"R_igraph_betweenness",                                    (DL_FUNC) &R_igraph_betweenness,                                     4},
     {"R_igraph_betweenness_cutoff",                             (DL_FUNC) &R_igraph_betweenness_cutoff,                              5},
     {"R_igraph_betweenness_subset",                             (DL_FUNC) &R_igraph_betweenness_subset,                              6},
+    {"R_igraph_bfs_closure",                                    (DL_FUNC) &R_igraph_bfs_closure,                                     7},
     {"R_igraph_bfs_simple",                                     (DL_FUNC) &R_igraph_bfs_simple,                                      3},
     {"R_igraph_biadjacency",                                    (DL_FUNC) &R_igraph_biadjacency,                                     4},
     {"R_igraph_bibcoupling",                                    (DL_FUNC) &R_igraph_bibcoupling,                                     2},
@@ -742,6 +745,7 @@ static const R_CallMethodDef CallEntries[] = {
     {"R_igraph_delete_vertices_idx",                            (DL_FUNC) &R_igraph_delete_vertices_idx,                             2},
     {"R_igraph_density",                                        (DL_FUNC) &R_igraph_density,                                         2},
     {"R_igraph_deterministic_optimal_imitation",                (DL_FUNC) &R_igraph_deterministic_optimal_imitation,                 6},
+    {"R_igraph_dfs_closure",                                    (DL_FUNC) &R_igraph_dfs_closure,                                     6},
     {"R_igraph_diameter",                                       (DL_FUNC) &R_igraph_diameter,                                        3},
     {"R_igraph_diameter_dijkstra",                              (DL_FUNC) &R_igraph_diameter_dijkstra,                               4},
     {"R_igraph_difference",                                     (DL_FUNC) &R_igraph_difference,                                      2},