Use text functions, such as text and sprintf, to manipulate and parse strings.

Example: Text Functions

real64 r = 0.123
text t(10) = text(r, "%.2f")

sprintf Functions

Use the sprintf function to write text to a text variable without formatting. The sprintf function is an alternative to the concatenation operator +.

The syntax is:

Target variable = sprintf (formatstring, arguments,...)

The data type of the target variable must be text. The format string can contain formatting codes. If no formatting codes are used, no arguments are specified.

Note The format string must be constant. Enclose the format string in double quotes. You cannot use a text variable as a format string.

Example: Valid Statements

program
  text textVariable(20)
  text textVariable2(20) = "Hello World"
  textVariable1 = sprintf("Constant text")
  textVariable1 = sprintf("Constant text %s", textVariable2)
endprogram

Example: Invalid Statements

program
  text textVariable(20)
  text formatStringVariable(20)
  text textVariable2(20) = "Hello World"
  textVariable1 = sprintf(formatStringVariable, textVariable2)
  textVariable1 = sprintf(textVariable2)
endprogram

Formatting Codes for sprintf

Prepend characters with the % sign.

Character Meaning
Minus sign ( - ) Left-aligned output.
Plus sign ( + ) Adds a prefix to the result if a number generates.
Blank Prefixes a blank to the result if the result is positive and left-aligned. Ignored if you specify blanks and +.
Hash ( # ) The hash behaves in the following ways before every result not equal to zero:
  • When specified with o format, the # character prefixes 0.
  • When specified with x format, the # character prefixes 0x.
  • When specified with X format, the # character prefixes 0X.
The # character always forces a decimal point in the following cases:
  • When specified together with the e format
  • When specified together with the E format
  • When specified together with the f format
In combination with text output ( %#s), PAtools generates non-printable characters (for example, <00> ) in texts.
Decimal string (with and without a dot)

A decimal string determines the number of characters to be generated. The exact meaning depends on the data type to be generated.

The following rule applies to all output of texts:

  • If the decimal string does not contain a dot, it then defines the number of characters to be written.
  • If the text for output is longer it is truncated.
  • If it is shorter, blanks are filled in up to this length on the left or the right depending on the selected alignment.
  • If the decimal string for text output contains a dot, the text is shortened. The text is shortened to the number of characters after the dot for output. The text is shortened even if the total length of the output is greater than the text. In this case, the remaining characters are generated as blanks. For example, the string TextPart with formatting information %10.4s results in the following output: Text.

The format rule applies to the output of integers in d, i, o, u, x, and X formats.

  • The minimum number of characters that are written can be defined in the decimal string.
  • If the value is longer, it is not truncated.
  • If the text for output is shorter than the defined length, the output is filled with leading or following blanks. The placement of the blanks depends on the alignment.
  • If you program a leading zero (for example, %020d), zeros are filled in until right alignment is reached.

For the output of real values, the decimal string defines the total length and determines the accuracy. Real values include e, f, and g.

  • The total length of the output is defined before the dot. The number of places after the decimal is defined after the dot for formats e, E and f.
  • The maximum number of significant places (numbers without zeros) is defined for formats g and G. For floating-point numbers, if the assigned total length is too short, the output is not shortened.
Asterisk (*) An asterisk after the percent sign means that the field length is not specified in the formatting code. Instead, the field length is specified as an additional integer value argument before the argument to be formatted.
d Writes an I4 integer as a signed decimal number.
D Dimension of a global variable.
N Name of a global variable.
i Writes an I4 integer as a signed number.
o Writes an unsigned U4 integer as an octal number.
u Value of an unsigned integer variable.
x, X Writes an unsigned U4 integer as a hexadecimal number (abcdef) or (ABCDEF).
f Writes a floating-point number in fixed-point notation or in exponential notation.
e, E Double R8 in scientific notation: [-]m.ddde±xx or [-]m.dddE±xx, where the accuracy (see #) defines the number of places after the decimal.
g, G Writes a floating-point number in fixed-point notation or in exponential notation.
s Writes a text up to the next blank.
c Writes the next character.
% The percent sign is output.

Modifiers

Modifiers are optional. Modifiers might limit the value range of values that are read or generated.

Character Meaning
h The conversion characters d, i, o, u, x, X are handled as a short value. -32,768 to 32,767 signed, or 0 to 65535 unsigned.
hh The conversion characters d, i, o, u, x, X are handled as a byte value. -128 to 127 signed, or 0 to 255 unsigned.
l The conversion characters d, i, o, u, x, X are handled as a long and double value.
L The conversion characters e, E, f, g, G are handled as a long double value.

Output of Special Characters

Special characters output without a prefixed percent sign.

Character Meaning
\<DIGIT> Special characters are displayed. Special characters must be specified in octal notation. For example: \42 = " and \57 = /.
\n Line break
\r Line feed
\t Tab

Examples of sprintf

Declarations:

text txt(40)
int32 int = 65
const text info(4) = "Info"
const real64real = 1234.5678
Type Fmt Example Content of txt
int32 %c txt = sprintf( "character: %c", int ) "character: A"
int32 %u txt = sprintf( "integer: %u", int ) "Integer: 65"
int32 %d txt = sprintf( "integer: %d", int ) "Integer: 65"
int32 %4d txt = sprintf( "integer: %4d", int ) "integer: 65"
int32 %04d txt = sprintf( "integer: %04d" , int ) "Integer: 0065"
int32 %X txt = sprintf( "hex: %X", int ) "hex: A3"
real64 %f txt = sprintf( "number: %f", real) "number: 1234.567800"
real64 %.2f txt = sprintf( "number: %.2f", real) "number: 1234.57"
real64 %10.2f txt = sprintf( "number.2f", real) "number: 1234.57"
real64 %e txt = sprintf("number: %e", real) "number: 1.23457e+03"
real64 %.2e txt = sprintf( "number: %.2e", real) "number: 1.23e+03"
real64 %g txt = sprintf( "number: %g", real) "number: 1234.57"
real64 %.1g txt = sprintf( "number: %.1g", real) "number: 1e+03"
real64 %.2G txt = sprintf( "number: %.2G", real) "number: 1.2e+03"
text %s txt = sprintf( "character sequence: %s", info) "character sequence: Info"
text %% txt = sprintf( "percent sign: %%" ) "percent sign: %"