Runtime Type : Types : Collection

Page Status: Beta
Jump to: navigation, search

Analogs: array, list, vector 

Inherits from: root→Object→Collection

Back to Runtime Types

Collection is one of the most widely used classes of all the Bungee runtime types. Collections are used to manage ordered lists of objects or primitives, called elements when contained in a collection. A collection can contain duplicate elements, and can also contain elements based on different classes.

A collection also has a selection manager for identifying and manipulating one or more specific elements in a selection list. Selection lists can de defined either through user interaction with controls bound to a collection, or through program logic. See Using Selection Lists for more information.

Contents

Key Concepts

Understanding how to use the collection type is one of the most important concepts in Bungee Connect. The collection type is integral to numerous common design patterns. This section presents several important concepts that when understood, help you make the best use collections.

Attributes and Behaviors

Element

Each object or primitive in a collection is called an element. In the case of collections of objects, each element has a type, commonly referred to as the element class or element type. For example, if you have a collection called people, and it contains Person objects, then the element class is the class named Person.

Index

Each element in a collection is assigned an ordinal number called an index, starting with zero (0) for the first element. Index values are often used by functions that manipulate individual elements in the collection (such as Collection.get and Collection.set).

Heterogeneous Collection

A collection can contain objects of different types. In order to do so, the collection's element class must be based on a class from which each element object type inherits. For example, if you wish to add Intern and Contractor objects to a collection called People, and both the Intern and Contractor classes inherit from a Person class, then set the collection's element class to Person.

Selection

It is possible to select one or more elements in the collection type, either programatically or by user interaction through various controls. For example, when a user clicks an item in a List control, the item in the List then appears to be selected. However, the actual selection is on the corresponding element in the collection to which the List control has been bound. In other words, the selection actually takes place in the application's Model rather than its View.

  • The collection type provides various functions that allow you to manipulate one or more selected elements.
  • Each control that can act as a list has a connection type containing a selectedElement node that allows you to link single-element selections to an external object. [link to one of the Control examples].
  • Because selections are an aspect of the collection type itself, by default, when two controls are bound to the same collection, they automatically synchronize to display the same element(s) as selected. To have two (or more) controls independently manage selections on a single collection, see Using Selection Lists.

Example Code

You can import example code into your Bungee Builder workspace for this runtime type from the Home tab in the Design Editor panel, under Open Example Code.

Common Uses

Declaring a Collection

You can declare a collection as a field or a var. Because Collection is a special type, declaring collections varies from the usual way of declaring an object's type.

Declaring a Field as a Collection

To declare a field as a Collection: add a field to a class, set the field's Type property (General tab) to the element class for the collection, and select the Is Collection property.

Declaring a Var as a Collection

To declare a var as a Collection in Bungee Logic, add a var statement in the code editor, then set its type to Collection. In order for the var to function properly as a collection, you must instantiate ('new') it by setting its Default Value property site to either Object or Collection. By setting the site to Collection, the var functions as a constructor, allowing you to declare default elements in the collection.

Populating Default Elements

If you wish to declare a collection and have it contain some elements by default, set the site on the field's Default Value property (General tab) to Collection, then click the detail button. In the detail dialog, you can add and remove elements based on the element class for the collection. For example, for a collection named people with an element class of Person, you could add several Person objects, or objects based on a subclass of Person.

Using a Collection of Collections

By declaring the element class for a collection as Collection, a collection can contain other collections, allowing you to increase the sophistication with which your applications manipulate data.

Using Collection Iteration in Bungee Logic:

You can perform programmatic actions to all elements in a collection by using the Collection Iteration statement in Bungee Logic.

Class Members

Fields

int32 numItems The number of elements in the collection.
int numSelected The number of elements selected for the selection list identified by the numSelectedName field.
string numSelectedName Contains the name of the selection list for the numSelected field. The numSelected field is updated when this field is assigned a new value.
boolean selectOnRemove A flag indicating whether elements are removed from the collection when they are selected.

Functions

