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" );

Note:In case you want to use vectorization, please use replace resp. replace all instead.

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	set or string	existing contents If provided as a string: The string will be looked for this content. If provided as a set: The string will be looked for all contents provided in the set. Note: If the string is a softquoted string, then the three wildcard symbols '?', '#' and '^' will apply, which are placeholders for single characters, numbers and alphabetic letters repsectively.
3 input	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 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