appendList

assocAt

assocPut

assocTake

deepCopy

first

indexOf

indexOfSorted

insertAt

insertPosition

isAtomic

isList

itemAt

last

listDepth

max

mid

min

printList

printListOutline

remove

removeAt

removeAtFast

sizeOf

sort

takeAt

Parameter	Description
list	any list
item	data to add

Appends item to the end of list and returns the resulting list.

Example:

my_list = [1 2 3];
printList(appendList(my_list, 4));

>> [1 2 3 4]

Parameter	Description
list	associative list
name	associative name

Given an associative list in list, this function will return the value associated with the name parameter. If the name does not exist in the list, null will be returned.

Example:

assoc_list = [["a" "b" "c"] [1 2 3]];
print assocAt(assoc_list, "a");

>> 1

See Also:

• assocPut
• assocTake

Parameter	Description
list	associative list
name	associative name
value	associative value

Given an associative list in list, this function will add a new name/value pair to the list as specified in name and value. The name and value can be of any type (integer, string, etc.). If there is already an item in the list with the same name, it's associated value will be replaced with value.

Examples:

1. assoc_list = [["a" "b" "c"] [1 2 3]];
   assocPut(assoc_list, "d", 5);
   printList(assoc_list);
   
   >> [["a" "b" "c" "d"] [1 2 3 5]]

2. assocPut(assoc_list, "b", 5);
   printList(assoc_list);
   
   >> [["a" "b" "c"] [1 5 3]]

See Also:

• assocAt
• assocTake

Parameter	Description
list	associative list
name	associative name

Given an associative list in list, this function will return the value associated with the name parameter. If the name does not exist in the list, null will be returned. After retreiving the value, the name/value pair is removed from the associative list.

Examples:

1. assoc_list = [["a" "b" "c" "d"] [1 2 3 5]];
   print assocTake(assoc_list, "d") & "\r";
   printList(assoc_list);
   
   >> 5
      [["a" "b" "c"] [1 2 3]]

2. assoc_list = [["a" "b" "c" "d"] [1 2 3 5]];
   print assocTake(assoc_list, "g");
   printList(assoc_list);
   
   >> 
      [["a" "b" "c" "d"] [1 2 3 5]]

See Also:

• assocAt
• assocPut

Parameter	Description
list	any list

Returns an exact copy of the list passed in list, including any number of sub-lists. Since most list operations take place on the actual list rather than with a copy of it (as described in the Lists documentation), this function allows you to make an actual copy of a list and manipulate the copy without affecting the original.

Compare examples one and two to see the differences between using deepCopy() or using a regular assignment statement. If you are unclear on why lists work in the manner they do, be sure to read the documentation describing lists.

Examples:

1. my_list = [1 2 3 4 5];
   new_list = deepCopy(my_list);
   new_list'3 = "hi!";
   printList(my_list);
   printList(new_list);
   
   >> [1 2 3 4 5]
      [1 2 "hi!" 4 5]

2. my_list = [1 2 3 4 5];
   new_list = my_list;
   new_list'3 = "hi!";
   printList(my_list);
   printList(new_list);
   
   >> [1 2 "hi!" 4 5]
      [1 2 "hi!" 4 5]

Parameter	Description
list	any list
[item-count]	number of items to return [optional]

Returns the first item of the list, or the first item-count items, if that parameter is defined. If item-count is larger than the number of items in the list, the whole list will be returned. If the list is empty, the returned value will be null.

Examples:

1. my_list = [1 2 3 4 5];
   print first(my_list);
   
   >> 1

2. print first(my_list, 3);
   
   >> 1 2 3

See Also:

• last
• mid

Parameter	Description
list	any list
value	the search value
[sublist-index]	index item of sub-list to search by [optional]

Returns the numerical index of the first item in list equal to value. If there is not a matching item in the list, zero will be returned.

The optional parameter sublist-index allows you to perform a search on a list of sub-lists. Each sub-list will be compared to value using the item at position sublist-index.

Examples:

1. my_list = [4 2 1 4 3]
   print indexOf(my_list, 4);
   
   >> 1

2. print indexOf(my_list, 5);
   
   >> 0

3. big_list = [["a" 1 2] [2 "a" 1] [2 1 "a"]];
   print indexOf(big_list, "a", 2);
   
   >> 2

Parameter	Description
list	any list
value	the search value

Returns the numerical index of the first item in list equal to value. If there is not a matching item in the list, zero will be returned.

This function works exactly the same as indexOf, except that list is assumed to be sorted in ascending order. This allows the list to be searched more efficiently, dramatically improving search times for large lists. The companion function insertPosition can be used to keep the list sorted when adding items.

Examples:

1. my_list = ["alpha" "delta" "gamma" "zeta"]
   print indexOfSorted(my_list, "gamma");
   
   >> 3

See Also:

• insertPosition

