aqString.AddListItem Method

Applies to TestComplete 15.47, last modified on January 20, 2023

Description

The aqString.AddListItem inserts a specified item at a specified position in a string list and returns the resulting list. Items in the list are delimited by the character or substring specified by the aqString.ListSeparator (the default is |). To determine the number of items in the list, use the aqString.GetListLength method.

Declaration

aqString.AddListItem(List, NewItem, Index)

List [in]    Required    String    
NewItem [in]    Required    String    
Index [in]    Optional    Integer Default value: -1   
Result String

Applies To

The method is applied to the following object:

Parameters

The method has the following parameters:

List

A string containing items delimited by the character or string specified by the aqString.ListSeparator property. The method does not change the List itself - it returns its copy after the new item has been added.

NewItem

A string to insert into the list.

Index

The index position of the insertion. Possible values are -1 through aqString.GetListLength(List). 0 means that NewItem will be inserted at the beginning of the list. If Index is omitted, equal to -1 or aqString.GetListLength(List), NewItem will be appended to the end of InputString.

Result Value

A copy of the List string with the NewItem inserted at position Index.

Remarks

The method inserts a new list item along with the needed preceding or subsequent delimiter.

An empty string is considered as containing one item -- an empty string item. So, when the aqString.AddListItem method is used to insert an item into an empty string, it returns a string containing the NewItem and the list separator.

Example

The following example uses the aqString.AddListItem method to insert new words into a sentence:

JavaScript, JScript

function AddListItemSample()
{
  var str = "The fox jumps over the dog";
  aqString.ListSeparator = " ";

  Log.Message(str);

  str = aqString.AddListItem(str, "quick", 1);
  Log.Message(str);

  str = aqString.AddListItem(str, "lazy", 6);
  Log.Message(str);

  str = aqString.AddListItem(str, "brown", 2);
  Log.Message(str);
}

// Result:
//   The fox jumps over the dog
//   The quick fox jumps over the dog
//   The quick fox jumps over the lazy dog
//   The quick brown fox jumps over the lazy dog

Python

def AddListItemSample():
  str = "The fox jumps over the dog"
  aqString.ListSeparator = " "
  Log.Message(str)
  str = aqString.AddListItem(str, "quick", 1)
  Log.Message(str)
  str = aqString.AddListItem(str, "lazy", 6)
  Log.Message(str)
  str = aqString.AddListItem(str, "brown", 2)
  Log.Message(str)

# Result:
# The fox jumps over the dog
# The quick fox jumps over the dog
# The quick fox jumps over the lazy dog
# The quick brown fox jumps over the lazy dog

VBScript

Sub AddListItemSample
  Dim str

  str = "The fox jumps over the dog"
  aqString.ListSeparator = " "

  Log.Message str

  str = aqString.AddListItem(str, "quick", 1)
  Log.Message str

  str = aqString.AddListItem(str, "lazy", 6)
  Log.Message str

  str = aqString.AddListItem(str, "brown", 2)
  Log.Message str
End Sub

' Result:
' The fox jumps over the dog
' The quick fox jumps over the dog
' The quick fox jumps over the lazy dog
' The quick brown fox jumps over the lazy dog

DelphiScript

procedure AddListItemSample;
var str;
begin
  str := 'The fox jumps over the dog';
  aqString.ListSeparator := ' ';

  Log.Message(str);

  str := aqString.AddListItem(str, 'quick', 1);
  Log.Message(str);

  str := aqString.AddListItem(str, 'lazy', 6);
  Log.Message(str);

  str := aqString.AddListItem(str, 'brown', 2);
  Log.Message(str);
end;

// Result:
// The fox jumps over the dog
// The quick fox jumps over the dog
// The quick fox jumps over the lazy dog
// The quick brown fox jumps over the lazy dog

C++Script, C#Script

function AddListItemSample()
{
  var str = "The fox jumps over the dog";
  aqString["ListSeparator"] = " ";

  Log["Message"](str);

  str = aqString["AddListItem"](str, "quick", 1);
  Log["Message"](str);

  str = aqString["AddListItem"](str, "lazy", 6);
  Log["Message"](str);

  str = aqString["AddListItem"](str, "brown", 2);
  Log.Message(str);
}

// Result:
//   The fox jumps over the dog
//   The quick fox jumps over the dog
//   The quick fox jumps over the lazy dog
//   The quick brown fox jumps over the lazy dog

See Also

Working With Strings
ChangeListItem Method
DeleteListItem Method
GetListItem Method
GetListLength Method
ListSeparator Property

Highlight search results