[WIP] Fix functions ignoring return.vs.es option

[Copilot]

Fix return.vs.es option handling in multiple functions

This PR fixes several functions that ignore the return.vs.es option and always return igraph.vs or igraph.es objects even when return.vs.es = FALSE.

Plan

• Analyze the issue and understand the pattern used in other functions
• Fix head_of() to respect return.vs.es option
• Fix tail_of() to respect return.vs.es option
• Fix as_adj_edge_list() to respect return.vs.es option
• Fix graph.get.isomorphisms.vf2() to respect return.vs.es option
• Fix graph.get.subisomorphisms.vf2() to respect return.vs.es option
• Fix graph.subisomorphic.lad() to respect return.vs.es option
• Update documentation for all fixed functions
• Add tests for the fixed functions
• Run tests to ensure no regressions

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Some functions that return vertex or edge sequences ignore the value of the option return.vs.es</issue_title>
<issue_description>### What happens, and what did you expect instead?

Several function that return vertex or edge sequences ignore the value of the option return.vs.es and return igraph.vs or igraph.es objects even if return.vs.es = FALSE. A few examples are demonstrated below.

I used two regex pattern to search of code that converts numeric indices to igraph.vs or igraph.es objects, respectively:

• "create_(v|e)s" finds uses of create_vs() and create_es() (also when they are used inside lapply() etc.).
• "(E|V)\([^)]\)\[" finds constructs of the form E(graph)[i + 1]

Most uses of those patterns are already combined with a check for the value of return.vs.es, but there are a few exceptions:

• head_of()
• tail_of()
• as_adj_edge_list()
• graph.get.isomorphisms.vf2()
• graph.get.subisomorphisms.vf2()
• graph.subisomorphic.lad()

I would expect that these functions return (lists of) numeric indices if return.vs.es = FALSE.

To reproduce

library(igraph)
#> 
#> Attaching package: 'igraph'
#> The following objects are masked from 'package:stats':
#> 
#>     decompose, spectrum
#> The following object is masked from 'package:base':
#> 
#>     union

g <- make_tree(6, children = 2)
V(g)$name <- paste0("V", 1:6)

# make sure the option is set to the default
igraph_options(return.vs.es = TRUE)

# in this case, all results are as expected
head_of(g, E(g)[c(1, 4)])
#> + 2/6 vertices, named, from d6aad98:
#> [1] V2 V5
tail_of(g, E(g)[c(1, 4)])
#> + 2/6 vertices, named, from d6aad98:
#> [1] V1 V2
as_adj_edge_list(g)[1]
#> $V1
#> + 2/5 edges from d6aad98 (vertex names):
#> [1] V1->V2 V1->V3
graph.get.isomorphisms.vf2(g, g)[1]
#> [[1]]
#> + 6/6 vertices, named, from d6aad98:
#> [1] V1 V2 V3 V4 V5 V6
graph.get.subisomorphisms.vf2(g, g)[1]
#> [[1]]
#> + 6/6 vertices, named, from d6aad98:
#> [1] V1 V2 V3 V4 V5 V6
graph.subisomorphic.lad(g, g, all.maps = TRUE)$maps[1]
#> [[1]]
#> + 6/6 vertices, named, from d6aad98:
#> [1] V1 V2 V3 V4 V5 V6

# changing the option does not affect the results
igraph_options(return.vs.es = FALSE)

head_of(g, E(g)[c(1, 4)])
#> + 2/6 vertices, named, from d6aad98:
#> [1] V2 V5
tail_of(g, E(g)[c(1, 4)])
#> + 2/6 vertices, named, from d6aad98:
#> [1] V1 V2
as_adj_edge_list(g)[1]
#> $V1
#> + 2/5 edges from d6aad98 (vertex names):
#> [1] V1->V2 V1->V3
graph.get.isomorphisms.vf2(g, g)[1]
#> [[1]]
#> + 6/6 vertices, named, from d6aad98:
#> [1] V1 V2 V3 V4 V5 V6
graph.get.subisomorphisms.vf2(g, g)[1]
#> [[1]]
#> + 6/6 vertices, named, from d6aad98:
#> [1] V1 V2 V3 V4 V5 V6
graph.subisomorphic.lad(g, g, all.maps = TRUE)$maps[1]
#> [[1]]
#> + 6/6 vertices, named, from d6aad98:
#> [1] V1 V2 V3 V4 V5 V6

^{Created on 2024-12-02 with reprex v2.1.1}

System information

R version 4.4.2 (2024-10-31)
Platform: x86_64-pc-linux-gnu
Running under: Ubuntu 24.04.1 LTS

Matrix products: default
BLAS: /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.12.0
LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0

locale:
[1] LC_CTYPE=en_GB.UTF-8 LC_NUMERIC=C LC_TIME=de_CH.UTF-8
[4] LC_COLLATE=en_GB.UTF-8 LC_MONETARY=de_CH.UTF-8 LC_MESSAGES=en_GB.UTF-8
[7] LC_PAPER=de_CH.UTF-8 LC_NAME=C LC_ADDRESS=C
[10] LC_TELEPHONE=C LC_MEASUREMENT=de_CH.UTF-8 LC_IDENTIFICATION=C

time zone: Europe/Zurich
tzcode source: system (glibc)

attached base packages:
[1] stats graphics grDevices utils datasets methods base

other attached packages:
[1] igraph_2.1.2

loaded via a namespace (and not attached):
[1] compiler_4.4.2 magrittr_2.0.3 cli_3.6.3 tools_4.4.2 rstudioapi_0.17.1
[6] lifecycle_1.0.4 pkgconfig_2.0.3 rlang_1.1.4</issue_description>

Comments on the Issue (you are @copilot in this section)

@maelle Thank you @stibu81 for the report!

@szhorvat any opinion?</comment_new>
<comment_new>@szhorvat

@szhorvat any opinion?

I agree with the principle of updating these functions to respect return.vs.es, but keep in mind that I rarely use R so there might be problematic consequences I am not thinking of.

I'd give these three an extra careful look:

• head_of()

• tail_of()

• as_adj_edge_list()

I think this is ultimately an R programming / API decision that should be made by you and @krlmlr.

@krlmlr Agree that we want to be consistent here, but `return.vs.es` is something we may want to get rid of in the medium term. ...

• Fixes Some functions that return vertex or edge sequences ignore the value of the option return.vs.es #1614

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.