Parameter	Description
list	any list
index	numerical index of a list position
value	a value to add to the list

Inserts the item given in value into a list, at the location specified by index. If index is greater than the number of items in the list, value will be added to the end of the list.

Examples:

1. my_list = [1 2 4 5];
   print insertAt(my_list, 3, 3);
   
   >> 1 2 3 4 5

2. print insertAt(my_list, 50, 3);
   
   >> 1 2 4 5 3

Parameter	Description
list	any list
value	a value to add to the list

Returns the position within list that value should be inserted at in order to keep the list sorted. The item is not inserted in the list; you must call insertAt to do this. This function is intended to be used along with indexOfSorted to greatly improve search times for large lists.

Examples:

1. my_list = ["alpha" "delta" "gamma" "zeta"];
   print insertPosition(my_list, "beta");
   
   >> 2

2. new_value = "mu";
   new_index = insertPosition( my_list, new_value);
   print insertAt( my_list, new_index, new_value);
   
   >> alpha delta gamma mu zeta

See Also:

• indexOfSorted

Parameter	Description
list	any list

Returns a boolean indicating whether or not list contains any sub-lists. If list is not already a list, it will be coerced into one prior to evaluation.

Examples:

1. my_list = [1 2 3 4 5];
   if isAtomic(my_list) then
     print "true";
   else
     print "false";
   end if;
   
   >> true

2. my_list = [1 2 3 ["a" "b"] 4];
   if isAtomic(my_list) then
     print "true";
   else
     print "false";
   end if;
   
   >> false

See Also:

• listDepth

Parameter	Description
item	anything

Returns a boolean indicating whether or not item is a valid list.

Examples:

1. x = [1 2 3 4];
   if isList(x) then
     print "true";
   else
     print "false";
   end if;
   
   >> true

2. x = "Hello World!";
   if isList(x) then
     print "true";
   else
     print "false";
   end if;
   
   >> false

Parameter	Description
list	any list
index	sequential index number

Returns the item in list at the index specified in index.

Example:

my_list = ["a" "b" "c" "d" "e"];
print itemAt(my_list, 4);

>> d

Parameter	Description
list	any list
[item-count]	number of items to return [optional]

Returns the last item of the list, or the last item-count items, if that parameter is defined. If item-count is larger than the number of items in the list, the whole list will be returned. If the list is empty, the returned value will be null.

Examples:

1. my_list = [1 2 3 4 5];
   print last(my_list);
   
   >> 5

2. print last(my_list, 3);
   
   >> 3 4 5

See Also:

• first
• mid

Parameter	Description
list	any list

Returns the maximum number of sub-lists contained within list. If the list is atomic, 1 will be returned.

Examples:

1. my_list = [1 2 3 ["a" "b" "c" ["d" 4 "e" 5]]];
   print listDepth(my_list);
   
   >> 3

2. my_list = [1 "a" 2 "b" 3];
   print listDepth(my_list);
   
   >> 1

See Also:

• isAtomic

Parameter	Description
list	any list

Returns the largest item in list. A list of strings will return the last string alphabetically. If the list is empty, null will be returned.

Examples:

1. my_list = [1 2 3 4 5];
   print max(my_list);
   
   >> 5

2. my_list = ["wall" "floor" "ceiling"];
   print max(my_list);
   
   >> wall

3. my_list = ["wall" 5 "floor" 2 "ceiling"];
   print max(my_list);
   
   >> wall

See Also:

• min

Parameter	Description
list	any list
index	numerical index of a list position
[item-count]	number of items to return [optional]

Returns the item of the list at position index. If item-count is defined, that many items will be returned beginning at index. If index is less than one, list position 1 will be used. If index is greater than the total number of items in the list, the last item position will be used. If item-count exceeds the number of items in the list, all values following index will be returned. If the list is empty, the returned value will be null.

Examples:

1. my_list = [1 2 3 4 5];
   print mid(my_list, 3);
   
   >> 3

2. print mid(my_list, 3, 50);
   
   >> 3 4 5

3. print mid(my_list, -2, 3);
   
   >> 1 2 3

4. print mid(my_list, 50, 3);
   
   >> 5

See Also:

• first
• last

Parameter	Description
list	any list

Returns the smallest item in list. A list of strings will return the first string alphabetically. If the list is empty, null will be returned.

Examples:

1. my_list = [1 2 3 4 5];
   print min(my_list);
   
   >> 1

2. my_list = ["wall" "floor" "ceiling"];
   print min(my_list);
   
   >> ceiling

3. my_list = ["wall" 5 "floor" 2 "ceiling"];
   print min(my_list);
   
   >> 2

See Also:

• max

Parameter	Description
list	any list

Given any list specified by list, this function will print the list in standard SiphonScript format. Very helpful when debugging templates or printing the contents of a list to WebSiphon's log window using appendLog().

