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