18.4.0 released Sep 25, 2023
Copy string

Purpose: Copies string to another string.

copy-string <source string> to [ define ] <dest string> \
    [ ( length [ define ] <length> ) \
        | ( [ bytes-written [ define ] <bytes written> ) ]

Use copy-string to copy <source string> to <dest string> (which can be created with optional "define"). <dest string> is allocated memory.

Without "length" clause, <source string> is treated as a null-terminated string and the number of bytes to copy is computed as its length. With "length" clause, exactly <length> bytes are copied into <dest string>, regardless of whether there is a null-character within <source string>, i.e. you can copy binary data this way. Regardless of whether "length" clause is used or not, <dest string> will always have a null-character at the end.

If "bytes-written" clause is used, then the number of bytes copied is stored into <bytes written>, which can be created with optional "define". "bytes-written" can be used only if "length" is not used, for obvious reason, as the two are equal otherwise. <bytes written> does not include the null-character placed at the end.

You can copy a string to itself. In this case, the original string remains and the new string points to a copy:
char *str = "original string"; // string to change

char *orig = str; // points to original copy of the string to change

copy-string str to str // make a copy of string to change and assign it to itself

str[0] = 'O'; // change the copy

// Now "str" points to "Original string" 
// and "orig" points to "original string"

After copy-string below, "my_str" will point to a copy of string "some value", and "bw" will be 10:
char *other_string="some value";
copy-string other_string to define my_str bytes-written define bw

Copy certain number of bytes, the result in "my_str" will be "som":
char *other_string="some value";
copy-string other_string to define my_str length 3

See also
See all

You are free to copy, redistribute and adapt this web page (even commercially), as long as you give credit and provide a link back to this page (dofollow) - see full license at CC-BY-4.0. Copyright (c) 2019-2023 Dasoftver LLC. Vely and elephant logo are trademarks of Dasoftver LLC. The software and information on this web site are provided "AS IS" and without any warranties or guarantees of any kind.