Function Summary
Adding/Removing
add Adds an element to the end of the collection and increments the index count by 1.
addCollection Adds all the elements from another collection you specify to the end of this collection in the order in which they exist in the added collection.
insert Inserts an element into the collection at the index you specify.
insertCollection Inserts all the elements from another collection you specify into this collection at the index you specify.
remove Removes an element from the collection at the index you specify
removeAll Removes all elements from the collection.
removeAllByValue Removes from the collection all instances of an element matching the value you specify.
removeByValue Removes from the collection the first (lowest indexed) instance of an element matching the value you specify.
removeSelected Removes all currently selected elements from the collection.
 Getting/Setting
get Retrieves the element at the index you specify.
getLastSelectedData Returns the element from the collection whose index is the last stored index in the selection list.
getSelectedData Creates and returns a sub-collection of elements from the original collection using the list of indices from the selection list.
getSubCollection Creates a sub-collection of elements from the original collection based on a starting index, a count, and whether to move forward or backward. 
selectedItems Returns a collection containing the current selection for one or more selected items.
singleSelectedItem Returns the currently selected element (single).
 Finding/Moving
findAllByValue Locates all instances of an element in a collection and stores the results in a second collection.
findByValue Locates the first instance of an element in a collection and returns the object and/or its index value.
move Moves an element from its current index to another index.
moveOne Moves the currently selected (single) element ‘up’ or ‘down’ by one index position.
set Replaces the element at a specified index with a specified element.
setFilter Sets a filter on the specified collection.
sort Sorts the elements in the collection, either in ascending (default) or descending order.
Selecting
clearSelection Removes the selected element from the specified named selection list.
clearSelectionMultiple Removes all selected elements from the specified named selection list.
deselect Removes the single selection from a specified named selection list.
deselectMultiple Removes multiple selections from a specified named selection list.
select Modifies the selected elements in the specified named selection list using the a single specified index.
selectMultiple Modifies the selected elements in the specified named selection list using the elements in a specified set of indexes.
selectNext Useful for a named selection list containing only one selected element. 
Resets
the single selected element to the element immediately following the currently selected element in the specified named selection list.
selectPrevious Useful for a named selection list containing only one selected element. 
Resets the single selected element to the element immediately preceeding the currently selected element in the specified named selection list.
selectByValue Locates the first element in the collection matching the data argument and selects the element in the specified named selection list.
Comparing
Complement Compares two collections and returns the elements in the first collection that are not in the second collection.
Intersection Compares two collections and returns the elements that are contained in both collections.
Union Compares two collections and returns all the elements that are in the first collection and all the elements in the second collection. Duplicate elements are returned only once.
Adding/Removing
add
Adds an element to the end of the collection and increments the index count by 1.

Syntax

add([in] Data element)

Parameters

element
The element to add to the collection.

Error Handling

If data is null, then no action is taken, and no error condition is raised.
addCollection

Adds all the elements from another collection you specify to the end of this collection in the order in which they exist in the added collection.

Syntax

addCollection([in] Data collection)

Parameters

collection
The collection whose elements will be added to this collection.

Error Handling

If data is null, then no action is taken, and no error condition is raised.
insert

Inserts an element into the collection at the index you specify. Shifts the element currently at that position (if any) and any subsequent elements to the right (increments their indices by 1).

Syntax

insert([in] int index, [in] Data element)

Parameters

index
The index at which to insert the new element.
element
The element to insert.

Error Handling

An exception is raised if the specified index is invalid (index < 0 | index > numItems - 1).
If data is null, then no action is taken, and no error condition is raised.
insertCollection

Inserts all the elements from another collection you specify into this collection at the index you specify. Shifts the element currently at that index (if any) and any subsequent elements to the right (increments their indices by the number of elements inserted). The new elements appear in this collection in the order in which they exist in the other collection.

Syntax

insertCollection([in] int index, [in] Data collection)

Parameters

index
The index at which to begin inserting.
collection
The collection containing the elements to insert.

Error Handling

An exception is raised if the specified index is invalid (index < 0 | index > numItems - 1).
If data is null, then no action is taken, and no error condition is raised.
remove

Removes an element from the collection at the index you specify. Shifts any subsequent elements to the left (subtracts 1 from their indices). If you do not specify an index, defaults to remove the element at index 0.

Syntax

remove([in] int index)