If the passed value is not a list, it will be printed as a single item of its own type.

Examples:

1. my_list = ["Monday" 1 "Tuesday" 2 "Wednesday" 3 "Thursday" 4 "Friday"];
   printList(my_list);
   
   >> ["Monday" 1 "Tuesday" 2 "Wednesday" 3 "Thursday" 4 "Friday"]

2. // To use this function with an appendLog(), you must stream the 
   // function output as in the example below.
   appendLog(stream printList(my_list));

See Also:

• printListOutline

Parameter	Description
list	any list

Given any list specified by list, this function will print the list as an outline using standard HTML outlining tags. Coupled with some of the functions in the File functions, this function could be used to generate a dynamic site outline.

If the passed value is not a list, it will be printed as a single item of its own type.

Example:

my_list = ["Heading One" ["Item One" "Item Two"] "Heading Two"];
printListOutline(my_list);

>>

• Heading One
  • Item One
  • Item Two
• Heading Two

Parameter	Description
list	any list
value	the value to remove

Removes all occurrences of value from a list. If there are no occurences of value in the list it will not be altered.

An attempt to coerce value to each list item's type will be performed during the removal process, so passing the string "4" will remove any integer or float list items whose value is 4 as well as any matching strings.

Examples:

1. my_list = [1 2 3 1 2 3 3 2 1];
   print remove(my_list, 3);
   
   >> 1 2 1 2 2 1

2. print remove(my_list, 0);
   
   >> 1 2 3 1 2 3 3 2 1

3. print remove(my_list, "2.0");
   
   >> 1 3 1 3 3 1

See Also:

• removeAt
• removeAtFast

Parameter	Description
list	any list
index	numerical index of a list position

Removes the item at position index from a list. The list will not be altered if index is out of range.

This function preserves the order of items in a list, so using it on a large list will be slower than removeAtFast(). If preserving list order is not necessary, use removeAtFast() for optimal speed.

Examples:

1. my_list = [1 2 3 4 5];
   print removeAt(my_list, 3);
   
   >> 1 2 4 5

2. print removeAt(my_list, 8);
   
   >> 1 2 3 4 5

See Also:

• remove
• removeAtFast

Parameter	Description
list	any list
index	numerical index of a list position

Removes the item at position index from a list. The list will not be altered if index is out of range.

The last item of the list will be moved to index rather than moving around many list items. As a result, this function is must faster than removeAt() but does not maintain list order. If preserving list order is important, use removeAt() instead.

Examples:

1. my_list = [1 2 3 4 5];
   print removeAtFast(my_list, 3);
   
   >> 1 2 5 4

2. print removeAtFast(my_list, 8);
   
   >> 1 2 3 4 5

See Also:

• remove
• removeAt

Parameter	Description
list	any list

Returns the number of items contained in list.

Examples:

1. print sizeOf(["a" "b" "c"]);
   
   >> 3

2. // The following conditional will only output "Yes!" if 
   // some_list contains at least one item.
   if sizeOf(some_list) > 0 then
     print "Yes!";
   end if;

Parameter	Description
list	any list
[descending]	sort in descending order [optional]
[sublist-index]	index item of sub-list to sort by [optional]

Returns the list passed to it, sorted in either ascending or descending order. If the descending parameter is not present or evaluates to false, list will be sorted in ascending order.

The optional parameter sublist-index allows you to perform sorting on a list of sub-lists. Each sub-list will be sorted as a single item based on the value of the item at the index specified in sublist-index. The third example below demonstrates this functionality.

Examples:

1. print sort(["lime" "peach" "orange" "grape" "apple"]);
   
   >> apple grape lime orange peach

2. a_list = [5 4 3 2 1 457 93023 23484 101 23.483 91 (-24) 3 "b" "a" "c"];
   print sort(a_list, true);
   
   >> c b a 93023 23484 457 101 23.483 5 4 3 3 2 1 -24

3. a_list = [["lime" 23] ["peach" 14] ["orange" 4] ["apple" 84]];
   printList(sort(a_list, false, 1);  // Sort by name
   printList(sort(a_list, false, 2);  // Sort by value
   
   >> [["apple" 84] ["lime" 23] ["orange" 4] ["peach" 14]]
      [["orange" 4] ["peach" 14] ["lime" 23] ["apple" 84]]

Parameter	Description
list	any list
index	sequential index number

Returns the item in list at the index specified in index, then removes that item from the list.

Examples:

1. my_list = ["a" "b" "c" "d" "e"];
   print takeAt(my_list, 3) & "\r";
   printList(my_list);
   
   >> c
      ["a" "b" "d" "e"]

2. a_list = [["big" 1] ["little" 2] ["medium" 3]];
   print takeAt(a_list, 1) & "\r";
   printList(a_list);
   
   >> big 1
      [["little" 2] ["medium" 3]]