R: Search for matches to a regular expression

ore_search {ore} | R Documentation

## Search for matches to a regular expression

### Description

Search a character vector for one or more matches to an Oniguruma-compatible regular expression. The result is of class `"orematches"`, for which printing and indexing methods are available.

### Usage

    ore_search(regex, text, all = FALSE, start = 1L, simplify = TRUE,
      incremental = !all)

    is_orematch(x)

    ## S3 method for class 'orematch'
    x[j, k, ...]

    ## S3 method for class 'orematches'
    x[i, j, k, ...]

    ## S3 method for class 'orematch'
    print(x, lines = getOption("ore.lines", 0L),
      context = getOption("ore.context", 30L), width = getOption("width", 80L),
      ...)

    ## S3 method for class 'orematches'
    print(x, lines = getOption("ore.lines", 0L), simplify = TRUE, ...)

### Arguments

`regex` | A single character string or object of class `"ore"`. In the former case, this will first be passed through `ore`.
`text` | A vector of strings to match against, or the result of a call to `ore_file` to search in a file. In the latter case, match offsets will be relative to the file's encoding.
`all` | If `TRUE`, then all matches within each element of `text` will be found. Otherwise, the search will stop at the first match.
`start` | An optional vector of offsets (in characters) at which to start searching. Will be recycled to the length of `text`.
`simplify` | If `TRUE`, an object of class `"orematch"` will be returned if `text` is of length 1. Otherwise, a list of such objects, with class `"orematches"`, will always be returned. When printing `"orematches"` objects, this controls whether or not to omit nonmatching elements from the output.
`incremental` | If `TRUE` and the `text` argument points to a file, the file is read in increasingly large blocks. This can reduce search time in large files.
`x` | An R object.
`j` | For indexing, the match number.
`k` | For indexing, the group number.
`...` | Ignored.
`i` | For indexing into an `"orematches"` object only, the string number.
`lines` | The maximum number of lines to print. The default is zero, meaning no limit. For `"orematches"` objects this is split evenly between the elements printed.
`context` | The number of characters of context to include either side of each match.
`width` | The number of characters in each line of printed output.

### Value

For `ore_search`, an `"orematch"` object, or a list of the same, each with elements

text

  A copy of the `text` element for the current match.

nMatches

  The number of matches found.

offsets

  The offsets (in characters) of each match.

byteOffsets

  The offsets (in bytes) of each match.

lengths

  The lengths (in characters) of each match.

byteLengths

  The lengths (in bytes) of each match.

matches

  The matched substrings.

groups

  Equivalent metadata for each parenthesised subgroup in `regex`, in a series of matrices. If named groups are present in the regex then `dimnames` will be set appropriately.

For `is_orematch`, a logical vector indicating whether the specified object has class `"orematch"`. For extraction with one index, a vector of matched substrings. For extraction with two indices, a vector or matrix of substrings corresponding to captured groups.

### Note

Only named *or* unnamed groups will currently be captured, not both. If there are named groups in the pattern, then unnamed groups will be ignored.

By default the `print` method uses the `crayon` package (if it is available) to determine whether or not the R terminal supports colour. Alternatively, colour printing may be forced or disabled by setting the `"ore.colour"` (or `"ore.color"`) option to a logical value.

### See Also

`ore` for creating regex objects; `matches` and `groups` for an alternative to indexing for extracting matching substrings.

### Examples

    # Pick out pairs of consecutive word characters
    match <- ore_search("(\\w)(\\w)", "This is a test", all=TRUE)

    # Find the second matched substring ("is", from "This")
    match[2]

    # Find the content of the second group in the second match ("s")
    match[2,2]

[Package ore version 1.7.0 Index]