List Class

Contains methods for the List collection type.

System

The list methods are all instance methods, that is, they operate on a particular instance of a list. For example, the following removes all elements from myList:

Even though the clear method does not include any parameters, the list that calls it is its implicit parameter.

  • When using a custom type for the list elements, provide an equals method in your class. Apex uses this method to determine equality and uniqueness for your objects. For more information on providing an equals method, see Using Custom Types in Map Keys and Sets.
  • If the list contains String elements, the elements are case-sensitive. Two list elements that differ only by case are considered distinct.

For more information on lists, see Lists.

The following are constructors for List.

  • List<T>()

    Creates a new instance of the List class. A list can hold elements of any data type T.

  • List<T>(listToCopy)

    Creates a new instance of the List class by copying the elements from the specified list. T is the data type of the elements in both lists and can be any data type.

  • List<T>(setToCopy)

    Creates a new instance of the List class by copying the elements from the specified set. T is the data type of the elements in the set and list and can be any data type.

Creates a new instance of the List class. A list can hold elements of any data type T.

public List<T>()

Creates a new instance of the List class by copying the elements from the specified list. T is the data type of the elements in both lists and can be any data type.

public List<T>(List<T> listToCopy)

  • listToCopy:

    Type: List<T>

    The list containing the elements to initialize this list from. T is the data type of the list elements.

Creates a new instance of the List class by copying the elements from the specified set. T is the data type of the elements in the set and list and can be any data type.

public List<T>(Set<T> setToCopy)

  • setToCopy: Type: Set<T> The set containing the elements to initialize this list with. T is the data type of the set elements.

The following are methods for List. All are instance methods.

  • add(listElement)

    Adds an element to the end of the list.

  • add(index, listElement)

    Inserts an element into the list at the specified index position and shifts all subsequent elements one index position to the right.

  • addAll(fromList)

    Adds all of the elements in the specified list to the list that calls the method. Both lists must be of the same type.

  • addAll(fromSet)

    Add all of the elements in specified set to the list that calls the method. The set and the list must be of the same type.

  • clear()

    Removes all elements from a list, consequently setting the list’s length to zero.

  • clone()

    Makes a duplicate copy of a list.

  • contains(listElement)

    Returns true if the list contains the specified element.

  • deepClone(preserveId, preserveReadonlyTimestamps, preserveAutonumber)

    Makes a duplicate copy of a list of sObject records, including the sObject records themselves.

  • equals(list2)

    Compares this list with the specified list and returns true if both lists are equal; otherwise, returns false.

  • get(index)

    Returns the list element stored at the specified index.

  • getSObjectType()

    Returns the token of the sObject type that makes up a list of sObjects.

  • hashCode()

    Returns the hashcode corresponding to this list and its contents.

  • indexOf(listElement)

    Returns the index of the first occurrence of the specified element in this list. If this list does not contain the element, returns -1.

  • isEmpty()

    Returns true if the list has zero elements.

  • iterator()

    Returns an instance of an iterator for this list.

  • remove(index)

    Removes the list element stored at the specified index, returning the element that was removed.

  • set(index, listElement)

    Sets the specified value for the element at the given index.

  • size()

    Returns the number of elements in the list.

  • sort()

    Sorts the items in the list in ascending order.

  • toString()

    Returns the string representation of the list.

Adds an element to the end of the list.

public Void add(Object listElement)

  • listElement:

    Type: Object

Type: Void

Inserts an element into the list at the specified index position and shifts all subsequent elements one index position to the right.

public Void add(Integer index, Object listElement)

  • index:

    Type: Integer

  • listElement:

    Type: Object

Type: Void

In this example, a list with six elements is created. Integers are added to the first and second index positions, and the subsequent elements are shifted to the right. After the two methods are called, the list has eight total elements.

Adds all of the elements in the specified list to the list that calls the method. Both lists must be of the same type.

public Void addAll(List fromList)

  • fromList:

    Type: List

Type: Void

Add all of the elements in specified set to the list that calls the method. The set and the list must be of the same type.

public Void addAll(Set fromSet)

  • fromSet:

    Type: Set

Type: Void

Removes all elements from a list, consequently setting the list’s length to zero.

public Void clear()

Type: Void

Makes a duplicate copy of a list.

public List<Object> clone()

Type: List<Object>

The cloned list is of the same type as the current list.

Note that if this is a list of sObject records, the duplicate list will only be a shallow copy of the list. That is, the duplicate will have references to each object, but the sObject records themselves will not be duplicated. For example:

To also copy the sObject records, you must use the deepClone method.

Returns true if the list contains the specified element.

