*! Help file for linewrap11.ado version 1.6 written by Mead Over & Joao Pedro Azevedo (mover@cgdev.org) 19Feb2021

help for linewrap11Version 1.6 19Feb2021, Requires Stata 11

Title

linewrap11 -- Split a long string into shorter strings
and, optionally, display them

Syntax

linewrap11
,
longstring(string)
[options]

Options

Lines of equal length (Default)
maxlength(integer) Each line will be either exactly or
approximately the same length, with the length controlled by this option.
If this option is omitted the default maximum line length will be about 79 characters.

square Each line before the last is chopped at exactly
maxlength(integer) characters. If this option is omitted
the default behavior is to wrap the long string at spaces, in order to avoid
splitting individual words.

stack In addition to returning each line of text in its own
macro, concatenate the lines into a single local macro.
This option is useful for constructing a graph title or legend for example.
See examples 3 and 4.

A line for each word
words This option is an alternative to the default
maxlength(integer) option. With words specified,
linewrap11 chops the long string into Stata "word"s, which
are defined by the spaces in the input string. Unlike the programmer's
command tokenize, linewrap11 only uses blanks to define words,
not other user specified characters such as commas or semi-colons.
Multiple spaces are treated as a single space.

A line for each character
characters This option is a second alternative to the default
maxlength(integer) option. With characters specified,
linewrap11 chops the long string into individual ASCII characters.
Multiple spaces are treated as a single space.

Display the wrapped text
display Display the wrapped lines in the results window
and print them in the output log. If this option is omitted, linewrap11
only returns the separate lines in the r() space

linenumbers Number the displayed lines. Only relevant if
option display is also specified

title(string) Optionally display a title before
displaying any other output

Change the names of returned macros
name(string) Allows the user to assign the names of the local macros
containing the text segments that are returned by linewrap11.

add Add the stored results to results previously stored in Stata's
stored results space.
Sequential executions of linewrap11 with distinctly specified name(string) options
- and without intervening Stata programs that clear the return space
- will accumulate the differently named local macros in the return space.
See examples 2, 3
and 4

replace Obsolete option.

Description

linewrap11 chops a long string into a set of shorter "lines"
and returns them in Stata's r() space in macros named
r(line1), r(line2), r(line3), ... r(line1n),
where n, the total number of lines, is returned as macro
r(nlines). Optionally, with the addition of the display option,
linewrap11 also displays a list of
the character strings into which it has chopped the long string.

Without options, linewrap11 wraps the longstring(string)
into lines of approximately 79 characters in length, breaking each line
at the last blank space before the 79'th character. Character strings longer
than 79 characters (or longer than the user specified maxlength(integer))
are presented in their entirety as a single "line". By adding the square option,
the user can require the lines to break exactly at maxlength(integer)
characters, regardless of blank space.

The words option specifies that the lines into which the long character
string is apportioned are "words", defined by the blanks. Each line containing
a single word can be of any length.

The name(string) option allows the user to change the names of the local macros
containing the text segments that are returned by linewrap11.
Use this option together with the add option
to accumulate the returned segments of text in Stata's return space.
Thus, after several sequential executions of linewrap11,
all the generated text segments are available in the return space
and are distinguishable by their different user-assigned name(string) options.

Examples

Example 1 Single execution

. linewrap11, longstr(Four score and seven years ago our fathers brought
forth on this continent, a new nation, conceived in Liberty, and dedicated to
the proposition that all men are created equal.
The quick red fox jumped over the lazy dog.)
title(Example with default maxlength of 79) display linenumbers

Produces output:

Example with default maxlength of 79:

1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123456789

1 Four score and seven years ago our fathers brought forth on this continent, a
2 new nation, conceived in Liberty, and dedicated to the proposition that all
3 men are created equal. The quick red fox jumped over the lazy dog.

. return list

Produces output:

macros:
r(nlines) : "3"
r(line3) : "men are created equal. The quick red fox jumped over the lazy dog."
r(line2) : "new nation, conceived in Liberty, and dedicated to the proposition that all"
r(line1) : "Four score and seven years ago our fathers brought forth on this continent, a"

Example 2 Sequential execution, accumulating text in stored results

Example using the name(string) option in order to preserve return list
accross several sequential executions of linewrap11.
Note that the option add is specified on the second execution.

. linewrap11, longstr(We the People of the United States, in Order to form
a more perfect Union, establish Justice, insure domestic Tranquility, provide for
the common defence, promote the general Welfare, and secure the Blessings of Liberty
to ourselves and our Posterity, do ordain and establish this Constitution for the
United States of America) max(40) name(first_)

. linewrap11, longstr(Four score and seven years ago our fathers brought
forth on this continent, a new nation, conceived in Liberty, and dedicated to
the proposition that all men are created equal.
The quick red fox jumped over the lazy dog.) name(second_) add

. return list

Produces output:

macros:
r(nlines_first_) : "9"
r(first_9) : "the United States of America"
r(first_8) : "and establish this Constitution for"
r(first_7) : "ourselves and our Posterity, do ordain"
r(first_6) : "and secure the Blessings of Liberty to"
r(first_5) : "defence, promote the general Welfare,"
r(first_4) : "Tranquility, provide for the common"
r(first_3) : "establish Justice, insure domestic"
r(first_2) : "Order to form a more perfect Union,"
r(first_1) : "We the People of the United States, in"
r(nlines_second_) : "3"
r(second_3) : "men are created equal. The quick red fox jumped over the lazy dog."
r(second_2) : "new nation, conceived in Liberty, and dedicated to the proposition that all"
r(second_1) : "Four score and seven years ago our fathers brought forth on this continent, a"

Example 3 Titles for a bar graph

But suppose the user would like to construct a vertical bar graph
in which each bar has a horizontal label that is vertically stacked.
A discussion on Statalist
points out that
Stata's graph bar does not offer an option to
stack the lines of a horizontal bar label vertically.
This program -linewrap11- can fill this gap.

Here's the use case offered by Sergiy Radyakin.

. sysuse auto, clear
(1978 Automobile Data)

. linewrap11 , longstring(`"very poor, but not as bad as the other guys"') maxlength(15) stack name(firstbar)

. linewrap11 , longstring(`"somewhat better, though still far from perfect"') maxlength(15) stack name(secondbar) add

. return list

macros:
r(nlines_firstbar) : "4"
r(firstbar) : ""very poor," "but not as" "bad as the" "other guys""
r(firstbar4) : "other guys"
r(firstbar3) : "bad as the"
r(firstbar2) : "but not as"
r(firstbar1) : "very poor,"
r(nlines_secondbar) : "4"
r(secondbar) : ""somewhat" "better," "though still" "far from perfect""
r(secondbar4) : "far from perfect"
r(secondbar3) : "though still"
r(secondbar2) : "better,"
r(secondbar1) : "somewhat"

. graph bar price if rep78<3, over(rep78, relabel(1 `"`r(firstbar)'"' 2 `"`r(secondbar)'"' )) ///
title("Desired Stata layout") name(better2, replace)

Example 4 Unicode (e.g. Chinese) character titles for a bar graph

Beginning with version 14, Stata can accommodate Unicode characters including,
for example, Chinese characters. Users of Stata 14 or greater can
wrap lines of text containing Unicode characters by using the
program linewrap instead of with this program, linewrap11.
The two programs are installed together. For an example using Unicode,
see Example 4 in linewrap's help file.

Authors

Mead Over, Senior Fellow, Center for Global Development

Joao Pedro Azevedo, Lead Economist, World Bank

Email: MOver@CGDev.Org if you observe any problems.