Collections Language

An extension to the Base Language that adds support for collections.

Introduction

Collection language provides a set of abstractions that enable the use of a few most commonly used containers, as well as a set of powerful tools to construct queries. The fundamental type provided by the collections is sequence, which is an abstraction analogous to Iterable in Java, or IEnumerable in .NET . The containers include list (both array-based and linked list), set and map. The collections language also provides the means to build expressive queries using closures, in a way similar to what LINQ does.

Null handling

Collections language has a set of relaxed rules regarding null elements and null sequences.

Null sequence is still a sequence

Null is a perfectly accepted value that can be assigned to a sequence variable. This results simply in an empty sequence.

Null is returned instead of exception throwing

Whereas the standard collections framework would have to throw an exception as a result of calling a method that cannot successfully complete, the collection language's sequence and its subtypes would return null value. For example, invoking first operation on an empty sequence will yield a null value instead of throwing an exception.

Skip and stop statements

skip

Applicable within a selectMany or forEach closure. The effect of the skip statement is that the processing of the current input element stops, and the next element (if available) is immediately selected.

stop

Applicable within a selectMany closure or a sequence initializer closure. The stop statement causes the construction of the output sequence to end immediately, ignoring all the remaining elements in the input sequence (if any).

—

Collections Runtime

Collections language uses a runtime library as its back end, which is designed to be extensible. Prior to version 1.5, the collections runtime library was written in Java and used only standard Java APIs. The release 1.5 brings a change: now the runtime library is available as an MPS model and uses constructs from jetbrains.mps.baseLanguage.closures language to facilitate passing of function-type parameters around.

The classes which constitute the collections runtime library can be found in the collections.runtime solution, which is available from the jetbrains.mps.baseLanguage.collections language.

---

Sequence

Sequence is an abstraction of the order defined on a collection of elements of some type. The only operation that is allowed on a sequence is iterating its elements from first to last. A sequence is immutable. All operations defined in the following subsections and declared to return a sequence, always return a new instance of a sequence or the original sequence.

Although it is possible to create a sequence that produces infinite number of elements, it is not recommended. Some operations may require one or two full traversals of the sequence in order to compute, and invoking such an operation on an infinite sequence would never yield result.

Sequence type

sequence<Type>

Creation

new sequence

Sequence can be created with initializer.

closure invocation

A sequence may be returned from a closure (see Closures).

array as a sequence

An array can be used as a sequence.

A list, a set and a map are sequences, too. All operations defined on a sequence are also available on an instance of any of these types.

Sequence type is assignable to a variable of type java.lang.Iterable. The opposite is also true.

Operations on sequence

Iteration and querying

foreach statement

Loop statement

is equivalent to

forEach

The code passed as a parameter (as a closure literal or by reference) is executed once for each element.

size

Gives number of elements in a sequence.

isEmpty

Test whether a sequence is empty, that is its size is 0.

isNotEmpty

Test whether a sequence contains any elements.

indexOf

Gives the index of a first occurrence in a sequence of an element that is passed to it as a parameter.

contains

Produces boolean value, indicating whether or not a sequence contains the specified element.

any / all

Produces boolean value that indicates whether any (in case of any operation) or all (in case of all) of the elements in the input sequence match the condition specified by the closure.

iterator

Produces an iterator.

enumerator

Produces an enumerator.

Selection and filtering

first

Yields the first element.

last

Yields the last element.

take

Produces a sequence that is sub-sequence of the original one, starting from first element and of size count.

skip

Produces a sequence that is sub-sequence of the original one, containing all elements starting with the element at index count.

cut

Produces a sequence that is a sub-sequence of the original one, containing all elements starting with first and up to (but not including) the element at index size minus count. In other words, this operation returns a sequence with all elements from the original one except the last count elements.

tail

Produces a sequence that is a sub-sequence of the original one, containing all elements starting with the element at index size minus count. In other words, this operations returns a sequence with count elements from the end of the original sequence, in the original order.

