nchar_ctl {fansi}R Documentation

ANSI Control Sequence Aware Version of nchar

Description

nchar_ctl counts all non Control Sequence characters. nzchar_ctl returns TRUE for each input vector element that has non Control Sequence sequence characters. By default newlines and other C0 control characters are not counted.

Usage

nchar_ctl(x, type = "chars", allowNA = FALSE, keepNA = NA,
  strip = "all", warn = getOption("fansi.warn"))

nzchar_ctl(x, keepNA = NA, warn = getOption("fansi.warn"))

Arguments

x

a character vector or object that can be coerced to character.

type

character string, one of "chars", or "width". For byte counts use base::nchar.

allowNA

logical: should NA be returned for invalid multibyte strings or "bytes"-encoded strings (rather than throwing an error)?

keepNA

logical: should NA be returned where ever x is NA? If false, nchar() returns 2, as that is the number of printing characters used when strings are written to output, and nzchar() is TRUE. The default for nchar(), NA, means to use keepNA = TRUE unless type is "width". Used to be (implicitly) hard coded to FALSE in R versions <= 3.2.0.

strip

character, any combination of the following values (see details):

  • "nl": strip newlines.

  • "c0": strip all other "C0" control characters (i.e. x01-x1f), except for newlines and the actual ESC character.

  • "sgr": strip ANSI CSI SGR sequences.

  • "csi": strip all non-SGR csi sequences.

  • "esc": strip all other escape sequences.

  • "all": all of the above, except when used in combination with any of the above, in which case it means "all but" (see details).

warn

TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi).

Details

nchar_ctl is just a wrapper around nchar(strip_ctl(...)). nzchar_ctl is implemented in native code and is much faster than the otherwise equivalent nzchar(strip_ctl(...)). You cannot change which Control Sequences count in nzchar_ctl, but you can always resort to nzchar(strip_ctl(..., strip='...')) if that is important.

These functions will warn if either malformed or non-CSI escape sequences are encountered, as these may be incorrectly interpreted.

Note

the keepNA parameter is ignored for R < 3.2.2.

See Also

fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results, strip_ctl for removing Control Sequences.

Examples

nchar_ctl("\033[31m123\a\r")
## with some wide characters
cn.string <-  sprintf("\033[31m%s\a\r", "\u4E00\u4E01\u4E03")
nchar_ctl(cn.string)
nchar_ctl(cn.string, type='width')

## Remember newlines are not counted by default
nchar_ctl("\t\n\r")

## The 'c0' value for the `strip` argument does
## not include newlines.
nchar_ctl("\t\n\r", strip="c0")
nchar_ctl("\t\n\r", strip=c("c0", "nl"))

## All of the following are Control Sequences
nzchar_ctl("\n\033[42;31m\033[123P\a")
[Package fansi version 0.3.0 Index]