diff --git a/.gitattributes b/.gitattributes index 3647e773f0..9c3e9230d1 100644 --- a/.gitattributes +++ b/.gitattributes @@ -6261,6 +6261,7 @@ docs/xml/lazutils/lcsvutils.xml svneol=native#text/plain docs/xml/lazutils/lookupstringlist.xml svneol=native#text/plain docs/xml/lazutils/maps.xml svneol=native#text/plain docs/xml/lazutils/masks.xml svneol=native#text/plain +docs/xml/lazutils/objectlists.xml -text svneol=native#text/plain docs/xml/lazutils/paswstring.xml svneol=native#text/plain docs/xml/lazutils/stringhashlist.xml svneol=native#text/plain docs/xml/lazutils/textstrings.xml svneol=native#text/plain diff --git a/docs/xml/lazutils/objectlists.xml b/docs/xml/lazutils/objectlists.xml new file mode 100644 index 0000000000..f15c070ba6 --- /dev/null +++ b/docs/xml/lazutils/objectlists.xml @@ -0,0 +1,669 @@ + + + + + + + Defines classes used to associate objects/pointers with objects/pointers + + +

+ Defines classes used to associate objects/pointers with objects/pointers. Converted to use generics by Juha. Item and Object types can now be defined. +

+ + + + + + + + + + + T2Pointer is a record type used to maintain an association between the pointers to the members in the record. + + + + + + Pointer to the item for the association + + + + + + Pointer to the associated item in the record + + + + + + Pointer to the T2Pointer record type + + Used to implement the list of item and object associations in TObjectArray. + + + + + + + + + + Implement an array of items with their associated objects + + +

+ TObjectArray is a generic type used to implement an array of items and their associated objects. TObjectArray allows the association to be defined using the TItem and TObj class types. Internally, it uses a list of records with pointers to the Items and Objects stored in the class. Properties and methods are provided to maintain and access the entries in the class instance, and the allocated storage for the array type. +

+ + + + + + + + + + + + + Gets the value for the Items property + + + + + + + + TItem value for the property + + + Ordinal position for the requested item + + + + Sets the value for the Items property + + + + + + + Ordinal position for the updated item + + + New TItem value for the property + + + + Gets the value for the Objects property + + + + + + + + TObj value for the property + + + Ordinal position for the requested object + + + + Sets the value for the Objects property + + + + + + + + Ordinal position for the updated object + + + New TObj value for the property + + + + Sets the value for the Capacity property + +

+ SetCapacity calls ReallocMem to ensure that List contains enough memory for the number of T2Pointer instances specified in AValue. The Count property is also updated in the method (when needed) to reflect the new value for the property. +

+ + + + + + + + New value for the property + + + + Sets the value for the Count property + +

+ SetCount calls SetCapacity when the new value for the property is larger than the existing value in Capacity. +

+ + + + + + + + + New value for the property + + + + + Increases the storage Capacity for the class instance + + +

+ Grow increases the storage Capacity (number of item/object associations) for the class instance. Grow ensures that Capacity has a minimum of size of five (5). Otherwise, the number of associations is always increased by doubling the value in the Capacity property, which in turn, reallocates the storage space needed for the List. +

+

+ Grow is used in the implementation of the AddObject and InsertObject methods. To avoid rampant memory consumption in large lists, caused by doubling the value in Capacity, explicitly set the value in Capacity to a reasonable size prior to calling the Add, AddObject, Insert, or InsertObject methods. +

+ + + + + + + + + + + + + + Decreases the Capacity and allocated storage for the class instance + + +

+ Shrink is a procedure used to decrease the Capacity (and subsequently) the allocated storage for the class instance. Shrink always halves the value in the Capacity property. It is called from the Delete method when Capacity has at least four (4) times the number of associations in the Count property. +

+ + + + + + + + + + + Adds the specified item + +

+ Add is an Integer function used to add the item specified in Item to the storage for the class instance. Add calls the AddObject method to store the value in Item. The associated object is unassigned (Nil) in the method. Use AddObject to store an Item and its associated object. +

