Skip to content
This repository
Browse code

Update docs to indicate lists not mutable as per 7673

  • Loading branch information...
commit c9b34304705a50a4fe3c1784f97f3305d9e9ca90 1 parent 09067cc
Hamish Friedlander authored
25  model/Filterable.php
@@ -2,7 +2,10 @@
2 2
 
3 3
 /**
4 4
  * Additional interface for {@link SS_List} classes that are filterable.
5  
- * 
  5
+ *
  6
+ * All methods in this interface are immutable - they should return new instances with the filter
  7
+ * applied, rather than applying the filter in place
  8
+ *
6 9
  * @see SS_List, SS_Sortable, SS_Limitable
7 10
  */
8 11
 interface SS_Filterable {
@@ -18,22 +21,22 @@ public function canFilterBy($by);
18 21
 	/**
19 22
 	 * Filter the list to include items with these charactaristics
20 23
 	 * 
21  
-	 * @example $list->filter('Name', 'bob'); // only bob in the list
22  
-	 * @example $list->filter('Name', array('aziz', 'bob'); // aziz and bob in list
23  
-	 * @example $list->filter(array('Name'=>'bob, 'Age'=>21)); // bob with the age 21
24  
-	 * @example $list->filter(array('Name'=>'bob, 'Age'=>array(21, 43))); // bob with the Age 21 or 43
25  
-	 * @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
  24
+	 * @example $list = $list->filter('Name', 'bob'); // only bob in the list
  25
+	 * @example $list = $list->filter('Name', array('aziz', 'bob'); // aziz and bob in list
  26
+	 * @example $list = $list->filter(array('Name'=>'bob, 'Age'=>21)); // bob with the age 21
  27
+	 * @example $list = $list->filter(array('Name'=>'bob, 'Age'=>array(21, 43))); // bob with the Age 21 or 43
  28
+	 * @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
26 29
 	 */
27 30
 	public function filter();
28 31
 	
29 32
 	/**
30 33
 	 * Exclude the list to not contain items with these charactaristics
31 34
 	 *
32  
-	 * @example $list->exclude('Name', 'bob'); // exclude bob from list
33  
-	 * @example $list->exclude('Name', array('aziz', 'bob'); // exclude aziz and bob from list
34  
-	 * @example $list->exclude(array('Name'=>'bob, 'Age'=>21)); // exclude bob that has Age 21
35  
-	 * @example $list->exclude(array('Name'=>'bob, 'Age'=>array(21, 43))); // exclude bob with Age 21 or 43
36  
-	 * @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
  35
+	 * @example $list = $list->exclude('Name', 'bob'); // exclude bob from list
  36
+	 * @example $list = $list->exclude('Name', array('aziz', 'bob'); // exclude aziz and bob from list
  37
+	 * @example $list = $list->exclude(array('Name'=>'bob, 'Age'=>21)); // exclude bob that has Age 21
  38
+	 * @example $list = $list->exclude(array('Name'=>'bob, 'Age'=>array(21, 43))); // exclude bob with Age 21 or 43
  39
+	 * @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
37 40
 	 */
38 41
 	public function exclude();
39 42
 	
5  model/Limitable.php
@@ -2,7 +2,10 @@
2 2
 
3 3
 /**
4 4
  * Additional interface for {@link SS_List} classes that are limitable - able to have a subset of the list extracted.
5  
- * 
  5
+ *
  6
+ * All methods in this interface are immutable - they should return new instances with the limit
  7
+ * applied, rather than applying the limit in place
  8
+ *
6 9
  * @see SS_List, SS_Sortable, SS_Filterable
7 10
  */
8 11
 interface SS_Limitable {
15  model/Sortable.php
@@ -2,7 +2,10 @@
2 2
 
3 3
 /**
4 4
  * Additional interface for {@link SS_List} classes that are sortable.
5  
- * 
  5
+ *
  6
+ * All methods in this interface are immutable - they should return new instances with the sort
  7
+ * applied, rather than applying the sort in place
  8
+ *
6 9
  * @see SS_List, SS_Filterable, SS_Limitable
7 10
  */
8 11
 interface SS_Sortable {
@@ -19,10 +22,10 @@ public function canSortBy($by);
19 22
 	 * Sorts this list by one or more fields. You can either pass in a single
20 23
 	 * field name and direction, or a map of field names to sort directions.
21 24
 	 *
22  
-	 * @example $list->sort('Name'); // default ASC sorting
23  
-	 * @example $list->sort('Name DESC'); // DESC sorting
24  
-	 * @example $list->sort('Name', 'ASC');
25  
-	 * @example $list->sort(array('Name'=>'ASC,'Age'=>'DESC'));
  25
+	 * @example $list = $list->sort('Name'); // default ASC sorting
  26
+	 * @example $list = $list->sort('Name DESC'); // DESC sorting
  27
+	 * @example $list = $list->sort('Name', 'ASC');
  28
+	 * @example $list = $list->sort(array('Name'=>'ASC,'Age'=>'DESC'));
26 29
 	 */
27 30
 	public function sort();
28 31
 	
@@ -30,7 +33,7 @@ public function sort();
30 33
 	/**
31 34
 	 * Reverses the list based on reversing the current sort.
32 35
 	 *
33  
-	 * @example $list->reverse();
  36
+	 * @example $list = $list->reverse();
34 37
 	 *
35 38
 	 * @return array
36 39
 	 */

0 notes on commit c9b3430

Please sign in to comment.
Something went wrong with that request. Please try again.