1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sprintf.R
\name{stri_sprintf}
\alias{stri_sprintf}
\alias{stri_string_format}
\alias{stri_printf}
\title{Format Strings}
\usage{
stri_sprintf(
format,
...,
na_string = NA_character_,
inf_string = "Inf",
nan_string = "NaN",
use_length = FALSE
)
stri_string_format(
format,
...,
na_string = NA_character_,
inf_string = "Inf",
nan_string = "NaN",
use_length = FALSE
)
stri_printf(
format,
...,
file = "",
sep = "\\n",
append = FALSE,
na_string = "NA",
inf_string = "Inf",
nan_string = "NaN",
use_length = FALSE
)
}
\arguments{
\item{format}{character vector of format strings}
\item{...}{vectors (coercible to integer, real, or character)}
\item{na_string}{single string to represent missing values;
if \code{NA}, missing values in \code{...}
result in the corresponding outputs be missing too;
use \code{"NA"} for compatibility with base R}
\item{inf_string}{single string to represent the (unsigned) infinity (\code{NA} allowed)}
\item{nan_string}{single string to represent the not-a-number (\code{NA} allowed)}
\item{use_length}{single logical value; should the number of code
points be used when applying modifiers such as \code{\%20s}
instead of the total code point width?}
\item{file}{see \code{\link[base]{cat}}}
\item{sep}{see \code{\link[base]{cat}}}
\item{append}{see \code{\link[base]{cat}}}
}
\value{
\code{stri_printf} is used for its side effect, which is printing
text on the standard output or other connection/file. Hence, it returns
\code{invisible(NULL)}.
The other functions return a character vector.
}
\description{
\code{stri_sprintf} (synonym: \code{stri_string_format})
is a Unicode-aware replacement for and enhancement of
the built-in \code{\link[base]{sprintf}} function.
Moreover, \code{stri_printf} prints formatted strings.
}
\details{
Vectorized over \code{format} and all vectors passed via \code{...}.
Unicode code points may have various widths when
printed on the console (compare \code{\link{stri_width}}).
These functions, by default (see the \code{use_length} argument), take this
into account.
These functions are not locale sensitive. For instance, numbers are
always formatted in the "POSIX" style, e.g., \code{-123456.789}
(no thousands separator, dot as a fractional separator).
Such a feature might be added at a later date, though.
All arguments passed via \code{...} are evaluated. If some of them
are unused, a warning is generated. Too few arguments result in an error.
Note that \code{stri_printf} treats missing values in \code{...}
as \code{"NA"} strings by default.
All format specifiers supported \code{\link[base]{sprintf}} are
also available here. For the formatting of integers and floating-point
values, currently the system \code{std::snprintf()} is called, but
this may change in the future. Format specifiers are normalized
and necessary sanity checks are performed.
Supported conversion specifiers: \code{dioxX} (integers)
\code{feEgGaA} (floats) and \code{s} (character strings).
Supported flags: \code{-} (left-align),
\code{+} (force output sign or blank when \code{NaN} or \code{NA}; numeric only),
\code{<space>} (output minus or space for a sign; numeric only)
\code{0} (pad with 0s; numeric only),
\code{#} (alternative output of some numerics).
}
\examples{
stri_printf("\%4s=\%.3f", c("e", "e\u00b2", "\u03c0", "\u03c0\u00b2"),
c(exp(1), exp(2), pi, pi^2))
x <- c(
"xxabcd",
"xx\u0105\u0106\u0107\u0108",
stri_paste(
"\u200b\u200b\u200b\u200b",
"\U0001F3F4\U000E0067\U000E0062\U000E0073\U000E0063\U000E0074\U000E007F",
"abcd"
))
stri_printf("[\%10s]", x) # minimum width = 10
stri_printf("[\%-10.3s]", x) # output of max width = 3, but pad to width of 10
stri_printf("[\%10s]", x, use_length=TRUE) # minimum number of Unicode code points = 10
# vectorization wrt all arguments:
p <- runif(10)
stri_sprintf(ifelse(p > 0.5, "P(Y=1)=\%1$.2f", "P(Y=0)=\%2$.2f"), p, 1-p)
# using a "preformatted" logical vector:
x <- c(TRUE, FALSE, FALSE, NA, TRUE, FALSE)
stri_sprintf("\%s) \%s", letters[seq_along(x)], c("\u2718", "\u2713")[x+1])
# custom NA/Inf/NaN strings:
stri_printf("\%+10.3f", c(-Inf, -0, 0, Inf, NaN, NA_real_),
na_string="<NA>", nan_string="\U0001F4A9", inf_string="\u221E")
stri_sprintf("UNIX time \%1$f is \%1$s.", Sys.time())
# the following do not work in sprintf()
stri_sprintf("\%1$#- *2$.*3$f", 1.23456, 10, 3) # two asterisks
stri_sprintf(c("\%s", "\%f"), pi) # re-coercion needed
stri_sprintf("\%1$s is \%1$f UNIX time.", Sys.time()) # re-coercion needed
stri_sprintf(c("\%d", "\%s"), factor(11:12)) # re-coercion needed
stri_sprintf(c("\%s", "\%d"), factor(11:12)) # re-coercion needed
}
\references{
\code{printf} in \code{glibc},
\url{https://man.archlinux.org/man/printf.3}
\code{printf} format strings -- Wikipedia,
\url{https://en.wikipedia.org/wiki/Printf_format_string}
}
\seealso{
The official online manual of \pkg{stringi} at \url{https://stringi.gagolewski.com/}
Gagolewski M., \pkg{stringi}: Fast and portable character string processing in R, \emph{Journal of Statistical Software} 103(2), 2022, 1-59, \doi{10.18637/jss.v103.i02}
Other length:
\code{\link{\%s$\%}()},
\code{\link{stri_isempty}()},
\code{\link{stri_length}()},
\code{\link{stri_numbytes}()},
\code{\link{stri_pad_both}()},
\code{\link{stri_width}()}
}
\concept{length}
\author{
\href{https://www.gagolewski.com/}{Marek Gagolewski} and other contributors
}
|
