QMChange()

The QMChange() function replaces occurrences of one substring with another in a string. It is analogous to the QMBasic CHANGE() function.

Format

VB	QMChange(ByVal Src as String, ByVal OldStr as String, ByVal NewStr as String, Optional ByRef Occurrences as Long, Optional ByRef Start as Long) as String

C	char * QMChange(char * Src, char * OldStr, char * NewStr, int Occurrences, int Start)

where

Src	is the string to be processed.

OldStr

is the substring to be replaced.

NewStr

is the replacement substring.

Occurrences

is the number of occurrences of OldStr to be replaced. If omitted or specified as less than one, all occurrences are replaced.

Start

is the occurrence number from one of the first occurrence of OldStr to be replaced. If omitted or less than one, replacement commences at the first occurrence of OldStr.

The QMChange() function returns a new string with the specified substrings replaced.

One use of QMChange() is to replace mark characters with carriage return / line feed pairs when transferring data from a dynamic array to a multi-line text box.

Note that in the C API library, a statement of the form

rec = QMChange(rec, old, new, 0, 0)

will return a pointer to a newly allocated memory area, overwriting the rec pointer. The old memory is not freed by this call and it is therefore necessary to retain a pointer to the original rec string so that it can be freed later.

Examples

VB	X = QMChange("ABRACADABRA", "A", "a", 3, 2)
C	X = QMChange("ABRACADABRA", "A", "a", 3, 2);

The above example changes three uppercase letter "A" to lowercase "a" in the supplied string starting at the second occurrence, returning the result. Note that the C version will set X too point to a dynamically allocated memory areas that must be released later using QMFree().