Force.com Apex Code Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
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:

1myList.clear();

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

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

1swfobject.registerObject("clippy.codeblock-1", "9");// Create a list
2List<Integer> ls1 = new List<Integer>();
3// Add two integers to the list
4ls1.add(1);
5ls1.add(2);
6

List<T>(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.

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

1swfobject.registerObject("clippy.codeblock-2", "9");List<Integer> ls1 = new List<Integer>();
2ls1.add(1);
3ls1.add(2);
4// Create a list based on an existing one
5List<Integer> ls2 = new List<Integer>(ls1);
6// ls2 elements are copied from ls1
7System.debug(ls2);// DEBUG|(1, 2)

List<T>(Set<T>)

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

1swfobject.registerObject("clippy.codeblock-3", "9");Set<Integer> s1 = new Set<Integer>();
2s1.add(1);
3s1.add(2);
4// Create a list based on a set
5List<Integer> ls = new List<Integer>(s1);
6// ls elements are copied from s1
7System.debug(ls);// DEBUG|(1, 2)

List Methods

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

add(Object)

Adds an element to the end of the list.

Signature

public Void add(Object listElement)

Parameters

listElement
Type: Object

Return Value

Type: Void

Example

1List<Integer> myList = new List<Integer>();
2myList.add(47);
3Integer myNumber = myList.get(0);
4system.assertEquals(myNumber, 47);

add(Integer, Object)

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.

1List<Integer> myList = new Integer[6];
2myList.add(0, 47);
3myList.add(1, 52);
4system.assertEquals(myList.get(1), 52);

addAll(List)

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(Set)

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

1Account a = new 
2     Account(Name='Acme',
3             BillingCity='New York');
4
5Account b = new Account();
6Account[] q1 = new 
7     Account[]{a,b};
8
9Account[] q2 = q1.clone();
10q1[0].BillingCity = 'San Francisco';
11
12System.assertEquals(
13      q1[0].BillingCity,
14      'San Francisco');
15System.assertEquals(
16      q2[0].BillingCity, 
17      'San Francisco');

deepClone(Boolean, Boolean, Boolean)

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

Signature

public List<Object> deepClone(Boolean opt_preserve_id, Boolean opt_preserve_readonly_timestamps, Boolean opt_preserve_autonumber)

Parameters

opt_preserve_id
Type: Boolean
The optional opt_preserve_id 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.
opt_preserve_readonly_timestamps
Type: Boolean
The optional opt_preserve_readonly_timestamps 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.
opt_preserve_autonumber
Type: Boolean
The optional opt_preserve_autonumber 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 SalesforceAPI version 22.0 or earlier, the default value for the opt_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.

1Account a = new 
2   Account(Name='Acme', 
3           BillingCity='New York');
4
5Account b = new Account(
6   Name='Salesforce');
7
8Account[] q1 = new 
9     Account[]{a,b};
10
11Account[] q2 = q1.deepClone();
12q1[0].BillingCity = 'San Francisco';
13
14System.assertEquals(
15     q1[0].BillingCity, 
16     'San Francisco');
17
18System.assertEquals(
19     q2[0].BillingCity,
20     'New York');
This example is based on the previous example and shows how to clone a list with preserved read-only timestamp and user ID fields.
1insert q1;
2
3List<Account> accts =
4   [SELECT CreatedById, 
5   CreatedDate, LastModifiedById, 
6   LastModifiedDate, BillingCity 
7   FROM Account 
8   WHERE Name='Acme' OR 
9     Name='Salesforce'];
10
11// Clone list while preserving 
12// timestamp and user ID fields.
13Account[] q3 = 
14   accts.deepClone(false,true,false);
15
16// Verify timestamp fields are 
17// preserved for the first 
18// list element. 
19System.assertEquals(
20    q3[0].CreatedById, 
21    accts[0].CreatedById);
22System.assertEquals(
23    q3[0].CreatedDate, 
24    accts[0].CreatedDate);
25System.assertEquals(
26    q3[0].LastModifiedById,
27    accts[0].LastModifiedById);
28System.assertEquals(
29    q3[0].LastModifiedDate,
30    accts[0].LastModifiedDate);

equals(List)

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(Integer)

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

1List<Integer> myList = new List<Integer>();
2myList.add(47);
3Integer myNumber = myList.get(0);
4system.assertEquals(myNumber, 47);
1List<String> colors = new String[3];
2colors[0] = 'Red';
3colors[1] = 'Blue';
4colors[2] = 'Green';

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

1Account a = new Account(name='test');
2insert a;
3// Create a generic sObject 
4// variable s
5SObject s = Database.query
6  ('SELECT Id FROM Account ' + 
7   'LIMIT 1');
8
9// Verify if that sObject 
10// variable is 
11// an Account token
12System.assertEquals(
13   s.getSObjectType(), 
14   Account.sObjectType);
15
16// Create a list of 
17// generic sObjects 
18List<sObject> q = 
19   new Account[]{};
20
21// Verify if the list of 
22// sObjects 
23// contains Account tokens
24System.assertEquals(
25   q.getSObjectType(), 
26   Account.sObjectType);

hashCode()

Returns the hashcode corresponding to this list and its contents.

Signature

public Integer hashCode()

Return Value

Type: Integer

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

1swfobject.registerObject("clippy.IterableExampleCRM", "9");global class CustomIterable 
2   implements Iterator<Account>{ 
3
4   List<Account> accs {get; set;} 
5   Integer i {get; set;} 
6
7   public CustomIterable(){ 
8       accs = 
9       [SELECT Id, Name, 
10       NumberOfEmployees 
11       FROM Account 
12       WHERE Name = 'false']; 
13       i = 0; 
14   }   
15
16   global boolean hasNext(){ 
17       if(i >= accs.size()) {
18           return false; 
19       } else {
20           return true; 
21       }
22   }    
23
24   global Account next(){ 
25       // 8 is an arbitrary 
26       // constant in this example
27       // that represents the 
28       // maximum size of the list.
29       if(i == 8){return null;} 
30       i++; 
31       return accs[i-1]; 
32   } 
33}

remove(Integer)

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

1List<String> colors = new String[3];
2colors[0] = 'Red';
3colors[1] = 'Blue';
4colors[2] = 'Green';
5String S1 = colors.remove(2);
6system.assertEquals(S1, 'Green');

set(Integer, Object)

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

1List<Integer> myList = new Integer[6];
2myList.set(0, 47);
3myList.set(1, 52);
4system.assertEquals(myList.get(1), 52);
1List<String> colors = new String[3];
2colors[0] = 'Red';
3colors[1] = 'Blue';
4colors[2] = 'Green';

size()

Returns the number of elements in the list.

Signature

public Integer size()

Return Value

Type: Integer

Example

1List<Integer> myList = new List<Integer>();
2Integer size = myList.size();
3system.assertEquals(size, 0);
4
5List<Integer> myList2 = new Integer[6];
6Integer size2 = myList2.size();
7system.assertEquals(size2, 6);

sort()

Sorts the items in the list in ascending order.

Signature

public Void sort()

Return Value

Type: Void

Usage

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:

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.

Note

Example

1List<Integer> q1 = new Integer[3];
2
3// Assign values to the first 
4// two elements
5q1[0] = 10;
6q1[1] = 5;
7
8q1.sort();
9// First element is null, second is 5
10system.assertEquals(q1.get(1), 5);