InsertListItem
Use this function to Insert/append a new item into a 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. |
Syntax
InsertListItem(String, Item, Index, Separator)
|
Parameter |
Description |
|
String |
The text string to parse where items are distinguished by a separator character (e.g. comma or semicolon) |
|
Item |
The new string to insert into the list of items. If this parameter is omitted or empty, the returned text will be unmodified and nothing is inserted. |
|
Index |
The index number where you want this new item inserted into the formatted string. If you omit this parameter, the item is appended to the end of the formatted text. If the index is zero, negative, or a value greater than the number of items in the list, the new item will be appended to the end of the list of items. |
|
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 inserting the specified item text. (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.)
Discussion and Examples
For the purposes of discussion, assume you have this existing list of states in a text string.
States = "Hawaii,Idaho,Kansas,Ohio,Texas"
#ndx = CodeInList("Ohio",States)
The value of #ndx is 4.
States = InsertListItem(States,"Montana",#ndx)
After this execution, States now contains: "Hawaii,Idaho,Kansas,Montana,Ohio,Texas"
This inserts Montana as the forth item in the list of items. Notice that the inserting means that both the content of the parameter and a new separator is added.
States = InsertListItem(States, "Alabama")
Omitting the index parameter simply appends the item to the existing list. The resulting data for States is now: "Hawaii,Idaho,Kansas,Montana,Ohio,Texas,Alabama"
When the index is zero, negative, or greater than the number of index items, the item will append to the end. The statements above demonstrate using zero and an index (10) greater than the number of items.
States = InsertListItem(States, "Oregon", -4)
States = InsertListItem(States, "Maine", 10)
Executing these two statements appended the items because the index is out of range. The variable States now contains: "Hawaii,Idaho,Kansas,Montana,Ohio,Texas,Alabama,Oregon,Maine"
To insert a new item to the beginning of a list requires that you specify one (1) as the index parameter.
States = InsertListItem(States, "Alaska", 1)
Executing this statement inserted the item to the beginning because the index is one (1). The variable States now contains: "Alaska,Hawaii,Idaho,Kansas,Montana,Ohio,Texas,Alabama,Oregon,Maine"
The next example specifies that the set of separator characters are the asterisk and dash.
States = InsertListItem(States, "Iowa", 2, "*-")
Since no items are separated with one of the characters from this set, the existing value of States will be assumed a single item. Therefore, this will cause new item to be appended to the text using a different separator. The value of States will now become: "Alaska,Hawaii,Idaho,Kansas,Montana,Ohio,Texas,Alabama,Oregon,Maine*Iowa"
| Note | It is advisable to be knowledgeable and consistent in the separator characters used by your list of items. |
Finally, remember that DAL text variables have a limit of 1024 characters in total. If inserting a new item causes the data of the resulting string to exceed that limit, text at the end of the list will be truncated.