The List Package offers a small set of functions for performing simple operations on values of the core OScript datatype List. It is important to note that none of the functions alter List(s) passed to them. Rather, those which manipulate a List's contents do so only by altering the copies of input List(s) they return. The major functionalities offered in the List Package are the following:

Allocate() to create an empty list of a given preallocated length.
Min() and Max() to return the minimum or maximum numerical value in a List.
SetAdd(), SetRemove(), and SetUnion() to treat a List as a set and add or remove unique values, or create a union of unique values.
Sort() to sort a list in ascending or descending order

Class Attributes

Ascending

Used with Sort() to specify ascending sort order.

Descending

Used with Sort() to specify descending sort order.

Class Methods

Allocate( Integer allocSize )

Returns a new List of size allocSize.

Create( Dynamic e1, Dynamic e2 )

Creates a list from the values in the argument list.

Max( List theList )

Returns the largest numerical value in the specified List.

Min( List theList )

Returns the smallest numerical value in the specified List.

SetAdd( List theList, Dynamic element )

Adds the specified element to a List only if it is not already in the List.

SetRemove( List theList, Dynamic element )

Removes the specified element from a List if it is currently in the List.

SetUnion( List list1, List list2 )

Returns a new List which is a union of the two specified Lists.

Sort( List theList, [Integer order] )

Sorts the specified List in either ascending or descending order.

Class Attributes

Integer Ascending

Used with Sort() to specify ascending sort order.

Integer Descending

Used with Sort() to specify descending sort order.

Class Methods

Allocate

List Allocate( Integer allocSize )

Returns a new List containing allocSize number of elements, each of which is set to Undefined.

Parameters

allocSize

The length of the new List returned.

Returns:

A new List of length allocSize.

Example

A short example:

List    a = List.Allocate( 6 )

Echo( "List ", a, " has length ", Length( a ), "." )

The output of the example is:

List {?,?,?,?,?,?} has length 6.

Create

List Create( Dynamic e1,
Dynamic e2 )

Returns a new List containing allocSize number of elements, each of which is set to Undefined.

Parameters

First element.

Second element.

Returns:

A new List of elements specified in the argument list.

Example

A short example:

List    a = List.Create( 1, 2, 3, 4 )

Echo( "List ", a, " has length ", Length( a ), "." )

The output of the example is:

List {1,2,3,4} has length 4.

Max

Dynamic Max( List theList )

Returns the largest numerical value in the specified List.

Parameters

theList

A List whose maximum numeric value is returned.

Returns:

One of the following data types and the maximum numerical value in the List if not Undefined:

Return Value.	Numeric List Values
Integer	Integers
Real	Reals or a combination of integers and Reals
Undefined	If the List does not contain any Integers or Reals

Example

See Min. Here is a short example:

List    a = { 4, "Hello", 2, 9, -47 }
List    b = { 3.2, 8, -27.98, "Goodbye", 300 }
List    c = { "one", "two", "three" }

Echo( "List.Max( ", a, " ) is ", Str.ValueToString( List.Max( a ) ), "." )
Echo( "List.Max( ", b, " ) is ", Str.ValueToString( List.Max( b ) ), "." )
Echo( "List.Max( ", c, " ) is ", Str.ValueToString( List.Max( c ) ), "." )

The output of the example is (note that the result of the second value is a Real, even thought the maximum value was an Integer):

List.Max( {4,'Hello',2,9,-47} ) is 9.
List.Max( {G3.2,8,G-27.98,'Goodbye',300} ) is G300.
List.Max( {'one','two','three'} ) is ?.

Min

Dynamic Min( List theList )

Returns the smallest numerical value in the specified List.

Parameters

theList

A List whose minimum numeric value is returned.

Returns:

One of the following data types, and the minimum numerical value in the List if not Undefined:

Return Value.	Numeric List Values
Integer	Integers
Real	Reals or a combination of integers and Reals
Undefined	If the List does not contain any Integers or Reals

Example

See Max which has an example as well. The results of the example for Minimum() are be similar, except the minimum value is returned instead of the maximum.

SetAdd

List SetAdd( List theList,
Dynamic element )

Returns a new List with the element added to the specified List if it is not already in that List. This causes the List to behave as a set would, ensuring that only unique items are added.

Parameters