+

+ The return value contains the ordinal position in List where the Item was stored. +

+ + + + + + + + + Ordinal position in storage when the item was added + + + Item added in the method + + + + + Adds the specified item and its associated object to the storage in the class instance + + +

+ AddObject is an Integer function which adds the specified item and its associated object to the storage in the class instance. AddObject calls the Grow method to increase storage in the class instance when Count reaches the value in Capacity. +

+

+ AddObject uses the List property to store the values in Item and Associated to the corresponding properties at the position in Count. The value in Count is incremented prior to exiting from the method. +

+

+ Use Add to store an Item with an unassigned associated object. +

+

+ Use methods like Delete, Remove, and Clear to remove one or all associations stored in List. +

+

+ Use the indexed Items and Objects properties to access values stored in an association at a specific position. +

+ + + + + + + + + + + + + + + + + Ordinal position where the association for the item and the object was stored + + + + Item stored in the association + + + Object stored in the association + + + + + Removes all item/object associations stored in the List + + +

+ Clear is a procedure used to remove all item/object associations stored in the List. Clear sets the values in Count and Capacity to zero (0), and calls ReallocMem to set the allocated memory size in List to zero (0). +

+

+ Use Delete or Remove to delete a single association by its position or item content. +

+ + + + + + + + + + + + + Deletes an item/object association stored at the specified position in the List + + +

+ Delete is a procedure used to deletes an item/object association stored at the specified position in the List. When List has a length greater than the value in Index+1, the Move routine in the System.pp unit is called to relocate any associations that occur after the position requested. +

+

+ Delete decrements the value in Count. The Shrink method is called when Capacity is larger than four (4) times the new value in Count. +

+

+ Use Remove to delete an association with a specific TItem class instance. +

+ + + + + + + + + + + Ordinal position in List for the association deleted in the method + + + + + Swaps the item/object associations at the specified positions in List + + +

+ Exchange is a procedure used to swap the item/object associations in the List at the ordinal positions specified in Index1 and Index2. +

+

+ Use Move to change the location for an item/object association, and reorder the List as needed. +

+ + + + + + + + + + Ordinal position for the first item/object association + + + + + Ordinal position for the second item/object association + + + + + + Gets the first TItem class instance in the List, or Nil when empty + + +

+ First is a TItem function used to get the class instance stored in the first association. First uses the List to access the T2Pointer stored in element zero (0) for the array. +

+

+ The return value is the Item in the association cast to the TItem class type used for the generic class specialization. When Count contains zero (0), the return value is Nil.

+ + + + + + + + + TItem class instance at the first position in the List + + + + + Gets the ordinal position in List where the specified TItem instance is stored + + +

+ IndexOf is an Integer function used to get the ordinal position in List where the TItem instance specified in Item is stored. IndexOf iterates over the storage in List in reverse order. +

+

+ The return value contains the ordinal position where the T2Pointer.Item member and the Item argument contain the same class instance. The return value is -1 when Item is not located in the associations stored in List. +

+ + + + + + + + Ordinal position for the requested TItem instance + + + TItem instance to locate in the List of associations + + + + + Inserts a new association at the specified position in List + + +

+ Insert is a procedure used to insert a new association at the specified position in List. Item contains the TItem class instance for the association. The object for the association is always set to Nil in the method. +

+

+ Use InsertObject to insert a new association using both an item and an object. +

+

+ Use Add or AddObject to append a new item/object association. +

+ + + + + + + + + + + Ordinal position where the association is inserted + + + TItem instance used in the inserted association + + + + + Inserts an item/object association at the specified position in the List + + + + + + Ordinal position in List where the association is inserted + + + TItem instance for the new association + + + TObj instance for the association + + + + + Gets the last TItem instance in the List, or Nil when empty + + +

+ Last is a TItem function used to get the last item instance in the allocated storage in List. Last uses the value in Count to determine the position for the last item/object association. When Count is zero (0), the List is empty and the return value is set to Nil. +

