aboutsummaryrefslogtreecommitdiff
path: root/engine/classes/ElggPriorityList.php
blob: 416df885c59c09b904ec4838d5e4377124ac64d0 (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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
<?php
/**
 * Iterate over elements in a specific priority.
 *
 * $pl = new ElggPriorityList();
 * $pl->add('Element 0');
 * $pl->add('Element 10', 10);
 * $pl->add('Element -10', -10);
 *
 * foreach ($pl as $priority => $element) {
 *	var_dump("$priority => $element");
 * }
 *
 * Yields:
 * -10 => Element -10
 * 0 => Element 0
 * 10 => Element 10
 *
 * Collisions on priority are handled by inserting the element at or as close to the
 * requested priority as possible:
 *
 * $pl = new ElggPriorityList();
 * $pl->add('Element 5', 5);
 * $pl->add('Colliding element 5', 5);
 * $pl->add('Another colliding element 5', 5);
 *
 * foreach ($pl as $priority => $element) {
 *	var_dump("$priority => $element");
 * }
 *
 * Yields:
 *	5 => 'Element 5',
 *	6 => 'Colliding element 5',
 *	7 => 'Another colliding element 5'
 *
 * You can do priority lookups by element:
 *
 * $pl = new ElggPriorityList();
 * $pl->add('Element 0');
 * $pl->add('Element -5', -5);
 * $pl->add('Element 10', 10);
 * $pl->add('Element -10', -10);
 *
 * $priority = $pl->getPriority('Element -5');
 * 
 * Or element lookups by priority.
 * $element = $pl->getElement(-5);
 *
 * To remove elements, pass the element.
 * $pl->remove('Element -10');
 *
 * To check if an element exists:
 * $pl->contains('Element -5');
 *
 * To move an element:
 * $pl->move('Element -5', -3);
 *
 * ElggPriorityList only tracks priority. No checking is done in ElggPriorityList for duplicates or
 * updating. If you need to track this use objects and an external map:
 *
 * function elgg_register_something($id, $display_name, $location, $priority = 500) {
 *	// $id => $element.
 *	static $map = array();
 *	static $list;
 *
 *	if (!$list) {
 *		$list = new ElggPriorityList();
 *	}
 *
 *	// update if already registered.
 *	if (isset($map[$id])) {
 *		$element = $map[$id];
 *		// move it first because we have to pass the original element.
 *		if (!$list->move($element, $priority)) {
 *			return false;
 *		}
 *		$element->display_name = $display_name;
 *		$element->location = $location;
 *	} else {
 *		$element = new stdClass();
 *		$element->display_name = $display_name;
 *		$element->location = $location;
 *		if (!$list->add($element, $priority)) {
 *			return false;
 *		}
 *		$map[$id] = $element;
 *	}
 *
 *	return true;
 * }
 *
 * @package    Elgg.Core
 * @subpackage Helpers
 */
class ElggPriorityList
	implements Iterator, Countable {

	/**
	 * The list of elements
	 *
	 * @var array
	 */
	private $elements = array();

	/**
	 * Create a new priority list.
	 *
	 * @param array $elements An optional array of priorities => element
	 */
	public function __construct(array $elements = array()) {
		if ($elements) {
			foreach ($elements as $priority => $element) {
				$this->add($element, $priority);
			}
		}
	}

	/**
	 * Adds an element to the list.
	 *
	 * @warning This returns the priority at which the element was added, which can be 0. Use
	 *          !== false to check for success.
	 *
	 * @param mixed $element  The element to add to the list.
	 * @param mixed $priority Priority to add the element. In priority collisions, the original element
	 *                        maintains its priority and the new element is to the next available
	 *                        slot, taking into consideration all previously registered elements.
	 *                        Negative elements are accepted.
	 * @param bool  $exact    unused
	 * @return int            The priority of the added element.
	 * @todo remove $exact or implement it. Note we use variable name strict below.
	 */
	public function add($element, $priority = null, $exact = false) {
		if ($priority !== null && !is_numeric($priority)) {
			return false;
		} else {
			$priority = $this->getNextPriority($priority);
		}

		$this->elements[$priority] = $element;
		$this->sorted = false;
		return $priority;
	}

	/**
	 * Removes an element from the list.
	 *
	 * @warning The element must have the same attributes / values. If using $strict, it must have
	 *          the same types. array(10) will fail in strict against array('10') (str vs int).
	 *
	 * @param mixed $element The element to remove from the list
	 * @param bool  $strict  Whether to check the type of the element match
	 * @return bool
	 */
	public function remove($element, $strict = false) {
		$index = array_search($element, $this->elements, $strict);
		if ($index !== false) {
			unset($this->elements[$index]);
			return true;
		} else {
			return false;
		}
	}

	/**
	 * Move an existing element to a new priority.
	 *
	 * @param mixed $element      The element to move
	 * @param int   $new_priority The new priority for the element
	 * @param bool  $strict       Whether to check the type of the element match
	 * @return bool
	 */
	public function move($element, $new_priority, $strict = false) {
		$new_priority = (int) $new_priority;
		
		$current_priority = $this->getPriority($element, $strict);
		if ($current_priority === false) {
			return false;
		}

		if ($current_priority == $new_priority) {
			return true;
		}

		// move the actual element so strict operations still work
		$element = $this->getElement($current_priority);
		unset($this->elements[$current_priority]);
		return $this->add($element, $new_priority);
	}

	/**
	 * Returns the elements
	 *
	 * @return array
	 */
	public function getElements() {
		$this->sortIfUnsorted();
		return $this->elements;
	}

	/**
	 * Sort the elements optionally by a callback function.
	 *
	 * If no user function is provided the elements are sorted by priority registered.
	 *
	 * The callback function should accept the array of elements as the first 
	 * argument and should return a sorted array.
	 *
	 * This function can be called multiple times.
	 *
	 * @param callback $callback The callback for sorting. Numeric sorting is the default.
	 * @return bool
	 */
	public function sort($callback = null) {
		if (!$callback) {
			ksort($this->elements, SORT_NUMERIC);
		} else {
			$sorted = call_user_func($callback, $this->elements);

			if (!$sorted) {
				return false;
			}

			$this->elements = $sorted;
		}
		
		$this->sorted = true;
		return true;
	}

	/**
	 * Sort the elements if they haven't been sorted yet.
	 *
	 * @return bool
	 */
	private function sortIfUnsorted() {
		if (!$this->sorted) {
			return $this->sort();
		}
	}

	/**
	 * Returns the next priority available.
	 *
	 * @param int $near Make the priority as close to $near as possible.
	 * @return int
	 */
	public function getNextPriority($near = 0) {
		$near = (int) $near;
		
		while (array_key_exists($near, $this->elements)) {
			$near++;
		}

		return $near;
	}

	/**
	 * Returns the priority of an element if it exists in the list.
	 * 
	 * @warning This can return 0 if the element's priority is 0.
	 *
	 * @param mixed $element The element to check for.
	 * @param bool  $strict  Use strict checking?
	 * @return mixed False if the element doesn't exists, the priority if it does.
	 */
	public function getPriority($element, $strict = false) {
		return array_search($element, $this->elements, $strict);
	}

	/**
	 * Returns the element at $priority.
	 *
	 * @param int $priority The priority
	 * @return mixed The element or false on fail.
	 */
	public function getElement($priority) {
		return (isset($this->elements[$priority])) ? $this->elements[$priority] : false;
	}

	/**
	 * Returns if the list contains $element.
	 *
	 * @param mixed $element The element to check.
	 * @param bool  $strict  Use strict checking?
	 * @return bool
	 */
	public function contains($element, $strict = false) {
		return $this->getPriority($element, $strict) !== false;
	}

	
	/**********************
	 * Interface methods *
	 **********************/

	/**
	 * Iterator
	 */

	/**
	 * PHP Iterator Interface
	 *
	 * @see Iterator::rewind()
	 * @return void
	 */
	public function rewind() {
		$this->sortIfUnsorted();
		return reset($this->elements);
	}

	/**
	 * PHP Iterator Interface
	 *
	 * @see Iterator::current()
	 * @return mixed
	 */
	public function current() {
		$this->sortIfUnsorted();
		return current($this->elements);
	}

	/**
	 * PHP Iterator Interface
	 *
	 * @see Iterator::key()
	 * @return int
	 */
	public function key() {
		$this->sortIfUnsorted();
		return key($this->elements);
	}

	/**
	 * PHP Iterator Interface
	 *
	 * @see Iterator::next()
	 * @return mixed
	 */
	public function next() {
		$this->sortIfUnsorted();
		return next($this->elements);
	}

	/**
	 * PHP Iterator Interface
	 *
	 * @see Iterator::valid()
	 * @return bool
	 */
	public function valid() {
		$this->sortIfUnsorted();
		$key = key($this->elements);
		return ($key !== NULL && $key !== FALSE);
	}

	/**
	 * Countable interface
	 *
	 * @see Countable::count()
	 * @return int
	 */
	public function count() {
		return count($this->elements);
	}
}