Class Ls extends System.Collections.ArrayList

Creates a new, empty list, optionally specifying initial capacity as int. The optional capacity merely provides a performance enhancement when the correct or usual capacity is known -- the list will be expanded as needed beyond this number.

The append method (and the + operator) adds an object to a list, returning a new list. if object is an ArrayList (or a derived class, such as another ls), then all of its members are added instead of the ArrayList itself.

The append$ method (and the | operator) modifies ls by adding the object in place, and returns the modified list. It also expands any Arraylist passed.

The add$ method (and the & operator) operates like append$, but ArrayLists are not expanded. This provides for composing nested lists.

The appendflat$ method operates like append$, but any ArrayList argument is completely flattened. Not only is the Arraylist replaced by its members, but any members of the ArrayList that are ArrayLists are recursively expanded.

In all of the above, if object is a primitive, it will be automatically boxed in a Var

.

Examples of list composition

ls.of(1) | 2 | "fred" | an_object | a_list

Creates a one-dimensional list from three primitives (which are boxed as Vars), an object, and the members of another list

    ls.of("1a") & "1b" &
    &     (ls.of("2a") &
    &           (ls.of("3a") & "3b"))
    

Creates a tree with three top nodes: "1a", "1b", and another list that contains two nodes: "2a" and another list that contains two nodes: "3a" and "3b". Note that the ampersands on the left side are Synergy/DE line-continuation characters.

Why didn't I use "<<" for append, and reserve "|" and "&" for union and intersection, respectively? Synergy/DE does not provide an override for "<<". I didn't want to use just "<" in case I add comparison operators later, and intersection and union seem like rare enough operations that requiring them to be spelled out should not be onerous.

Property for referencing the first element of a list. Because this is a property, auto-boxing of primitives does not occur. In the first form, if the list is empty, ^null is returned. In the second form, if the list is empty, then object is added.

Property for referencing the second and following elements of a list. When retrieved, a new ls containing the second through last items is returned. When set, the second through last elements of the list are removed and replaced with the elements of ls2.

Both of these methods truncate the list at the length specified by int (in other words, removing items from that index to the end). The chop method returns a truncated copy of the original list, leaving the original unmodified, while chop$ modifies and returns the original list.

Both of these methods remove null elements from a list. The compact$ method modifies and returns the original list, while compact returns a modified shallow copy, leaving the original untouched.

Returns true if object is a member of the list, otherwise false. This test uses IndexOf, which in turn invokes the Equals() method to compare objects. To determine whether a list is a subset of another list, see issubsetof and issupersetof.

Returns a shallow copy of a list (members are copied by reference).

Returns the count of the number of elements in the list that, when passed to mapboolean's test method, return true. See MapBoolean.

Copies all members of all nested lists. Unlike copy, which copies all members by reference even if they are lists, deepcopy makes a copy of any member that is a list, recursively.

Creates and returns a new empty list. This method is provided because the syntax new ls() is not valid in all contexts where the result of a method can be used instead.

Override of object.Equals() to specialize the comparison of an ls and any ArrayList. The two lists are considered equal if they have the same Count, and invoking Equals() on each of the members of ls returns true when passed the corresponding member of object (or both are ^null).

Returns the first element of ls for which mapboolean.test() returns true. If no objects match, ^null is returned.

Returns a list of all elements of ls for which mapboolean.test() returns true. If no objects match, an empty list is returned.

Returns a copy of a list in which all members that are ArrayLists are recursively replaced by their members. The result is a flat list of all non-ArrayList members.

Creates a new ls from arraylist, hash, or array. Members are copied by reference.

For hash, an alist will be created in which each element is a pair composed from the key value and associated object from the Hash. See keyfind.

