Update for ND6.... Since ND6 allows strings the size of 2 GB, this function needs to be updated - the position within a string can be longer than an Integer variable can handle. So Integer has been changed to Long in the function.

This is a LotusScript function which mimics the @ReplaceSubstring function in the formula language.

The function takes three parameters as input:
sourcestr - the string to be changed
fromstr - the substring that you wish to change
tostr - the string you wish fromstr to become.

The output is a new string.

For example:
newString = ReplaceSubstring("abcdef", "b", "x")
which will result in newString having a value of "axcdef".

The third parameter can be null, which would remove all occurrences of the substring.

If the second parameter is null or there are no instances of that substring in sourcestr, the original string will be returned.

Revision: the old version would not handle a call of, for example, ReplaceSubstring("a+b", "+", "++") since the source string was part of the destination string. This new version handles that situation.

Here is the source code....

Function ReplaceSubstring(sourcestr As String, fromstr As String, tostr As String) As String
   ' This function replaces characters in a string. Take all the occurrences of "fromstr"
   ' in the source string and replace them with "tostr"
   Dim tempstr As String
   Dim convstr As String
   Dim i As Long
   Dim length As Long
   tempstr = sourcestr
   If Len(fromstr) = 0 Then
      ReplaceSubstring = sourcestr
      Exit Function
   End If
   If Instr(tostr, fromstr) <> 0 Then ' If, for example, "\" is being replaced with "\\"
      ' Find a character (or set) that is not in the source string.
      ' Try the extended characters (over 128 ASCII)
      i = 128
      length = 1
      convstr = ""
      While convstr = ""
         If Instr(tempstr, String$(length, Chr$(i))) = 0 Then convstr = String$(length, Chr$(i))
         i = i + 1
         If i = 256 Then ' If all the extended characters were in there
            length = length + 1 ' Start over, but try 2 extended characters (or 3 or 4)
            i = 128
         End If
      Wend
      ' Go through tempstr twice - once replacing fromstr with the computed
      ' string, then replacing the computed string with tostr
      While Instr(tempstr, fromstr) <> 0
         tempstr = Left(tempstr, Instr(tempstr, fromstr)-1) & convstr _
         & Mid(tempstr, Instr(tempstr, fromstr)+Len(fromstr))
      Wend
      While Instr(tempstr, convstr) <> 0
         tempstr = Left(tempstr, Instr(tempstr, convstr)-1) & tostr _
         & Mid(tempstr, Instr(tempstr, convstr)+Len(convstr))
      Wend
   Else ' It's a normal replace substring call - fromstr is not part of tostr
      While Instr(tempstr, fromstr) <> 0
         tempstr = Left(tempstr, Instr(tempstr, fromstr)-1) & tostr _
         & Mid(tempstr, Instr(tempstr, fromstr)+Len(fromstr))
      Wend
   End If
   ReplaceSubstring = tempstr
End Function


Here are some examples.....

ReplaceSubstring("hellothere", "l", "x") = "hexxothere"
ReplaceSubstring("this is a string", "is", "x") = "thx x a string"
ReplaceSubstring("Here is a long string", "", "xxx") = "Here is a long string"
ReplaceSubstring("Here is a long string", " ", "") = "Hereisalongstring"
ReplaceSubstring("\mysubdir\mydatabase.nsf", "\", "/") = "/mysubdir/mydatabase.nsf"
ReplaceSubstring("literal \s\w characters", "\", "\\") = "literal \\s\\w characters"
ReplaceSubstring("Getting rid of unwanted words", "unwanted", "unneeded") = "Getting rid of unneeded words"

There is also a more generic way of using this function. The more generic way uses variants for the parameters, which means that you could pass arrays of values. The arrays will be treated in exactly the same way as arrays in the formula language @ReplaceSubstring. Refer to Notes help if you don't know how that works. That code is on the next page....