KCML Collections
The KCML collection classes implement collections of pool handles, each referencing a string with the actual data. They can be organized various ways: Vector (array), List, Map and Hash.
Where applicable, identical methods are available for all types of collections allowing change of use after creation. The appropriate collection type to use in each circumstance depends on the functionality required - Vector and List contain elements in the order they are added, Map stores the element in sorted order, Hash contains no defined order but benefits from the fastest lookup. A Vector is fastest at index lookup as it is the only collection to behave like an array rather than requiring an iteration through a collection but the compromise is that inserting and removing items from the middle of a Vector is slowest. Both Map and Hash allow fast lookup, while Vector and List require a linear search.
Collection types
| Type | Purpose |
|---|
| Vector |
The Vector class resembles an array. That makes indexed access fast, but searching for elements slow.
The Add() and AddKey() methods grow the array as needed, but Insert() and Remove() are likely to
be slow.
|
| List |
The List class implements a linked list. That makes Insert() and Remove() fast,
but index access and searching for elements will be slow.
|
| Map |
The Map class implements a tree search. This makes Searching, Adding and Removing entries fast
but index lookup is slow. The iterator returns the collection in sorted order.
|
| Hash |
The Hash class implements a hashed array. This makes Searching, Adding and Removing entries
the fastest but index lookup is slow. The iterator returns the collection in an
implementation defined order. The order is not guaranteed and may be different on different
platforms or versions of KCML.
|
DEFCLASS
DEFCLASS KCML_VectorClass
DEFMETHOD SetKey(BYREF Key$()_KCML_SORT_REC_KEY) AS Void
A key may be used to define the order for sorted collections and to find items in the collection.
The simplest and default key is a simple string. The SetKey method can be used to define a complex
key using a string array of type KCML_SORT_REC_KEY, where each element of the array specifies a
segment of the key. The key is into the data of the element, so the simpler form of Add is used
where no separate key is specified.
DEFMETHOD Add(NewElement AS X) AS Void
Add a pool memory handle to the collection. Where the order is controlled by the user the item
is inserted at the end. This form of Add must be used when SetKey has been used to define a key,
and also may be used for unordered lists where searching is not required.
DEFMETHOD AddKey(NewElement AS X, Key$) AS Void
Add a pool memory handle to the collection. The key specifies the key for searching and sorting.
Where the order is controlled by the user the item
is inserted at the end. This form may only be used where SetKey has not been used to define
a key into the data.
DEFMETHOD InsertKey(NewElement AS X, Key$, BYREF BeforeKey$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Insert an item into the middle of an unordered collection. The item is inserted before the item
specified by Key.
DEFMETHOD InsertIndex(NewElement AS X, BeforeOrdinal AS Integer) AS Bool
Insert an item into the middle of an unordered collection. The item is inserted before the item
specified by the index Ordinal.
DEFMETHOD InsertElement(NewElement AS X, BeforeElement AS X) AS Bool
Insert an item into the middle of an unordered collection. The items is inserted before the item
whose value is specified by BeforeElement.
DEFMETHOD InsertIterator(NewElement AS X, BeforeIterator AS KCML_IteratorClass<KCML_VectorClass, X>) AS Bool
Insert an item into the middle of an unordered collection. The items is inserted before the item
whose value is specified by the iterator BeforeIterator.
DEFMETHOD RemoveKey(BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Remove an item from the collection. The item is specified by Key.
DEFMETHOD RemoveIndex(Ordinal AS Integer) AS Bool
Remove an item from the collection. The item is specified by its position Ordinal.
DEFMETHOD RemoveElement(Element AS X) AS Bool
Remove an item from the collection. The item is specified by its value Element.
DEFMETHOD RemoveIterator(Iterator AS KCML_IteratorClass<KCML_VectorClass, X>) AS Bool
Remove an item from the collection. The item is specified by its iterator Element.
DEFMETHOD GetEnumerator(Iterator AS KCML_IteratorClass<KCML_VectorClass, X>) AS Void
Sets the passed iterator to an iterator over the called collection.
DEFMETHOD Count() AS Numeric
Returns the number of items in the collection.
DEFMETHOD RemoveAll() AS Void
Removes all items from the collection.
DEFMETHOD Find(BYREF Element AS X, BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Finds an item in the collection. The key is either a string, where SetKey has not been used
(in which case trailing blanks will be stripped), or
a string completed to the sort specification.
DEFMETHOD FindIndex(BYREF Element AS X, Ordinal AS Integer) AS Bool
DEFMETHOD Set(NewValue AS X, BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
DEFMETHOD SetIndex(NewValue AS X, Ordinal AS Integer) AS Bool
DEFMETHOD SetElement(NewValue AS X, Element AS X) AS Bool
DEFCLASS KCML_ListClass
DEFMETHOD SetKey(BYREF Key$()_KCML_SORT_REC_KEY) AS Void
A key may be used to define the order for sorted collections and to find items in the collection.
The simplest and default key is a simple string. The SetKey method can be used to define a complex
key using a string array of type KCML_SORT_REC_KEY, where each element of the array specifies a
segment of the key. The key is into the data of the element, so the simpler form of Add is used
where no separate key is specified.
DEFMETHOD Add(NewElement AS X) AS Void
Add a pool memory handle to the collection. Where the order is controlled by the user the item
is inserted at the end. This form of Add must be used when SetKey has been used to define a key,
and also may be used for unordered lists where searching is not required.
DEFMETHOD AddKey(NewElement AS X, Key$) AS Void
Add a pool memory handle to the collection. The key specifies the key for searching and sorting.
Where the order is controlled by the user the item
is inserted at the end. This form may only be used where SetKey has not been used to define
a key into the data.
DEFMETHOD InsertKey(NewElement AS X, Key$, BYREF BeforeKey$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Insert an item into the middle of an unordered collection. The item is inserted before the item
specified by Key.
DEFMETHOD InsertIndex(NewElement AS X, BeforeOrdinal AS Integer) AS Bool
Insert an item into the middle of an unordered collection. The item is inserted before the item
specified by the index Ordinal.
DEFMETHOD InsertElement(NewElement AS X, BeforeElement AS X) AS Bool
Insert an item into the middle of an unordered collection. The items is inserted before the item
whose value is specified by BeforeElement.
DEFMETHOD InsertIterator(NewElement AS X, BeforeIterator AS KCML_IteratorClass<KCML_ListClass, X>) AS Bool
Insert an item into the middle of an unordered collection. The items is inserted before the item
whose value is specified by the iterator BeforeIterator.
DEFMETHOD RemoveKey(BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Remove an item from the collection. The item is specified by Key.
DEFMETHOD RemoveIndex(Ordinal AS Integer) AS Bool
Remove an item from the collection. The item is specified by its position Ordinal.
DEFMETHOD RemoveElement(Element AS X) AS Bool
Remove an item from the collection. The item is specified by its value Element.
DEFMETHOD RemoveIterator(Iterator AS KCML_IteratorClass<KCML_ListClass, X>) AS Bool
Remove an item from the collection. The item is specified by its iterator Element.
DEFMETHOD GetEnumerator(Iterator AS KCML_IteratorClass<KCML_ListClass, X>) AS Void
Sets the passed iterator to an iterator over the called collection.
DEFMETHOD Count() AS Numeric
Returns the number of items in the collection.
DEFMETHOD RemoveAll() AS Void
Removes all items from the collection.
DEFMETHOD Find(BYREF Element AS X, BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Finds an item in the collection. The key is either a string, where SetKey has not been used
(in which case trailing blanks will be stripped), or
a string completed to the sort specification.
DEFMETHOD FindIndex(BYREF Element AS X, Ordinal AS Integer) AS Bool
DEFMETHOD Set(NewValue AS X, BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
DEFMETHOD SetIndex(NewValue AS X, Ordinal AS Integer) AS Bool
DEFMETHOD SetElement(NewValue AS X, Element AS X) AS Bool
DEFCLASS KCML_MapClass
DEFMETHOD SetKey(BYREF Key$()_KCML_SORT_REC_KEY) AS Void
A key may be used to define the order for sorted collections and to find items in the collection.
The simplest and default key is a simple string. The SetKey method can be used to define a complex
key using a string array of type KCML_SORT_REC_KEY, where each element of the array specifies a
segment of the key. The key is into the data of the element, so the simpler form of Add is used
where no separate key is specified.
DEFMETHOD Add(NewElement AS X) AS Void
Add a pool memory handle to the collection. Where the order is controlled by the user the item
is inserted at the end. This form of Add must be used when SetKey has been used to define a key,
and also may be used for unordered lists where searching is not required.
DEFMETHOD AddKey(NewElement AS X, Key$) AS Void
Add a pool memory handle to the collection. The key specifies the key for searching and sorting.
Where the order is controlled by the user the item
is inserted at the end. This form may only be used where SetKey has not been used to define
a key into the data.
DEFMETHOD RemoveKey(BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Remove an item from the collection. The item is specified by Key.
DEFMETHOD RemoveIndex(Ordinal AS Integer) AS Bool
Remove an item from the collection. The item is specified by its position Ordinal.
DEFMETHOD RemoveElement(Element AS X) AS Bool
Remove an item from the collection. The item is specified by its value Element.
DEFMETHOD RemoveIterator(Iterator AS KCML_IteratorClass<KCML_MapClass, X>) AS Bool
Remove an item from the collection. The item is specified by its iterator Element.
DEFMETHOD GetEnumerator(Iterator AS KCML_IteratorClass<KCML_MapClass, X>) AS Void
Sets the passed iterator to an iterator over the called collection.
DEFMETHOD Count() AS Numeric
Returns the number of items in the collection.
DEFMETHOD RemoveAll() AS Void
Removes all items from the collection.
DEFMETHOD Find(BYREF Element AS X, BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Finds an item in the collection. The key is either a string, where SetKey has not been used
(in which case trailing blanks will be stripped), or
a string completed to the sort specification.
DEFMETHOD FindIndex(BYREF Element AS X, Ordinal AS Integer) AS Bool
DEFCLASS KCML_HashClass
DEFMETHOD SetKey(BYREF Key$()_KCML_SORT_REC_KEY) AS Void
A key may be used to define the order for sorted collections and to find items in the collection.
The simplest and default key is a simple string. The SetKey method can be used to define a complex
key using a string array of type KCML_SORT_REC_KEY, where each element of the array specifies a
segment of the key. The key is into the data of the element, so the simpler form of Add is used
where no separate key is specified.
DEFMETHOD Add(NewElement AS X) AS Void
Add a pool memory handle to the collection. Where the order is controlled by the user the item
is inserted at the end. This form of Add must be used when SetKey has been used to define a key,
and also may be used for unordered lists where searching is not required.
DEFMETHOD AddKey(NewElement AS X, Key$) AS Void
Add a pool memory handle to the collection. The key specifies the key for searching and sorting.
Where the order is controlled by the user the item
is inserted at the end. This form may only be used where SetKey has not been used to define
a key into the data.
DEFMETHOD RemoveKey(BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Remove an item from the collection. The item is specified by Key.
DEFMETHOD RemoveIndex(Ordinal AS Integer) AS Bool
Remove an item from the collection. The item is specified by its position Ordinal.
DEFMETHOD RemoveElement(Element AS X) AS Bool
Remove an item from the collection. The item is specified by its value Element.
DEFMETHOD RemoveIterator(Iterator AS KCML_IteratorClass<KCML_HashClass, X>) AS Bool
Remove an item from the collection. The item is specified by its iterator Element.
DEFMETHOD GetEnumerator(Iterator AS KCML_IteratorClass<KCML_HashClass, X>) AS Void
Sets the passed iterator to an iterator over the called collection.
DEFMETHOD Count() AS Numeric
Returns the number of items in the collection.
DEFMETHOD RemoveAll() AS Void
Removes all items from the collection.
DEFMETHOD Find(BYREF Element AS X, BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Finds an item in the collection. The key is either a string, where SetKey has not been used
(in which case trailing blanks will be stripped), or
a string completed to the sort specification.
DEFMETHOD FindIndex(BYREF Element AS X, Ordinal AS Integer) AS Bool
DEFSTRUCT Methods
| Method | Vector | List | Map | Hash |
|---|
| SetKey(Key) |
X
|
X
|
X
|
X
|
| Add(NewElement) |
X
|
X
|
X
|
X
|
| AddKey(NewElement, Key) |
X
|
X
|
X
|
X
|
| InsertKey(NewElement, Key, BeforeKey, bStripTrailingSpace) |
X
|
X
| | |
| InsertIndex(NewElement, BeforeOrdinal) |
X
|
X
| | |
| InsertElement(NewElement, BeforeElement) |
X
|
X
| | |
| InsertIterator(NewElement, BeforeIterator) |
X
|
X
| | |
| RemoveKey(Key, bStripTrailingSpace) |
X
|
X
|
X
|
X
|
| RemoveIndex(Ordinal) |
X
|
X
|
X
|
X
|
| RemoveElement(Element) |
X
|
X
|
X
|
X
|
| RemoveIterator(Iterator) |
X
|
X
|
X
|
X
|
| GetEnumerator(Iterator) |
X
|
X
|
X
|
X
|
| Count() |
X
|
X
|
X
|
X
|
| RemoveAll() |
X
|
X
|
X
|
X
|
| Find(Element, Key, bStripTrailingSpace) |
X
|
X
|
X
|
X
|
| FindIndex(Element, Ordinal) |
X
|
X
|
X
|
X
|
| Set(NewValue, Key, bStripTrailingSpace) |
X
|
X
| | |
| SetIndex(NewValue, Ordinal) |
X
|
X
| | |
| SetElement(NewValue, Element) |
X
|
X
| | |
SetKey(Key)
PUBLIC DEFSUB 'SetKey(BYREF kthis$_KCML_Class<_X>, CONST BYREF Key$()_KCML_SORT_REC_KEY) AS Void
A key may be used to define the order for sorted collections and to find items in the collection.
The simplest and default key is a simple string. The SetKey method can be used to define a complex
key using a string array of type KCML_SORT_REC_KEY, where each element of the array specifies a
segment of the key. The key is into the data of the element, so the simpler form of Add is used
where no separate key is specified.
Add(NewElement)
PUBLIC DEFSUB 'Add(BYREF kthis$_KCML_Class<_X>, NewElement AS PTR(X$_X)) AS Void
Add a pool memory handle to the collection. Where the order is controlled by the user the item
is inserted at the end. This form of Add must be used when SetKey has been used to define a key,
and also may be used for unordered lists where searching is not required.
AddKey(NewElement, Key)
PUBLIC DEFSUB 'AddKey(BYREF kthis$_KCML_Class<_X>, NewElement AS PTR(X$_X), Key$) AS Void
Add a pool memory handle to the collection. The key specifies the key for searching and sorting.
Where the order is controlled by the user the item
is inserted at the end. This form may only be used where SetKey has not been used to define
a key into the data.
InsertKey(NewElement, Key, BeforeKey, bStripTrailingSpace)
PUBLIC DEFSUB 'InsertKey(BYREF kthis$_KCML_Class<_X>, NewElement AS PTR(X$_X), Key$, CONST BYREF BeforeKey$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Insert an item into the middle of an unordered collection. The item is inserted before the item
specified by Key.
InsertIndex(NewElement, BeforeOrdinal)
PUBLIC DEFSUB 'InsertIndex(BYREF kthis$_KCML_Class<_X>, NewElement AS PTR(X$_X), BeforeOrdinal AS Integer) AS Bool
Insert an item into the middle of an unordered collection. The item is inserted before the item
specified by the index Ordinal.
InsertElement(NewElement, BeforeElement)
PUBLIC DEFSUB 'InsertElement(BYREF kthis$_KCML_Class<_X>, NewElement AS PTR(X$_X), BeforeElement AS PTR(X$_X)) AS Bool
Insert an item into the middle of an unordered collection. The items is inserted before the item
whose value is specified by BeforeElement.
InsertIterator(NewElement, BeforeIterator)
PUBLIC DEFSUB 'InsertIterator(BYREF kthis$_KCML_Class<_X>, NewElement AS PTR(X$_X), CONST BYREF BeforeIterator$_KCML_IteratorClass<_COLLECTION, _X>) AS Bool
Insert an item into the middle of an unordered collection. The items is inserted before the item
whose value is specified by the iterator BeforeIterator.
RemoveKey(Key, bStripTrailingSpace)
PUBLIC DEFSUB 'RemoveKey(BYREF kthis$_KCML_Class<_X>, CONST BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Remove an item from the collection. The item is specified by Key.
RemoveIndex(Ordinal)
PUBLIC DEFSUB 'RemoveIndex(BYREF kthis$_KCML_Class<_X>, Ordinal AS Integer) AS Bool
Remove an item from the collection. The item is specified by its position Ordinal.
RemoveElement(Element)
PUBLIC DEFSUB 'RemoveElement(BYREF kthis$_KCML_Class<_X>, Element AS PTR(X$_X)) AS Bool
Remove an item from the collection. The item is specified by its value Element.
RemoveIterator(Iterator)
PUBLIC DEFSUB 'RemoveIterator(BYREF kthis$_KCML_Class<_X>, CONST BYREF Iterator$_KCML_IteratorClass<_COLLECTION, _X>) AS Bool
Remove an item from the collection. The item is specified by its iterator Element.
GetEnumerator(Iterator)
PUBLIC DEFSUB 'GetEnumerator(BYREF kthis$_KCML_Class<_X>, BYREF Iterator$_KCML_IteratorClass<_COLLECTION, _X>) AS Void
Sets the passed iterator to an iterator over the called collection.
Count()
PUBLIC DEFSUB 'Count(BYREF kthis$_KCML_Class<_X>) AS Numeric
Returns the number of items in the collection.
RemoveAll()
PUBLIC DEFSUB 'RemoveAll(BYREF kthis$_KCML_Class<_X>) AS Void
Removes all items from the collection.
Find(Element, Key, bStripTrailingSpace)
PUBLIC DEFSUB 'Find(BYREF kthis$_KCML_Class<_X>, BYREF Element AS PTR(X$_X), CONST BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
Finds an item in the collection. The key is either a string, where SetKey has not been used
(in which case trailing blanks will be stripped), or
a string completed to the sort specification.
FindIndex(Element, Ordinal)
PUBLIC DEFSUB 'FindIndex(BYREF kthis$_KCML_Class<_X>, BYREF Element AS PTR(X$_X), Ordinal AS Integer) AS Bool
Set(NewValue, Key, bStripTrailingSpace)
PUBLIC DEFSUB 'Set(BYREF kthis$_KCML_Class<_X>, NewValue AS PTR(X$_X), CONST BYREF Key$, bStripTrailingSpace AS BOOL = TRUE) AS Bool
SetIndex(NewValue, Ordinal)
PUBLIC DEFSUB 'SetIndex(BYREF kthis$_KCML_Class<_X>, NewValue AS PTR(X$_X), Ordinal AS Integer) AS Bool
SetElement(NewValue, Element)
PUBLIC DEFSUB 'SetElement(BYREF kthis$_KCML_Class<_X>, NewValue AS PTR(X$_X), Element AS PTR(X$_X)) AS Bool