REPLBYTES

The REPLBYTES function replaces one or more bytes in a text expression.

Return Value

TEXT

Syntax

REPLBYTES(text-expression replacement [start])

Arguments

text-expression: The expression in which REPLBYTES replaces bytes. When the bytes to replace from text-expression contain embedded line breaks, these breaks are removed. Other line breaks are preserved. Removed line breaks are not counted toward the total number of bytes replaced. Line breaks in the replacement expression are retained in the output of REPLBYTES, but are likewise not counted.
replacement: A text expression that contains one or more bytes that will replace existing bytes in text-expression.
start: An integer that represents the byte position at which to begin replacing bytes. The position of the first byte in text-expression is 1. When you omit this argument, REPLBYTES starts with the first byte. REPLBYTES replaces as many bytes of text-expression as are required for the bytes specified by replacement. When the value of start is greater than the length of text-expression, REPLBYTES simply returns text-expression.

Notes

Single-Byte Characters

When you are using a single-byte character set, you can use the REPLCHARS function instead of the REPLBYTES function.

NTEXT Data Type

This function does not accept NTEXT arguments, because it is oriented toward byte-manipulation instead of character manipulation. It always returns values of type TEXT. When you must use this function on NTEXT values, use the CONVERT or TO_CHAR function to convert the NTEXT value to TEXT.

Changing Occurrences of a Specified String in a Text Value

You can use the CHANGECHARS function to change one or more occurrences of a specified string in a text value to another string.

Examples

Example 20-22 Replacing Text as Bytes

This example shows how to replace a portion of the text value Hello there, Joe.

The statement

SHOW REPLBYTES('Hello there, Joe', 'Jane', 14)

produces the following output.

Hello there, Jane

Example 20-23 How REPLBYTES Handles Line Breaks

This example shows how REPLBYTES preserves but ignores line breaks.

var1 = JOINLINES('Hello' 'there' 'Joe')
var2 = JOINLINES('Hi' 'Jane')

The statement

SHOW REPLBYTES(var1 var2)

produces the following output.

Hi
Janehere
Joe

REPLBYTES has replaced the first 6 bytes of var1 (Hellot of HellothereJoe) with the 6 bytes of var2 (HiJane). It has preserved the line breaks following Hi (from var2) and there (from var1).

To replace all 13 bytes in var1, you must specify 13 replacement bytes; for example, you can add 7 spaces after Jane.

var2 = JOINLINES('Hi' 'Jane       ')

The statement

SHOW REPLBYTES(var1 var2)

produces the following output.

Hi
Jane