Functions for Collections

The Dylan run-time system provides default implementations for all of the functions described in this section.

size   collection  =>  {integer or #f}	[Generic Function]

size returns the number of keys contained in collection. A default method is provided by the Dylan run-time system which simply counts while iterating through the collection. size may return #f for collections of unbounded size.

class-for-copy   mutable-collection  =>  class	[G.F. Method]

class-for-copy returns an appropriate collection class for creating mutable copies of the argument. For collections that are already mutable, the collection's actual class is generally the most appropriate, so the <object> method of class-for-copy can be used. The class-for-copy value of a sequence should be an instantiable subclass of <mutable-sequence>, and the class-for-copy value of an explicit-key-collection should be an instantiable subclass of <mutable-explicit-key-collection>.

empty?   collection  =>  boolean	[Generic Function]

Returns #t if collection contains no elements, and #f otherwise.

do   procedure collection #rest more-collections 	[Function]
=>  false

do applies procedure to corresponding elements of all the collections. Returns #f. If all the collections are sequences, do guarantees that they will be processed in their natural order.

? do (method (a b) print (a + b) end,
      #(100, 100, 200, 200),
      #(1, 2, 3, 4))
101
102
203
204
#f

map   procedure collection #rest more-collections  	[Function]
=>  new-collection

map creates a new collection whose elements are obtained by calling procedure on corresponding elements of all the collection arguments. If all the collections are sequences, processing is performed in the natural order.

map returns a collection whose value is an instance of the class-for-copy value of collection. The new collection is created by calling make on that class, with a size: initialization argument whose value is the number of corresponding elements in the argument collections.

? map (\+,
       #(100, 100, 200, 200),
       #(1, 2, 3, 4))
#(101, 102, 203, 204)

map-as   class procedure collection #rest more-collections 	[Function]
=>  new-collection	

map-as creates a new collection of class class whose elements are obtained by applying procedure to corresponding elements of the collection arguments. class must be an instantiable subclass of <mutable-collection> and acceptable as the required argument to make. size: with a non-negative integer value must be an acceptable initarg for make of the class. The new collection is created by calling make on the indicated class, with a size: initialization argument whose value is the number of corresponding elements in the argument collections. If all the collections are sequences (including the created collection), processing is done in the natural order.

? map-as (<vector>, \+,
          #(100, 100, 200, 200),
          #(1, 2, 3, 4))
#(101, 102, 203, 204)

map-into mutable-collection procedure	[Function]
	collection #rest more-collections  
=> mutable-collection

map-into returns the mutable-collection argument after modifying it by replacing its elements with the results of applying procedure to corresponding elements of collection and more-collections. If mutable-collection and all the other collections are sequences, processing is done in the natural order.

When mutable-collection is an instance of <stretchy-collection>, the usual alignment requirement (described in the section on collection alignment) is relaxed. In this case, the key sequence of mutable-collection is not considered during alignment. Rather, only the key sequences for the source collections are aligned, with procedure called on the corresponding elements. The result of each call to procedure is then stored into mutable-collection with the corresponding key (possibly stretching mutable-collection in the process), using element-setter. Other keys in mutable-collection remain undisturbed.

The target collection for map-into must have the same key-test function as the rest of the collections, even if it is a <stretchy-collection> and therefore does not get aligned. Otherwise, an error is signalled.

mutable-collection may be the same as collection or any of the more-collections.

? define variable x = list (100, 100, 200, 200)
x
? map-into (x, \+, #(1, 2, 3, 4))
#(101, 102, 203, 204)
? x
#(101, 102, 203, 204)

any?   procedure collection #rest more-collections   	[Function]
=>  value

If procedure returns a value other than #f when applied to some group of corresponding elements of collection and more-collections, then any? returns the (first) value returned by procedure. Otherwise, if procedure returns #f when applied to every such group, then any? returns #f. If all the collection arguments are sequences, any? operates in natural order. In all cases, any? stops on the first true value returned by procedure.

? any? (\>, #(1, 2, 3 ,4), #(5, 4, 3, 2))
#t
? any? (even?, #(1, 3, 5, 7))
#f

every?   procedure collection #rest more-collections 	[Function]
=>  boolean

every? is similar to any?, but every? returns #f if procedure ever returns #f and otherwise returns #t.

? every? (\>, #(1, 2, 3, 4), #(5, 4, 3, 2))
#f
? every? (odd?, #(1, 3, 5, 7))
#t

reduce   procedure initial-value collection  =>  value	[Generic Function]

procedure is a binary function used to combine all the elements of collection into a single value. If collection is empty, reduce returns initial-value; otherwise, procedure is applied to initial-value and the first element of collection to produce a new value. If more elements remain in the collection, then procedure is called again, this time with the value from the previous application and the next element from collection. This process continues until all elements of collection have been processed. Processing is always done in the natural order for collection.

? define variable high-score = 10
high-score
? reduce (max, high-score, #(3, 1, 4, 1, 5, 9))
10
? reduce (max, high-score, #(3, 12, 9, 8, 8, 6))
12

reduce1   procedure collection  =>  value	[Generic Function]

reduce1 is just like reduce, except that the first element of collection is taken as an initial value, and all the remaining elements of collection are processed as if by reduce. (In other words, the first value isn't used twice.) For unstable collections, "first" element effectively means "an element chosen at random." It is an error for collection to be an empty collection. Processing is done in the natural order for collection.

? reduce1 (\+, #(1, 2, 3, 4, 5))
15

member?  value collection #key test  =>  boolean	[Generic Function]

member? returns #t if and only if collection contains value (as determined by test, which defaults to ==). The test function may be non-commutative: it is always called with value as its first argument and an element from collection as its second argument.

? define constant flavors = #(#"vanilla", #"pistachio", #"ginger")
flavors
? member? (#"vanilla", flavors)      
#t                                   
? member? (#"banana", flavors)
#f

find-key   collection procedure #key skip failure  =>  key	[Generic Function]

This function returns a key value such that (procedure (element collection key)) is true. If no element in the collection satisfies procedure, it returns failure (default #f).

The skip argument (default 0) indicates that the first skip matching elements should be ignored. If skip or fewer elements of collection satisfy predicate, then failure is returned.

? flavors
#(#"vanilla", #"pistachio", #"ginger")
? find-key (flavors, has-nuts?)
1
? flavors[1]
#"pistachio"

replace-elements!   mutable-collection predicate 	[Generic Function]
	new-value-fn #key count
=>  mutable-collection	

This function replaces those elements of mutable-collection for which predicate returns true. The elements are replaced with the value of calling new-value-fn on the element. If count is specified, no more than count elements are replaced.

? define variable numbers = list (10, 13, 16, 19)
numbers
? replace-elements! (numbers, odd?, double)
#(10, 26, 16, 38)

fill!   mutable-collection value #key start end	[Generic Function]

fill! alters mutable-collection so that (element mutable-collection key) returns value for every key.

If mutable-collection is a mutable sequence, then start and end keywords may be specified to indicate that only a part of the sequence should be filled. start is considered an inclusive bound and defaults to 0; end is an exclusive bound and defaults to the length of the sequence.

? define variable numbers = list (10, 13, 16, 19)
numbers
? fill! (numbers, 3, start: 2)
#(10, 13, 3, 3)

key-test collection => test-function	[Generic Function]

Returns the function used by the collection to compare keys. All collection classes must provide or inherit a method that returns a result consistent with their iteration protocol and element methods. A given method for key-test must return the same value (compared with ==) each time it is called.