Table of Contents

StringBuilder

Namespace
ZAux
Implements

In situations where repeated modifications of a string are required, the overhead and performance indications associated with creating strings is substantial, especially for PLCs and real-time environments.

The StringBuilder function block can be used for modifying strings with much less memory overhead than traditionally function blocks. It also brings a performance boost when concatenating many strings together in a loop. This function block is using the fluent interface design pattern to perform operations on strings, which allows string concatenation in the following way

PROGRAM MAIN
VAR
  StringBuilder : ZAux.StringBuilder;
  Text : ZCore.ZString;
END_VAR
-------------------------------------
Text := StringBuilder.Append('Variable- : ').AppendReal(5.4444, 1).Append('mm/s').ToString(); // returns 'Variable-1: 5.4mm/s'
Text := StringBuilder.AppendParamLreal('Variable-1', 5.4444, 1, 'mm/s').ToString(); // also returns 'Variable-1: 5.4mm/s and should be prefered to the preceeding call'

Although the string builder takes some of the load away that occurs when dealing with strings, building strings will still always be critical for realtime systems and should be used with care.

FUNCTION_BLOCK StringBuilder IMPLEMENTS ZCore.IStringBuilder

Methods

Append

The Append method can be used to add text to the end of a string represented to the StringBuilder. The following example uses a StringBuilder to write Velocity = 5.4 mm/s into the text variable. Usage:

 _stringBuilder : ZAux.StringBuilder;
 _text : ZCore.ZString;
 ---------------------------------------
 _text := _stringBuilder.Append('Velocity = ').AppendReal(5.4444, 1).Append(' mm/s').ToString();

For already instantiated strings, it is faster to use the AppendRef method instead. This method, however, should be used if dealing with rvalues (temporary strings)

