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