{"Package":"fansi","Title":"ANSI Control Sequence Aware String Functions","Description":"Counterparts to R string manipulation functions that account for\nthe effects of ANSI text formatting control sequences.","Version":"1.0.7","Authors@R":"c(\nperson(\"Brodie\", \"Gaslam\", email=\"brodie.gaslam@yahoo.com\",\nrole=c(\"aut\", \"cre\")),\nperson(\"Elliott\", \"Sales De Andrade\", role=\"ctb\"),\nperson(given=\"R Core Team\",\nemail=\"R-core@r-project.org\", role=\"cph\",\ncomment=\"UTF8 byte length calcs from src/util.c\"\n),\nperson(\"Michael\",\"Chirico\", role=\"ctb\",\nemail=\"michaelchirico4@gmail.com\", comment = c(ORCID=\"0000-0003-0787-087X\")\n),\nperson(given = \"Unicode, Inc.\",\nrole = c(\"cph\", \"dtc\"),\ncomment = \"Unicode Character Database derivative data in src/width.c\")\n)","Depends":"R (>= 3.1.0)","License":"GPL-2 | GPL-3","URL":"https://github.com/brodieG/fansi","BugReports":"https://github.com/brodieG/fansi/issues","VignetteBuilder":"knitr","Suggests":"unitizer, knitr, rmarkdown","Imports":"grDevices, utils","RoxygenNote":"7.3.3","Encoding":"UTF-8","Collate":"'constants.R' 'fansi-package.R' 'internal.R' 'load.R' 'misc.R'\n'nchar.R' 'strwrap.R' 'strtrim.R' 'strsplit.R' 'substr2.R'\n'trimws.R' 'tohtml.R' 'unhandled.R' 'normalize.R' 'sgr.R'","NeedsCompilation":"yes","Packaged":"2025-11-18 23:27:14 UTC; brodie","Author":"Brodie Gaslam [aut, cre],\nElliott Sales De Andrade [ctb],\nR Core Team [cph] (UTF8 byte length calcs from src/util.c),\nMichael Chirico [ctb] (ORCID: ),\nUnicode, Inc. [cph, dtc] (Unicode Character Database derivative data in\nsrc/width.c)","Maintainer":"Brodie Gaslam ","Repository":"CRAN","Date/Publication":"2025-11-19 14:20:02 UTC","repoType":"cran","tarballUrl":"ftp://cran.r-project.org/pub/R/src/contrib/fansi_1.0.7.tar.gz","jsonAuthors":[{"name":"Brodie Gaslam","email":"brodie.gaslam@yahoo.com","maintainer":true},{"name":"Elliott Sales De Andrade","email":null,"maintainer":false},{"name":"R Core Team ","email":"R-core@r-project.org","maintainer":false},{"name":"Michael Chirico","email":"michaelchirico4@gmail.com","maintainer":false},{"name":"Unicode, Inc. ","email":null,"maintainer":false}],"readme":"\n\n# fansi - ANSI Control Sequence Aware String Functions\n\n[![R build\nstatus](https://github.com/brodieG/fansi/workflows/R-CMD-check/badge.svg)](https://github.com/brodieG/fansi/actions)\n[![](https://codecov.io/gh/brodieG/fansi/branch/master/graphs/badge.svg?branch=rc)](https://app.codecov.io/github/brodieG/fansi?branch=rc)\n[![](http://www.r-pkg.org/badges/version/fansi)](https://cran.r-project.org/package=fansi)\n[![Dependencies\ndirect/recursive](https://tinyverse.netlify.app/badge/fansi)](https://tinyverse.netlify.app/)\n\nCounterparts to R string manipulation functions that account for the\neffects of ANSI text formatting control sequences.\n\n## Formatting Strings with Control Sequences\n\nMany terminals will recognize special sequences of characters in strings\nand change display behavior as a result. For example, on my terminal the\nsequences `\"\\033[3?m\"` and `\"\\033[4?m\"`, where `\"?\"` is a digit in 1-7,\nchange the foreground and background colors of text respectively: \n\n fansi <- \"\\033[30m\\033[41mF\\033[42mA\\033[43mN\\033[44mS\\033[45mI\\033[m\"\n\n![](https://github.com/brodieG/fansi/raw/v1.0-rc/extra/images/fansi-1.png)\n\nThis type of sequence is called an ANSI CSI SGR control sequence. Most\n\\*nix terminals support them, and newer versions of Windows and Rstudio\nconsoles do too. You can check whether your display supports them by\nrunning `term_cap_test()`.\n\nWhether the `fansi` functions behave as expected depends on many\nfactors, including how your particular display handles Control\nSequences. See `?fansi` for details, particularly if you are getting\nunexpected results.\n\n## Manipulation of Formatted Strings\n\nANSI control characters and sequences (*Control Sequences* hereafter)\nbreak the relationship between byte/character position in a string and\ndisplay position. For example, to extract the “ANS” part of our colored\n“FANSI”, we would need to carefully compute the character positions:\n\n![](https://github.com/brodieG/fansi/raw/v1.0-rc/extra/images/fansi-2.png)\n\nWith `fansi` we can select directly based on display position:\n\n![](https://github.com/brodieG/fansi/raw/v1.0-rc/extra/images/fansi-3.png)\n\nIf you look closely you’ll notice that the text color for the `substr`\nversion is wrong as the naïve string extraction loses the\ninitial`\"\\033[37m\"` that sets the foreground color. Additionally, the\ncolor from the last letter bleeds out into the next line.\n\n## `fansi` Functions\n\n`fansi` provides counterparts to the following string functions:\n\n- `substr` (and `substr<-`)\n- `strsplit`\n- `strtrim`\n- `strwrap`\n- `nchar` / `nzchar`\n- `trimws`\n\nThese are drop-in replacements that behave (almost) identically to the\nbase counterparts, except for the *Control Sequence* awareness. There\nare also utility functions such as `strip_ctl` to remove *Control\nSequences* and `has_ctl` to detect whether strings contain them.\n\nMuch of `fansi` is written in C so you should find performance of the\n`fansi` functions to be slightly slower than the corresponding base\nfunctions, with the exception that `strwrap_ctl` is much faster.\nOperations involving `type = \"width\"` will be slower still. We have\nprioritized convenience and safety over raw speed in the C code, but\nunless your code is primarily engaged in string manipulation `fansi`\nshould be fast enough to avoid attention in benchmarking traces.\n\n## Width Based Substrings\n\n`fansi` also includes improved versions of some of those functions, such\nas `substr2_ctl` which allows for width based substrings. To illustrate,\nlet’s create an emoji string made up of two wide characters:\n\n pizza.grin <- sprintf(\"\\033[46m%s\\033[m\", strrep(\"\\U1F355\\U1F600\", 10))\n\n![](https://github.com/brodieG/fansi/raw/v1.0-rc/extra/images/pizza-grin.png)\n\nAnd a colorful background made up of one wide characters:\n\n raw <- paste0(\"\\033[45m\", strrep(\"FANSI\", 40))\n wrapped <- strwrap2_ctl(raw, 41, wrap.always=TRUE)\n\n![](https://github.com/brodieG/fansi/raw/df4019e/extra/images/wrapped-2.png)\n\nWhen we inject the 2-wide emoji into the 1-wide background their widths\nare accounted for as shown by the result remaining rectangular:\n\n starts <- c(18, 13, 8, 13, 18)\n ends <- c(23, 28, 33, 28, 23)\n substr2_ctl(wrapped, type='width', starts, ends) <- pizza.grin\n\n![](https://github.com/brodieG/fansi/raw/v1.0-rc/extra/images/wrapped-1.png)\n\n`fansi` width calculations use heuristics to account for graphemes,\nincluding combining emoji:\n\n emo <- c(\n \"\\U1F468\",\n \"\\U1F468\\U1F3FD\",\n \"\\U1F468\\U1F3FD\\u200D\\U1F9B3\",\n \"\\U1F468\\u200D\\U1F469\\u200D\\U1F467\\u200D\\U1F466\"\n )\n writeLines(\n paste(\n emo,\n paste(\"base:\", nchar(emo, type='width')),\n paste(\"fansi:\", nchar_ctl(emo, type='width'))\n ) )\n ##

Description

Usage

Arguments

Value

Examples