Forms a text structure by appending or concatenating values of scalars, variates, texts, factors pointers or formulae; allows the case of letters to be changed or values to be truncated and reversed.
Options
TEXT = text |
Stores the text that is formed |
|---|---|
CASE = string token |
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 |
METHOD = string token |
Whether to append or concatenate the values of the structures (append, concatenate) default conc |
SEPARATOR = string |
Characters to separate all except last two strings in each line when concatenating; default '' (i.e. none) |
LASTSEPARATOR = string |
Characters to separate last two strings in each line when concatenating; default uses the characters defined by SEPARATOR |
PREFIX = string |
Characters to put at the start of each line when concatenating; default '' (i.e. none) |
END = string |
Characters to put at the end of each line when concatenating; default '' (i.e. none) |
SIGNIFICANTFIGURES = scalar |
Specifies the number of significant figures to include for numerical data; default 4 |
Parameters
STRUCTURE = scalars, variates, factors, texts, pointers or formulae |
Structures whose values are to be appended or concatenated |
|---|---|
WIDTH = scalars or variates |
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 |
DECIMALS = scalars or variates |
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 the precision defined by the SIGNIFICANTFIGURES option |
SKIP = scalars or variates |
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 |
FREPRESENTATION = string tokens |
How to represent factor values (labels, levels, ordinals); default is to use labels if available, otherwise levels |
DREPRESENTATION = scalars or texts |
Format to use for dates and times (stored in numerical structures) |
REVERSE = string tokens |
Whether to reverse the strings of characters formed from the units of each structure (yes, no); default no |
MISSING = texts |
String to use to represent missing values of numerical structures; default '*' |
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. The SIGNIFICANTFIGURES option specifies the number of significant figures to aim for if DECIMALS is not set, or if it contains missing values (default 4). A numerical value will then be converted as though it had been printed with the number of decimals required to give SIGNIFICANTFIGURES significant figures, and any trailing zero decimal values had then been removed. Missing numerical values are represented by the asterisk character (*) by default, in the usual way, but you can specify another string of characters using the MISSING parameter.
A formula is converted to a text before being concatenated. The maximum width is defined as 200. So this will be a text with one line, unless the result is more than 200 characters wide.
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:
given |
to leave the case of each letter exactly as given in the string; |
|---|---|
upper |
to change all letters to upper case (or capitals); |
lower |
to change all letters to lower case; |
changed |
to put lower-case letters into upper case, and upper-case letters into lower case; |
sentence |
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; |
title |
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. The defaults for SEPARATOR, PREFIX and END are the empty string '', while LASTSEPARATOR uses the characters defined by SEPARATOR as its default. So by default no characters are inserted.
Options: TEXT, CASE, METHOD, SEPARATOR, LASTSEPARATOR, PREFIX, END, SIGNIFICANTFIGURES.
Parameters: STRUCTURE, WIDTH, DECIMALS, SKIP, FREPRESENTATION, DREPRESENTATION, REVERSE, MISSING.
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.
See also
Directives: TEXT, CONCATENATE, EDIT, EQUATE, TXBREAK, TXFIND, TXPOSITION, TXREPLACE.
Procedures: APPEND, FVSTRING, SUBSET, STACK, TXPROGRESSION , UNSTACK.
Functions: CHARACTERS, GETFIRST, GETLAST, GETPOSITION, POSITION.
Commands for: Calculations and manipulation.
Example
" Examples 1:4.7.1a, 1:4.7.2.a and 1:4.7.7 " TEXT [VALUES='1. Adams','2. Baker','3. Clarke','4. Day',\ '5. Edwards','6. Field','7. Good','8. Hall',\ '9. Irving','10. Jones'] Name TEXT [VALUES='B.J.','J.S.','K.R.','A.T.','R.S.',\ 'T.W.','S.I.','D.M.','H.M.','C.C.'] Initials " Form text Fullname containing the number, name and initials." CONCATENATE [NEWTEXT=Fullname] OLDTEXT=Name,', ',Initials PRINT Fullname; JUSTIFICATION=left " Now reform Fullname to contain just the first initial and the name." CONCATENATE [NEWTEXT=Fullname] OLDTEXT=Initials,Name;\ WIDTH=2,*; SKIP=*,!(9(2),3) PRINT Fullname; JUSTIFICATION=left VARIATE [VALUES=35,42,19,26,33,52,23,28,44,17] Age TXCONSTRUCT [TEXT=Fullname; SEPARATOR=''; LASTSEPARATOR=', age ';\ END='.'] Initials,Name,Age; WIDTH=2,*,*; SKIP=*,!(9(2),3),* PRINT Fullname; JUSTIFICATION=left