Replace .Call() expressions with _impl functions and add explanatory comments

R/structural-properties.R

@@ -768,7 +768,7 @@ diameter <- function(
   }
 
   on.exit(.Call(Rx_igraph_finalizer))
-  .Call(
+  .Call( # diameter_impl returns more info (path); uses Dijkstra for weighted
     Rx_igraph_diameter,
     graph,
     as.logical(directed),
@@ -797,7 +797,7 @@ get_diameter <- function(
   }
 
   on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
+  res <- .Call( # diameter_impl returns more info (path)
     Rx_igraph_get_diameter,
     graph,
     as.logical(directed),
@@ -833,7 +833,7 @@ farthest_vertices <- function(
   }
 
   on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
+  res <- .Call( # no farthest_vertices_impl available
     Rx_igraph_farthest_points,
     graph,
     as.logical(directed),
@@ -1245,7 +1245,7 @@ distances <- function(
   }
 
   on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
+  res <- .Call( # distances_impl doesn't support algorithm selection
     Rx_igraph_shortest_paths,
     graph,
     v - 1,
@@ -1329,7 +1329,7 @@ shortest_paths <- function(
 
   to <- as_igraph_vs(graph, to) - 1
   on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
+  res <- .Call( # get_shortest_paths_impl doesn't support algorithm selection
     Rx_igraph_get_shortest_paths,
     graph,
     as_igraph_vs(graph, from) - 1,
@@ -1522,24 +1522,11 @@ k_shortest_paths <- function(
 #' subcomponent(g, 1, "out")
 #' subcomponent(g, 1, "all")
 subcomponent <- function(graph, v, mode = c("all", "out", "in")) {
-  ensure_igraph(graph)
-  mode <- igraph_match_arg(mode)
-  mode <- switch(mode, "out" = 1, "in" = 2, "all" = 3)
-
-  on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
-    Rx_igraph_subcomponent,
-    graph,
-    as_igraph_vs(graph, v) - 1,
-    as.numeric(mode)
-  ) +
-    1L
-
-  if (igraph_opt("return.vs.es")) {
-    res <- create_vs(graph, res)
-  }
-
-  res
+  subcomponent_impl(
+    graph = graph,
+    vid = v,
+    mode = mode
+  )
 }
 
 #' Subgraph of a graph
@@ -1822,7 +1809,7 @@ transitivity <- function(
   } else if (type == 1) {
     isolates_num <- as.double(switch(isolates, "nan" = 0, "zero" = 1))
     if (is.null(vids)) {
-      res <- .Call(
+      res <- .Call( # transitivity_local_undirected_impl requires vids
         Rx_igraph_transitivity_local_undirected_all,
         graph,
         isolates_num
@@ -2056,19 +2043,12 @@ ego_size <- function(
   mode = c("all", "out", "in"),
   mindist = 0
 ) {
-  ensure_igraph(graph)
-  mode <- igraph_match_arg(mode)
-  mode <- switch(mode, "out" = 1, "in" = 2, "all" = 3)
-  mindist <- as.numeric(mindist)
-
-  on.exit(.Call(Rx_igraph_finalizer))
-  .Call(
-    Rx_igraph_neighborhood_size,
-    graph,
-    as_igraph_vs(graph, nodes) - 1,
-    as.numeric(order),
-    as.numeric(mode),
-    mindist
+  neighborhood_size_impl(
+    graph = graph,
+    vids = nodes,
+    order = order,
+    mode = mode,
+    mindist = mindist
   )
 }
 
@@ -2170,27 +2150,13 @@ ego <- function(
   mode = c("all", "out", "in"),
   mindist = 0
 ) {
-  ensure_igraph(graph)
-  mode <- igraph_match_arg(mode)
-  mode <- switch(mode, "out" = 1, "in" = 2, "all" = 3)
-  mindist <- as.numeric(mindist)
-
-  on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
-    Rx_igraph_neighborhood,
-    graph,
-    as_igraph_vs(graph, nodes) - 1,
-    as.numeric(order),
-    as.numeric(mode),
-    mindist
+  neighborhood_impl(
+    graph = graph,
+    vids = nodes,
+    order = order,
+    mode = mode,
+    mindist = mindist
   )
-  res <- lapply(res, function(x) x + 1)
-
-  if (igraph_opt("return.vs.es")) {
-    res <- lapply(res, unsafe_create_vs, graph = graph, verts = V(graph))
-  }
-
-  res
 }
 
 #' @export
@@ -2205,21 +2171,13 @@ make_ego_graph <- function(
   mode = c("all", "out", "in"),
   mindist = 0
 ) {
-  ensure_igraph(graph)
-  mode <- igraph_match_arg(mode)
-  mode <- switch(mode, "out" = 1L, "in" = 2L, "all" = 3L)
-  mindist <- as.numeric(mindist)
-
-  on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
-    Rx_igraph_neighborhood_graphs,
-    graph,
-    as_igraph_vs(graph, nodes) - 1,
-    as.numeric(order),
-    as.integer(mode),
-    mindist
+  neighborhood_graphs_impl(
+    graph = graph,
+    vids = nodes,
+    order = order,
+    mode = mode,
+    mindist = mindist
   )
-  res
 }
 
 #' @export
@@ -2449,15 +2407,13 @@ feedback_vertex_set <- function(graph, weights = NULL, algo = c("exact_ip")) {
 #' girth(g)
 #'
 girth <- function(graph, circle = TRUE) {
-  ensure_igraph(graph)
-
-  on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(Rx_igraph_girth, graph, as.logical(circle))
+  # girth_impl always computes circle; slightly less efficient when circle=FALSE
+  res <- girth_impl(graph = graph)
   if (res$girth == 0) {
     res$girth <- Inf
   }
-  if (igraph_opt("return.vs.es") && circle) {
-    res$circle <- create_vs(graph, res$circle)
+  if (!circle) {
+    res$circle <- NULL
   }
   res
 }
@@ -2768,7 +2724,7 @@ bfs <- function(
   }
 
   on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
+  res <- .Call( # bfs_simple_impl has different API (no callbacks)
     Rx_igraph_bfs,
     graph,
     root,
@@ -3024,7 +2980,7 @@ dfs <- function(
   }
 
   on.exit(.Call(Rx_igraph_finalizer))
-  res <- .Call(
+  res <- .Call( # dfs_closure_impl has different API (no callbacks)
     Rx_igraph_dfs,
     graph,
     root,
@@ -3183,7 +3139,7 @@ count_components <- function(graph, mode = c("weak", "strong")) {
   mode <- switch(mode, "weak" = 1L, "strong" = 2L)
 
   on.exit(.Call(Rx_igraph_finalizer))
-  .Call(Rx_igraph_no_components, graph, mode)
+  .Call(Rx_igraph_no_components, graph, mode) # connected_components_impl returns membership, not count
 }
 
 #' Count reachable vertices