|
CHANGE stage v1.2 |
Pipelines v2.1 |
|
Syntax |
┌─STRing─┐
>>──CHANGE──┬─────────┬──┤ Range ├──┼────────┼──fromstring──tostring──┬───────────┬──><
└─ANYCase─┘ └─REGexp─┘ └─maxchange─┘
Range: ┌─1-*─────────────────┐├──┼─────────────────────┼────────────────────────────────────────────────────────────┤ ├─columnrange─────────┤
│
┌─<───────────┐ │
└─(─┴─columnrange─┴─)─┘ Notes:(1) columnrange is unsigned.
|
Purpose |
Use the CHANGE stage to replace a character
or string of characters with another character or string of characters of the
same or different length. CHANGE reads records from its primary input stream,
replacing any occurrences of fromstring
that are found within the specified columnrange
with tostring, and writes the records
to its primary output stream. If fromstring
does not appear in an input record, CHANGE writes the record unchanged to its
secondary output stream, if it is connected, otherwise it writes the unchanged
record to its primary output stream.
|
Operands |
|
● |
ANYCase when specified in conjunction with the
STRING operand; the case of letters
are preserved in the following manner: The text
specified in fromstring and in the
input record are compared in uppercase. If fromstring is found and contains one or more uppercase characters
or contains no letters; then tostring
replaces the given text in the output record without change of case.
Otherwise, an attempt is made to preserve the case of the text being
replaced. When the text contains no uppercase letters and starts with one or
more lowercase letters, the following rules determine the case of the
replacement text in tostring. |
||||||
|
|
|
||||||
|
|
When specified in conjunction with the REGEXP
operand; the regular expression fromstring
is compared with the contents of an input record without regard to case. |
||||||
|
● |
is an unsigned integer column range in which to search for fromstring. If you do not specify columnrange, CHANGE searches the
entire record for occurrences of fromstring.
You can specify any number of columnrange operands. If you specify
more than one, you must place at least one space between each columnrange and you must enclose the
set of columnrange operands within
parentheses. If you specify more than one columnrange
operand, the range of columns must not overlap. |
||||||
|
● |
STRing specifies that the fromstring and tostring operands are literal strings. |
||||||
|
● |
REGexp specifies that the fromstring
operand is a regular expression of characters to locate
and the tostring operand is an
expression format string. |
||||||
|
● |
in conjunction with the STRING operand; fromstring defines a string that is to be replaced by tostring. If you specify a null string for fromstring, CHANGE inserts tostring immediately before the first column of the columnrange which defines the leftmost column of the record. When used in conjunction with the REGEXP operand; fromstring is a regular expression of characters to locate. If columnrange
is not specified and if both fromstring
and tostring consist only of decimal
numbers (0-9), you cannot specify a left parenthesis or a number as the
delimiting character. |
||||||
|
● |
in conjunction with the STRING operand; tostring defines a
string that is to replace fromstring.
If you specify a null string for tostring,
CHANGE deletes occurrences of fromstring
within the range or ranges you specify for columnrange. When used in conjunction with the REGEXP operand; tostring defines a format string which
specifies the way in which the occurrences of the expression fromstring are to be changed/formatted. |
||||||
|
|
|
|
Streams |
The following streams are used by the CHANGE stage:
|
|
Usage |
|
1. |
CHANGE
does not delay the records. |
|
2. |
If
the CHANGE stage discovers that all of its output streams are not connected,
the CHANGE stage ends. |
|
3. |
If columnrange is not specified and if both fromstring and tostring
consist of only decimal numbers (0-9), you cannot specify a left parenthesis
or a number as the delimiting character. For example: change /8//9/
is not equivalent to change 383393
The first CHANGE stage changes the
string 8 to 9. The second stage results in an error message because 383393 is processed as a columnrange
operand rather than a delimited string. The error message is issued because fromstring and tostring are missing and they are required operands. |
|
4. |
CHANGE can also be used to delete words.
By specifying a NULL tostring; for instance '//', CHANGE will effectively delete the
word specified by fromstring. See
the following ooRexx example: deleting words. |
|
5. |
CHANGE verifies that its secondary
input stream is not connected and then begins execution. |
|
Examples |
The following examples of the CHANGE command use the ANYCASE operand and the rules that apply for preserving the case of letters.
|
1. |
'pipe literal /Mick/ | change anycase /mick/ /mack/ | console' output:Mack |
|
2. |
'pipe literal /Mack MacNeill/ | change anycase /mac/ /mc/ | console' output:Mck McNeill |
|
3. |
'pipe literal /Mack MacNeill/ | change anycase /macn/ /mcn/ | console' output:Mack Mcneill |
|
4. |
'pipe literal /Mack MacNeill/ | change anycase /macn/ /mcN/ | console' output:Mack McNeill |
|
5. |
'pipe literal /Mack MacNeill/ | change anycase /Macn/ /mcn/ | console' output:Mack mcneill |
|
6. |
'pipe literal /Mack MacNeill/ | change anycase /MacN/ /McN/ | console' output:Mack McNeill |
|
7. |
This
example shows how you can delete uppercase and lowercase combinations of a
word using the ANYCASE operand with a regular expression. |
|
Related |
|
History |
|
Version |
Date |
Action |
Description |
Pipelines |
|
1.2 |
??.??.2024 |
changed |
Application-wide rewrite. |
|
|
04.02.2012 |
added |
Support for
the REGEXP operand; which specifies that the fromstring and tostring
operands are interpreted as a regular expression and a format string,
respectively. |
||
|
1.0 |
06.09.2007 |
created |
First version. |
|
|