Android Programming Press on the image to return to the main documentation page.

Collections (Core)

List of types:

List
Map

List

Lists are similar to dynamic arrays. You can add and remove items from a list and it will change its size accordingly.
A list can hold any type of object. However if a list is declared as a process global object it cannot hold activity objects (like views).
Basic4android automatically converts regular arrays to lists. So when a List parameter is expected you can pass an array instead.
For example:
Dim List1 As List
List1.Initialize
List1.AddAll(Array As Int(1, 2, 3, 4, 5))
Use the Get method to get an item from the list.
Lists can be saved and loaded from files using File.WriteList and File.ReadList.
You can use a For loop to iterate over all the values:
For i = 0 To List1.Size - 1
Dim number As Int
number = List1.Get(i)
...
Next

Events:

None

Members:


  Add (item As Object)

  AddAll (List As List)

  AddAllAt (Index As Int, List As List)

  Clear

  Get (Index As Int) As Object

  IndexOf (Item As Object) As Int

  Initialize

  Initialize2 (Array As List)

  InsertAt (Index As Int, Item As Object)

  IsInitialized As Boolean

  RemoveAt (Index As Int)

  Set (Index As Int, Item As Object)

  Size As Int [read only]

  Sort (Ascending As Boolean)

  SortCaseInsensitive (Ascending As Boolean)

  SortType (FieldName As String, Ascending As Boolean)

  SortTypeCaseInsensitive (FieldName As String, Ascending As Boolean)

Members description:

Add (item As Object)
Adds an item at the end of the list.
AddAll (List As List)
Adds all elements in the specified collection to the end of the list.
Note that you can add an array directly.
Example:
List.AddAll(Array As String("value1", "value2"))
AddAllAt (Index As Int, List As List)
Adds all elements in the specified collection starting at the specified index.
Clear
Removes all the items from the list.
Get (Index As Int) As Object
Gets the item in the specified index. The item is not removed from the list.
IndexOf (Item As Object) As Int
Returns the index of the specified item, or -1 if it was not found.
Initialize
Initializes an empty list.
Initialize2 (Array As List)
Initializes a list with the given values. This method should be used to convert arrays to lists.
Note that if you pass a list to this method then both objects will share the same list,
and if you pass an array the list will be of a fixed size. Meaning that you cannot later add or remove items.
Example:
Dim List1 As List
List1.Initialize2(Array As Int(1,2,3,4,5))
Example:
Dim List1 As List
Dim SomeArray(10) As String
'Fill array...
List1.Initialize2(SomeArray)
InsertAt (Index As Int, Item As Object)
Inserts the specified element in the specified index, before the current item at that index.
As a result all items with index equal to or larger than the specified index are shifted.
IsInitialized As Boolean
RemoveAt (Index As Int)
Removes the item at the specified index.
Set (Index As Int, Item As Object)
Replaces the current item in the specified index with the new item.
Size As Int [read only]
Returns the number of items in the list.
Sort (Ascending As Boolean)
Sorts the list.
The items must all be numbers or strings.
SortCaseInsensitive (Ascending As Boolean)
Lexicographically sorts the list, ignoring the characters case.
The items must all be numbers or strings.
SortType (FieldName As String, Ascending As Boolean)
Sorts a list with items of user defined type. The list is sorted based on the specified field.
FieldName - The case-sensitive field name that will be used for sorting. Field must contain numbers or strings.
Ascending - Whether to sort ascending or descending.
Example:
Sub Process_Globals
  Type Person(Name As String, Age As Int)
End Sub

Sub Activity_Create(FirstTime As Boolean)
  Dim Persons As List
  Persons.Initialize
  For i = 1 To 50
    Dim p As Person
    p.Name = "Person" & i
    p.Age = Rnd(0, 121)
    Persons.Add(p)
  Next
  Persons.SortType("Age", True) 'Sort the list based on the Age field.
  For i = 0 To Persons.Size - 1
    Dim p As Person
    p = Persons.Get(i)
    Log(p)
  Next
End Sub
SortTypeCaseInsensitive (FieldName As String, Ascending As Boolean)
Similar to SortType. Lexicographically sorts the list, ignoring the characters case.

Map

A collection that holds pairs of keys and values. The keys are unique. Which means that if you add a key/value pair (entry) and
the collection already holds an entry with the same key, the previous entry will be removed from the map.
Fetching an item is done by looking for its key. This is usually a very fast operation (O(1) compared to O(n) in a list).
The key should be a string or a number. The value can be any type of object.
Note that this map implementation does return items in the same order as they were added.
Usually you will use Put to add items and Get or GetDefault to get the values based on the key.
If you need to iterate over all the items you can use a For loop like:
For Each Key As String In Map.Keys
Dim Value As Object = Map.Get(Key)
Next
Similar to a list, a map can hold any object, however if it is a process global variable then it cannot hold activity objects (like views).
Maps are very useful for storing applications settings.
You can save and load maps with "simple values" with File.WriteMap and File.ReadMap. More complex maps can be saved with B4XSerializator.

Events:

None

Members:


  Clear

  ContainsKey (Key As Object) As Boolean

  Get (Key As Object) As Object

  GetDefault (Key As Object, Default As Object) As Object

  GetKeyAt (Index As Int) As Object

  GetValueAt (Index As Int) As Object

  Initialize

  IsInitialized As Boolean

  Keys As IterableList

  Put (Key As Object, Value As Object) As Object

  Remove (Key As Object) As Object

  Size As Int [read only]

  Values As IterableList

Members description:

Clear
Clears all items from the map.
ContainsKey (Key As Object) As Boolean
Tests whether there is an item with the given key.
Example:
If Map.ContainsKey("some key") Then ...
Get (Key As Object) As Object
Returns the value of the item with the given key.
Returns Null if the value doesn't exist.
GetDefault (Key As Object, Default As Object) As Object
Returns the value of the item with the given key. If no such item exists the specified default value is returned.
GetKeyAt (Index As Int) As Object
Returns the key of the item at the given index.
GetKeyAt and GetValueAt should be used to iterate over all the items.
These methods are optimized for iterating over the items in ascending order.
Example:
For i = 0 to Map.Size - 1
  Log("Key: " & Map.GetKeyAt(i))
  Log("Value: " & Map.GetValueAt(i))
Next
GetValueAt (Index As Int) As Object
Returns the value of the item at the given index.
GetKeyAt and GetValueAt should be used to iterate over all the items.
These methods are optimized for iterating over the items in ascending order.
Example:
For i = 0 to Map.Size - 1
  Log("Key: " & Map.GetKeyAt(i))
  Log("Value: " & Map.GetValueAt(i))
Next
Initialize
Initializes the object.
Example:
Dim Map1 As Map
Map1.Initialize
IsInitialized As Boolean
Keys As IterableList
Returns an object which can be used to iterate over all the keys with a For Each block.
Example:
For Each k As String In map1.Keys
  Log(k)
Next
Put (Key As Object, Value As Object) As Object
Puts a key/value pair in the map, overwriting the previous item with this key (if such exists).
Returns the previous item with this key or null if there was no such item.
Note that if you are using strings as the keys then the keys are case sensitive.
Example:
Map1.Put("Key", "Value")
Remove (Key As Object) As Object
Removes the item with the given key, if such exists.
Returns the item removed or null if no matching item was found.
Size As Int [read only]
Returns the number of items stored in the map.
Values As IterableList
Returns an object which can be used to iterate over all the values with a For Each block.
Example:
For Each v As Int In map1.Values
  Log(v)
Next
Top