Fast string wrapping

Wrap each element of a character vector to a target width. CRLF/CR are normalized to LF when present and existing newlines may be preserved. Internal runs of whitespace are collapsed to single spaces between words.

Usage

fstr_wrap(x, width = 72L, indent = 0L, exdent = 0L, keep_newlines = FALSE)

fstrwrap(x, width = 72L, indent = 0L, exdent = 0L, keep_newlines = FALSE)

Arguments

x

(character vector)
The text to wrap.

width

(Scalar numeric: 72L; [1, .Machine$integer.max])
Target column width in characters for wrapping, including the cost of any indent or exdent.

indent

(Scalar numeric: 0L; [0, .Machine$integer.max])
Number of leading spaces to prepend to the first line of each wrapped element. If the element does not wrap, the indent is still applied.

exdent

(Scalar numeric: 0L; [0, .Machine$integer.max])
Number of leading spaces to prepend to each line after the first. Has no effect if the element does not wrap.

keep_newlines

(Scalar logical: c(FALSE, TRUE))
FALSE (default) collapses all whitespace including newlines into spaces before wrapping. TRUE splits the input at "\n" and wraps each line independently.

Value

Character vector of the same length as x.

Details

Words are defined by splitting on the regular expression \\s+, and empty tokens are dropped. NA elements are returned as NA_character_. When keep_newlines = TRUE, input is split into lines at "\n", each line is word-wrapped independently, and empty lines are preserved as empty strings.

A greedy algorithm buffers contiguous words and flushes them to the output when adding the next word would exceed the target width. If the entire line fits within the width when accounting for indent, the line is returned unwrapped. Long words are not broken; they are placed on a line even if they exceed the width. Line length is computed as the sum of the prefix and buffered words plus inter-word spaces.

Names on the input vector are preserved on the output. The result for each element is a single string with any inserted wraps represented by "\n".

See also

base::strwrap()

Examples

#----------------------------------------------------------------------------
# fstr_wrap()
#----------------------------------------------------------------------------
library(bkbase)

# Basic wrapping
txt <- "This is a simple example sentence that will be wrapped."
cat(fstr_wrap(txt, width = 20))
#> This is a simple
#> example sentence
#> that will be
#> wrapped.

# Indent for the first line and exdent for continuation lines
txt <- "Indented wrapping across multiple lines of text."
cat(fstr_wrap(txt, width = 20, indent = 2, exdent = 4))
#>   Indented wrapping
#>     across multiple
#>     lines of text.

# Existing newlines are preserved and each line is wrapped independently
txt <- "First line that is somewhat long.\nSecond line that is also long."
cat(fstr_wrap(txt, width = 25, exdent = 2))
#> First line that is
#>   somewhat long. Second
#>   line that is also long.

txt <- "This is a sentence.
Next is the second sentence.
Finally, the third sentence."
cat(fstr_wrap(txt, keep_newlines = FALSE))
#> This is a sentence. Next is the second sentence. Finally, the third
#> sentence.
cat(fstr_wrap(txt, keep_newlines = TRUE))
#> This is a sentence.
#> Next is the second sentence.
#> Finally, the third sentence.

# Names preserved and NA propagated
txt <- c(a = "short line", b = NA_character_)
fstr_wrap(txt, width = 25)
#>            a            b 
#> "short line"           NA