Important: The information in this document is obsolete and should not be used for new development.
Replacing Items in a CollectionThe Collection Manager provides two methods for replacing items in a collection:
- You can use the
AddCollectionItemfunction, specifying the collection tag and collection ID of an existing item.
- You can use the
ReplaceIndexedCollectionItemfunction, specifying the collection index of an existing item.
The new item does not have to be the same size as the replaced item. For example, Listing 5-10 shows how you can use the
- The Collection Manager also provides the utility functions,
ReplaceCollectionItemHdl, which allow you to specify a handle, rather than a pointer, to the item's data. See "Working With Macintosh Memory Manager Handles" beginning on page 5-92 for more information about these functions.
AddCollectionItemfunction to replace the data in a collection item with a new data of a different length. (This example uses the collection created in "Adding Items to a Collection" beginning on page 5-17, in which the item identified by the collection tag
'QUOT'and the collection ID 1 contains the 29-character string "Fourscore and seven years ago")
Listing 5-10 Replacing an item in a collection
anErr = AddCollectionItem(pointsAndQuotes, 'QUOT', 1, 22, "Eighty-seven years ago");
You cannot replace a collection item if its lock attribute is set. For example, the previous section shows how to set the lock attribute of the item with the collection tag
'QUOT'and the collection ID 0. If you try to replace this item using
anErr = AddCollectionItem(pointsAndQuotes, 'QUOT', 0, 24, "Plus c'est la meme chose");the code sets the
anErrvariable to the
collectionItemLockedErrvalue and the Collection Manager does not replace the item.
If you know the collection index of an item, you can use the
ReplaceIndexedCollectionItemfunction to replace the item. This function finds the specified item more efficiently than the
AddCollectionItemfunction. Listing 5-11 shows an example of this function.
Listing 5-11 Replacing an item using the item's index
long index; . . . /* find the index. */ anErr = GetCollectionItemInfo(pointsAndQuotes, 'QUOT', 1, &index, dontWantSize, dontWantAttributes); . . . /* replace the item. */ anErr = ReplaceIndexedCollectionItem(pointsAndQuotes, index, 22, "Eighty-seven years ago");The example in Listing 5-11 uses the
GetCollectionItemInfofunction to find the collection index that the Collection Manager has assigned to the item with a collection tag of
'QUOT' and a collection ID of 1. Finding this collection index requires some processing time. However, once you've found the item's collection index, you can use it to find information about the item quickly, because functions that search for a collection item using the item's collection index operate more efficiently than functions that search using the item's collection tag and collection ID. Typically, if you want to search for an item only once, you use the item's collection tag and collection ID. If you know that you have to search for the same item repeatedly, you find the item's collection index and use the collection index when examining or editing the item.
For more information about identifying collection items, see "Methods of Identifying Collection Items" on page 5-11.
For more information about the
AddCollectionItemfunction and the
ReplaceIndexedCollectionItemfunction, see "Adding and Replacing Items in a Collection" beginning on page 5-62.