docs

Home All functions Categories

vuReplaceCharsEx(MainStrg, MainSize, OldStrg, NewStrg)

vuReplaceCharsEx(*CSTRING,LONG,*CSTRING,*CSTRING), Long

Description

Replaces all occurrences of OldStrg with NewStrg inside MainStrg. The caller supplies MainStrg’s total allocated buffer capacity so the function can verify the entire result will fit, including the terminating null byte, before changing MainStrg.

This is the recommended alternative to the legacy vuReplaceChars function for new applications.

Parameters

Parameter Data Type Description
MainStrg CSTRING Destination CSTRING, updated in place only after validation succeeds. Must be null-terminated within MainSize bytes.
MainSize LONG Total allocated bytes of MainStrg including the terminating null. For a Clarion CSTRING, normally pass SIZE(MainStrg). This value must reflect the actual buffer capacity.
OldStrg CSTRING Substring to find. Must not be empty.
NewStrg CSTRING Replacement substring. May be empty, shorter, or longer than OldStrg.

Returns

LONG return Meaning
1 The operation completed. If no occurrences of OldStrg were present, MainStrg stays unchanged and the function still returns 1.
0 Validation failed: invalid MainSize, empty OldStrg, missing null terminator within the supplied buffer, or a replacement result too large to fit. MainStrg is left unchanged.

The returned LONG is not the resulting string and does not count replacements.

Example

MainStrg CSTRING(256)
OldStrg  CSTRING(128)
NewStrg  CSTRING(128)
Result   LONG

CODE
MainStrg = 'Microsoft Windows XP is no longer supported.'
OldStrg  = 'Windows XP'
NewStrg  = 'Windows Vista'

Result = vuReplaceCharsEx(MainStrg, SIZE(MainStrg), OldStrg, NewStrg)
IF Result = 1
  MESSAGE(MainStrg)  ! Microsoft Windows Vista is no longer supported.
ELSE
  MESSAGE('Replacement failed or destination too small.')
END

Notes

Home All functions Categories