Use this function to remove a specific indexed component from the formatted list of items. The modified list of items is returned.
| Note | Use the CodeInList and ParseListCount functions to search( comma or semicolon) delimited data for indexed items. |
RemoveListItem(String, Index, Separator)
|
Parameter |
Description |
|
String |
The text string to parse where items are distinguished by a separator character (e.g. comma or semicolon) |
|
Index |
The index number of the item you want from within that formatted string. If you omit this parameter, the first indexed item parsed from the formatted text is removed. If the index is zero, negative, or a value greater than the number of items in the list, the returned text will be unmodified. |
|
Separator |
This is a set of character separators used within the formatted text parameter. If you omit this parameter, the comma and semicolon will be the set of valid separators used. Note that each character of the parameter data is considered a valid separating character and not the entire string as one unit. |
The return value is the delimited text string after removing the specified item. (This function must return a value and a syntax error will occur if used in a statement that does not pick up the returned value.)
For the purposes of discussion, assume you have this list of these 9 states in a text string.
States = "Hawaii,Idaho,Kansas,Ohio,Oregon,Texas,Utah,Vermont,Wyoming"
#ndx = CodeInList("Ohio",States)
The value of #ndx is 4.
States = RemoveListItem(States, #ndx)
States now contains: "Hawaii,Idaho,Kansas,Oregon,Texas,Utah,Vermont,Wyoming"
Removing the 4th item (“Ohio”) from the list also included removing the separator following the item. The resulting string continues to be a valid list of separated items. Now that the list is modified, there is a new item in the 4th position.
States = RemoveListItem(States, #ndx)
Since we did not change the value of #ndx (which is 4), calling the statement a second time will again remove the 4th item. Since “Oregon” is the 4th item at the point where this function is called, the value of States will become: "Hawaii,Idaho,Kansas,Texas,Utah,Vermont,Wyoming".
If you omit the second parameter that specifies the item to remove, this function will assume to remove the first item in the list.
States = RemoveListItem(States)
Prior to this statement, “Hawaii” was first and the list. After the statement, States now contains: "Idaho,Kansas,Texas,Utah,Vermont,Wyoming"
When the item index is zero, negative, or greater than the number of index items, the string of items will remain the same. The statements below demonstrate using zero and an index (10) greater than the number of items.
States = RemoveListItem(States, 0)
States = RemoveListItem(States, 10)
Executing these two statements has no effect on the result because the index is out of range. Therefore, the variable States still remains: "Idaho,Kansas,Texas,Utah,Vermont,Wyoming"
States = RemoveListItem(States, 2, "*-")
The next example specifies that the possible separator characters as the asterisk and dash.
States = RemoveListItem(States, 2, "*-")
Since there are no such characters separating the content, the content will be assumed a single item. (Remember, you do not need a separator at the end of the list.) The statement asks to find the second item which is not possible. Therefore, the string returned is unchanged and States continues to contain: "Idaho,Kansas,Texas,Utah,Vermont,Wyoming"
Now consider this example using the same separator lists.
States = RemoveListItem(States, 1, "*-")
Since there are no separators found matching the asterisk or dash, the assumption will be that there is only one item in the list. Since this statement asks to remove the first item, the result will be the variable States is now empty: (States = “”)
Take note and be sure not to use an incorrect set of separator characters for your data as your text will be considered a single item.
Finally, remember that the separator parameter is a “set” of characters. As a default, the comma and semicolon are considered valid separators. For instance, modify the original statement to the following.
States = "Hawaii,Idaho;Kansas;Ohio,Oregon,Texas,Utah,Vermont,Wyoming"
You will note the mix of commas and semicolons between items. Since these are the default separators, the list of states is still perceived the same.
#ndx = ParseListCount(States)
The value of #ndx is 9.
Note however, that since the RemoveListItem function is looking to modify the list, the separator used between items could change to match the first one in the set. For instance, consider this statement.
States = RemoveListItem(States, 8)
The result will be to remove “Vermont” (the eighth item). Notice the changed in separator between the earlier items that used semicolons. Since comma is the first item in the separator set, this has become the separator used in the result.
States will now be: "Hawaii,Idaho,Kansas,Ohio,Oregon,Texas,Utah,Wyoming"
Similarly, if the next statement specified the separators in a different order, the result would change again.
States = RemoveListItem(States, 8, ";,")
“Wyoming” is the eighth item before execution. In this statement, the set of separators is reversed from the default, so semicolon is considered first and then comma. The result of this statement will be that States contains: "Hawaii;Idaho;Kansas;Ohio;Oregon;Texas;Utah"
Notice how the items are now separated by semicolons instead of commas because the removal rebuilt the list and first separator specified in the set is the semicolon.
As a final note: Once the item to be removed has been located, the remainder of the search line will be unchanged. For instance, using the last value of States above where semicolons separate the items, execute the following statement.
States = RemoveListItem(States, 2, ",;")
After locating the second item – which is to be removed – the final value in States will be: "Hawaii,Kansas;Ohio;Oregon;Texas;Utah"
Here you see that the first item, which had to be parsed to find the second item, is now separated from subsequent items with a comma. However, note the rest of the line remains separated by semicolons as originally provided. This is because once the second item was located and removed, the rest of the line did not have to be parsed and was left unchanged.
Just be aware that if you use multiple separators in your items and are not consistent in how you specify the separator character set, the actual value used may change.
© Copyright 2016, Oracle and/or its affiliates. All rights reserved. Legal Notices