\HeaderA{strwidth}{Plotting Dimensions of Character Strings and Math Expressions}{strwidth}
\aliasA{strheight}{strwidth}{strheight}
\keyword{dplot}{strwidth}
\keyword{character}{strwidth}
\begin{Description}\relax
These functions compute the width or height, respectively, of the
given strings or mathematical expressions \code{s[i]} on
the current plotting device in \emph{user} coordinates, \emph{inches}
or as fraction of the figure width \code{par("fin")}.
\end{Description}
\begin{Usage}
\begin{verbatim}
strwidth(s, units = "user", cex = NULL, font = NULL, vfont = NULL, ...)
strheight(s, units = "user", cex = NULL, font = NULL, vfont = NULL, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{s}] a character or \LinkA{expression}{expression} vector whose dimensions
are to be determined.  Other objects are coerced by
\code{\LinkA{as.graphicsAnnot}{as.graphicsAnnot}}.
\item[\code{units}] character indicating in which units \code{s} is measured;
should be one of \code{"user"}, \code{"inches"}, \code{"figure"};
partial matching is performed.
\item[\code{cex}] numeric \bold{c}haracter \bold{ex}pansion factor; multiplied
by \code{\LinkA{par}{par}("cex")} yields the final character size; the
default \code{NULL} is equivalent to \code{1}.
\item[\code{font, vfont, ...}] additional information about the font,
possibly including the graphics parameter \code{"family"}:
see \code{\LinkA{text}{text}}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Where an element of \code{s} is a multi-line string (that is, contains
newlines \code{\bsl{}n}), the width and height are of an enclosing
rectangle of the string as plotted by \code{\LinkA{text}{text}}.  The
inter-line spacing is controlled by \code{cex},
\code{\LinkA{par}{par}("lheight")} and the \sQuote{point size} (but not the
actual font in use).

Measurements in \code{"user"} units (the default) are only available
after \code{\LinkA{plot.new}{plot.new}} has been called -- otherwise an error is
thrown.
\end{Details}
\begin{Value}
Numeric vector with the same length as \code{s}, giving the
width or height for each \code{s[i]}.  \code{NA} strings are given
width and height 0 (as they are not plotted).
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{text}{text}}, \code{\LinkA{nchar}{nchar}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
str.ex <- c("W","w","I",".","WwI.")
op <- par(pty='s'); plot(1:100,1:100, type="n")
sw <- strwidth(str.ex); sw
all.equal(sum(sw[1:4]), sw[5])
#- since the last string contains the others

sw.i <- strwidth(str.ex, "inches"); 25.4 * sw.i # width in [mm]
unique(sw / sw.i)
# constant factor: 1 value
mean(sw.i / strwidth(str.ex, "fig")) / par('fin')[1] # = 1: are the same

## See how letters fall in classes
##  -- depending on graphics device and font!
all.lett <- c(letters, LETTERS)
shL <- strheight(all.lett, units = "inches") * 72 # 'big points'
table(shL) # all have same heights ...
mean(shL)/par("cin")[2] # around 0.6

(swL <- strwidth(all.lett, units="inches") * 72) # 'big points'
split(all.lett, factor(round(swL, 2)))

sumex <- expression(sum(x[i], i=1,n), e^{i * pi} == -1)
strwidth(sumex)
strheight(sumex)

par(op)#- reset to previous setting
\end{ExampleCode}
\end{Examples}

