B4P Reference

Function Names

substitute, substitute all

Description

The function substitute substitutes the first occurrence of the specified old contents by new contents.
The function substitute all substitutes all occurrences of the specified old contents by new contents.

Comparing wtih the replace() function, the 1st parameter is an input-output parameter where the contents are modified:
substitute( a[], "Hello", "Hi" ); is the same as a[] = replace( a[], "Hello", "Hi" );

Call as: procedure

Restrictions

Indirect parameter passing is disabled

Parameter count

3-4

Parameters

No.	Type	Description
1 io	string	input string Destination string with contents to substitute
2 input	parameter set or string	existing contents If provided as a string: The string will be looked for this content. If provided as a parameter set: The string will be looked for all contents provided in the parameter set. Note: If the string is an unquoted or softquoted string, then the three wildcard symbols '?', '#' and '^' will apply, which are placeholders for single characters, numbers and alphabetic letters repsectively.
3 input	parameter set or string	new contents These new contents will be inserted. If provided as a string: New contents to replacing the identified old contents. If provided as a parameter set: Number of elements must either be equal to the number of elements in the 2nd function parameter, or just 1 element
Opt. 4 input	numeral	starting position String substitution begins at a specified characcter position. For example, 2 skips the first two chracters in the input string. Default value: 0

Exceptions

3rd parameter contains different number of elements than 2nd parameter, and is not 1

Examples

      original[] = "the house, the mouse, and the spouse";



      st1[] = original[];

      st2[] = original[];

      substitute     ( st1[], the, a );

      substitute all ( st2[], the, a );

      echo(st1[]);

      echo(st2[]);



      st1[] = original[];

      st2[] = original[];

      substitute     ( st1[], { the, spouse, mouse, house }, { THE, SPOUSE, MOUSE, HOUSE } );

      substitute all ( st2[], { the, spouse, mouse, house }, { THE, SPOUSE, MOUSE, HOUSE } );

      echo(st1[]);

      echo(st2[]);

Output

a house, the mouse, and the spouse
a house, a mouse, and a spouse
THE HOUSE, the MOUSE, and the SPOUSE
THE HOUSE, THE MOUSE, and THE SPOUSE

Try it yourself: Open LIB_Function_substitute.b4p in B4P_Examples.zip. Decompress before use.

substitute, substitute all