Parameters

index
The index of the element to remove.

Error Handling

An exception is raised if the index you specified is invalid (index < 0 | index > numItems - 1).

removeAll

Removes all elements from the collection.

Syntax

removeAll()

Error Handling

If the collection is already empty, then no action is taken, and no error condition is raised.
removeAllByValue

Removes from the collection all instances of an element matching the value you specify. If the collection does not contain the element, the collection is unchanged. If a matching element is found in the collection, the index of each element with an index greater than the index of the removed elements decrements by 1.

Syntax

removeAllByValue([in] Data value, [in] string path)

Parameters

value
The value to match.
path
Not needed for a collection of primitives. If you leave path <not set>, then each element in the collection is compared with the value in value to determine if there is a match and path is ignored.

If the collection contains complex objects, use path to speficy the path of the field to compare, using dotted notation. The removeByValue function attempts to resolve the path you specified for each element in the collection until a match is found. If the path cannot be resolved for a particular element, then the element is compared with the value in value to determine if it matches.

Error Handling

If there is no match for value or path, or if path is null, then no action is taken, and no error condition is raised. If value is null, then the function tries to find where the value of the field you specified in path is null.
removeByValue

Removes from the collection the first (lowest indexed) instance of an element matching the value you specify. If the collection does not contain the element, the collection is unchanged. If a matching element is found in the collection, the index of each element with an index greater than the index of the removed element decrements by 1.

Syntax

removeData([in] Data value, [in] string path)

Parameters

value
The value to match.
path
Not needed for a collection of primitives. If you leave path <not set>, then each element in the collection is compared with the value in value to determine if there is a match and path is ignored.

If the collection contains complex objects, use path to speficy the path of the field to compare, using dotted notation. The removebyValue function attempts to resolve the path you specified for each element in the collection until a match is found. If the path cannot be resolved for a particular element, then the element is compared with the value in value to determine if it matches.

Error Handling

If there is no match for value or path, or if path is null, then no action is taken, and no error condition is raised. If value is null, then the function tries to find where the value of the field you specified in path is null.
removeSelected

Removes the selection for a specified selection list. Both single and multiple selections are allowed.

Syntax

removeSelected([in] string selectionName)

Parameters

selectionName
The name of the selection list. If you do not specify a selection list name, then the selected elements are removed from the default selection list.

Error Handling

 


Getting/Setting
get

Retrieves the element at a specified index.

Syntax

get([in] int index, [out] Data element)

Parameters

index
The zero-based index of the element to retrieve.
element
A data value that receives the element at the specified index. This value is null if the specified index is invalid.

Error Handling

No element is returned and an exception is raised if the specified index is invalid ( index < 0 | index > numItems - 1). 
getLastSelectedData

Returns the element from the collection whose index is the last stored index in the selection list.

Syntax

getLastSelectedData([in] string selectionName, [out] Data element)

Parameters

selectionName
The name of the selection list containing the index to use. If you don't specify a name, then the selection is retrieved from the default selection list.
element
Contains the element returned.

Error Handling

If name is invalid (null or non-existent selection list), then selectedData is null, no action is taken, and no error condition is raised.
getSelectedData

Creates and returns a sub-collection of elements from the original collection using the list of indices from the selection list.

Syntax

getSelectedData([in] string selectionName, [out] Collection selectedData)

Parameters

selectionName
The name of the selection list containing the indices of the selected items to use for the sub-collection. If you don't specify a name, then the selection is retrieved from the default selection list.
selectedData
Contains the sub-collection returned.

Error Handling

If name is invalid, then selectedData is null, no action is taken, and no error condition is raised.
getSubCollection

Creates a sub-collection of elements from the original collection based on a starting index, a count, and whether to move forward or backward.

Syntax

getSubCollection([in] int start, [in] int count, [in] boolean backup, [out] Collection result)

Parameters

start
The index to start from.
count
The number of elements to include in the sub-collection.
backup
Indicates whether to count forward or backward from the start index.
result
Contains the resulting sub-collection returned.

Error Handling

If the count goes beyond the top or bottom of the master collection, then only the existing part is copied to the sub-collection. No error condition is raised.
selectedItems

