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 Index

    o Ascending
    Used with Sort() to specify ascending sort order.
    o Descending
    Used with Sort() to specify descending sort order.

    Class Methods Index

    o Allocate( Integer allocSize )
    Returns a new List of size allocSize.
    o Max( List theList )
    Returns the largest numerical value in the specified List.
    o Min( List theList )
    Returns the smallest numerical value in the specified List.
    o SetAdd( List theList, Dynamic element )
    Adds the specified element to a List only if it is not already in the List.
    o SetRemove( List theList, Dynamic element )
    Removes the specified element from a List if it is currently in the List.
    o SetUnion( List theList1, List theList2 )
    Returns a new List which is a union of the two specified Lists.
    o Sort( List theList, [Integer order] )
    Sorts the specified List in either ascending or descending order.

    Class Attributes

    o Ascending 
     Integer Ascending

    Used with Sort() to specify ascending sort order.

    o Descending 
     Integer Descending

    Used with Sort() to specify descending sort order.

    Class Methods

    o 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.

    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.
    o 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

    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 ?.
    o 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
     

    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.

    o 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.

    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}.
    o 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.

    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}.
    o 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.

    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}.

    o 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.

    List contents are sorted in the following fashion by datatype:

    Type Sort order
    String ASCII order
    Integers and Reals Numerical order
    Dates chronological order

    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}.