ArrayList extensions for Synergy/DE

Synergy/DE version 9 includes a System.Collections.ArrayList class that mirrors the .NET version of the same name.  It’s a big improvement over earlier array constructs in terms of usability with objects, because it’s dynamic.  But it doesn’t provide very many methods, and there is no facility for generating an array in a single statement.

The code you can download below include an ls class that extends ArrayList to add several members.  Because ls is derived from ArrayList, any place in the following where an arraylist is specified, an ls may be used.  The symbol “=>” is used below as shorthand for “returns”.  “ls2” means “a new ls”.  Where “ls” is not italicized, it should be taken literally as a class reference (e.g., in a static method invocation).  Italicized words indicate an instrance of that class.

ls.from(arraylist) => ls

Creates a new ls from arraylist.  Members are copied by reference (shallow copy).

ls.of(object) => ls

Creates a new ls containing the one object object.  if object is a primitive, it will be automatically boxed in a Var.

ls + arraylist => ls2
ls.append(arraylist) => ls2

Creates a new ls that contains all the members of ls followed by all the members of arraylist. You can use either form:  the “+” operator, or an explicit call to the “append” method.

ls + object => ls2
ls.append(object) => ls2

Creates a new ls that contains all the member of ls followed by object.  Primitives are auto-boxed as Var.

ls | arraylist => ls
ls.append$(arraylist) => ls

Appends the elements of arraylist to ls in place, returning the modified ls.  I’ve adopted the convention of appending a “$” to the end of the names of methods with side-effects.

ls | object => ls
ls.append$(object)

Appends object to ls in place, returning the modified ls.  Primitives are auto-boxed as Var.  The bitwise “or” operator provides a shorthand for composing a list.  E.g.,

ls.of(“fred”)|”wilma”|42|an_object|another_array

To append an arraylist and retain its arrayness (in other words, create a nested array), you must cast it as (object):

ls.of((object)(ls.of(1)|2|3))      ;1,2,3 are a branch from node 0
&   |(object)another_ls            ;Node 1 branches to the members of another_ls
&   |(object)(ls.of((object)arraylist1))  ;Node 2 contains an ArrayList

ls.copy() => ls2

Creates and returns a shallow copy of ls.

ls.appendflat$(arraylist) => ls

Appends the elements of arraylist to ls, returning the modified ls.  If elements in arraylist are also ArrayLists, recursively appends those elements rather than the Arraylists themselves.

ls.chop(length) => ls2

Returns a new ls of length length containing the first length elements of ls.

ls.chop$(length) => ls

Destructively removes elements from ls starting at index length to the end of the list, returning the modified ls.

ls.intersection(arraylist) => ls2

Creates a new ls from all of the elements that occur in both ls and arraylist.  Because we use IndexOf to verify membership, and IndexOf uses Object.Equal, and Var overrides Equal, Vars having the same value will be treated as equal.

ls.union(arraylist) => ls2

Creates a new ls from all of the elements that occur in either ls or arraylist.  If the same element occurs in both, it will not be duplicated.  See note above under intersection regarding Vars.

ls.rotate$(ndx…) => ls

Destructively rotates elements of ls between one or more specified indices (zero-based), shifting left.  That is, the element at the second index (if specified) will be moved to the first index, etc. and the element at the first index will be moved to the last specified index.  Returns the modified ls.

ls.push(object) => ls

Inserts object as the first element in ls, returning the modified ls.  Even though this method has the side-effect of modifying its receiver, I’ve omitted the customary $ because its stack-based name should communicate that fact.  Note also that unlike append or append$, if object is an ArrayList, it is stored as a single object.

ls.pop() => object

Removes the first element from ls and returns that element.  If ls is empty, returns ^null.

ls.reverse() => ls2

Returns a shallow copy of ls with the order of its members reversed.

ls.flatten() => ls2

Returns a new ls containing all of the members of ls, but with any ArrayList members recursively flattened.  In other words, all ArrayList nesting is eliminated – each original ArrayList member is replaced by its members.

ls.car => object

Property to return the first element of ls, or ^null if ls is empty.

ls.car = object

Destructively sets the first element of ls to object (without expanding ArrayLists).  Because this is a property, you cannot pass primitive types here.  You must box them explicitly.

ls.cdr => ls2

Returns a new ls constructed of all members of ls except the first one.

ls.cdr = ls2

Removes the second and following elements from ls, then appends the elements from ls2.

This is just the first installment in my intended extensions for lists.  I plan to add associative array capabilities next (much like my Hash class, which isn’t compatible with ls) as well as sorting, mapping, and filtering using functors.