For array, up to 3 dimensions are supported for dynamic object arays ([#,#,#]@class), and those dimensions will be preserved as lists within lists. Note that no automatic type conversions will occur. In particular, strings are not converted to VarAlpha. Use the map method to perform these conversions, if desired. For instance, to convert a multi-dimensioned array of strings to a list of lists of VarAlpha:

ls.from(array).map(new MapDeep(new MapAlpha()))

Real arrays of primitive types ([*]type) only work on Synergy/DE version 9.3 and above, due to a compiler bug (tr#30719). If you try to use real arrays with this method in Synergy/DE version 9.1* or even in the 9.2.1 beta, it will crash the Synergy/DE runtime. This method only supports real arrays of one dimension, because I got tired of fighting with the compiler. The primitive values will be boxed as Vars.

Note also that since arrays are 1-based while ArrayLists are 0-based, the indices of members in the resulting list will be one less than their indices in the original array. That goes for both array and realarray

Returns true if every member of ls can be found in ls2, otherwise false.

Returns true if every member of arraylist can be found in ls, otherwise false.

Returns a string composed of the return value of the ToString() method of each non-null element in the list, separated by string.

Adds object2 to the association for key object. If object or object2 are primitives, they will be boxed as Vars. Unlike method keyset, this method does not delete any previous association with the key, it merely adds another object to the sublist for the association. This allows for multiple objects associated with the same key, as in a multimap.. Use the method keygetl to retrieve all associations for a key as an ls.

Removes the entire first association in the list whose key matches object. See keyfind for details. If object is a primitive, it will be automatically boxed in a Var.

Finds a member of an alist using object as a key. For each element of ls, if that element is also an ls with at least one member, object's Equal() method is invoked to test for a match against the first element of that ls. If it returns true, the ls is returned. If the key is a primitive, it is automatically boxed as a Var. This supports the alist construct in which elements of a list are themselves lists in which the first element is treated as a key. This implementation is a bit naive and underperforms for large arrays (O(n*(n/2)) to randomly access all elements). For a much faster version that is limited to alphanumeric keys and does not provide many of the features of ls, try Hash.

Gets the value object2 associated with a key object in an alist. If no such key exists in the alist, ^null is returned. If object is a primitive, it is automatically boxed as a Var, except for numeric types passed to the Indexer (in order to avoid hiding ArrayList.Indexer). If more than one value is associated with the key, they are returned in an ls.

Gets the list of values associated with key object in an alist. If object is primitive, it will be boxed in a Var. If the key is not found, an empty ls is returned.

Sets the value object2 associated with a key object in an alist. If the alist already contains an association for the specified key, then that association sublist's cdr is replaced by object2. Otherwise, a new sublist is added to ls containing the pair object, object2. If either object is a primitive, it is automatically boxed as a Var, except for numeric types passed to the Indexer (in order to avoid hiding ArrayList.Indexer).

Returns a new list containing all of the members of the original list that are also found in arraylist (which can be another ls). Because of the implementation of ls.Equals(), elements that are instances of ls and contain the same members will be treated as identical.

Accesses the last member of ls. If the list contains no elements, the get method returns ^null, while the set method adds an element.

Creates a new single-element ls containing object. if object is a primitive, it will be automatically boxed in a Var.

This macro provides an alternative syntax for creating a list containing two objects. If either object is primitive, it will be boxed as a Var. This macro is exactly equivalent to ls.of(object) & object2

These methods map each object in the list to another object, which is the result of passing the original object to mapobject's map method. The ls method map produces a new list, while map$ replaces each item in the original list. See MapObject.

This method operates like map, except that any ^null that results from calling mapobject.map will not be included in the resulting list.

Assumes that both lists are sorted, and returns a merged list. The two methods use different algorithms, with merge$ inserting items from arraylist into ls, while merge appends items from each list to the new ls2. Method mergesort uses the merge, which performs slightly better with large lists.

Comparisons between the members of the two lists are performed by calling the test method of compare. See Compare functors.

Sorts the list, using compare, and returns a new list (leaving ls unmodified). See Compare functors. MergeSort appears from testing to be faster than QuickSort when the list contains more than circa 100,000 elements. Therefore, sort uses a combination of the two, depending on the size of each segment.

Removes and returns the first element of the list. If the list is empty, returns ^null.

Removes and returns the last element of the list. If the list is empty, returns ^null. There is no push_last method, because that functionality is already supplied by the methods add (ArrayList) and add$.

Inserts object at the front of the list, returning the modified list.

Sorts the list, using compare. See Compare functors. Both methods use the in-place QuickSort algorithm, but quicksort copies the list first, while quicksort$ modifies ls. QuickSort appears from testing to be faster than MergeSort when the list contains fewer than circa 100,000 elements. Therefore, sort uses a combination of both, based on the size of each segment.

This QuickSort algorithm reverts to an Insertion sort when the number of elements is less than 5. When doing a QuickSort, the middle item is used as a pivot -- experimentation with optimizing the pivot value (median of 3, or pseudomedian of 9) yielded no improvements. The "collapse the walls" algorithm was adopted for speed, but note that this means the sort is not stable (i.e., the order of duplicates is not preserved).

These methods implement the equivalent of reduce, fold, inject, or accumulate in other languages. They iterate over the members of the list, invoking Reducer's reduce method, passing it the accumulator object and he list member. What Reducer returns becomes the new accumulator object, the final value of which is returned.

The methods reduce and reduceRight differ in the order in which members are processed. The reduce method goes lowest index to highest, while reduceRight does the reverse.

If object2 is passed, it is treated as an initial value, and the first call to Reducer will pass that as the accumulator. If object2 is not passed, then the first call to Reducer will pass the first (or last) member of the list as the accumulator, and will begin with the second member as the member argument.

If object2 is a primitive, it will automatically be boxed as a Var.

Removes all occurences of object from ls, returning either a new ls (in the case of remove and the operator -), or the modified receiver (in the case of remove$). If object is not a member of ls, no error occurs. if object is primitive, it will be boxed in a Var so that Var comparisons will apply. See subtract for a method to remove all elements of one list from another.

Removes objects from a list that return true when passed to mapboolean's test method. See MapBoolean. The method removeif leaves ls unmodified, while removeif$ modifies and returns ls.

Creates and returns a copy of the original list with the order of its members reversed.

Swaps members of a list by index. At least one index is required. The element at the first specified index will be moved to the last specified index. The member at the second specified index (if any) will be moved to the first specified index, and so forth. Returns the modified list.

Sorts a list, using compare. See Compare functors. The method sort$ uses QuickSort to sort the list in-place, while sort creates a sorted copy of the list. For sort, MergeSort is used for lists containing 100,000 elements or more, but when any segment within the sort contains fewer than 100,000 elements, QuickSort is used to sort that segment.

Returns a list containing the members of the original list beginning at the index specified by int, up to and including the index specified by int2. If int2 is omitted, the last element in the list is assumed.

Removes all the elements of arraylist from ls. In the case of subtract and the operator -, the ls is unmodified and a new list is returned -- while subtract$ modifies and returns its receiver. If an element in arraylist does not occur in ls, no error occurs. See remove for removing objects from a list.

Creates a new Hash from this list. If boolean is passed, it specifies whether the new Hash has case-sensitive keys. If not passed, case-sensitivity is true by default.

Not all elements in a list may qualify for inclusion in the new Hash. To be included, they must conform to the model of an alist with a unique alphanumeric key for each object. In other words, only elements that are themselves an ls containing at least two elements where the first two elements are non-null will be considered. The first element's string representation will be used as the hash key, and the second element will be stored as the associated object.

Override of object.ToString() to specialize the string representation of lists. the list is represented as a "[" followed by the result of ToString() on each of its elements (separated by commas), followed by a closing "]". Null elements are represented as "^null".

Returns a list containing all of the members of the original list and all of the members in arraylist (which can be another ls). If object is passed (i.e., a non-ArrayList object), it will be treated as a list of one object -- and if it is primitive it will be boxed as a Var. The union method returns a new list, while union$ modifies the receiver. Unlike append, any element found in both lists is not duplicated. You can therefore use this method to add objects uniquely, as in a set. Because of the implementation of ls.Equals(), elements that are instances of ls and contain the same members will be treated as identical.

Both of these methods remove duplicates from a list (based on the element's Equals method). The uniq method returns a uniq'd copy of the list, while uniq$ modifies and returns the original list.

If either of the objects is a list, its first element will be used -- otherwise the object itself. If that first element is a list, its first element will be used, and so on recursively until a non-list is encountered. Then the result returned from invoking compare's test method for those two objects will be returned.

This Comparer is useful for sorting associative lists by key. An associative list (or alist) is one in which each element is itself a list, comprised of a key and data. See keyfind.

Reverses the order provided by compare.

This comparer treats each object as a list. if either of the objects is not a list, then it is automatically wrapped in a list. Each list is then compared (using compare) element by element until not equal, or the end of a list is reached. If one of the lists then contains more elements, it is treated as greater -- if the same, they're equal.

Uses mapobject to map only the first of the two objects to be compared before passing both to compare's test method. This comparer should not be used in a sort, but it may be useful in other contexts, such as the ls methods countif or removeif.

Uses mapobject to map both of the objects to be compared before passing them to compare's test method. This comparer should be used when mapping objects for sorting.

Compares the result of ToString() on both objects. ^null is considered equal to "".

When the constructor is invoked without arguments, defaults to case-insensitive, natural order. If called with arguments, boolean is true for case-sensitive, boolean2 is true for natural order or false for alphanumeric order.

This class also provides the static method TestNatural that compares two strings according to natural order rules.

Compares Var objects using Var's built-in comparisons. Non-Vars are treated as greater than Vars, and their order relative to each other is undefined.

Compares Var objects, casting them to alphanumeric. Non-Vars are treated as greater than Vars, and their order relative to each other is undefined.

Compares Var objects, casting them to decimal. Non-Vars are treated as greater than Vars, and their order relative to each other is undefined.

Compares Var objects, casting them to integer. Non-Vars are treated as greater than Vars, and their order relative to each other is undefined.

All reducers must be derived from this class, and must override the method reduce, which has the following signature:

Reducer.reduce(object, object2) => object3

where:

• object is the accumulator object. On the first call, this will be either the initial value passed to ls.reduce/reduceRight, or the first/last element of the list if no initial value was passed. On subsequent calls, it will be the result of the previous call.
• object2 is the next member of the list.
• object3 is the new value for the accumulator.

You may derive your own reducer class to implement whatever reduction you need, but the following classes are provided.