Forms a text structure by appending or concatenating values of scalars, variates, texts, factors or pointers; allows the case of letters to be changed or values to truncated and reversed.

Options

Stores the text that is formed

Case to use for letters (given, lower, upper, changed, sentence, title); default give leaves the case of each letter as given in the original texts

Whether to append or concatenate the values of the structures (append, concatenate) default conc

Characters to separate all except last two strings in each line when concatenating; default '' (i.e. none)

Characters to separate last two strings in each line when concatenating; default '' (i.e. none)

Characters to put at the start of each line when concatenating; default '' (i.e. none)

Characters to put at the end of each line when concatenating; default '' (i.e. none)

Parameters

STRUCTURE = scalars, variates, factors, texts or pointers

Structures whose values are to be appended or concatenated

Number of characters to take from the strings formed from the units of each STRUCTURE, a negative value takes all the (unskipped) characters other than trailing spaces; if omitted or set to a missing value, all the (unskipped) characters are taken

Number of decimal places to use for numerical structures; if omitted or set to a missing value, a default is used which aims to print the value to its full precision

Number of characters to skip at the left-hand side of the strings formed from the units of each STRUCTURE, a negative value skips all initial spaces; if omitted or set to a missing value, no characters are skipped

How to represent factor values (labels, levels, ordinals); default is to use labels if available, otherwise levels

Format to use for dates and times (stored in numerical structures)

Whether to reverse the strings of characters formed from the units of each structure (yes, no); default no

Description

The TXCONSTRUCT directive forms a text from the values of scalars, variates, texts, factors or pointers. The new text is saved using the TEXT option, and the structures from which it is to be formed are listed using the STRUCTURE parameter.

By default the values of the structures are concatenated alongside each other (as with the CONCATENATE directive); alternatively you can set option METHOD=append to append them below each other. When you are concatenating, the structures in the STRUCTURE list must generally contain the same number of values (and this then defines the number of lines in the new text). The exception is that the STRUCTURE list can include scalars or texts containing a single string if you want to put the same numbers or strings into every line of the new text.

Numerical values (from scalars, variates or factors) are converted into strings of characters before they are used. As in the PRINT directive, you can use the DREPRESENTATION parameter to indicate whether these are to be treated as dates. Alternatively, if they are to remain as numbers, the DECIMALS parameter specifies the number of decimal places to use. DECIMALS can be set to a scalar if all the values of the structure are to be printed with the same number of decimals, or to a variate if you want to represent different units of a variate or factor structure with different numbers of decimals. If DECIMALS is not set, or if it contains missing values, TXCONSTRUCT aims to represent the values to their full precision (as though they had been printed with a full number of decimal places and then trailing zeros had been removed).

The SKIP parameter allows you to skip characters at the start of the strings provided by each structure. You can supply a scalar to skip the same number of characters in every string, or a variate if you want to make different skips in every string. Similarly the WIDTH parameter specifies how many characters are to be taken, after omitting any initial characters as specified by SKIP. The strings formed from scalars, variates, factors and pointers do not contain any initial or trailing spaces. You can set a negative skip to ignore all the initial spaces in a string taken from a text structure, and set a negative width to ignore all its trailing spaces. The REVERSE parameter allows you to reverse the strings from any of the structures.

The CASE option enables you to change the case of letters in the strings. The available settings are:

to leave the case of each letter exactly as given in the string;

to change all letters to upper case (or capitals);

to change all letters to lower case;

to put lower-case letters into upper case, and upper-case letters into lower case;

to put the first character in the text (if a letter) into upper case, then to use upper case only at the start of each new sentence;

to begin each new word with a capital letter, but otherwise to use lower case.

When METHOD=concatenate you can use the SEPARATOR, LASTSEPARATOR, PREFIX and END options to insert characters automatically between the adjacent pairs of strings in each line. LASTSEPARATOR supplies a string of characters to insert between the last pair of strings, SEPARATOR supplies characters to insert between all the other pairs of strings, PREFIX supplies characters to put at the start of each line, and END supplies characters to put at the end of each line. By default these all contain the empty string '', so no characters are inserted.

Parameters: STRUCTURE, WIDTH, DECIMALS, SKIP, FREPRESENTATION, DREPRESENTATION, REVERSE.

Action with RESTRICT

TXCONSTRUCT takes account of restrictions on any of the vectors that occur in the statement. If more than one vector is restricted, then each such restriction must be the same. The values of the units in the new text that are excluded by the restriction are left unchanged.