REPLACE( ) method

Replaces an item in a combo box, radio set, or selection list. Replaces an existing text string in an editor with a new text string.

Return type:

LOGICAL

Applies to:

BROWSE widget (column), COMBO-BOX widget, EDITOR widget, RADIO-SET widget, SELECTION-LIST widget

This is the syntax for combo-box, selection-list or browse column.

 

Syntax (combo-box, selection-list, or browse column)

REPLACE ( { new-item-list | new-label , new-value }   , { list-item | list-index } )

new-item-list

A character-string expression that specifies a single item or a delimiter-separated list of items to add to the widget.

new-label

A character-string expression that specifies the label of a label-value pair to add to the widget.

new-value

The new value assigned when a user selects the label.

Note:

Use new-item-list when the widget’s entries consist of single items. Use new-label and new-value when the widget’s entries consist of label-value pairs.

list-item

A character-string expression that specifies a single value in the widget.

list-index

An integer expression that specifies the ordinal position of an existing entry in the combo box list or selection list.

For combo boxes and selection lists, REPLACE replaces list-item with either new-label-list or the label-value pair represented by new-label and new-value. If list-item is currently selected, the new item is not selected when it appears in the list. If the method is successful, it returns TRUE.

For browses, this method applies only to combo-box browse columns.

This is the syntax for an editor:

 

Syntax (editor)

REPLACE ( old-string , new-string , flag )

old-string

A character-string expression to be replaced. For the large editor widget in Windows, you can use wildcard characters for regular expression pattern matching. A question mark(?) in a particular position indicated that any single character is acceptable in that position. An asterisk (*) indicates that any group of characters is acceptable, including a null group of characters. If you want to specify a question mark (?) or asterisk (*) as a literal character rather than a wildcard character in the string, use ?? and ** respectively.

new-string

A character-string expression to replace old-string.

flag

An integer expression that specifies the type of search to be performed.

For editors, REPLACE searches from the current text cursor position for an occurrence of old-string and replaces it with new-string. If the replace operation is successful, the method returns TRUE. The flag value determines the type of search and replace to perform. Table 101 lists the flag values that correspond to each search and replace type.

 

Table 101:

REPLACE flag values

Type of search	Flag value
FIND-NEXT-OCCURRENCE	1
FIND-PREV-OCCURRENCE	2
FIND-CASE-SENSITIVE	4
FIND-GLOBAL	8
FIND-WRAP-AROUND	16

For a single operation, you cannot specify both FIND-NEXT-OCCURRENCE and FIND-PREV-OCCURRENCE, nor can you specify both FIND-WRAP-AROUND and FIND-GLOBAL. All other combinations of flags are valid. For example, you can specify a combination of FIND-NEXT-OCCURRENCE + FIND-GLOBAL + FIND-CASE-SENSITIVE. The default is FIND-NEXT_OCCURRENCE to search to the end of the editor string.

 

Syntax (radio-set)

REPLACE ( new-label , new-value , old-label )

new-label

A character-string expression that specifies the new item label.

new-value

The new value assigned when a user selects the item.

old-label

A character-string expression that specifies the label of the item to be replaced.

The REPLACE( ) method for radio sets replaces the label, the value, or both the label and value of the specified radio item. To retain the existing label or value, substitute an empty string.

REPLACE( new-label , new-value , old-label ) replaces the specified radio item with a new item, consisting of both a new label and a new value.

REPLACE( new-label , "" , old-label ) replaces only the label of the specified radio item, retaining the value.

REPLACE( "" , new-value , old-label ) replaces only the value of the specified radio item, retaining the label.

If the new label is longer than the existing radio set size can accommodate, the radio set appearance changes depending on setting of the AUTO-RESIZE attribute. If AUTO-RESIZE is TRUE, the radio set expands to accommodate the label. If AUTO-RESIZE is FALSE, the new label is clipped to fit the current size. However, note that the label is clipped only on the display. The new radio set item is identified by the full label regardless of its length.

If the replace operation is successful, the method returns TRUE.