public Boolean contains(Object listElement)

  • listElement:

    Type: Object

Type: Boolean

Makes a duplicate copy of a list of sObject records, including the sObject records themselves.

public List<Object> deepClone(Boolean preserveId, Boolean preserveReadonlyTimestamps, Boolean preserveAutonumber)

  • preserveId:

    Type: Boolean

    The optional preserveId argument determines whether the IDs of the original objects are preserved or cleared in the duplicates. If set to true, the IDs are copied to the cloned objects. The default is false, that is, the IDs are cleared.

  • preserveReadonlyTimestamps:

    Type: Boolean

    The optional preserveReadonlyTimestamps argument determines whether the read-only timestamp and user ID fields are preserved or cleared in the duplicates. If set to true, the read-only fields CreatedById, CreatedDate, LastModifiedById, and LastModifiedDate are copied to the cloned objects. The default is false, that is, the values are cleared.

  • preserveAutonumber:

    Type: Boolean

    The optional preserveAutonumber argument determines whether the autonumber fields of the original objects are preserved or cleared in the duplicates. If set to true, auto number fields are copied to the cloned objects. The default is false, that is, auto number fields are cleared.

Type: List<Object>

The returned list is of the same type as the current list.

  • deepClone only works with lists of sObjects, not with lists of primitives.
  • For Apex saved using Salesforce API version 22.0 or earlier, the default value for the preserve_id argument is true, that is, the IDs are preserved.

To make a shallow copy of a list without duplicating the sObject records it contains, use the clone method.

This example performs a deep clone for a list with two accounts.

This example is based on the previous example and shows how to clone a list with preserved read-only timestamp and user ID fields.

Compares this list with the specified list and returns true if both lists are equal; otherwise, returns false.

public Boolean equals(List list2)

  • list2:

    Type: List

    The list to compare this list with.

Type: Boolean

Two lists are equal if their elements are equal and are in the same order. The == operator is used to compare the elements of the lists.

The == operator is equivalent to calling the equals method, so you can call list1.equals(list2); instead of list1 == list2;.

Returns the list element stored at the specified index.

public Object get(Integer index)

Type: Object

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 as shown in the example.

If the element referenced is out of bounds, this exception is thrown: System.ListException: List index is out of bounds.

Returns the token of the sObject type that makes up a list of sObjects.

public Schema.SObjectType getSObjectType()

Type: Schema.SObjectType

Use this method with describe information to determine if a list contains sObjects of a particular type.

Note that this method can only be used with lists that are composed of sObjects.

For more information, see Understanding Apex Describe Information.

Returns the hashcode corresponding to this list and its contents.

public Integer hashCode()

Type: Integer

Returns the index of the first occurrence of the specified element in this list. If this list does not contain the element, returns -1.

public Integer indexOf(Object listElement)

  • listElement:

    Type: Object

Type: Integer

Returns true if the list has zero elements.

public Boolean isEmpty()

Type: Boolean

Returns an instance of an iterator for this list.

public Iterator iterator()

Type: Iterator

From the returned iterator, you can use the iterable methods hasNext and next to iterate through the list.

You don’t have to implement the iterable interface to use the iterable methods with a list.

See Custom Iterators.

Removes the list element stored at the specified index, returning the element that was removed.

public Object remove(Integer index)

Type: Object

Sets the specified value for the element at the given index.

public Void set(Integer index, Object listElement)

  • index:

    Type: Integer

    The index of the list element to set.

  • listElement:

    Type:

    Object The value of the list element to set.

Type: Void

To set 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.

Returns the number of elements in the list.

public Integer size()

Type: Integer

Sorts the items in the list in ascending order.

public Void sort()

Type: Void

Using this method, you can sort primitive types, SelectOption elements, and sObjects (standard objects and custom objects). For more information on the sort order used for sObjects, see Sorting Lists of sObjects. You can sort custom types (your Apex classes) if they implement the Comparable interface. Alternatively, a class implementing the Comparator interface can be passed as a parameter to the List.sort method.

When you use sort() methods on List<Id>s that contain both 15-character and 18-character IDs, IDs for the same record sort together in API version 35.0 and later.

In the following example, the list has three elements. When the list is sorted, the first element is null because it has no value assigned. The second element and third element have values of 5 and 10.

Returns the string representation of the list.

public String toString()

Type: String

When used in cyclic references, the output is truncated to prevent infinite recursion. When used with large collections, the output is truncated to avoid exceeding total heap size and maximum CPU time.

  • Up to 10 items per collection are included in the output, followed by an ellipsis (…).
  • If the same object is included multiple times in a collection, it’s shown in the output only once; subsequent references are shown as (already output).