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