page

Results in a sequence that is a sub-sequence of the original one, containing all elements starting with the element at index start and up to (but not including) the element at index end.

This is equivalent to

Where skip = start, count = end - start .

where

Produces a sequence that is a sub-sequence of the original one, with all elements for which the code passed as a parameter returns true.

findFirst

Results in the first element that matches the parameter closure.

findLast

Results in the last element that matches the parameter closure.

Transformation and sorting

select

Results in a sequence consisting of elements, each of which is the result of applying the parameter function to each element of the original sequence in turn.

selectMany

Produces a sequence that is a concatenation of all sequences, which are all the results of applying the parameter closure to each element of the original sequence in turn. The statements skip and stop are available within the parameter closure.

distinct

Produces a sequence, which contains all elements from the original sequence in the original order, with all the elements having cardinality exactly 1. Of all occurrences of an element in the original sequence only the first occurrence is included in the resulting sequence.

sortBy

Produces a sequence with all elements from the original one in the order, which corresponds to an order induced by an imaginary sequence produced by applying the selector function to each element in the original sequence in turn. The selector function can be thought of as returning a key, which is used to sort elements in a sequence. The ascending parameter controls the sort order.

alsoSortBy

Equivalent to sortBy, unless used as a chain operation immediately following sortBy or another alsoSortBy. The result is a sequence sorted with a compound key, with the first component taken from previous sortBy or alsoSortBy (which is also a compound key), and the last component taken from this operation.

sort

Produces a sequence containing all elements from the original one in the order produced by applying the comparator function (passed as a closure literal or by reference) to a list with elements from the original sequence. The ascending parameter controls the sort order (order is reversed if the value is false).

Binary operations

intersect

Produces a sequence containing elements contained both by the original sequence and the parameter sequence.

except

Produces a sequence containing all elements from the original sequence that are not also members of the parameter sequence.

union

Produces a sequence containing elements both from the original sequence and the one passed as a parameter.

disjunction

Produces exclusive disjunction (symmetric difference) of the original sequence and the one passed as a parameter.

concat

Produces a sequence, which is a concatenation of the original one with the sequence passed as a parameter

Conversion

reduceLeft / reduceRight

Operation reduceLeft/reduceRight applies the combinator function passed as a parameter to all elements of the sequence in turn. One of the function parameters is a sequence element, and another is the result of previous application of the function. Operation reduceLeft takes first two sequence elements and applies the function to them, then takes the result of the first application and the third sequence element, etc. Operation reduceRight does the same, but moving from the sequence's tail backwards.

• reduceLeft

• reduceRight

foldLeft / foldRight

Operation foldLeft/foldRight behaves similarly to reduceLeft/reduceRight, with the difference that it also accepts a seed value. Also the combinator function is asymmetric (it takes a Type and a Z parameters and returns a Z value). The result of the operation is of type Z.

• foldLeft

• foldRight

join

This operation is only available on a sequence of strings. The result is a string that is produced by concatenating all elements with the optional separator. The default separator is " " (single space).

toList

Returns new list containing all the elements from the original sequence.

toArray

Returns new array containing all the elements from the original sequence.

---

List

A basic list container backed by either array list or linked list.

List type

list<Type>

List creation

new arraylist
new linkedlist

Creates an empty list. Optionally, initial values may be specified right in the new list creation expression.

Alternatively, a sequence may be specified that is used to copy elements from.

Operations on list

iterator

This operation is redefined for list to return a modifying_iterator.

get

Yields the element at index position.

• indexed access
  

  set

  Operand type	Parameter type	Result type
  list<Type>	int Type	Type

  Sets the element at index position to the specified value. Yields the new value.
  
