B4i Library iMapList - combining a Map and a List

A MapList is a combination of a Map and a List and implements most of the attributes and methods of both types.

Why would you want to use as MapList? To have fast lookup (by Key) and to have control over the order of Values held in the MapList.

An example: You have an App that presents a user with a list of items, allowing the User to add items to the list or to reorder the list in a way that makes sense to them. You need to be able to translate between the items/order the user is seeing in the App and the data describing those items held in your App. Using a MapList, you can add items as the User adds them in the App, you can present them back to the user in the order added, you can also assign a unique key to each item and store that in the App UI, so that if the user reorders the list you can adjust the order of the items in the MapList using the unique keys along with Remove(Key) and InsertAt(Index, Key, Value).

Here are some key differences between a MapList and a regular Map or List:

1. All methods that add items into a MapList require both a Key and a Value (Key/Value pairs). Like a Map, Keys can link to only one MapList entry.
2. The order of Items added is maintained in an internal Key List and defaults to the order added, unless any of AddAllAt, AddMapAt, InsertAt, Put, Sort or SortCaseInsensitive is used.
3. Duplicate Keys will overwrite the previous item Value and if using Add, will move the Key to the end of the Key List (unless using AddAllAt, AddMapAt, InsertAt to insert Keys/Values at a specific location). If using Put, the previous item value will be overwritten and the Key will not be moved to the end of the Key List.
4. Maps and Lists differ in how they handle out of bounds Index values ... with MapList out of bounds Indexes will throw an exception, while unmatched Keys return null.

Properties/Methods are as follows (fully documented in IDE metadata):

• To Add/Update items: Add, Put, InsertAt, InsertBefore, InsertAfter, AddAll, AddMap, AddAllAt, AddMapAt, Set
• To Remove items: Clear, Remove, RemoveAt,
• To Retrieve items: Get(Key), GetDefault, GetKeyAt, GetValueAt, Keys (ForEach list), Values (ForEach list)
• To Reorder items: Move, SortKeys, SortKeysCaseInsensitive
• To Retrieve sorted lists: SortedKeys, SortedKeysCaseInsensitive, SortedValues, SortedValuesCaseInsensitive
• Informational/other: Size, ContainsKey, IndexOf, IndexOfKey, Initialize, IsInitialized, IsEmpty, ToString

The following Map/List methods are not implemented for the following reasons:

• Get(Index) - Get what from Index? Use GetKeyAt/GetValueAt instead
• Initialize2 - Arrays can't be used with MapList, convert to a Map first
• Sort, SortcaseInsensitive - Replaced with SortKeys/SortKeysCaseInsensitive, SortedKeys/SortedKeysCaseInsensitive and SortedValues/SortedValuesCaseInsensitive
• SortType - MapList doesn't understand User-Defined Types
• SortTypeCaseInsensitive - MapList doesn't understand User-Defined Types

Release History:

• 15-Jun-17: 1.00 Initial release for Android platform
• 10-Jul-17: 2.00 Port to iOS.
  Added Add, AddMap, AddMapAt, IsEmpty, Move, ToString.
  Adjusted Put method so that it no longer maintains the order that keys were added (=Add).
• 16-Aug-17: 2.01 Removed 'class released' messages