+ + + + + + + + + TItem instance stored at the last position in List + + + + + Relocates the association stored at the position in CurIndex to the position in NewIndex + + +

+ Move is a procedure used to relocate the association stored at the position in CurIndex to the position in NewIndex. No actions are performed in the method when CurIndex and Index contain the same value. +

+

+ Move gets the T2Pointer stored at the position in CurIndex from the List. Move call the Move routine in the System.pp unit to relocate any associations stored between the positions in CurIndex and NewIndex. The relocated associations are moved towards the end of List when CurIndex is greater than NewIndex. +

+

+ The T2Pointer is reassigned to the position in NewIndex. +

+ + + + + + + + Ordinal position where the association is currently stored + + + Ordinal position where the association is moved + + + + + Assigns TItem class instances specified in SrcList to the List storage in the class + + +

+ Assign is a procedure used to stored TItem class instances in SrcList to the List storage for the class. Assign calls the Clear method to remove all existing item/object associations stored in List. +

+

+ Assign sets the the value in Count to the the length in SrcList. The method iterates over the values in the TList instance, and stores the TItem instances in the corresponding positions in List. The associated object for all entries in List is unassigned (Nil). +

+ + + + + + + + + + + TList with the TItem class instances stored in the method + + + + + + Removes the association with the specified TItem class instance + + +

+ Remove is an Integer function used to delete the item/object association with the specified TItem class instance. The return value contains the result returned from IndexOf. The return value is -1 when Item is not found in List. When Item exists in List, the Delete method is called to remove the association at the position in the return value. +

+ + + + + + + + + Ordinal position for the association removed in the method + + + TItem class instance to locate in the List + + + + + Removes all associations where the Item class instance is unassigned (contains Nil) + + +

+ Pack is a procedure used to remove all associations where the Item class instance is unassigned (contains Nil). Pack iterates over the allocated storage in List to determine if the T2Pointer.Item member is unassigned. When an an unassigned item is found, subsequent associations are moved into the storage position(s) for any unused items. Pack updates the value in the Count property to reflect the new number of associations in List. +

+ + + + + + + + + + + Specifies the number of associations that can be stored in the List + + +

+ Capacity is an Integer property which specifies the number of item/object associations that can be stored in the List. Changing the value in Capacity causes the memory in List to be reallocated to accommodate the new capacity value. The value in Count may also be affected when the value in Capacity is reduced. +

+ + + + + + + + + + + Number of item/object associations currently stored in the List + + +

+ Count is an Integer property which indicates the number of item/object associations currently stored in the List. Changing the value in Count causes Capacity to be updated when Count exceeds the value in Capacity. +

+

+ The value in Count is maintained in method which add or remove item/object associations in List, such as: Add, AddObject, Insert, InsertObject, Delete, Remove, Clear and Pack. +

+ + + + + + + + + + + + + + + + + + Provides indexed access to the TItem class instances stored in the List + + +

+ Items is an indexed property which provides access to the TItem class instances stored in the List. +

+ + + + + + + + + Ordinal position for the requested value + + + + + Provides indexed access to the TObj class instances stored in the List + + +

+ Objects is an indexed property used to provide access to the TObj class instances stored in the List. +

+ + + + + + + + + Ordinal position for the requested value + + + + + Provides access to the list which implements the storage for the item/object associations in the class instance + + +

+ List is a read-only P2Pointer property which provides access to the list which implements the storage for the class instance. It is organized as pointers to a sequence of T2Pointer records. To access the record, and its Item and Object properties, use a subscript in the range 0..Count-1. For example: +

+ +// type TMyObjStrsArr = specialize TObjectArray<TMyObject, TStrings>; +// var aObjArr: TMyObjStrsArr; +// var lFound: Boolean; + +lFound := False; +for iPos := 0 to aObjArr.Count-1 do +begin + lFound := (aObjArr.List[iPos].Item.Name = 'Foo'); + if lFound then break; +end; +Exit(lFound); + +

+ Content in the record can be accessed using the indexed Items and Objects properties as well. +

+ + + + + + + + + + + + + +