REPLACE block
Short summary
Name |
REPLACE |
→POU type |
|
Category |
|
Conform to →IEC-standard |
currently restricted
|
Graphical interface |
|
Available since |
version 1.31.0 (for logi.CAD 3) |
Functionality
The block replaces a part of a string by another string and returns the newly created string.
At input IN1, enter a string (= 1st string). At input IN2, enter another string (= 2nd string). At input L, enter the number of characters to replace (= the length of the part to delete). At input P, enter the position within the 1st string. The block begins at this position to delete the characters and to insert the 2nd string instead of the deleted characters.
Special cases (see under "Example for usage within ST-editor" ) :
In case of L = 0, the block does not delete any characters in the 1st string. The 2nd string value is inserted at the position P. In this case, the output ENO is set to value TRUE.
If a negative value is connected to L, the corresponding characters before the position P are deleted in the string. In this case, the output ENO is set to value FALSE. If the block would delete characters outside of the visible range (in front of position 1), the block does not delete and insert any characters.
If the value 0 or a negative value is connected to P, the block does not delete and insert any characters. In this case, the output ENO is set to value FALSE as well.
If the value for L and/or P is > the length of the string for IN1, the block does not delete any characters or just the characters that are within the visible range. In case of P > length of the string, the newly created string is filled with blanks until before the position P, the 2nd string is inserted beginning with P. In this case, the output ENO is set to value FALSE as well.
logi.CAD 3 determines the character positions within a string as follows: 1, 2, ..., n. 1 corresponds to the leftmost character position and n to the length of the string.
Three-character combination of the dollar sign ($) followed by two hexadecimal digits are evaluated as single character. Example: The string '$B15' (corresponds to '±5') consists of 2 characters. See →character string literal for more examples for those combinations.
Inputs, return value
|
Identifier |
Description |
|
Inputs: |
IN1 |
STRING |
1st input value (= string where to replace) |
IN2 |
STRING |
2nd input value (= string to insert) |
|
L |
USINT, UINT, UDINT, ULINT, SINT, INT, DINT or LINT(corresponds to →generic data type ANY_INT) |
number of characters to replace |
|
P |
USINT, UINT, UDINT, ULINT, SINT, INT, DINT or LINT(corresponds to →generic data type ANY_INT) |
start position in the 1st input value |
|
Return value: |
– |
STRING |
|
Input EN and output ENO are available when →calling the block. See "Execution control: EN, ENO" for information on input EN and output ENO.
See:
"Blocks for safe logic" whether this block is supported for developing safety-relevant applications.
"Highlighting safe logic in the FBD-editor" for the effects when using the block as a block for safe logic .
Internal error diagnostic for block
The block checks the would-be return value.
If the return value cannot be mapped in the available memory (the return value is too large), the output ENO of the block is set to value FALSE (or an equivalent). When you are using nested blocks with STRING values, observe that the memory for STRING values is restricted (see "In case of nested string blocks: How can the return value be entirely mapped ?" for details and examples).
The following special case might occur regarding this error case: If the result of the call is assigned to a variable that is used as input parameter for the call of this block as well (see the following example), the output ENO of the embracing →POU is set to value FALSE for this error case (but not the output ENO of the called block). Example: ResultString := REPLACE(IN1 := 'abc', IN2 := ResultString, L := 2, P := 1);
Moreover, the block checks the connected values whether a non-existent character position in a string is accessed. This is the case, if the value for L or P is > the length of the string for IN1, a negative value is connected to L or P or the value 0 is connected to P. The output ENO of the block is set to value FALSE (or an equivalent) in all these cases.
Example for usage within ST-editor
PROGRAM Test
VAR
result1, result3, result4, result5, result6, result7, result8, result9 : STRING[
15
];
result2 : STRING[
6
];
CheckENO1, CheckENO2, CheckENO3, CheckENO4, CheckENO5, CheckENO6, CheckENO7, CheckENO8, CheckENO9 : BOOL;
END_VAR
result1 := REPLACE(IN1 :=
'a string'
, IN2 :=
'call'
, L :=
3
, P :=
3
, ENO => CheckENO1);
(* The variable
'result1'
evaluates to <
'a calling'
>. The variable
'CheckENO1'
evaluates to
'TRUE'
. *)
result2 := REPLACE(IN1 :=
'a string'
, IN2 :=
'call'
, L :=
3
, P :=
3
, ENO => CheckENO2);
(* The variable
'result2'
evaluates to <
'a call'
>. The variable
'CheckENO2'
evaluates to
'FALSE'
. Reason:
'result2'
is declared with length
'6'
and the would-be
return
value exceeds
this
length. *)
result3 := REPLACE(IN1 :=
'a string'
, IN2 :=
'call'
, L :=
0
, P :=
3
, ENO => CheckENO3);
(* The variable
'result3'
evaluates to <
'a callstring'
>. The variable
'CheckENO3'
evaluates to
'TRUE'
. *)
result4 := REPLACE(IN1 :=
'a string'
, IN2 :=
'call'
, L := -
1
, P :=
2
, ENO => CheckENO4);
(* The variable
'result4'
evaluates to <
'call string'
>. The variable
'CheckENO4'
evaluates to
'FALSE'
. Reason: negative value
for
'L'
*)
result5 := REPLACE(IN1 :=
'a string'
, IN2 :=
'call'
, L := -
3
, P :=
2
, ENO => CheckENO5);
(* The variable
'result5'
evaluates to <
'a string'
>. The variable
'CheckENO5'
evaluates to
'FALSE'
. Reason: negative value
for
'L'
*)
(* None of the characters are deleted and inserted because characters outside the visible range would be deleted. *)
result6 := REPLACE(IN1 :=
'a string'
, IN2 :=
'call'
, L :=
3
, P := -
1
, ENO => CheckENO6);
(* The variable
'result6'
evaluates to <
'a string'
>. The variable
'CheckENO6'
evaluates to
'FALSE'
. Reason: negative value
for
'P'
*)
result7 := REPLACE(IN1 :=
'a string'
, IN2 :=
'call'
, L :=
12
, P :=
2
, ENO => CheckENO7);
(* The variable
'result7'
evaluates to <
'acall'
>. The variable
'CheckENO7'
evaluates to
'FALSE'
. Reason: value
for
'L'
> the length of string
'a string'
*)
result8 := REPLACE(IN1 :=
'a string'
, IN2 :=
'call'
, L :=
3
, P :=
10
, ENO => CheckENO8);
(* The variable
'result8'
evaluates to <
'a string call'
>. The variable
'CheckENO8'
evaluates to
'FALSE'
. Reason: value
for
'P'
> the length of string
'a string'
*)
result9 := REPLACE(IN1 :=
'$B15 deviation'
, IN2 :=
'80'
, L :=
1
, P :=
2
, ENO => CheckENO9);
(* The variable
'result9'
evaluates to <
'$B180 deviation'
>. The variable
'CheckENO9'
evaluates to
'TRUE'
. *)
END_PROGRAM
When creating your application within the ST-editor, enter a call of a block by typing the text as requested by the syntax or use Content Assist.