Returns a collection containing the current selection for one or more selected elements.

Syntax

selectedItems([in] string selectionName, [out] Collection(CollectionItem) items)

Parameters

selectionName
The name of the selection list. If you don't specify a name, then the selection is retrieved from the default selection list.
items
A value that recieves a collection containing the current selection. Both the index and the element's value are returned.

Error Handling

An exception is raised if the specified index is invalid (index < 0 | index > numItems - 1).
singleSelectedItem

Returns the current selection for a selection list you specify.

Syntax

singleSelectedItem([in] string selectionName, [out] CollectionItem item)

Parameters

selectionName
The name of the selection list. If you don't specify a name, then the selection is retrieved from the default selection list.
item
A value that receives the current selection. Both the index and the element's value are returned.

Error Handling

If more than one element is selected, - 1 is returned as the index.

 


Finding/Moving
findAllByValue

Locates all instances of an element in a collection. Returns a collection containing all elements that are currently selected (multiple).

Syntax

findByValue([in] Data value, [in] string path, [out] Collection(CollectionItem) elements)

Parameters

value
The value to seek for finding an element. This parameter can be the value of a primitive element, or can be used with the path argument to find based ond the value of a field for a complex element type. It is also possible to provide a whole object for this parameter in order to locate object that exactly matches, field for field.
path
The name of the field on which to perform the search. In the case of a collection of primitives, you do not need to provide this parameter. For complex objects, specify the field by name. Use dotted path notation such as “name.last” to identify complex fields. When findByValue is used on a collection of heterogeneous element types, the function attempts to resolve the path specified for each element in the collection. When the path cannot be resolved for a particular element, no path is specified, then the element is compared directly with the value provided in the data argument to determine a match.
elements
The output collection of the items found. Each item found is passed into the collection as a Data.

Error Handling

If data is null, then the function attempts to find an object in the collection that is equal to the object in memberName . If memberName is null, then no action is taken, and no error condition is raised.
findByValue

Locates the first instance of an element in a collection. Returns a collection containing all elements that are currently selected (multiple).

Syntax

findByValue([in] Data value, [in] string path, [out] Data element, [out] int index) 

Parameters

value
The value to seek for finding an element. This parameter can be the value of a primitive element, or can be used with the path argument to find based ond the value of a field for a complex element type. It is also possible to provide a whole object for this parameter in order to locate object that exactly matches, field for field.
path
The name of the field on which to perform the search. In the case of a collection of primitives, you do not need to provide this parameter. For complex objects, specify the field by name. Use dotted path notation such as “name.last” to identify complex fields. When findByValue is used on a collection of heterogeneous element types, the function attempts to resolve the path specified for each element in the collection. When the path cannot be resolved for a particular element, no path is specified, then the element is compared directly with the value provided in the data argument to determine a match.
element
Returns the whole object for the element found.
index
Returns the index for the first matching element found in the collection. A value of -1 indicates that no match was found.

Error Handling

If data is null, then the function attempts to find an object in the collection that is equal to the object in memberName . If memberName is null, then no action is taken, and no error condition is raised.
move

Moves an element from its current index to another index.

Syntax

move([in] int oldIndex, [in] int newIndex)

Parameters

oldIndex 
The index of the element to move.
newIndex 
The new index for the element being moved.

Error Handling

An exception is raised if either the old or new indexes are invalid (index < 0 | index > numItems - 1).
moveOne

Moves the currently selected (single) element up or down by one position.

Syntax

moveOne([in] string direction)

Parameters

direction 
The direction to move the current selection. Valid values are up and down (case insensitive), typically assigned by setting the site to Data and entering the desired direction. Values other than up or down are ignored.

Error Handling

set

Replces the element at a specified index.

Syntax

set([in] int index, [in] Data element)

Parameters

index
The index of the element to replace.
element
The element to place at the specified index.

Error Handling

An exception is raised if the specified index is invalid (index < 0 | index > numItems - 1).
setFilter

Establishes a filtered collection, populating it with elements from a source collection by object type (class). using criteria defined in a FilterFolder object. Elements in a filtered collection simply reference their counterparts in the source collection, so changes to an element in the filtered collection are applied to the corresponding element in the source collection (and vice-versa). However, adding elements to the filtered collection does not add a corresponding element to the source collection.

