# $EPIC: numlines.txt,v 1.3 2006/08/01 05:36:58 sthalik Exp $
======Synopsis:======
$__numlines__(<columns> <string>)

======Technical:======
This function tells you the number of lines that the given string would
occupy after final display in a window with a width of <columns>.

======Practical:======
This function can be used to determine how many lines a particular string will
occupy in particular window. One thing this could be used for is scripting a
file pager that will correctly pause between each screen of output, regardless
of long lines and [[SET]] [[set CONTINUED_LINE|CONTINUED_LINE]]|[[set
INDENT|INDENT]].

======Returns:======
number of lines <string> will occupy if displayed in a window with a
width of <columns>, or nothing on error.

======Examples:======
<file>
$numlines(6 foo bar baz)                  returns 2
$numlines($word(0 $geom()) foo bar baz)   probably returns 1
$numlines(foo bar baz)                    returns nothing
</file>

======Notes:======
This does NOT take into account [[SET]] [[set OUTPUT_REWRITE|OUTPUT_REWRITE]]
so you may want to turn it off before outputting anything that may depend on
$numlines() being accurate.