Package {ahocorasick}

Build an Aho-Corasick automaton

Description

ac_build() compiles a character vector of patterns into a reusable automaton backed by the Rust aho-corasick crate.

Usage

ac_build(
  patterns,
  match_kind = c("standard", "leftmost_first", "leftmost_longest"),
  implementation = c("auto", "noncontiguous_nfa", "contiguous_nfa", "dfa"),
  ascii_case_insensitive = FALSE,
  duplicate = c("keep", "error", "deduplicate")
)

Arguments

Value

An immutable ⁠<ac_automaton>⁠ object.

See Also

ac_locate(), ac_locate_df(), ac_detect(), ac_count(), ac_extract(), ac_extract_df(), ac_replace(), ac_patterns().

Examples

ac <- ac_build(c("hello", "world"))
length(ac)
ac_info(ac)

Count pattern matches in documents

Description

ac_count() returns the number of pattern matches in each document.

Usage

ac_count(ac, doc, overlapping = FALSE, na = c("keep", "zero", "error"))

Arguments

Value

An integer vector with the same length as doc.

See Also

ac_count_file(), ac_detect(), ac_locate(), ac_extract().

Examples

if (requireNamespace("dplyr", quietly = TRUE)) {
  ac <- ac_build(c("hello", "world"))
  docs <- data.frame(doc = c("hello world", "nothing", "world"))
  dplyr::mutate(docs, n_matches = ac_count(ac, doc))
}

Count pattern matches in files

Description

ac_count_file() returns the number of pattern matches in each file.

Usage

ac_count_file(ac, path, stream = FALSE, overlapping = FALSE)

Arguments

Value

An integer vector with the same length as path.

See Also

ac_count(), ac_detect_file(), ac_locate_bytes().

Examples

ac <- ac_build(c("hello", "world"))
path <- tempfile()
writeLines("hello hello world", path)
ac_count_file(ac, path)

Detect pattern matches in documents

Description

ac_detect() returns whether each document has at least one pattern match.

Usage

ac_detect(ac, doc, na = c("keep", "false", "error"))

Arguments

Value

A logical vector with the same length as doc.

See Also

ac_detect_file(), ac_count(), ac_locate(), ac_extract().

Examples

if (requireNamespace("dplyr", quietly = TRUE)) {
  ac <- ac_build(c("hello", "world"))
  docs <- data.frame(doc = c("hello world", "nothing", "world"))
  dplyr::mutate(docs, matched = ac_detect(ac, doc))
}

Detect pattern matches in files

Description

ac_detect_file() returns whether each file has at least one pattern match.

Usage

ac_detect_file(ac, path, stream = FALSE)

Arguments

Value

A logical vector with the same length as path.

See Also

ac_detect(), ac_count_file(), ac_locate_bytes().

Examples

ac <- ac_build(c("hello", "world"))
path <- tempfile()
writeLines("hello world", path)
ac_detect_file(ac, path)

Extract pattern matches from documents

Description

ac_extract() returns one list element per document. Each element contains the matched text and the corresponding pattern values.

Usage

ac_extract(ac, doc, overlapping = FALSE, na = c("keep", "empty", "error"))

Arguments

Value

A list with the same length as doc. Each element is a data frame with one row per match and two columns:

• matches: Text matched in the document.

• patterns: Pattern values corresponding to each match.

See Also

ac_extract_df(), ac_locate(), ac_detect(), ac_count().

Examples

if (
  requireNamespace("dplyr", quietly = TRUE) &&
    requireNamespace("tibble", quietly = TRUE) &&
    requireNamespace("tidyr", quietly = TRUE)
) {
  ac <- ac_build(c("hello", "world"))
  tibble::tibble(doc = c("hello world", "nothing", "world")) |>
    dplyr::mutate(extracted = ac_extract(ac, doc)) |>
    tidyr::unnest(extracted)
}

Extract pattern matches as a data frame

Description

ac_extract_df() is the data-frame form of ac_extract(). It is useful when you want one row per match instead of one list element per document.

Usage

ac_extract_df(ac, doc, overlapping = FALSE, na = c("omit", "keep", "error"))

Arguments

Value

A data frame with one row per match and three columns: doc_id, matches, and patterns.

See Also

ac_extract(), ac_locate_df().

Examples

ac <- ac_build(c("hello", "world"))
doc <- c("hello world", "nothing", "world hello")
ac_extract_df(ac, doc)

Extract pattern matches from files

Description

ac_extract_file() returns one list element per file. Each element contains the matched text and the corresponding pattern values.

Usage

ac_extract_file(ac, path, stream = FALSE, overlapping = FALSE)

Arguments

Value

A list with the same length as path. Each element is a data frame with one row per match and two columns:

• matches: Text matched in the file.

• patterns: Pattern values corresponding to each match.

See Also

ac_extract(), ac_detect_file(), ac_count_file().

Examples

ac <- ac_build(c("hello", "world"))
path <- tempfile()
writeLines("hello world", path)
ac_extract_file(ac, path)

Return automaton metadata

Description

Return automaton metadata

Usage

ac_info(ac)

