Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update docs to indicate lists not mutable as per 7673

  • Loading branch information...
commit c9b34304705a50a4fe3c1784f97f3305d9e9ca90 1 parent 09067cc
@hafriedlander hafriedlander authored
Showing with 27 additions and 18 deletions.
  1. +14 −11 model/Filterable.php
  2. +4 −1 model/Limitable.php
  3. +9 −6 model/Sortable.php
View
25 model/Filterable.php
@@ -2,7 +2,10 @@
/**
* Additional interface for {@link SS_List} classes that are filterable.
- *
+ *
+ * All methods in this interface are immutable - they should return new instances with the filter
+ * applied, rather than applying the filter in place
+ *
* @see SS_List, SS_Sortable, SS_Limitable
*/
interface SS_Filterable {
@@ -18,22 +21,22 @@ public function canFilterBy($by);
/**
* Filter the list to include items with these charactaristics
*
- * @example $list->filter('Name', 'bob'); // only bob in the list
- * @example $list->filter('Name', array('aziz', 'bob'); // aziz and bob in list
- * @example $list->filter(array('Name'=>'bob, 'Age'=>21)); // bob with the age 21
- * @example $list->filter(array('Name'=>'bob, 'Age'=>array(21, 43))); // bob with the Age 21 or 43
- * @example $list->filter(array('Name'=>array('aziz','bob'), 'Age'=>array(21, 43))); // aziz with the age 21 or 43 and bob with the Age 21 or 43
+ * @example $list = $list->filter('Name', 'bob'); // only bob in the list
+ * @example $list = $list->filter('Name', array('aziz', 'bob'); // aziz and bob in list
+ * @example $list = $list->filter(array('Name'=>'bob, 'Age'=>21)); // bob with the age 21
+ * @example $list = $list->filter(array('Name'=>'bob, 'Age'=>array(21, 43))); // bob with the Age 21 or 43
+ * @example $list = $list->filter(array('Name'=>array('aziz','bob'), 'Age'=>array(21, 43))); // aziz with the age 21 or 43 and bob with the Age 21 or 43
*/
public function filter();
/**
* Exclude the list to not contain items with these charactaristics
*
- * @example $list->exclude('Name', 'bob'); // exclude bob from list
- * @example $list->exclude('Name', array('aziz', 'bob'); // exclude aziz and bob from list
- * @example $list->exclude(array('Name'=>'bob, 'Age'=>21)); // exclude bob that has Age 21
- * @example $list->exclude(array('Name'=>'bob, 'Age'=>array(21, 43))); // exclude bob with Age 21 or 43
- * @example $list->exclude(array('Name'=>array('bob','phil'), 'Age'=>array(21, 43))); // bob age 21 or 43, phil age 21 or 43 would be excluded
+ * @example $list = $list->exclude('Name', 'bob'); // exclude bob from list
+ * @example $list = $list->exclude('Name', array('aziz', 'bob'); // exclude aziz and bob from list
+ * @example $list = $list->exclude(array('Name'=>'bob, 'Age'=>21)); // exclude bob that has Age 21
+ * @example $list = $list->exclude(array('Name'=>'bob, 'Age'=>array(21, 43))); // exclude bob with Age 21 or 43
+ * @example $list = $list->exclude(array('Name'=>array('bob','phil'), 'Age'=>array(21, 43))); // bob age 21 or 43, phil age 21 or 43 would be excluded
*/
public function exclude();
View
5 model/Limitable.php
@@ -2,7 +2,10 @@
/**
* Additional interface for {@link SS_List} classes that are limitable - able to have a subset of the list extracted.
- *
+ *
+ * All methods in this interface are immutable - they should return new instances with the limit
+ * applied, rather than applying the limit in place
+ *
* @see SS_List, SS_Sortable, SS_Filterable
*/
interface SS_Limitable {
View
15 model/Sortable.php
@@ -2,7 +2,10 @@
/**
* Additional interface for {@link SS_List} classes that are sortable.
- *
+ *
+ * All methods in this interface are immutable - they should return new instances with the sort
+ * applied, rather than applying the sort in place
+ *
* @see SS_List, SS_Filterable, SS_Limitable
*/
interface SS_Sortable {
@@ -19,10 +22,10 @@ public function canSortBy($by);
* Sorts this list by one or more fields. You can either pass in a single
* field name and direction, or a map of field names to sort directions.
*
- * @example $list->sort('Name'); // default ASC sorting
- * @example $list->sort('Name DESC'); // DESC sorting
- * @example $list->sort('Name', 'ASC');
- * @example $list->sort(array('Name'=>'ASC,'Age'=>'DESC'));
+ * @example $list = $list->sort('Name'); // default ASC sorting
+ * @example $list = $list->sort('Name DESC'); // DESC sorting
+ * @example $list = $list->sort('Name', 'ASC');
+ * @example $list = $list->sort(array('Name'=>'ASC,'Age'=>'DESC'));
*/
public function sort();
@@ -30,7 +33,7 @@ public function sort();
/**
* Reverses the list based on reversing the current sort.
*
- * @example $list->reverse();
+ * @example $list = $list->reverse();
*
* @return array
*/
Please sign in to comment.
Something went wrong with that request. Please try again.