If a string is appended to the current string, which would exceed 255 characters (see ZString, the string is cut off and the last characters are set to ' ...'

METHOD Append (
 text : ZCore.ZString) : ZCore.IStringBuilder

Inputs

text ZString

Returns

IStringBuilder

AppendBool

Append a BOOL in the form of True or False to a string. There exist more ways to append a bool variable, which result in slightly different appended strings.

METHOD val Appended STRING
AppendBool TRUE True
AppendBool FALSE False
AppendOnOff TRUE On
AppendOnOff FALSE Off
AppendYesNo TRUE Yes
AppendYesNo FALSE No 
_stringBuilder : ZAux.StringBuilder;
_io1 : BOOL := TRUE;
_io2 : BOOL := FALSE;
_text : ZCore.ZString
---------------------------------------
_text := _stringBuilder.AppendBool(_io1).ToString(); // adds the text 'True' to the string
_text := _stringBuilder.AppendBool(_io2).ToString(); // adds the text 'False' to the string

See Append for details about appending.

METHOD AppendBool (
 val : BOOL) : ZCore.IStringBuilder

Inputs

val BOOL

Returns

IStringBuilder

AppendDint

Append a DINT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : DINT := 42;
_text : ZCore.ZString;
 ---------------------------------------
_text := _stringBuilder.AppendDint(_answer).ToString(); // adds the text '42' to the string

See Append for details.

METHOD AppendDint (
 val : DINT) : ZCore.IStringBuilder

Inputs

val DINT

Returns

IStringBuilder

AppendError

This Append method can be used to return a detailed error summary for an object that failed. It is mainly used within the Zeugwerk Framework context and therefore easy to use.

 _stringBuilder : ZAux.StringBuilder;
 _ctrl : ZEquipment.OnOffController;
 ---------------------------------------
_stringBuilder.AppendError(_ctrl).ToString(); // adds the actual ongoing ErrorMessage to the string

METHOD AppendError (
 error : ZCore.IError) : ZCore.IStringBuilder

Inputs

error IError

Returns

IStringBuilder

AppendFormat

This method can be used to add text to the end of a string represented to the StringBuilder It supports formatting with the usual printf syntax ('%d', '%3.3f') The argument arg may be a primitive, numeric variable (e.g. INT, DINT, LREAL).

Usage:

 _stringBuilder : ZAux.StringBuilder;
 _text : STRING(255);
 _value : REAL := 42.0123;
 ---------------------------------------
 _text := _stringBuilder.Append('Velocity = ').AppendFormat(_value, 1).Append(' mm/s').ToString();

METHOD AppendFormat (
 arg : ANY,
 format : ZCore.ZString) : ZCore.IStringBuilder

Inputs

arg ANY

format ZString

i.e '%d', '%3.3f'

Returns

IStringBuilder

AppendInt

Append an INT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : INT := 42;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendInt(_answer).ToString(); // adds the text '42' to the string

See Append for details.

METHOD AppendInt (
 val : INT) : ZCore.IStringBuilder

Inputs

val INT

Returns

IStringBuilder

AppendLreal

Append a floating-point type to the string. The number of decimal places that should be used can be configured with an additional parameter. The number of decimals can actually be negative (-1) to prevent the decimal point from showing up.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.Append('Value: ').AppendLreal(4, 0).ToString(); > returns 'Value: 4.'
_text := _stringBuilder.Append('Value: ').AppendLreal(4, -1).ToString(); > returns 'Value: 4'
_text := _stringBuilder.Append('Value: ').AppendLreal(4, 3).ToString(); > returns 'Value: 4.000'

See Append for details.

METHOD AppendLreal (
 val : LREAL,
 decimalPlaces : SINT) : ZCore.IStringBuilder

Inputs

val LREAL

decimalPlaces SINT

Returns

IStringBuilder

AppendOnOff

Append a BOOL in the form of On or Off to a string. There exist more ways to append a bool variable, which result in slightly different appended strings.

_stringBuilder : ZAux.StringBuilder;
_io1 : BOOL := TRUE;
_io2 : BOOL := FALSE;
_text : ZCore.ZString;
 ---------------------------------------
_text := _stringBuilder.AppendOnOff(_io1).ToString(); // adds the text 'On' to the string
_text := _stringBuilder.AppendOnOff(_io2).ToString(); // adds the text 'Off' to the string

See AppendBool for variants of appending bools. See Append for details about appending.

METHOD AppendOnOff (
 val : BOOL) : ZCore.IStringBuilder

Inputs

val BOOL

Returns

IStringBuilder

AppendParamBool

Append a parameter with value type BOOL in the form of True or False to a string. This is especially useful for logging parameters. For adding the boolean, internally the method AppendBool is used.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamBool('Parameter 1', TRUE).ToString(); // adds the text 'Parameter 1: True' to the string
_text := _stringBuilder.AppendParamBool('Parameter 2', FALSE).ToString(); // adds the text 'Parameter 2: False' to the string

See Append for details.

METHOD AppendParamBool (
 name : STRING,
 val : BOOL) : ZCore.IStringBuilder

Inputs

name STRING

val BOOL

Returns

IStringBuilder

AppendParamDint

Append a parameter with value type DINT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamDint('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

METHOD AppendParamDint (
 name : STRING,
 val : DINT,
 unit : STRING(10)) : ZCore.IStringBuilder

Inputs

name STRING

val DINT

unit STRING(10)

Returns

IStringBuilder

AppendParamInt

Append a parameter with value type INT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamInt('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

METHOD AppendParamInt (
 name : STRING,
 val : INT,
 unit : STRING(10)) : ZCore.IStringBuilder

Inputs

name STRING

val INT

unit STRING(10)

Returns

IStringBuilder

AppendParamLreal

Append a parameter with value type LREAL to the string. This is especially useful for logging parameters. The number of decimal places that should be used can be configured with an additional parameter. The number of decimals can actually be negative (-1) to prevent the decimal point from showing up.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamLreal('Value', val:=5, decimalPlaces:=-1, unit:='mm').ToString();  // returns 'Value: 5mm'
_text := _stringBuilder.AppendParamLreal('Value', val:=5, decimalPlaces:=-3, unit:='deg').ToString();  // returns 'Value: 5.000deg'

See Append for details.

METHOD AppendParamLreal (
 name : STRING,
 val : LREAL,
 decimalPlaces : SINT,
 unit : STRING(10)) : ZCore.IStringBuilder

Inputs

name STRING

val LREAL

decimalPlaces SINT

unit STRING(10)

Returns

IStringBuilder

AppendParamOnOff

Append a parameter with value type BOOL in the form of On or Off to a string. This is especially useful for logging parameters. For adding the boolean, internally the method AppendBool is used.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamOnOff('Parameter 1', TRUE).ToString(); // adds the text 'Parameter 1: On' to the string
_text := _stringBuilder.AppendParamOnOff('Parameter 2', FALSE).ToString(); // adds the text 'Parameter 2: Off' to the string

See Append for details.

METHOD AppendParamOnOff (
 name : STRING,
 val : BOOL) : ZCore.IStringBuilder

Inputs

name STRING

val BOOL

Returns

IStringBuilder

AppendParamReal

Append a parameter with value type REAL to the string. This is especially useful for logging parameters. The number of decimal places that should be used can be configured with an additional parameter. The number of decimals can actually be negative (-1) to prevent the decimal point from showing up.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamReal('Value', val:=5, decimalPlaces:=-1, unit:='mm').ToString();  // returns 'Value: 5mm'
_text := _stringBuilder.AppendParamReal('Value', val:=5, decimalPlaces:=-3, unit:='deg').ToString();  // returns 'Value: 5.000deg'

See Append for details.

METHOD AppendParamReal (
 name : STRING,
 val : REAL,
 decimalPlaces : SINT,
 unit : STRING(10)) : ZCore.IStringBuilder

Inputs

name STRING

val REAL

decimalPlaces SINT

unit STRING(10)

Returns

IStringBuilder

AppendParamString

Append a parameter with value type BOOL in the form of True or False to a string. This is especially useful for logging parameters. For adding the boolean, internally the method AppendBool is used.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamBool('Parameter 1', TRUE).ToString(); // adds the text 'Parameter 1: True' to the string
_text := _stringBuilder.AppendParamBool('Parameter 2', FALSE).ToString(); // adds the text 'Parameter 2: False' to the string

See Append for details.

METHOD AppendParamString (
 name : STRING,
 str : STRING) : ZCore.IStringBuilder

Inputs

name STRING

str STRING

Returns

IStringBuilder

AppendParamUdint

Append a parameter with value type INT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamUdint('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

METHOD AppendParamUdint (
 name : STRING,
 val : UDINT,
 unit : STRING(10)) : ZCore.IStringBuilder

Inputs

name STRING

val UDINT

unit STRING(10)

Returns

IStringBuilder

AppendParamUint

Append a parameter with value type UINT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamUint('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

METHOD AppendParamUint (
 name : STRING,
 val : UINT,
 unit : STRING(10)) : ZCore.IStringBuilder

Inputs

name STRING

val UINT

unit STRING(10)

Returns

IStringBuilder

AppendParamUlint

Append a parameter with value type ULINT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamUlint('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

METHOD AppendParamUlint (
 name : STRING,
 val : ULINT,
 unit : STRING(10)) : ZCore.IStringBuilder

Inputs

name STRING

val ULINT

unit STRING(10)

Returns

IStringBuilder

AppendParamYesNo

Append a parameter with value type BOOL in the form of Yes or No to a string. This is especially useful for logging parameters. For adding the boolean, internally the method AppendBool is used.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamYesNo('Parameter 1', TRUE).ToString(); // adds the text 'Parameter 1: Yes' to the string
_text := _stringBuilder.AppendParamYesNo('Parameter 2', FALSE).ToString(); // adds the text 'Parameter 1: No' to the string

See Append for details.

METHOD AppendParamYesNo (
 name : STRING,
 val : BOOL) : ZCore.IStringBuilder

Inputs

name STRING

val BOOL

Returns

IStringBuilder

AppendReal

Append a floating-point type to the string. The number of decimal places that should be used can be configured with an additional parameter. The number of decimals can actually be negative (-1) to prevent the decimal point from showing up.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
 _text := _stringBuilder.Append('Value: ').AppendReal(4, 0).ToString();
returns 'Value: 4.'
 _text := _stringBuilder.Append('Value: ').AppendReal(4, -1).ToString();
returns 'Value: 4'
 _text := _stringBuilder.Append('Value: ').AppendReal(4, 3).ToString();
returns 'Value: 4.000'

Please note that for the previous example it is also useful to use AppendParamReal.

See Append for details.

METHOD AppendReal (
 val : REAL,
 decimalPlaces : SINT) : ZCore.IStringBuilder

Inputs

val REAL

decimalPlaces SINT

Returns

IStringBuilder

AppendRef

see Append

METHOD AppendRef (
 text : REFERENCE TO ZCore.ZString) : ZCore.IStringBuilder

Inputs

text REFERENCE TO ZString

Returns

IStringBuilder

AppendUdint

Append an UDINT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : UDINT := 42;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendUdInt(_answer).ToString(); // adds the text '42' to the string

See Append for details.

METHOD AppendUdint (
 val : UDINT) : ZCore.IStringBuilder

Inputs

val UDINT

Returns

IStringBuilder

AppendUint

Append an UINT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : UINT := 42;
_text : ZCore.ZString;
---------------------------------------
_stringBuilder.AppendUint(_answer).ToString(); // adds the text '42' to the string

See Append for details.

METHOD AppendUint (
 val : UINT) : ZCore.IStringBuilder

Inputs

val UINT

Returns

IStringBuilder

AppendUlint

Append an ULINT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : ULINT := 424242;
_text : ZCore.ZString;
---------------------------------------
_stringBuilder.Append('Answer: ').AppendUlint(_answer).ToString(); // adds the text 'Answer: 424242' to the string

See Append for details.

METHOD AppendUlint (
 val : ULINT) : ZCore.IStringBuilder

Inputs

val ULINT

Returns

IStringBuilder

AppendUrlEncoded

The Append method can be used to add text to the end of a string represented to the StringBuilder. The following example uses a StringBuilder to write Velocity = 5.4 mm/s into the text variable. Usage:

 _stringBuilder : ZAux.StringBuilder;
 _text : ZCore.ZString;
 ---------------------------------------
 _text := _stringBuilder.Append('Velocity = ').AppendReal(5.4444, 1).Append(' mm/s').ToString();

For already instantiated strings, it is faster to use the AppendRef method instead. This method, however, should be used if dealing with rvalues (temporary strings)

If a string is appended to the current string, which would exceed 255 characters (see ZString, the string is cut off and the last characters are set to ' ...'

In contrast to Append, this method also encodes the passed string for an URL format so that it can be used for http requests.

METHOD AppendUrlEncoded (
 text : ZCore.ZString) : ZCore.IStringBuilder

Inputs

text ZString

Returns

IStringBuilder

AppendYesNo

Append a BOOL in the form of Yes or No to a string. There exist more ways to append a bool variable, which result in slightly different appended strings.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString
 ---------------------------------------
_stringBuilder.AppendYesNo(TRUE).ToString(); // adds the text 'Yes' to the string
_stringBuilder.AppendYesNo(FALSE).ToString(); // adds the text 'No' to the string

See AppendBool for variants of appending bools. See Append for details about appending.

METHOD AppendYesNo (
 val : BOOL) : ZCore.IStringBuilder

Inputs

val BOOL

Returns

IStringBuilder

Reset

Explicity resets the string that the string builder is currently holding. Please note, that calling ToString also resets the string and hence, this method is usually not required.

METHOD Reset () : ZCore.IStringBuilder

Returns

IStringBuilder

ToString

Returns the string that is currently hold by the StringBuilder and then resets the internal string memory to empty.

METHOD ToString () : ZCore.ZString

Returns

ZString