REPLACERX; replacement callback function

REPLACERX type can be used with str.replacerx instead of replacement string. Definition:


type REPLACERX ifrom ito fcallout paramc frepl paramr $repl


ifrom - start from here. 0-based character index in s (subject string). Default: 0.

ito - do until here. Default: s length.

fcallout - callout callback function.

paramc - some value or pointer to be accessed by callout callback function.

frepl - replacement callback function.

paramr - some value or pointer to be accessed by replacement callback function.

repl - replacement string. Ignored if frepl is nonzero.


Before passing the variable to the function, you can set one or more members that you use, leaving other members uninitialized, that is 0.


If frepl and fcallout are 0, str.replacerx behavior is same as usually (when using replaceto string), plus you can set s portion (ifrom to ito) where replacements must occur.

Replacement callback function

If frepl is address of a user-defined function, the function is called each time when a match is found during replacement process. It provides replacement string.


A template is available in menu -> File -> New -> Templates.


The function must begin with:

function# REPLACERXCB&x


x is variable of type REPLACERXCB. This variable is filled by str.replacerx. Callback function can (and should) modify match and maybe some other members. In most cases you will only set match to be replacement string, and return 0.


type REPLACERXCB ~match ~strnew $subject CHARRANGE*vec lenv number REPLACERX*rrx


match - copy of matched substring. Function can modify it. It will become replacement string.

strnew - string that is being formatted from replacements and nonmatching portions of s. Finally it will replace s. Now it contains the portion of s from the beginning to the current match, with previous replacements.

subject - unmodified subject string ( s).

vec - array of offsets in s. First element (vec[0]) contains offsets (beginning and end) of match. Subsequent elements contain offsets for submatches. If n-th subexpression not found then vec[n].cpMin and vec[n].cpMax are -1.

lenv - number of elements in vec array. It can be 1 (if no submatches) or more.

number - number of replacements (1 on first replacement, 2 on second and so on).

rr - address of variable that was passed to str.replacerx.


Return values

0 indicates that match is replacement string. It will be appended to string being formatted. If match is not modified, matched substring will not be replaced.
> 0 indicates that nothing should be appended to string being formatted. This return value can be used either to remove matched substring, or when callback function itself appends replacement to strnew.
-1 stop replacement process. str.replacerx will return immediately. It returns number of replacements not including current, or -1 for single replacement mode. To stop replacement process and include current replacement, set x.rr.ito = 0.
< -1 generate error with this error number. Should be < -100.



 multiply all decimal numbers in s by 5:
str s="A2 B100"
s.replacerx("\d+" &r)
out s ;;A10 B500

#sub replacerx_callback
function# REPLACERXCB&x
x.match = val(x.match) * 5