reSub Function

Purpose

Replaces a specified substring with another substring in a string using regular expressions.

Syntax

n = reSub(strvar, pattern, subst [, max])

reSub strvar, pattern, subst [, max]

n = reSub(array$(), pattern, subst, from, to [, hi[] [, max]])

reSub array$(), pattern, subst, from, to [, hi[] [, max]]

strvar:string variable
pattern, subst:string expression
from, to, max:iexp
hi[]:Hash Int
array$():string array
n:iexp

Description

reSub replaces occurrences of the regular expression pattern in the string variable strvar or string array array$() with subst. max specifies the maximum number of replacements to make. For example, the following statement replaces all spaces in a string:

reSub a$, " ", ""

If reSub is used as a function, then the return value indicates the number of replacements made. The number of spaces replaced in the following example is 3:

a$ = "This is a test"

n% = reSub(a$, " ", "")

The pattern "\s+" searches all spaces, tabs, #13, and #10.

a$ = "abc def ghi"

reSub a$, "\s+", "-" // result: "abc-def-ghi"

Like reMatch, reSub can replace in a one dimensional string array. The first parameter is a string array, and the second and third specify the search pattern and replacement text (like a simple reSub). These parameters are followed by the smallest and largest array indices to process. When only these parameters are specified (from, to), then only the first string at array$(from) is enclosed in the search and replace. When used as a function, reSub returns this index. An additional max limits the number of replacements (bug, which see). The following replacement affects only sa(0), the to parameter is redundant.

Debug.Show

Dim i As Integer

Dim sa$()

Array sa$() = "Turbo PasCall" #10 "MS C" #10 "MS Cpp" _

#10 "Visual Basic" #10 "Unix Perl" #10 "MS CSharp"

reSub sa(), " ", "-", 1, 1

For i = 0 To Dim?(sa()) - 1 : Trace sa(i) : Next

To replace a range of array elements a sixth parameter of type Hash Int is mandatory. (Dim hi As Hash Int). Then all string array elements between from and to are processed and their index is placed in hi[]. The return value or reSub is the number of replaced string elements (the same as hi[%]). When the search string pattern isn't found, then the Hash will not contain any entries, e.g. hi[%] = 0. Is hi[] omitted, then the return value is $8000000 = _MinInt. Not 0, because the searched string may have index = 0, with Dim x$(-9 .. 9) the index can even be negative.

Note: The parameter max seems to be erroneous. (see Known Issues)

Example

Debug.Show

Dim i As Integer

Dim sa$(), hi As Hash Int

Array sa$() = "Turbo PasCall" #10 "MS C" #10 "Cpp" _

#10 "Visual Basic" #10 "Unix Perl" #10 "MS CSharp"

Trace reSub(sa(), " ", "-", 0, UBound(sa()), hi[])

Debug "The elements that are processed:"

For Each i In hi[]

Debug i

Debug "The results:"

For i = 0 To Dim?(sa()) - 1

Trace sa(i)

This prints in the Output window:

TRACE:(1):reSub(sa(), " ", "-", 0, UBound(sa()), hi[]) = 5

The elements that are processed:

0
1
3
4
5

The results:

TRACE:(2):sa(i) = Turbo-PasCall
TRACE:(2):sa(i) = MS-C
TRACE:(2):sa(i) = Cpp
TRACE:(2):sa(i) = Visual-Basic
TRACE:(2):sa(i) = Unix-Perl
TRACE:(2):sa(i) = MS-CSharp

Remarks

The VB function a$ = Replace$(sexp, find, replace [, start[, count[, compare]]]) is easily converted to GFA-BASIC 32.

VB Replace Function

Dim sexp As String

sexp = Replace(sexp, "aa", "xx")

Print sexp

GFA-BASIC 32 reSub Command

Dim sexp As String

' Dim Cmp = Mode(Compare)

' Mode Compare 0

reSub sexp, "aa", "xx"

' Mode Compare Cmp

Print sexp

For an overview of the regular expressions in pattern see reMatch.

Known Issues

1. Both the reSub function and command can NOT take a non-variable string as their first parameter otherwise a 'Variable?' error will be raised; instead, the string needs to be defined as a variable first, then put into the reSub statement as below:

Local a$ = "This is a test"

reSub a$, " ", "-"

...instead of...

reSub "This is a test", " ", "-"

2. There have been reports that the max parameter does not work as described: apparently it does limit the number of replacements, but returns an incorrect result. However, these reports may be historic as the error examples that were listed now return the correct result.