Syntax

setFilter([in] Collection collection, [in] FilterFolder filter)

Parameters

sourceCollection 
The source collection from elements will be gathered according to the filter.
filterFolder
The FilterFolder object to apply to the collection.

Error Handling

If filter is null, then the collection is not filtered. If collection is null, then no action is taken, and no error condition is raised.
sort
Sorts the elements in the collection, either in ascending (default) or descending order.
  • If the element type is a primitive (e.g., int or string), sorting is simply performed by value.
  • If the element is a complex type, then sorting is performed by a field specified as the primary key, and optionally by a secondary key.
  • If the collection contains heterogeneous object types, then each object type must have a field of the same name as the specified primary and secondary keys.

Syntax

sort([in] string primaryKey, [in] string secondaryKey, [in] boolean descending, [in] boolean ignoreCase)

Parameters

primaryKey

The name of the field to use as the primary key. For complex fields, use standard dotted notation.
This is typically implemented by setting the site to “Data” and entering the name of the field.

secondaryKey

The name of the field to use as the secondary key.

descending

Sort in descending order (greatest value first) rather than ascending.

ignoreCase

Ignore case when comparing elements in the collection. By default, all lower case letters are sorted after upper case letters.

 Error Handling 


Selecting
clearSelection

Removes the selected element from the specified named selection list.

This function should only be used with a selection list that has only one selected element.

Syntax

clearSelection([in] string selectionName)

Parameters

selectionName
The name of the selection list. If no name is specified, then a selected element is removed from the default selection list.
Error Handling
If selectionName is invalid, then no action is taken, and no error condition is raised. If selectionName is a selection list with multiple selected elements, the change to the selection list is indeterminant.
clearSelectionMultiple

Removes all selected elements from the specified named selection list.

Syntax

clearSelectionMultiple([in] string selectionName)

Parameters

selectionName
The name of the selection list. If no name is specified, then all selected elements are removed from the default selection list.
Error Handling
If selectionName is invalid, then no action is taken, and no error condition is raised.
deselect

Removes a single selected element from a specified named selection list.

If there are multiple elements selected in the named selection list, only the element at the index you specify will be deselected.  If the element at the index you specify is not currently selected in the named selection list specified, no action is taken.

Syntax

deselect([in] string selectionName, [in] int index)

Parameters

selectionname
The name of the selection list. If no name is specified, then the selection is modified for the default selection list.
index 
The index of the element to deselect in the specified selection list.
Error Handling
If selectionName is invalid, then no action is taken, and no error condition is raised. If index is invalid (less than -1 or greater than the size of the collection) then an IndexRangeException is raised.
deselectMultiple

Removes multiple selected elements from a specified named selection list.

Any elements selected in the named selection list you specify with selectionName, whose index is contained in the collection you specify with indexes, will be deselected in the selection list.

Syntax

deselectMultiple([in] string selectionName, [in] Collection(int) indexes)

Parameters

selectionName 
The name of the selection list. If no name is specified, then the selection is modified for the default selection list.
indexes
A collection of indexes to deselect in the specified selection list.

Error Handling

If selectionName is invalid, then no action is taken, and no error condition is raised. An InvalidTypeException is raised if indexes is not a collection. 

select

Modifies the selected elements in the specified named selection list using a single specified index.

Syntax

select([in] string selectionName, [in] int index, [in] boolean selectRemoves)

Parameters

selectionName
The name of the selection list. If no name is specified, then the selection is modified for the default selection list.
index
The index of the element to select.
selectRemoves
A boolean that determines if the element specified with index will be added to the selected elements in the selection list, selectionName, or if element specified with index will become the only selected element in the selection list, selectionName.

If selectRemoves is false, the element specified with index is added to the selected elements of the specified selection list.

If selectRemoves is true, all other selected elements are removed first, then the element specified with index becomes the only element selected in the specified selection list.

Error Handling

If selectionName is invalid, then no action is taken, and no error condition is raised. If index is invalid (less than -1 or greater than the size of the collection) then an IndexRangeException is raised.
selectMultiple

