Replace

(Engine-Level Function)

Description:	Performs a case sensitive search and replace operation on a buffer and returns the resulting buffer.
Returns:	Buffer
Usage:	Script or steady state.
Function Groups:	String and Buffer
Related to:	Locate
Format:	Replace(Buffer, Offset, N, Search, Replace)
Parameters:

Buffer

Required. Any text expression giving the buffer to search. There is no limit on the size of the buffer.

Offset

Required. Any numeric expression giving the buffer offset from 0 to start the search. Must be non-negative, otherwise Invalid will be returned.

N

Required. Any numeric expression giving the number of buffer characters (bytes) to search.

Search

Required. Any text expression giving the search string. The search is case sensitive. If an empty string is provided in this parameter, Replace will return the original text.

Replace

Required. Any text expression giving the replace string.

Comments:

This function returns a buffer that is the same as Buffer, except that within the first N bytes following Offset, all occurrences of Search are replaced with Replace. Because the search and replace strings are delimited by quotation marks, to include a set of quotation marks as part of either, you must use two sets of quotation marks inside of the quotation marks that delimit the string (see example).

Example:

If a variable exists such that:

txt = "abcdefABCDEF";

And the following statement is executed:

txt = Replace(txt { Buffer },
              0 { Start at beginning of buffer },
              12 { Search through 12 characters },
              "fA" { Search for this string },
              "-wow-" { Replace string with this });

The result will be that txt will contain the string "abcde-wow-BCDEF".

As a further example of how this function is used, if quotation marks were considered illegal characters in a certain context and therefore needed to removed from a string, the following statement could be used to achieve this:

txt = Replace(stringWithQuotes { Search buffer },
              0 { Start at beginning },
              StrLen(stringWithQuotes) { Search entire string },
              """" { Find all quotes },
              "" { Replace with nothing });