R: Find positions of elements in an Rd object

Rdo_locate {Rdpack} | R Documentation

## Find positions of elements in an Rd object

### Description

Find positions of elements for which a function returns TRUE. Optionally, apply another function to the selected elements and return the results along with the positions.

### Usage

    Rdo_locate(object, f = function(x) TRUE, pos_only = TRUE,
               lists = FALSE, fpos = NULL, nested = TRUE)

### Arguments

`object` | an Rd object
`f` | a function returning TRUE if an element is desired and FALSE otherwise.
`pos_only` | if TRUE, return only the positions; if this argument is a function, return also the result of applying the function to the selected element, see Details.
`lists` | if FALSE, examine only leaves, if TRUE, examine also lists, see Details.
`fpos` | a function with two arguments, `object` and position, it is called and the value is returned along with the position, see Details.
`nested` | a logical value, it has effect only when `lists` is TRUE, see ‘Details’.

### Details

With the default setting of `lists = FALSE`, the function `f` is applied to each leave (a character string) of the Rd object. If `lists = TRUE` the function `f` is applied also to each branch (a list). In this case, argument `nested` controls what happens when `f` returns TRUE. If `nested` is TRUE, each element of the list is also inspected recursively, otherwise this is not done and, effectively, the list is considered a leaf. If `f` does not return TRUE, the value of `nested` has no effect and the elements of the list are inspected.

The position of each object for which `f` returns TRUE is recorded as a numeric vector.

`fpos` and `pos_only` provide two ways to do something with the selected elements. Argument `fpos` is more powerful than `pos_only` but the latter should be sufficient and simpler to use in most cases.

If `fpos` is a function, it is applied to each selected element with two arguments, `object` and the position, and the result returned along with the position. In this case argument `pos_only` is ignored. If `fpos` is NULL the action depends on `pos_only`.

If `pos_only = TRUE`, `Rdo_locate` returns a list of such vectors (not a matrix since the positions of the leaves are, in general, at different depths).

If `pos_only` is a function, it is applied to each selected element and the result returned along with the position.

### Value

a list with one entry for each selected element. Each entry is a numeric vector or a list with two elements:

`pos` | the position, a vector of positive integers,
`value` | the result of applying the function to the element at `pos`.

### Note

The following needs additional thought.

In some circumstances an empty list, tagged with `Rd_tag` may turn up, e.g. `list()` with `Rd_tag="\dots"` in an `\arguments` section.

On the one hand this is a list. On the other hand it may be considered a leaf. It is not clear if any attempt to recurse into such a list should be made at all.

### Author(s)

Georgi N. Boshnakov

### See Also

`Rdo_sections` and `Rdo_locate_core_section` which locate top level sections

### Examples

    # todo: put examples here!

[Package Rdpack version 0.10-1 Index]