• indexed access
  

  add

  Operand type	Parameter type	Result type
  list<Type>	Type	Type

  Adds an element to the list.
  

  addFirst

  Operand type	Parameter type	Result type
  list<Type>	Type	Type

  Adds an element to the list as the first element.
  

  addLast

  Operand type	Parameter type	Result type
  list<Type>	Type	Type

  Adds an element to the list as the last element.
  

  insert

  Operand type	Parameter type	Result type
  list<Type>	int Type	Type

  Inserts an element into the list at the position index.
  

  remove

  Operand type	Parameter type	Result type
  list<Type>	Type	Type

  Removes an element from the list.
  

  removeFirst

  Operand type	Parameter type	Result type
  list<Type>	none	Type

  Removes the first element from the list.
  

  removeLast

  Operand type	Parameter type	Result type
  list<Type>	none	Type

  Removes the last element from the list.
  

  removeAt

  Operand type	Parameter type	Result type
  list<Type>	int	Type

  Removes an element from the list located at the position index.
  

  addAll

  Operand type	Parameter type	Result type
  list<Type>	sequence<Type>	list<Type>

  Adds all elements in the parameter sequence to the list.
  

  removeAll

  Operand type	Parameter type	Result type
  list<Type>	sequence<Type>	list<Type>

  Removes all elements in the parameter sequence from the list.
  

  clear

  Operand type	Parameter type	Result type
  list<Type>	none	void

  Clears all elements from the list.
  

reverse

Produces a list with all elements from the original list in the reversed order.

---

Set

A basic set container backed by either hash set or linked hash set.

Set type

set<Type>

Set creation

new hashset
new linked_hashset

Creates an empty set. Optionally, initial values may be specified right in the new set creation expression.

Alternatively, a sequence may be specified that is used to copy elements from.

Operations on set

iterator

This operation is redefined for set to return a modifying_iterator.

add

Adds an element to the set.

addAll

Adds all elements in the parameter sequence to the set.

remove

Removes an element from the set.

removeAll

Removes all elements in the parameter sequence from the set.

clear

Clears all elements from the set.

---

Sorted Set

A subtype of set that provides iteration over its elements in the natural sorting order, backed by a tree set.

Sorted Set type

set<Type>

Sorted set creation

new treeset

Creates an empty set. Optionally, initial values may be specified right in the new set creation expression.

Alternatively, a sequence may be specified that is used to copy elements from.

Operations on sorted set

headSet

Results in a sorted_set that is a subset of all elements from the original set in the original sorting order, starting with the first element and up to but not including the specified element.

tailSet

Results in a sorted_set that is a subset of all elements from the original set in the original sorting order, starting with the specified element.

subSet

Results in a sorted_set that is a subset of all elements from the original set in the original sorting order, starting with the first specified element and up to but not including the second specified element.

---

Map

A map container backed by either a hash map or a linked hash map.

Map type

map<KeyType, ValueType>

The map type is retrofitted to be a subtype of sequence.

Map creation

new hashmap
new linked_hashmap

Creates an empty map. Optionally, initial values may be specified right in the new map creation expression.

Operations on map

get value by key

keys

Results in a sequence containing all the keys in the map.

containsKey

Returns true if the map contains a mapping for the specified key, false otherwise.

values

Results in a sequence containing all the values in the map.

containsValue

Returns true if the map contains a mapping with the specified value, false otherwise.

mappings

Results in a set of mappings contained by this map. The mappings can be removed from the set, but not added.

assign value to a key

remove

Removes the specified key and the associated value from the map.

clear

Clears all key-value pairs from the map.

putAll

Puts all mappings from the map specified as a parameter into this map, replacing existing mappings.

—

Sorted Map

A subtype of map that provides iteration over keys conforming to the natural sorting order, backed by a tree map.

Sorted map type

map<KeyType, ValueType>

Sorted map creation

new treemap

Creates an empty tree map. Optionally, initial values may be specified right in the new map creation expression.

Operations on sorted map

headMap

