StringBuilder

Namespace: ZAux

Implements: IStringBuilder

FUNCTION_BLOCK StringBuilder IMPLEMENTS ZCore.IStringBuilder

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.

Methods

Append

METHOD Append (
 [input] text : ZCore.ZString) : ZCore.IStringBuilder

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 ' ...'

Inputs

text ZString

Returns

IStringBuilder

AppendBool

METHOD AppendBool (
 [input] val : BOOL) : ZCore.IStringBuilder

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.

Inputs

val BOOL

Returns

IStringBuilder

AppendDint

METHOD AppendDint (
 [input] val : DINT) : ZCore.IStringBuilder

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.

Inputs

val DINT

Returns

IStringBuilder

AppendError

METHOD AppendError (
 [input] error : ZCore.IError) : ZCore.IStringBuilder

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

Inputs

error IError

Returns

IStringBuilder

AppendFormat

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

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();

Inputs

arg ANY

format ZString

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

Returns

IStringBuilder

AppendInt

METHOD AppendInt (
 [input] val : INT) : ZCore.IStringBuilder

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.

Inputs

val INT

Returns

IStringBuilder

AppendLreal

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

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.

Inputs

val LREAL
decimalPlaces SINT

Returns

IStringBuilder

AppendOnOff

METHOD AppendOnOff (
 [input] val : BOOL) : ZCore.IStringBuilder

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.

Inputs

val BOOL

Returns

IStringBuilder

AppendParamBool

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

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.

Inputs

name STRING
val BOOL

Returns

IStringBuilder

AppendParamDint

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

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.

Inputs

name STRING
val DINT
unit STRING(10)

Returns

IStringBuilder

AppendParamInt

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

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.

Inputs

name STRING
val INT
unit STRING(10)

Returns

IStringBuilder

AppendParamLreal

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

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.

Inputs

name STRING
val LREAL
decimalPlaces SINT
unit STRING(10)

Returns

IStringBuilder

AppendParamOnOff

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

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.

Inputs

name STRING
val BOOL

Returns

IStringBuilder

AppendParamReal

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

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.

Inputs

name STRING
val REAL
decimalPlaces SINT
unit STRING(10)

Returns

IStringBuilder

AppendParamString

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

_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.

Inputs

name STRING
str STRING

Returns

IStringBuilder

AppendParamUdint

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

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.

Inputs

name STRING
val UDINT
unit STRING(10)

Returns

IStringBuilder

AppendParamUint

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

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.

Inputs

name STRING
val UINT
unit STRING(10)

Returns

IStringBuilder

AppendParamUlint

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

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.

Inputs

name STRING
val ULINT
unit STRING(10)

Returns

IStringBuilder

AppendParamYesNo

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

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.

Inputs

name STRING
val BOOL

Returns

IStringBuilder

AppendReal

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

_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.

Inputs

val REAL
decimalPlaces SINT

Returns

IStringBuilder

AppendRef

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

see Append

Inputs

text REFERENCE TO ZString

Returns

IStringBuilder

AppendUdint

METHOD AppendUdint (
 [input] val : UDINT) : ZCore.IStringBuilder

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.

Inputs

val UDINT

Returns

IStringBuilder

AppendUint

METHOD AppendUint (
 [input] val : UINT) : ZCore.IStringBuilder

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.

Inputs

val UINT

Returns

IStringBuilder

AppendUlint

METHOD AppendUlint (
 [input] val : ULINT) : ZCore.IStringBuilder

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.

Inputs

val ULINT

Returns

IStringBuilder

AppendUrlEncoded

METHOD AppendUrlEncoded (
 [input] text : ZCore.ZString) : ZCore.IStringBuilder

 _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.

Inputs

text ZString

Returns

IStringBuilder

AppendYesNo

METHOD AppendYesNo (
 [input] val : BOOL) : ZCore.IStringBuilder

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.

Inputs

val BOOL

Returns

IStringBuilder

Reset

METHOD Reset () : ZCore.IStringBuilder

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.

Returns

IStringBuilder

ToString

METHOD ToString () : ZCore.ZString

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

Returns

ZString

Table of Contents

StringBuilder

Methods

Append

Inputs

Returns

AppendBool

Inputs

Returns

AppendDint

Inputs

Returns

AppendError

Inputs

Returns

AppendFormat

Inputs

Returns

AppendInt

Inputs

Returns

AppendLreal

Inputs

Returns

AppendOnOff

Inputs

Returns

AppendParamBool

Inputs

Returns

AppendParamDint

Inputs

Returns

AppendParamInt

Inputs

Returns

AppendParamLreal

Inputs

Returns

AppendParamOnOff

Inputs

Returns

AppendParamReal

Inputs

Returns

AppendParamString

Inputs

Returns

AppendParamUdint

Inputs

Returns

AppendParamUint

Inputs

Returns

AppendParamUlint

Inputs

Returns

AppendParamYesNo

Inputs

Returns

AppendReal

Inputs

Returns

AppendRef

Inputs

Returns

AppendUdint

Inputs

Returns

AppendUint

Inputs

Returns

AppendUlint

Inputs

Returns

AppendUrlEncoded

Inputs

Returns

AppendYesNo

Inputs