List

List Class

Objects of class List allow sets of objects to be sequentially added, removed, and used as method receivers.

Instance Methods

+= (Object obj1, ...)

Add the items given in the argument to the receiver List. For example:

int main () {
  List new l;

  l = "first", "second", "third", "fourth";
  l += "fifth", "sixth", "seventh", "eighth";

  l map {
    printf ("%s\n", self);
v  }
}

= (Object obj1, ...)

Push the arguments on to the receiver List. The arguments are a comma separated list of objects. For example:

int main () {
  List new l;

  l = "first", "second", "third", "fourth";

  l map {
    printf ("%s\n", self);
  }
}

The = method initializes a list with only the objects that are given as arguments. The memthod deletes any previous list contents.

append (Object obj1, ...)

Add the objects given in the argument to the receiver List. This is a synonym for the += method, above.

init (Object obj1, ...)

This is a synonym for the = method, above.

map (OBJECT *(*method)())

map (OBJECT *(*method)(), Object argument)

map (OBJECT *(*method)(), Object argument1, Object argument2)

Execute method, an instance method of class List, for each member of the receiver List. Within method, self refers to each successive list element. Here is an example.

List instanceMethod printElement (void) {
  printf ("%s\n", self);  /* Here, for each call to the printElement
                             method, "self" is each of myList's
                             successive members, which are String
                             objects. */
}

int main () {

  List new myList;

  myList = "item1", "item2", "item3";  /* Initialize the List with
                                          three String objects. */
  myList map printElement;

}

The map method can also use a code block as its argument. The example above, written with a code block, would look like this.

int main () {

  List new myList;

  myList = "item1", "item2", "item3";  /* Initialize the List with
                                          three String objects. */
  myList map {
    printf ("%s\n", self);
  }

}

If given with two arguments, method’s parameter list must have one parameter. The parameter’s class is significant within method; that is, map can use any class of object for argument. Here is the example above with one argument for the printElement method;

List instanceMethod printElement (String leftMargin) {
  printf ("%s%s\n", leftMargin, self);

}

int main () {

  List new myList;
  String new leftMargin;

  myList = "item1", "item2", "item3";  /* Initialize the List with
                                          three String objects. */
  leftMargin = "- ";

  myList map printElement, leftMargin;

}

Calling map with three arguments works similarly. The map methods in List class all return NULL.

mapRev (OBJECT *(*method)())

Like map, except that it executes method for the last member that was added to the receiver List, then the previous member, and so on until the mapRev executes method for the first member of the list before returning.

new (list1, list2, list3, ...;)

Create the List objects list1, etc. For example:

List new list1, list2, list3;

pop (void)

Remove the object from the end of the receiver’s list and return the object.

popItemRef (void)

Here for backward compatibility; it is now the same as pop.

push (OBJECT *(*object)(int))

Add object to the end of the receiver’s list contents.

pushItemRef (OBJECT *(*object)(int))

Also here for backward compatibility, this method is now the same as push.

shift (OBJECT *(*object)(int))

Add object as the first element of the receiver’s list contents.

sortAscending (void)

sortDescending (void)

sortAscendingByName (void)

sortDescendingByName (void)

Sorts the receiver list based on either the members’ values or names, in ascending or descending order. The sort algorithm is very simple minded, but due to the mechanics of determining earlier/later List members, the methods are as fast for small and medium Lists as more complex sort algorithms.

If possible, you should try to add members in order rather than try to re-arrange a List later. For this, refer to the methods in SortedList class See SortedList.

unshift (void)

Remove the first object from the receiver’s list and return the object.

value (void)

Class List objects have no value instance variable. Instead, return the List object’s contents, or NULL if the list is empty.