Results in a sorted_map that is a submap of the original map, containing all the mappings in the original sorting order, starting with the first key and up to but not including the specified key.

tailMap

Results in a sorted_map that is a submap of the original map, containing all the mappings in the original sorting order, starting with the specified key.

subMap

Results in a sorted_map that is a submap of the original map, containing all the mappings in the original sorting order, starting with the first specified key and up to but not including the second specified key.

—

Stack

A simple stack abstraction, backed by linked list.

Stack type

stack<Type>

Stack creation

new linkedlist

Creates an empty stack. Optionally, initial values may be specified right in the new linked list creation expression.

Alternatively, a sequence may be specified that is used to copy elements from.

Operations on stack

iterator

This operation is redefined for stack to return a modifying_iterator.

addFirst / push

Appends an element to the head of the stack.

removeFirst / pop

Removes an element from the head of the stack.

first / peek

Retrieves the first element at the head of the stack without removing it.

—

Queue

A simple queue abstraction, backed by linked list or priority queue.

Queue type

queue<Type>

Queue creation

new linkedlist
new priority_queue

Creates an empty queue. Optionally, initial values may be specified right in the new linked list creation expression.

Alternatively, a sequence may be specified that is used to copy elements from.

Operations on queue

iterator

This operation is redefined for queue to return a modifying_iterator.

addLast

Appends an element to the tail of the queue.

removeFirst

Removes an element from the head of the queue.

first

Retrieves the first element at the head of the queue without removing it.

last

Retrieves the first element at the tail of the queue without removing it.

—

Deque

A simple double-linked queue abstraction, backed by linked list.

Deque type

queue<Type>

Deque creation

new linkedlist

Creates an empty deque. Optionally, initial values may be specified right in the new linked list creation expression.

Alternatively, a sequence may be specified that is used to copy elements from.

Operations on deque

iterator

This operation is redefined for deque to return a modifying_iterator.

addFirst / push

Appends an element to the head of the deque.

addLast

Appends an element to the tail of the deque.

removeFirst / pop

Removes an element from the head of the deque.

first

Retrieves the first element at the head of the deque without removing it.

last

Retrieves the first element at the tail of the deque without removing it.

—

Iterator

A helper type that is analogous to java.util.Iterator. An instance of the iterator can be obtained with the iterator operation on a sequence.

Iterator type

iterator<Type>

Operations on iterator

hasNext

Tests if there is an element available.

next

Returns the next element.

---

Modifying Iterator

A subtype of iterator that supports remove operation.

Modifying Iterator type

modifying_iterator<Type>

Operations on modifying iterator

remove

Removes the element this iterator is currently positioned at.

---

Enumerator

An alternative to the iterator, a helper type that works similar to .NET's IEnumerator. An instance of the enumerator can be obtained with the enumerator operation on a sequence.

Enumerator type

enumerator<Type>

Operations on enumerator

moveNext

Moves to the next element. Returns true if there is an element available.

current

Returns the element this enumerator is currently positioned at.

---

Mapping

A helper type used by map and sorted_map.

Mapping type

mapping<KeyType, ValueType>

Operations on mapping

get value

set value

get key

---

Custom Containers

Custom containers is a simple way to provide own implementation of standard container types, thus allowing for easy extensibility of the collections language.

Example: weakHashMap

Provided the following declaration is reachable from the model currently being edited...

... one can use the weak version of hashmap thusly:

Custom Containers Declaration

A root node of concept CustomContainers may have one or more declarations.

---

Primitive Containers

Collections framework include a set of custom containers designed to work with primitive data types. Using primitive types helps optimize speed and/or size of the containers. These containers are available with a separate language jetbrains.mps.baseLanguage.collections.trove.

Primitive list containers

list<?,?>

Primitive set containers

set<?,?>

Primitive maps

map<byte,?>

map<double,?>

map<float,?>

map<int,?>

map<long,?>

map<short,?>

<K> map<K,?>

---

Previous Next