Modifies the selected elements in the specified named selection list using the elements in a specified collection of indexes.

Syntax

selectMultiple([in] string selectionName, [in] Collection(int) indexes, [in] boolean selectRemoves)

Parameters

selectionName
The name of the selection list. If no name is specified, then the selection is modified for the default selection list.
indexes
A collection containing the indexes of the elements to select.
selectRemoves
A boolean that determines if the elements specified with indexes will be added to the selected elements in the selection list, selectionName, or if the elements specified with indexes will become the only selected elements in the selection list, selectionName.

If selectRemoves is false, the elements specified with indexes are added to the selected elements of the specified selection list.

If selectRemoves is true, all other selected elements are removed first, then the elements specified with indexes become the only elements selected in the specified selection list.

Error Handling

If selectionName is invalid, then no action is taken, and no error condition is raised. An InvalidTypeException is raised if indexes is not a collection.
selectNext

Useful for a named selection list containing only one selected element. Resets the single selected element to the element immediately following (next highest index number) the currently selected element in the specified named selection list. If the single selected element in the specified selection list is at the last index in the collection, selectNext will select the first element in the collection for the specified selection list.

Syntax

selectNext([in] string selectionName)

Parameters

selectionName
The name of the selection list. If no name is specified, then the selection is modified for the default selection list.

Error Handling

selectPrevious

Useful for a named selection list containing only one selected element. Resets the single selected element to the element immediately preceding (next lower index number) the currently selected element in the specified named selection list. If the single selected element in the specified selection list is at the first index in the collection, selectNext will select the last element in the collection for the specified selection list.

Syntax

selectPrevious([in] string selectionName)

Parameters

selectionName
The name of the selection list. If no name is specified, then the selection is modified for the default selection list.

Error Handling

selectByValue

Locates the first element in the collection matching the data argument and selects the element in the specified named selection list. Any previous selections are removed from the specified selection list and only the element specified with data will be selected in the selection list. If no matching element is found, the selection list is not changed.

Syntax

selectByValue([in] string selectionName, [in] Data value, [out] boolean found, [in] string path)

Parameters

selectionName
The name of the selection list. If no name is specified, then the selection is set for the default selection list.
value
An object matching the element to select.
found
An object that receives a flag indicating whether the specified element was found in the collection.
True indicates that the specified element was found and the selection list was changed.
False indicates that no element was found and the selection list was not changed.
path
The path of the field to compare, specified using dotted notation. The selectByValue function attempts to resolve the specified path for each element in the collection. If the path cannot be resolved for a particular element, then the element is compared with the value in value to determine if it matches. If no path is specified, then each element is compared with the value in value to determine if it matches.

Error Handling


Comparing
Complement

Compares two collections and returns the elements in the first collection that are not in the second collection.

Syntax

complement([in] string path, [in] Collection collection, [out] Collection complement)

Parameters

path
A dotted path to the field you want to use in comparing the objects in the collection.
collection
The second collection to which the first collection is compared.
complement 
A collection consisting of the elements in the first collection that are not in the second collection.
Error Handling
Intersection

Compares two collections and returns the elements that are contained in both collections.

Syntax

intersection([in] string path, [in] Collection collection, [out] Collection intersection)

Parameters

path
A dotted path to the field you want to use in comparing the objects in the collection.
collection
The second collection to which the first collection is compared.
intersection
A collection consisting of the elements that are in both collections.
Error Handling
Union

Compares two collections and returns all the elements that are in the first collection and all the elements in the second collection. Duplicate elements are returned only once.

Syntax

union([in] string path, [in] Collection collection, [out] Collection union)

Parameters

path
A dotted path to the field you want to use in comparing the objects in the collection.
collection
The second collection to which the first collection is compared.
union
A collection consisting of all the elements in the first collection and all the elements in the second collection.
Error Handling
 

 

Properties

Common Properties

Common Properties Index

Specialized Properties

  None.

Unique Properties

Best Practices

 

Advanced Concepts

 

See Also

Using Selection Lists, Map, CollectionItem, FilterFolder

    Copyright © 2005 - 2007 Bungee Labs. All rights reserved.