Runtime Type : Types : Collection
Analogs: array, list, vector
Inherits from: root→Object→Collection
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
path
- value
- The value to match.
- 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
path
- value
- The value to match.
- 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
item
- selectionName
- The name of the selection list. If you don't specify a name, then the selection is retrieved from the default selection list.
- 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
Specialized Properties
None.
Unique Properties
Best Practices
Advanced Concepts