www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/TypedData/ListInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\TypedData;
   4
   5 /**
   6  * Interface for a list of typed data.
   7  *
   8  * A list of typed data contains only items of the same type, is ordered and may
   9  * contain duplicates. Note that the data type of a list is always 'list'.
  10  *
  11  * When implementing this interface which extends Traversable, make sure to list
  12  * IteratorAggregate or Iterator before this interface in the implements clause.
  13  *
  14  * @see \Drupal\Core\TypedData\ListDefinitionInterface
  15  *
  16  * @ingroup typed_data
  17  */
  18 interface ListInterface extends TraversableTypedDataInterface, \ArrayAccess, \Countable {
  19
  20   /**
  21    * Gets the data definition.
  22    *
  23    * @return \Drupal\Core\TypedData\ListDataDefinitionInterface
  24    *   The data definition object describing the list.
  25    */
  26   public function getDataDefinition();
  27
  28   /**
  29    * Determines whether the list contains any non-empty items.
  30    *
  31    * @return bool
  32    *   TRUE if the list is empty, FALSE otherwise.
  33    */
  34   public function isEmpty();
  35
  36   /**
  37    * Gets the definition of a contained item.
  38    *
  39    * @return \Drupal\Core\TypedData\DataDefinitionInterface
  40    *   The data definition of contained items.
  41    */
  42   public function getItemDefinition();
  43
  44   /**
  45    * Returns the item at the specified position in this list.
  46    *
  47    * @param int $index
  48    *   Index of the item to return.
  49    *
  50    * @return \Drupal\Core\TypedData\TypedDataInterface|null
  51    *   The item at the specified position in this list, or NULL if no item
  52    *   exists at that position.
  53    *
  54    * @throws \Drupal\Core\TypedData\Exception\MissingDataException
  55    *   If the complex data structure is unset and no item can be created.
  56    */
  57   public function get($index);
  58
  59   /**
  60    * Sets the value of the item at a given position in the list.
  61    *
  62    * @param int $index
  63    *   The position of the item in the list. Since a List only contains
  64    *   sequential, 0-based indexes, $index has to be:
  65    *   - Either the position of an existing item in the list. This updates the
  66    *   item value.
  67    *   - Or the next available position in the sequence of the current list
  68    *   indexes. This appends a new item with the provided value at the end of
  69    *   the list.
  70    * @param mixed $value
  71    *   The value of the item to be stored at the specified position.
  72    *
  73    * @return $this
  74    *
  75    * @throws \InvalidArgumentException
  76    *   If the $index is invalid (non-numeric, or pointing to an invalid
  77    *   position in the list).
  78    * @throws \Drupal\Core\TypedData\Exception\MissingDataException
  79    *   If the complex data structure is unset and no item can be set.
  80    */
  81   public function set($index, $value);
  82
  83   /**
  84    * Returns the first item in this list.
  85    *
  86    * @return \Drupal\Core\TypedData\TypedDataInterface
  87    *   The first item in this list.
  88    *
  89    * @throws \Drupal\Core\TypedData\Exception\MissingDataException
  90    *   If the complex data structure is unset and no item can be created.
  91    */
  92   public function first();
  93
  94   /**
  95    * Appends a new item to the list.
  96    *
  97    * @param mixed $value
  98    *   The value of the new item.
  99    *
 100    * @return \Drupal\Core\TypedData\TypedDataInterface
 101    *   The item that was appended.
 102    */
 103   public function appendItem($value = NULL);
 104
 105   /**
 106    * Removes the item at the specified position.
 107    *
 108    * @param int $index
 109    *   Index of the item to remove.
 110    *
 111    * @return $this
 112    */
 113   public function removeItem($index);
 114
 115   /**
 116    * Filters the items in the list using a custom callback.
 117    *
 118    * @param callable $callback
 119    *   The callback to use for filtering. Like with array_filter(), the
 120    *   callback is called for each item in the list. Only items for which the
 121    *   callback returns TRUE are preserved.
 122    *
 123    * @return $this
 124    */
 125   public function filter($callback);
 126
 127 }