summaryrefslogtreecommitdiffstats
path: root/core/lib/Drupal/Core/TypedData/ListInterface.php
blob: 1dab39a0f71e45567a3db8a5cfb08a3b73bb84b9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
<?php

namespace Drupal\Core\TypedData;

/**
 * Interface for a list of typed data.
 *
 * A list of typed data contains only items of the same type, is ordered and may
 * contain duplicates. Note that the data type of a list is always 'list'.
 *
 * When implementing this interface which extends Traversable, make sure to list
 * IteratorAggregate or Iterator before this interface in the implements clause.
 *
 * @see \Drupal\Core\TypedData\ListDefinitionInterface
 *
 * @ingroup typed_data
 */
interface ListInterface extends TraversableTypedDataInterface, \ArrayAccess, \Countable {

  /**
   * Gets the data definition.
   *
   * @return \Drupal\Core\TypedData\ListDataDefinitionInterface
   *   The data definition object describing the list.
   */
  public function getDataDefinition();

  /**
   * Determines whether the list contains any non-empty items.
   *
   * @return bool
   *   TRUE if the list is empty, FALSE otherwise.
   */
  public function isEmpty();

  /**
   * Gets the definition of a contained item.
   *
   * @return \Drupal\Core\TypedData\DataDefinitionInterface
   *   The data definition of contained items.
   */
  public function getItemDefinition();

  /**
   * Returns the item at the specified position in this list.
   *
   * @param int $index
   *   Index of the item to return.
   *
   * @return \Drupal\Core\TypedData\TypedDataInterface|null
   *   The item at the specified position in this list, or NULL if no item
   *   exists at that position.
   *
   * @throws \Drupal\Core\TypedData\Exception\MissingDataException
   *   If the complex data structure is unset and no item can be created.
   */
  public function get($index);

  /**
   * Sets the value of the item at a given position in the list.
   *
   * @param int $index
   *   The position of the item in the list. Since a List only contains
   *   sequential, 0-based indexes, $index has to be:
   *   - Either the position of an existing item in the list. This updates the
   *   item value.
   *   - Or the next available position in the sequence of the current list
   *   indexes. This appends a new item with the provided value at the end of
   *   the list.
   * @param mixed $value
   *   The value of the item to be stored at the specified position.
   *
   * @return $this
   *
   * @throws \InvalidArgumentException
   *   If the $index is invalid (non-numeric, or pointing to an invalid
   *   position in the list).
   * @throws \Drupal\Core\TypedData\Exception\MissingDataException
   *   If the complex data structure is unset and no item can be set.
   */
  public function set($index, $value);

  /**
   * Returns the first item in this list.
   *
   * @return \Drupal\Core\TypedData\TypedDataInterface
   *   The first item in this list.
   *
   * @throws \Drupal\Core\TypedData\Exception\MissingDataException
   *   If the complex data structure is unset and no item can be created.
   */
  public function first();

  /**
   * Appends a new item to the list.
   *
   * @param mixed $value
   *   The value of the new item.
   *
   * @return \Drupal\Core\TypedData\TypedDataInterface
   *   The item that was appended.
   */
  public function appendItem($value = NULL);

  /**
   * Removes the item at the specified position.
   *
   * @param int $index
   *   Index of the item to remove.
   *
   * @return $this
   */
  public function removeItem($index);

  /**
   * Filters the items in the list using a custom callback.
   *
   * @param callable $callback
   *   The callback to use for filtering. Like with array_filter(), the
   *   callback is called for each item in the list. Only items for which the
   *   callback returns TRUE are preserved.
   *
   * @return $this
   */
  public function filter($callback);

}