Apex Developer Guide

Apex Developer Guide
Getting Started with Apex
Writing Apex
Running Apex
Debugging, Testing, and Deploying Apex
Apex Language Reference
Apex DML Operations
ApexPages Namespace
AppLauncher Namespace
Approval Namespace
Auth Namespace
Cache Namespace
Canvas Namespace
ChatterAnswers Namespace
commercepayments Namespace
ConnectApi Namespace
Database Namespace
Datacloud Namespace
DataSource Namespace
Dom Namespace
EventBus Namespace
Flow Namespace
KbManagement Namespace
Messaging Namespace
Metadata Namespace
Process Namespace
QuickAction Namespace
Reports Namespace
Schema Namespace
Search Namespace
Sfc Namespace
Site Namespace
Support Namespace
System Namespace
AccessType Enum
Address Class
Answers Class
ApexPages Class
Approval Class
Blob Class
Boolean Class
BusinessHours Class
Callable Interface
Cases Class
Comparable Interface
Continuation Class
Cookie Class
Crypto Class
Custom Settings Methods
Database Class
Date Class
Datetime Class
Decimal Class
Double Class
EncodingUtil Class
Enum Methods
EventBus Class
Exception Class and Built-In Exceptions
FlexQueue Class
FeatureManagement Class
Formula Class
FormulaRecalcFieldError Class
FormulaRecalcResult Class
Http Class
HttpCalloutMock Interface
HttpRequest Class
HttpResponse Class
Id Class
Ideas Class
InstallHandler Interface
Integer Class
JSON Class
JSONGenerator Class
JSONParser Class
JSONToken Enum
Limits Class
List Class
List Constructors
List Methods
Location Class
Long Class
Map Class
Matcher Class
Math Class
Messaging Class
MultiStaticResourceCalloutMock Class
Network Class
OrgLimit Class
OrgLimits Class
PageReference Class
Packaging Class
Pattern Class
Queueable Interface
QueueableContext Interface
QuickAction Class
RemoteObjectController
ResetPasswordResult Class
RestContext Class
RestRequest Class
RestResponse Class
SandboxPostCopy Interface
Schedulable Interface
SchedulableContext Interface
Schema Class
Search Class
Security Class
SelectOption Class
Set Class
Site Class
SObject Class
SObjectAccessDecision Class
StaticResourceCalloutMock Class
String Class
StubProvider Interface
System Class
Test Class
Time Class
TimeZone Class
Trigger Class
TriggerOperation Enum
Type Class
UninstallHandler Interface
URL Class
UserInfo Class
UserManagement Class
Version Class
WebServiceCallout Class
WebServiceMock Interface
XmlStreamReader Class
XmlStreamWriter Class
TerritoryMgmt Namespace
TxnSecurity Namespace
UserProvisioning Namespace
VisualEditor Namespace
wave Namespace
Appendices
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

List Class

Contains methods for the List collection type.

Namespace

System

Usage

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.

Note

For more information on lists, see Lists.

List Constructors

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.

Signature

public List<T>()

Example

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.

Signature

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

Parameters

listToCopy
Type: List<T>
The list containing the elements to initialize this list from. T is the data type of the list elements.

Example

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.

Signature

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

Parameters

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

Example

List Methods

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

add(listElement)

Adds an element to the end of the list.

Signature

public Void add(Object listElement)

Parameters

listElement
Type: Object

Return Value

Type: Void

Example

add(index, listElement)

Inserts an element into the list at the specified index position.

Signature

public Void add(Integer index, Object listElement)

Parameters

index
Type: Integer
listElement
Type: Object

Return Value

Type: Void

Example

In the following example, a list with six elements is created, and integers are added to the first and second index positions.

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.

Signature

public Void addAll(List fromList)

Parameters

fromList
Type: List

Return Value

Type: Void

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.

Signature

public Void addAll(Set fromSet)

Parameters

fromSet
Type: Set

Return Value

Type: Void

clear()

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

Signature

public Void clear()

Return Value

Type: Void

clone()

Makes a duplicate copy of a list.

Signature

public List<Object> clone()

Return Value

Type: List<Object>

Usage

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.

Example

contains(listElement)

Returns true if the list contains the specified element.

Signature

public Boolean contains(Object listElement)

Parameters

listElement
Type: Object

Return Value

Type: Boolean

Example

deepClone(preserveId, preserveReadonlyTimestamps, preserveAutonumber)

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

Signature

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

Parameters

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.

Return Value

Type: List<Object>

Usage

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.

Note

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

Example

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.

equals(list2)

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

Signature

public Boolean equals(List list2)

Parameters

list2
Type: List
The list to compare this list with.

Return Value

Type: Boolean

Usage

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;.

get(index)

Returns the list element stored at the specified index.

Signature

public Object get(Integer index)

Parameters

index
Type: Integer

Return Value

Type: Object

Usage

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.

Example

getSObjectType()

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

Signature

public Schema.SObjectType getSObjectType()

Return Value

Type: Schema.SObjectType

Usage

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.

Example

hashCode()

Returns the hashcode corresponding to this list and its contents.

Signature

public Integer hashCode()

Return Value

Type: Integer

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.

Signature

public Integer indexOf(Object listElement)

Parameters

listElement
Type: Object

Return Value

Type: Integer

Example

isEmpty()

Returns true if the list has zero elements.

Signature

public Boolean isEmpty()

Return Value

Type: Boolean

iterator()

Returns an instance of an iterator for this list.

Signature

public Iterator iterator()

Return Value

Type: Iterator

Usage

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

You do not have to implement the iterable interface to use the iterable methods with a list.

Note

See Custom Iterators.

Example

remove(index)

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

Signature

public Object remove(Integer index)

Parameters

index
Type: Integer

Return Value

Type: Object

Example

set(index, listElement)

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

Signature

public Void set(Integer index, Object listElement)

Parameters

index
Type: Integer
The index of the list element to set.
listElement
Type: Object
The value of the list element to set.

Return Value

Type: Void

Usage

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.

Example

size()

Returns the number of elements in the list.

Signature

public Integer size()

Return Value

Type: Integer

Example

sort()

Sorts the items in the list in ascending order.

Signature

public Void sort()

Return Value

Type: Void

Usage

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 also sort custom types (your Apex classes) if they implement the Comparable Interface interface.

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.

Example

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 while the second element has the value of 5.

toString()

Returns the string representation of the list.

Signature

public String toString()

Return Value

Type: String

Usage

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).