## Character enumeration guide

## General

Consider an example source string value of ABCDwxyz. The columns for this value are enumerated as follows:

12345678 |
← |
normal enumeration column numbers |
||

ABCDwxyz |
||||

end-relative enumeration column numbers with * suffix |
→ |
87654321 |

Notes:

- Throughout this document, when column references appear in explanations and examples, they are color-coded to help remind you which type of column reference or enumeration type is being used.

Since there are a limited number of useful colors available, a given color may be used for more than one purpose; red will often but not always mean end-relative. Read the context to confirm the meaning.

- For fixed-length data, normal enumeration is the easiest to understand and use. Follow the examples below in blue for normal column range notation.

- When your goal is to access the right-hand “tail” portion of a value, the remaining-columns notation can be useful. To select an entire string value (like ABCDwxyz above) you can use a using remaining-columns reference with a 1+ notation. This will work for a string of any length.

When starting column number is 1, the 1 can be omitted and you can use the + plus by itself to mean the same as 1+. When + is used in this way, it is comparable to the ! Picture code that copies the entire found string. A + plus sign, whether preceded by a number or alone, must always be followed by a blank, unless it's the last thing in your mapping string.

- When you are dealing with variable-length data, perhaps as found by a Regular Expression find string on your CHANGE command, the end-relative and mixed-mode end-relative notations can help you deal with data when you don't know its exact size in advance.

- When it is easier to view your data from the standpoint of its right-hand end (wherever that may be), end-relative enumeration is a convenient notation, in which your column numbers are “reversed” (as compared to how normal column notation does it), and an “*” asterisk suffix is used. (By “reversed”, refer to the red column numbers in the diagram above.) Follow the examples below in red for end‑relative column range notation, noting carefully the column-number ordering that is used.

- For mixed-mode end-relative notation, the first (left-hand) number always uses normal enumeration, while the second (right-hand) number always uses end-relative enumeration. The separator for these numbers is a / slash to indicate forward column ordering, and is a \ backslash to indicate reverse column ordering. Mixed-mode end-relative notation can be useful in cases where, for example, you want to reference all but the first 2 and last 2 positions of a value and start with relative position 3 in both directions; you would do that with a 3/3* column reference. Follow the examples below in violet for mixed-mode end-relative column range notation, observing carefully the special syntax it uses.

Note that only by using a \ backslash do you indicate column reversal in mixed-mode enumeration; you do not reverse the numbers to indicate column reversal, as is done with normal enumeration.

Examples using the source string ABCDwxyz:

To explicitly reference the entire source string normally as ABCDwxyz:

1-8 normal column range notation

8-1* end-relative column range notation

1/1* mixed-mode end-relative column range notation, forward

1+ remaining-columns notation

To explicitly reference the entire source string in reverse to obtain zyxwDCBA:

8-1 normal column range notation

1-8* end-relative column range notation

1\1* mixed-mode end-relative column range notation, reversed order

\1+ reversed order remaining-columns notation

To locate substring ABCD within the source string:

1-4 normal column range notation

8-5* end-relative column range notation

1/5* mixed-mode end-relative column range notation, forward

To locate substring wxyz within the source string:

5-8 normal column range notation

4-1* end-relative column range notation

5/1* mixed-mode end-relative column range notation, forward

5+ remaining-columns notation

To locate and reverse substring ABCD within the source string to get DCBA:

4-1 normal column range notation

5-8* end-relative column range notation

1\5* mixed-mode end-relative column range notation, reversed order

To locate and reverse substring wxyz within the source string to get zyxw:

8-5 normal column range notation

1-4* end-relative column range notation

5\1* mixed-mode end-relative column range notation, reversed order

\5+ reversed order remaining-columns notation

To locate substring BCDwxy within the source string:

2-7 normal column range notation

7-2* end-relative column range notation

2/2* mixed-mode end-relative column range notation, forward

To locate and reverse substring BCDwxy within the source string to get yxwDCB:

7-2 normal column range notation

2-7* end-relative column range notation

2\2* mixed-mode end-relative column range notation, reversed order

## Column Reference Syntax

[ dot-notation ] column-item

Column-item: one of the following formats:

5 single column, normal notation

5* single column, end-relative notation

1-4 column range, forward order, normal notation

4-1 column range, reversed order, normal notation

8-5* column range, forward order, end-relative notation

5-8* column range, reversed order, end-relative notation

2/3* column range, forward order, mixed-mode end-relative notation

2\3* column range, reversed order, mixed-mode end-relative notation

5+ remaining columns (like 5 and above), forward order

\5+ remaining columns (like 5 and above), reversed order

0 as-yet-unreferenced source-string columns, forward order

\0 as-yet-unreferenced source-string columns, reversed order

When a column reference appears by itself without an associated command code, the column reference is considered a copying command that refers to data in the source string; it would require dot notation to make it refer to the current result string.

For example, to copy column 1 to 4 of the source string into the result string, simply specify 1-4 without a command code. To copy column 1 to 4 from the beginning of the result string and appending it to the end of that same result string, specify .1-4 without a command code.

When a column reference appears as part of a command code, it is treated like an operand to that command. See Specific Command Coding Notes for complete information on how each command code operates, and how it treats its operands.

## Dot Notation

When a column reference is preceded by a dot, the reference is to the current contents of the result string at the time the reference is made.

Without the dot, it may reference to the original source string or to the result string, depending on whether a copying command or a modifying command is used.

- When a command is a copying command, dot notation causes a column reference to refer to the current contents of the result string instead of the source string.

- When a command is a modifying command, all column references refer to the current contents of the result string regardless of whether . dot notation is used or not. A modifying command always refers to the result string, and so “dot mode” is implied for such commands.

See description of each command code for the meaning of the column reference operand for that command.

1-4 may refer to columns 1-4 in the source string or in the result string

.1-4 refers to columns 1-4 in the result string only

Dot-notation cannot be combined with unreferenced columns (column number of 0).

Created with the Personal Edition of HelpNDoc: Create help files for the Qt Help Framework