6.22.1 Types of Collections
The type of collection will depend on its purpose, you can choose from:
Sorted Array Collection (PRIM_SACO)
Dictionary Collection (PRIM_DCOL)
Sorted Dictionary Collection (PRIM_SDCO)
Keyed collections are an unordered sequence of components identified by a key value. No duplicates of the key value are allowed. A keyed collection can be keyed by any field in the repository.
Define_Com Class(#prim_kcol<#Prim_Form #Std_num>) Name(#Forms)
Adding items to the collection is relatively slow as the key has to be maintained. However, lookup in the collection is comparatively fast as the key is used to directly access the item.
#Form <= #Forms<#std_num>
or
#Form <= #Forms<123>
Iterating over the collection using the FOR command will return the items in key order.
Keyed collections are best suited to relatively small amounts of data used where fast lookup is required.
List collections provide an ordered collection of components. The features of the list component are positional in nature, in reference to a given index or to the beginning or end of the list. Indexing is always relative to 1.
Define_Com Class(#prim_lcol<#Prim_Form>) Name(#Forms)
Adding items to the collection is relatively quick as there is no key to maintain. However, lookup in the collection is relatively slow due to the sequential nature of the list unless the specific index is known. Items can be added at specific positions, for example, first, last, before or after a specific index.
#Forms.InsertBefore(#Form 5)
Iterating over the collection using the FOR command will return the items in the order that they were added.
List collections are best suited to situations where the data will be collected and then later iterated over.
Array collections provide a dynamically sized, ordered collection of components. The features of the array component are positional in nature, in reference to a given index or to the beginning or end of the collection. Indexing is always relative to 1.
Define_Com Class(#prim_acol<#Prim_Form>) Name(#Forms)
Adding items to the collection is relatively quick as there is no key to maintain. However, lookup in the collection is relatively slow due to the sequential nature of the list unless the specific index is known. Items can be added at specific positions, for example, first, last, before or after a specific index.
#Forms.InsertFirst(#Form)
Iterating over the collection using the FOR command will return the items in the order that they were added.
Array collections are best suited to situations where the data will be continually and directly accessed.
Sorted Array Collection (PRIM_SACO)
Sorted Array collections provide a dynamically sized, sorted collection of components. The features of the array component are positional in nature, in reference to a given index or to the beginning or end of the collection. Indexing is always relative to 1.
Define_Com Class(#prim_saco<#Prim_Form>) Name(#Forms)
Adding items to the collection is relatively slow as the collection is sorted. Whenever the collection needs to sequence two objects it fires the Compare event. This allows you to determine the sort sequence for the items based on whatever arbitrary sequence you need.
Lookup in the collection is relatively slow due to the non-keyed nature of the list unless the specific index is known.
#Forms.Insert(#Form)
Iterating over the collection using the FOR command will return the items based on the order of the sort defined.
Sorted Array collections are best suited to situations where the data will be continually and directly accessed and you want to determine the sort sequence.
Set collections provide an unordered collection of components. Set collections cannot contain duplicate instances.
Define_Com Class(#prim_scol<#Prim_Form>) Name(#Forms)
Adding items to the collection is relatively quick as there is no key to maintain. However, lookup in the collection is relatively slow due to the non-keyed nature of the collection.
#Forms.Insert(#Form)
Iterating over the collection using the FOR command will return the items in a seemingly random order.
Set collections are best suited to processing large collections of objects to ensure a singularity.
Dictionary Collection (PRIM_DCOL)
Dictionary collections are an unordered sequence of key-value component pairs. Duplicate keys are not allowed.
Define_Com Class(#prim_dcol<#Prim_Form #Prim_objt>) Name(#Forms)
Adding items to the collection is relatively slow as the key has to be maintained. However, lookup in the collection is comparatively fast, as the key is used to directly access the item.
#Forms.Insert(#Form #Key)
Iterating over the collection using the FOR command will return the items in key order. However, as the key is a component the order will appear to be random.
Dictionary collections are best suited to relatively small amounts of data where fast lookup is required.
Sorted Dictionary Collection (PRIM_SDCO)
Dictionary collections are a sorted sequence of key-value component pairs. Duplicate keys are not allowed.
Define_Com Class(#prim_sdco<#Prim_Form #Prim_objt>) Name(#Forms)
Adding items to the collection is relatively slow as the collection is sorted. Whenever the collection needs to sequence two objects it fires the Compare event. This allows you to determine the sort sequence for the items based on whatever arbitrary sequence you require.
#Forms.Insert(#Form #Key)
Iterating over the collection using the FOR command will return the items based on the order of the defined sort.
Sorted Dictionary collections are best suited to relatively small amounts of data where fast lookup is required and you want to determine the sort sequence.