-

STRING_COPY

Type Function
Description Performs a bytewise copy of each character of an input string (STRING, WSTRING data type) into a buffer (any array, typically an array of bytes).

The array index where the copy of the first character of the input string has to start is specified using the BUF_OFF parameter. This parameter determines the byte offset inside the buffer. The offset is calculated as follows:

        BUF_OFF = Array index at which copying has to start x Size in bytes occupied by each array element

Example:

If you have an array of DINT elements (each element occupies 4 bytes) and you want to start copying from array index [3], BUF_OFF must have the following value (see also the examples below):

        MyArray : ARRAY[0..5] OF DINT;

        BUF_OFF = 3 x SIZEOF(DINT) = 3 x 4 = 12
Notes
  • Check that BUFFER length starting at BUF_OFF is >= CNT otherwise nothing will be copied; the function returns the value FALSE.
  • If the number of characters of the input string (IN) is less than CNT, nothing will be copied; the function returns the value FALSE.
  • The trailing null character \0 at strings will not be copied. Only the string characters will be copied.
  • The input parameters IN, BUFFER, and CNT must match to each other so that the function is executed correctly and the entire input string is copied into the buffer. Characters of the input string are truncated and not copied into the buffer in the following cases:

    • The number of characters of the input string (IN) is greater than CNT; the function returns the value TRUE. The number of characters (CNT) of the input string are copied into the array.
    • The size of array elements (starting at BUF_OFF) is less than CNT; the function returns the value FALSE. There are no characters copied into the array.
  • Consider with the starting address of a buffer containing STRUCTs. The STRUCT may contain padding bytes due to alignment that are also written and are not considered when using the function SIZEOF to determine the number of bytes occupied by the STRUCT elements.
  • This function should only be used if an array is needed. Otherwise the function GET_CHAR should be used.
Parameters Inputs

IN

BUFFER

BUF_OFF

CNT

Output

OUT
Error behavior Error behavior
Additional information EN/ENO behavior
Examples Examples in ST