infer_notation: Infer the notation(s) for a row or column label

In RCLabels: Manipulate Matrix Row and Column Labels with Ease

Infer the notation(s) for a row or column label

Description

It is convenient to know which notation is applicable to row or column labels. This function infers which notations are appropriate for x.

Usage

infer_notation(
  x,
  inf_notation = TRUE,
  notations = RCLabels::notations_list,
  allow_multiple = FALSE,
  retain_names = FALSE,
  choose_most_specific = TRUE,
  must_succeed = TRUE
)

Arguments

x	A row or column label (or vector of labels).
inf_notation	A boolean that tells whether to infer notation for x. Default is TRUE.
notations	A list of notations from which matches will be inferred. This function might not work as expected if notation is not a list. If notation is not a list, notations is returned in full. Default is RCLabels::notations_list.
allow_multiple	A boolean that tells whether multiple notation matches are allowed. If FALSE (the default), multiple matches give an error.
retain_names	A boolean that tells whether to retain names from notations on the outgoing matches. Default is FALSE. If TRUE, the return value is always a named list. If only one of notations is returned (for example, because choose_most_specific = TRUE), names are never supplied.
choose_most_specific	A boolean that indicates whether the most-specific notation will be returned when more than one of notations matches x and allow_multiple = FALSE. When FALSE, the first matching notation in notations is returned when allow_multiple = FALSE. Default is TRUE. See details.
must_succeed	A boolean that if TRUE (the default), causes an error to be thrown if a matching notation is not found for any label in x. When FALSE, an unsuccessful notation inference will return NULL.

Details

This function is vectorized. Thus, x can be a vector, in which case the output is a list of notations.

notations is treated as a store from which matches for each label in x can be determined. notations should be a named list of notations. When retain_names = TRUE, the names on notations will be retained, and the return value is always a list.

By default (allow_multiple = FALSE), a single notation object is returned for each item in x if only one notation in notations is appropriate for x. If allow_multiple = FALSE (the default) and more than one notation is applicable to x, an error is thrown. Multiple matches can be returned when allow_multiple = TRUE.

If multiple notations are matched, the return value is a list.

When choose_most_specific = TRUE (the default), the most specific notation in notations is returned. "Most specific" is defined as the matching notation whose sum of characters in the pref_start, pref_end, suff_start and suff_end elements is greatest. If choose_most_specific = TRUE and two matching notations in notations have the same number of characters, only the first match is returned. When choose_most_specific = TRUE, the value of allow_multiple no longer matters. allow_multiple = FALSE is implied and at most one of the notations will be returned.

When inf_notation = FALSE (default is TRUE), notations are returned unmodified, essentially disabling this function. Although calling with inf_notation = FALSE seems daft, this behavior enables cleaner code elsewhere.

Value

A single notation object (if x is a single row or column label) or a list of notation objects (if x is a vector or a list). If no notations match x, NULL is returned, either alone or in a list.

Examples

# Does not match any notations in RCLabels::notations_list
# and throws an error, because the default value for `must_succeed`
# is `TRUE`.
## Not run: 
infer_notation("abc")

## End(Not run)
# This returns `NULL`, because `must_succeed = FALSE`.
infer_notation("abc", must_succeed = FALSE)
# This succeeds, because the label is in the form of a
# notation in `RCLabels::notation_list`,
# the default value of the `notation` argument.
infer_notation("a -> b")
# Names of the notations can be retained, in which case
# the return value is always a list.
infer_notation("a -> b", retain_names = TRUE)
# This function is vectorized.
# The list of labels matches
# all known notations in `RCLabels::notations_list`.
infer_notation(c("a -> b", "a (b)", "a [b]", "a [from b]", "a [of b]",
                 "a [to b]", "a [in b]", "a [-> b]", "a.b"),
                 retain_names = TRUE)
# By default, the most specific notation is returned.
# But when two or more matches are present,
# multiple notations can be returned, too.
infer_notation("a [from b]",
               allow_multiple = TRUE, retain_names = TRUE,
               choose_most_specific = FALSE)
infer_notation(c("a [from b]", "c [to d]"),
               allow_multiple = TRUE, retain_names = TRUE,
               choose_most_specific = FALSE)
# As shown above, "a \[from b\]" matches 2 notations:
# `RCLabels::bracket_notation` and `RCLabels::from_notation`.
# The default value for the notation argument is
# RCLabels::notations_list,
# which includes `RCLabels::bracket_notation`
# and `RCLabels::from_notation` in that order.
# Thus, there is some flexibility to how this function works
# if the value of the `notation` argument is a list of notations
# ordered from least specific to most specific,
# as `RCLabels::notations_list` is ordered.
# To review, the next call returns both `RCLabels::bracket_notation` and
# `RCLabels::from_notation`, because `allow_multiple = TRUE` and
# `choose_most_specific = FALSE`, neither of which are default.
infer_notation("a [from b]",
               allow_multiple = TRUE,
               choose_most_specific = FALSE,
               retain_names = TRUE)
# The next call returns `RCLabels::from_notation`, because
# the most specific notation is requested, and
# `RCLabels::from_notation` has more characters in its specification than
# `RCLabels::bracket_notation`.
infer_notation("a [from b]",
               choose_most_specific = TRUE,
               retain_names = TRUE)
# The next call returns the `RCLabels::bracket_notation`, because
# `choose_most_specific = FALSE`, and the first matching
# notation in `RCLabels::notations_list` is `RCLabels::bracket_notation`.
infer_notation("a [from b]",
               choose_most_specific = FALSE,
               retain_names = TRUE)

RCLabels documentation built on May 29, 2024, 5:56 a.m.