A list is an ordered collection of typed primitives, sObjects, user-defined objects, Apex objects or collections that are distinguished by their indices. For example, the following table is a visual representation of a list of Strings:
| Index 0 | Index 1 | Index 2 | Index 3 | Index 4 | Index 5 |
|---|---|---|---|---|---|
| 'Red' | 'Orange' | 'Yellow' | 'Green' | 'Blue' | 'Purple' |
The index position of the first element in a list is always 0.
Because lists can contain any collection, they can be nested within one another and become multidimensional. For example, you can have a list of lists of sets of Integers. A list can only contain up to five levels of nested collections inside it.
To declare a list, use the List keyword followed by the primitive data, sObject, nested list, map, or set type within <> characters. For example:
// Create an empty list of String List<String> my_list = new List<String>(); // Create a nested list List<List<Set<Integer>>> my_list_2 = new List<List<Set<Integer>>>(); // Create a list of account records from a SOQL query List<Account> accs = [SELECT Id, Name FROM Account LIMIT 1000];
To access elements in a list, use the system methods provided by Apex. For example:
List<Integer> MyList = new List<Integer>(); // Define a new list MyList.add(47); // Adds a second element of value 47 to the end // of the list MyList.get(0); // Retrieves the element at index 0 MyList.set(0, 1); // Adds the integer 1 to the list at index 0 MyList.clear(); // Removes all elements from the list
For more information, including a complete list of all supported methods, see List Methods.
When using one-dimensional lists of primitives or sObjects, you can also use more traditional array notation to declare and reference list elements. For example, you can declare a one-dimensional list of primitives or sObjects by following the data or sObject type name with the [] characters:
String[] colors = new List<String>();
To reference an element of a one-dimensional list of primitives or sObjects, you can also follow the name of the list with the element's index position in square brackets. For example:
colors[3] = 'Green';
All lists are initialized to null. Lists can be assigned values and allocated memory using literal notation. For example:
| Example | Description |
|---|---|
List<Integer> ints = new Integer[0];
|
Defines an Integer list with no elements |
List<Account> accts = new Account[]{};
|
Defines an Account list with no elements |
List<Integer> ints = new Integer[6];
|
Defines an Integer list with memory allocated for six Integers |
List<Account> accts = new Account[] {new Account(), null, new Account()}; |
Defines an Account list with memory allocated for three Accounts, including a new Account object in the first position, null in the second position, and another new Account object in the third position |
List<Contact> contacts = new List<Contact>
(otherList);
|
Defines the Contact list with a new list |
Apex automatically generates IDs for each object in a list of sObjects when the list is successfully inserted or upserted into the database with a data manipulation language (DML) statement. Consequently, a list of sObjects cannot be inserted or upserted if it contains the same sObject more than once, even if it has a null ID. This situation would imply that two IDs would need to be written to the same structure in memory, which is illegal.
For example, the insert statement in the following block of code generates a ListException because it tries to insert a list with two references to the same sObject (a):
try { // Create a list with two references to the same sObject element Account a = new Account(); Account[] accs = new Account[]{a, a}; // Attempt to insert it... insert accs; // Will not get here System.assert(false); } catch (ListException e) { // But will get here }
For more information on DML statements, see Apex Data Manipulation Language (DML) Operations.
You can use the generic sObject data type with lists. You can also create a generic instance of a list.