Arguments

Value

A list of automaton metadata.

See Also

ac_build(), ac_patterns().

Examples

ac <- ac_build(c("hello", "world"))
ac_info(ac)

Locate pattern matches in strings

Description

ac_locate() searches a character vector with a compiled automaton and returns one list element per document. Character offsets are 1-based and inclusive, so they can be used directly with substr().

Usage

ac_locate(ac, doc, overlapping = FALSE, na = c("keep", "empty", "error"))

Arguments

Value

A list with the same length as doc. Each element is a data frame with one row per match and three columns:

• pattern_id: Index of the matched pattern in ac_patterns(ac).

• start: 1-based index of the first character in each match.

• end: 1-based index of the last character in each match.

See Also

ac_locate_df(), ac_locate_bytes(), ac_extract(), ac_detect(), ac_count().

Examples

if (
  requireNamespace("dplyr", quietly = TRUE) &&
    requireNamespace("tibble", quietly = TRUE) &&
    requireNamespace("tidyr", quietly = TRUE)
) {
  ac <- ac_build(c("hello", "world"))
  tibble::tibble(doc = c("hello world", "nothing", "world")) |>
    dplyr::mutate(hits = ac_locate(ac, doc)) |>
    tidyr::unnest(hits)
}

Locate pattern matches with byte offsets

Description

ac_locate_bytes() searches a character vector with a compiled automaton and returns byte offsets from the Rust aho-corasick crate. Byte offsets are 0-based, and byte_end is end-exclusive.

Usage

ac_locate_bytes(ac, doc, overlapping = FALSE, na = c("omit", "keep", "error"))

Arguments

Value

A data frame with one row per match and four columns: doc_id, pattern_id, byte_start, and byte_end.

See Also

ac_locate(), ac_locate_df().

Examples

ac <- ac_build(c("hello", "world"))
doc <- c("hello world", "nothing", "world hello")
ac_locate_bytes(ac, doc)

Locate pattern matches as a data frame

Description

ac_locate_df() is the data-frame form of ac_locate(). It is useful when you want one row per match instead of one list element per document.

Usage

ac_locate_df(ac, doc, overlapping = FALSE, na = c("omit", "keep", "error"))

Arguments

Value

A data frame with one row per match and four columns: doc_id, pattern_id, start, and end.

See Also

ac_locate(), ac_locate_bytes(), ac_extract_df().

Examples

ac <- ac_build(c("hello", "world"))
doc <- c("hello world", "nothing", "world hello")
ac_locate_df(ac, doc)

Locate pattern matches in files

Description

ac_locate_file() searches files with a compiled automaton and returns one list element per file. Character offsets are 1-based and inclusive, so they can be used directly with substr().

Usage

ac_locate_file(ac, path, overlapping = FALSE)

Arguments

Details

File location search is always non-streaming. Converting byte offsets from a streaming search into R-facing character offsets would require a second pass over the same file to reconstruct UTF-8 character boundaries. Keeping ac_locate_file() as a simple in-memory search is the clearest implementation.

Value

A list with the same length as path. Each element is a data frame with one row per match and three columns:

• pattern_id: Index of the matched pattern in ac_patterns(ac).

• start: 1-based index of the first character in each match.

• end: 1-based index of the last character in each match.

See Also

ac_locate(), ac_detect_file(), ac_count_file(), ac_extract_file().

Examples

ac <- ac_build(c("hello", "world"))
path <- tempfile()
writeLines("hello world", path)
ac_locate_file(ac, path)

Return patterns stored in an automaton

Description

Return patterns stored in an automaton

Usage

ac_patterns(ac)

Arguments

Value

A character vector of stored patterns.

See Also

ac_build(), ac_info().

Examples

ac <- ac_build(c("hello", "world"))
ac_patterns(ac)

Replace pattern matches in documents

Description

ac_replace() replaces all non-overlapping matches in each document with the corresponding replacement string.

Usage

ac_replace(ac, doc, replace_with, na = c("keep", "empty", "error"))

Arguments

Value

A character vector with the same length and names as doc.

See Also

ac_build(), ac_detect(), ac_count(), ac_extract(), ac_locate().

Examples

ac <- ac_build(c("fox", "brown", "quick"))
ac_replace(
  ac,
  "The quick brown fox.",
  c("sloth", "grey", "slow")
)

ac <- ac_build(c("append", "appendage", "app"), match_kind = "leftmost_first")
ac_replace(ac, "append the app to the appendage", c("x", "y", "z"))

Replace pattern matches in files

Description

ac_replace_file() replaces all non-overlapping matches in input files and writes the result to output files.

Usage

ac_replace_file(ac, path, replace_with, output = NULL, stream = FALSE)

Arguments

Value

A character vector of output file paths with the same length as path.

See Also

ac_replace(), ac_detect_file(), ac_count_file().

Examples

ac <- ac_build(c("fox", "brown", "quick"))
path <- tempfile(fileext = ".txt")
writeLines("The quick brown fox.", path)
ac_replace_file(path = path, ac = ac, replace_with = c("sloth", "grey", "slow"))