theList

The List set to add the element to.

element

A value (of any data type) to add.

Returns:

A new List copy of theList containing the additional element at the end only if the element was found in theList. Otherwise, if the element was not found, theList is returned.

Example

Assumes that the List passed it is a set and contains only unique values, meaning that behavior on Lists which contain duplicate values is undefined. Use SetRemove to remove values added with SetAdd(). Remember that SetAdd() never modifies the List passed it, it only adds the element to a copy of the original list if the element is not already present (the copying process follows Oscript's parameter passing conventions, see Assoc.Copy() for an explanation). Here is a short example:

List    a = { 1, 2, 3 }

Echo( "List.SetAdd( ", a, ", ", 3, " ) = ", List.SetAdd( a, 3 ), "." )
Echo( "List.SetAdd( ", a, ", ", 4, " ) = ", List.SetAdd( a, 4 ), "." )
Echo( "{ @", a, ", 3 } = ", { @a, 3 }, "." )

The output of the example is:

List.SetAdd( {1,2,3}, 4 ) = {1,2,3,4}.
List.SetAdd( {1,2,3}, 3 ) = {1,2,3}.
{ @{1,2,3}, 3 } = {1,2,3,3}.

SetRemove

List SetRemove( List theList,
Dynamic element )

If the element is in the List, then a copy of the List is returned which does not contain the element. Otherwise, the original List is returned. SetRemove() effectively treats the List as a set.

Parameters

theList

The List set to remove the element from.

element

A value (of any data type), which is the element to be removed.

Returns:

A new List copy of theList minus the element if the element was found in in theList. Otherwise, if the element was not found, theList is returned.

Example

Assumes that the List passed it is a set and contains only unique values, meaning that behavior on Lists which contain duplicate values is undefined. Thus SetRemove() should be used in conjunction with SetAdd(). Remember that SetRemove() never modifies the List passed it, it only removes the element from a copy of the original list if the element is present (the copying process follows Oscript's parameter passing conventions, see Assoc.Copy() for an explanation). Here is a short example:

List    a = { 1, 2, 3 }

Echo( "List.SetRemove( ", a, ", ", 3, " ) = ", List.SetRemove( a, 3 ), "." )
Echo( "List.SetRemove( ", a, ", ", 4, " ) = ", List.SetRemove( a, 4 ), "." )

The output of the example is:

List.SetRemove( {1,2,3}, 3 ) = {1,2}.
List.SetRemove( {1,2,3}, 4 ) = {1,2,3}.

SetUnion

List SetUnion( List list1,
List list2 )

Returns a new List which is a union of the two specified lists.

Parameters

list1

The first list that will compose the union.

list2

The second list that will compose the union.

Returns:

A new List which is a union of list1 and list2.

Example

Assumes that the List passed it is a set thus SetUnion() should be used in conjunction with SetAdd(). Remember that SetUnion() never modifies the Lists passed it, it creates a new list which is the union of the two lists passed in as parameters. Here is a short example:

List    a = { 1, 2, 3 }
List    b = { 1, 3, 5, 7 }

Echo( "List.SetUnion( ", a, ", ", b, " ) = ", List.SetUnion( a, b ), "." )

The output of the example is:

List.SetUnion( {1,2,3}, {1,3,5,7} ) = {1,2,3,5,7}.

Sort

List Sort( List theList,
[Integer order] )

Returns a new List which is a copy of specified List sorted in either ascending or descending order.

Parameters

theList

The List to be sorted.

order

Either List.Ascending or List.Descending indicating the order in which to sort the List. Ascending order is assumed if order is not specified.

Returns:

A sorted copy of the List.

Example

List contents are sorted in the following fashion by datatype:

Sorting a List containing elements of datatypes other than the ones listed above yields unpredictable results. Results are also unpredictable if the elements in the List are not of the same datatype (aside from mixing Integers and Reals). The copying process follows OScript's parameter passing conventions (see Assoc.Copy() for an explanation). A short example of Sort() is:

List    a = { 1, 200, 40, 90, -67, 32.6 }

Echo( "List.Sort( ", a, " ) = ", List.Sort( a ), "." )

The output of the example is:

List.Sort( {1,200,40,90,-67,G32.6} ) = {-67,1,G32.6,40,90,200}.