1: <?php
2: /**
3: * This file contains the array utility class.
4: *
5: * @package Core
6: * @subpackage Util
7: * @author Murat Purc <murat@purc.de>
8: * @copyright four for business AG <www.4fb.de>
9: * @license http://www.contenido.org/license/LIZENZ.txt
10: * @link http://www.4fb.de
11: * @link http://www.contenido.org
12: */
13:
14: defined('CON_FRAMEWORK') || die('Illegal call: Missing framework initialization - request aborted.');
15:
16: /**
17: * Array helper class.
18: *
19: * @package Core
20: * @subpackage Util
21: */
22: class cArray {
23:
24: /**
25: * Strip whitespaces (or other characters) from the beginning and end of
26: * each item in array.
27: * Similar to trim() function.
28: *
29: * @param array $arr
30: * Array of strings that will be trimmed.
31: * @param string $charlist [optional]
32: * Optionally the stripped characters can also be specified using
33: * the charlist parameter. Simply list all characters that you want
34: * to be stripped. With .. you can specify a range of characters.
35: * @return array
36: * Array of trimmed strings.
37: */
38: public static function trim(array $arr, $charlist = NULL) {
39: foreach ($arr as $key => $value) {
40: $arr[$key] = isset($charlist) ? trim($value, $charlist) : trim($value);
41: }
42:
43: return $arr;
44: }
45:
46: /**
47: * Search for given value in given array and return key of its first
48: * occurance.
49: *
50: * If value wasn't found at all false will be returned. If given array
51: * contains subarrays, these will be searched too. If value is found in
52: * subarray the returned key is that of the subarray.
53: *
54: * Usually the values are tested for equality with the given $search. If the
55: * flag $partial is not false values are tested to contain $search.
56: * Otherwise, if $strict equals true values are tested for identity with
57: * $search. Otherwise (which is the default) values are tested for equality.
58: *
59: * Be careful when searching by equality in arrays containing values that
60: * are no strings! The same is true for searching by equality for values
61: * that are no strings. PHPs behaviour is quite weird concerning comparision
62: * of different data types. E.g. '0' equals '0.0', 'foo' equals 0, 'foo'
63: * equals 0.0, NULL equals '' and false equals '0'! When dealing with
64: * nonstrings consider to use the strict mode!
65: *
66: * Another caveat is when searching for an empty string when using the
67: * partial mode. This would lead to an error and is considered a bug!
68: *
69: * @todo There should be only one flag for $partial and $strict in order to
70: * avoid ambiguities (imagine $partial=true & $strict=true).
71: * @param array $arr
72: * array to search
73: * @param mixed $search
74: * value to search for
75: * @param bool $partial [optional]
76: * if values are tested to contain $search
77: * @param bool $strict [optional]
78: * if values are tested for identity
79: * @return mixed
80: * key of the array containing the searched value or false
81: */
82: public static function searchRecursive(array $arr, $search, $partial = false, $strict = false) {
83: foreach ($arr as $key => $value) {
84: if (is_array($value)) {
85: $ret = static::searchRecursive($value, $search, $partial, $strict);
86: if ($ret !== false) {
87: return $ret;
88: }
89: } else {
90: if ($partial !== false) {
91: // BUGFIX empty search
92: if (0 === strlen($search)) {
93: return false;
94: }
95: // convert $search explicitly to string
96: // we do not want to use the ordinal value of $search
97: $found = false !== strpos($value, strval($search));
98: } else if ($strict == true) {
99: // search by identity
100: $found = $value === $search;
101: } else {
102: // search by equality
103: $found = $value == $search;
104: }
105: if ($found) {
106: return $key;
107: }
108: }
109: }
110:
111: return false;
112: }
113:
114: /**
115: * Sorts an array by changing the locale temporary to passed value.
116: *
117: * @param array $arr
118: * The array to sort
119: * @param string $locale
120: * The locale to change before sorting
121: * @return array
122: * Sorted array
123: */
124: public static function sortWithLocale(array $arr, $locale) {
125: $oldlocale = setlocale(LC_COLLATE, 0);
126: setlocale(LC_COLLATE, $locale);
127:
128: uasort($arr, 'strcoll');
129:
130: setlocale(LC_COLLATE, $oldlocale);
131:
132: return $arr;
133: }
134:
135: /**
136: * Very cool algorithm for sorting multi-dimensional arrays.
137: *
138: * Found at http://us2.php.net/manual/en/function.array-multisort.php
139: *
140: * Syntax:
141: * <pre>
142: * $new_array = cArray::csort($array [, 'col1' [, SORT_FLAG [,
143: * SORT_FLAG]]]...);
144: * </pre>
145: *
146: * Explanation:
147: * - $array is the array you want to sort
148: * - 'col1' is the name of the column you want to sort
149: * - SORT_FLAGS are: SORT_ASC, SORT_DESC, SORT_REGULAR, SORT_NUMERIC,
150: * SORT_STRING
151: *
152: * You can repeat the 'col', FLAG, FLAG as often as you want. The highest
153: * prioritiy is given to the first - so the array is sorted by the last
154: * given column first, then the one before ...
155: *
156: * Example:
157: * <pre>
158: * $array = cArray::csort($array, 'town', 'age', SORT_DESC, 'name');
159: * </pre>
160: *
161: * @return array
162: */
163: public static function csort() {
164: $args = func_get_args();
165: $marray = array_shift($args);
166: $msortline = "return(array_multisort(";
167: $i = 0;
168: foreach ($args as $arg) {
169: $i++;
170: if (is_string($arg)) {
171: foreach ($marray as $row) {
172: $a = strtoupper($row[$arg]);
173: $sortarr[$i][] = $a;
174: }
175: } else {
176: $sortarr[$i] = $arg;
177: }
178: $msortline .= "\$sortarr[" . $i . "],";
179: }
180: $msortline .= "\$marray));";
181: @eval($msortline);
182: return $marray;
183: }
184:
185: /**
186: * Ensures that the passed array has the key, sets it by using the value.
187: *
188: * @param array $aArray
189: * @param string $sKey
190: * @param mixed $mDefault [optional]
191: * @return bool
192: */
193: public static function initializeKey(&$aArray, $sKey, $mDefault = '') {
194: if (!is_array($aArray)) {
195: if (isset($aArray)) {
196: return false;
197: }
198: $aArray = array();
199: }
200:
201: if (!array_key_exists($sKey, $aArray)) {
202: $aArray[$sKey] = $mDefault;
203: }
204: }
205: }
206: