Coverage Report - org.as3collections.utils.CollectionUtil
 
Classes in this File Line Coverage Branch Coverage Complexity
CollectionUtil
42%
46/109
N/A
0
 
 1  
 /*
 2  
  * Licensed under the MIT License
 3  
  * 
 4  
  * Copyright 2010 (c) Flávio Silva, http://flsilva.com
 5  
  *
 6  
  * Permission is hereby granted, free of charge, to any person
 7  
  * obtaining a copy of this software and associated documentation
 8  
  * files (the "Software"), to deal in the Software without
 9  
  * restriction, including without limitation the rights to use,
 10  
  * copy, modify, merge, publish, distribute, sublicense, and/or sell
 11  
  * copies of the Software, and to permit persons to whom the
 12  
  * Software is furnished to do so, subject to the following
 13  
  * conditions:
 14  
  *
 15  
  * The above copyright notice and this permission notice shall be
 16  
  * included in all copies or substantial portions of the Software.
 17  
  *
 18  
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 19  
  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 20  
  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 21  
  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 22  
  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 23  
  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 24  
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 25  
  * OTHER DEALINGS IN THE SOFTWARE.
 26  
  * 
 27  
  * http://www.opensource.org/licenses/mit-license.php
 28  
  */
 29  
 
 30  1
 package org.as3collections.utils 
 31  
 {
 32  
         import org.as3collections.ICollection;
 33  
         import org.as3collections.IIterator;
 34  
         import org.as3collections.lists.ArrayList;
 35  
         import org.as3coreaddendum.system.IEquatable;
 36  
         import org.as3coreaddendum.system.comparators.AlphabeticalComparison;
 37  
         import org.as3utils.ArrayUtil;
 38  
         import org.as3utils.ReflectionUtil;
 39  
 
 40  
         import flash.errors.IllegalOperationError;
 41  
 
 42  
         /**
 43  
          * A utility class to work with implementations of the <code>ICollection</code> interface.
 44  
          * <p><code>CollectionUtil</code> handles <code>null</code> input collections quietly in almost all methods. When not, it's documented in the method.
 45  
          * That is to say that a <code>null</code> input will not thrown an error in almost all methods.</p>
 46  
          * 
 47  
          * @author Flávio Silva
 48  
          */
 49  
         public class CollectionUtil
 50  
         {
 51  
                 /**
 52  
                  * <code>CollectionUtil</code> is a static class and shouldn't be instantiated.
 53  
                  * 
 54  
                  * @throws         IllegalOperationError         <code>CollectionUtil</code> is a static class and shouldn't be instantiated.
 55  
                  */
 56  
                 public function CollectionUtil()
 57  0
                 {
 58  0
                         throw new IllegalOperationError("CollectionUtil is a static class and shouldn't be instantiated.");
 59  
                 }
 60  
                 
 61  
                 //TODO:asdoc e ordenar
 62  
                 public static function containsDuplication(collection:ICollection): Boolean
 63  
                 {
 64  0
                         return getDuplicate(collection).size() > 0;
 65  
                 }
 66  
                 
 67  
                 public static function getDuplicate(collection:ICollection): ICollection
 68  
                 {
 69  0
                         if (!collection || collection.isEmpty()) return new ArrayList();
 70  
                         
 71  0
                         var duplicate:ICollection = new ArrayList();
 72  0
                         var temp:ICollection = new ArrayList();
 73  0
                         var it:IIterator = collection.iterator();
 74  
                         var element:*;
 75  
                         
 76  0
                         while(it.hasNext())
 77  
                         {
 78  0
                                 element = it.next();
 79  
                                 
 80  0
                                 if (temp.contains(element)) duplicate.add(element);
 81  
                                 
 82  0
                                 temp.add(element); 
 83  
                         }
 84  
                         
 85  0
                         return duplicate;
 86  
                 }
 87  
                 
 88  
                 /**
 89  
                  * Returns <code>true</code> if the collection contains only elements of the <code>type</code> argument.
 90  
                  * <p>This method uses <code>org.as3utils.ArrayUtil.containsOnlyType()</code></p>
 91  
                  * 
 92  
                  * @param          collection         the collection to check. May be <code>null</code>.
 93  
                  * @param          element         the type of the elements.
 94  
                  * @param          strict                 defines if the type of the elements should be strictly equal.
 95  
                  * @return         <code>true</code> if the collection contains only elements of the <code>type</code> argument. If the collection is <code>null</code> or empty returns <code>false</code>.
 96  
                  */
 97  
                 public static function containsOnlyType(collection:ICollection, type:*, strict:Boolean = false): Boolean
 98  
                 {
 99  1
                         if(!collection || collection.isEmpty()) return false;
 100  
                         
 101  1
                         var array:Array = collection.toArray();
 102  1
                         return ArrayUtil.containsOnlyType(array, type, strict);
 103  
                 }
 104  
                 
 105  
                 /**
 106  
                  * Performs an arbitrary, specific evaluation of equality between the two arguments.
 107  
                  * If one of the collections or both collections are <code>null</code> it will be returned <code>false</code>.
 108  
                  * <p>Two different objects are considered equal if:</p>
 109  
                  * <p>
 110  
                  * <ul><li>object A and object B are instances of the same class (i.e. if they have <b>exactly</b> the same type)</li>
 111  
                  * <li>object A contains all elements of object B</li>
 112  
                  * <li>object B contains all elements of object A</li>
 113  
                  * <li>elements have exactly the same order</li>
 114  
                  * </ul></p>
 115  
                  * <p>This implementation <b>takes care</b> of the order of the elements in the collections.
 116  
                  * So, for two collections are equal the order of elements returned by the iterator object must be equal.</p>
 117  
                  * 
 118  
                  * @param          collection1         the first collection.
 119  
                  * @param          collection2         the second collection.
 120  
                  * @return         <code>true</code> if the arbitrary evaluation considers the objects equal.
 121  
                  */
 122  
                 public static function equalConsideringOrder(collection1:ICollection, collection2:ICollection): Boolean
 123  
                 {
 124  1
                         if (!collection1 || !collection2) return false;
 125  1
                         if (collection1 == collection2) return true;
 126  
                         
 127  1
                         if (!ReflectionUtil.classPathEquals(collection1, collection2)) return false;
 128  1
                         if (collection1.size() != collection2.size()) return false;
 129  
                         
 130  1
                         var itC1:IIterator = collection1.iterator();
 131  1
                         var itC2:IIterator = collection2.iterator();
 132  
                         var o1:*;
 133  
                         var o2:*;
 134  
                         
 135  
                         //two loops for better performance
 136  1
                         if (collection1.allEquatable && collection2.allEquatable)
 137  
                         {
 138  1
                                 while (itC1.hasNext())
 139  
                                 {
 140  1
                                         o1 = itC1.next();
 141  1
                                         o2 = itC2.next();
 142  
                                         
 143  1
                                         if (!(o1 as IEquatable).equals(o2)) return false;
 144  
                                 }
 145  
                         }
 146  
                         else
 147  
                         {
 148  1
                                 while (itC1.hasNext())
 149  
                                 {
 150  1
                                         o1 = itC1.next();
 151  1
                                         o2 = itC2.next();
 152  
                                         
 153  1
                                         if (o1 != o2) return false;
 154  
                                 }
 155  
                         }
 156  
                         
 157  1
                         return true;
 158  
                 }
 159  
                 
 160  
                 /**
 161  
                  * Performs an arbitrary, specific evaluation of equality between this object and the <code>other</code> object.
 162  
                  * If one of the collections or both collections are <code>null</code> it will be returned <code>false</code>.
 163  
                  * <p>Two different objects are considered equal if:</p>
 164  
                  * <p>
 165  
                  * <ul><li>object A and object B are instances of the same class (i.e. if they have <b>exactly</b> the same type)</li>
 166  
                  * <li>object A contains all elements of object B</li>
 167  
                  * <li>object B contains all elements of object A</li>
 168  
                  * </ul></p>
 169  
                  * <p>This implementation <b>does not takes care</b> of the order of the elements in the collections.</p>
 170  
                  * 
 171  
                  * @param          collection1         the first collection.
 172  
                  * @param          collection2         the second collection.
 173  
                  * @return         <code>true</code> if the arbitrary evaluation considers the objects equal.
 174  
                  */
 175  
                 public static function equalNotConsideringOrder(collection1:ICollection, collection2:ICollection): Boolean
 176  
                 {
 177  1
                         if (!collection1 || !collection2) return false;
 178  1
                         if (collection1 == collection2) return true;
 179  
                         
 180  1
                         if (!ReflectionUtil.classPathEquals(collection1, collection2)) return false;
 181  1
                         if (collection1.size() != collection2.size()) return false;
 182  
                         
 183  
                         // because collections has same size
 184  
                         // it's not necessary to perform bidirectional validation
 185  
                         // i.e. if collection1 contains all elements of collection2
 186  
                         // consequently collection2 contains all elements of collection1
 187  1
                         return collection1.containsAll(collection2);
 188  
                 }
 189  
                 
 190  
                 /**
 191  
                  * Returns the collection object containing only objects of the type of the <code>type</code> argument.
 192  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 193  
                  * 
 194  
                  * @param          collection         the collection for filtering. May be <code>null</code>.
 195  
                  * @param          type                 the type of the objects that should remain in the collection.
 196  
                  * @return         the collection object containing only objects of the type of the <code>type</code> argument.
 197  
                  */
 198  
                 public static function filterByType(collection:ICollection, type:Class): ICollection
 199  
                 {
 200  0
                         if (!collection || collection.isEmpty()) return collection;
 201  
                         
 202  0
                         var it:IIterator = collection.iterator();
 203  
                         
 204  0
                         while (it.hasNext())
 205  
                         {
 206  0
                                 if (!ReflectionUtil.classPathEquals(it.next(), type)) it.remove();
 207  
                         }
 208  
                         
 209  0
                         return collection;
 210  
                 }
 211  
 
 212  
                 /**
 213  
                  * Returns the largest number in the specified collection.
 214  
                  * 
 215  
                  * @param          collection         the collection object to check. May be <code>null</code>.
 216  
                  * @return         the largest number in the collection object. If the collection argument is <code>null</code> or empty then the return is <code>NaN</code>.
 217  
                  */
 218  
                 public static function maxValue(collection:ICollection): Number
 219  
                 {
 220  0
                         if (!collection || collection.isEmpty()) return NaN;
 221  
                         
 222  0
                         var arr:Array = collection.toArray();
 223  0
                         return ArrayUtil.maxValue(arr);
 224  
                 }
 225  
 
 226  
                 /**
 227  
                  * Returns the index position of the largest number in the specified collection.
 228  
                  * 
 229  
                  * @param          collection         the collection object to check. May be <code>null</code>.
 230  
                  * @return         the index position of the largest number in the collection object. If the collection argument is <code>null</code> or empty then the return is -1.
 231  
                  */
 232  
                 public static function maxValueIndex(collection:ICollection): int
 233  
                 {
 234  0
                         if (!collection || collection.isEmpty()) return -1;
 235  
                         
 236  0
                         var arr:Array = collection.toArray();
 237  0
                         return ArrayUtil.maxValueIndex(arr);
 238  
                 }
 239  
 
 240  
                 /**
 241  
                  * Removes all occurances of a the given <code>element</code> argument from the given collection argument.
 242  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 243  
                  * 
 244  
                  * @param collection
 245  
                  * @param element
 246  
                  * @return
 247  
                  */
 248  
                 public static function removeAllOccurances(collection:ICollection, element:*): ICollection
 249  
                 {
 250  0
                         if (!collection || collection.isEmpty()) return null;
 251  
                         
 252  0
                         var it:IIterator = collection.iterator();
 253  
                         
 254  0
                         while (it.hasNext())
 255  
                         {
 256  0
                                 if (it.next() == element) it.remove();
 257  
                         }
 258  
                         
 259  0
                         return collection;
 260  
                 }
 261  
 
 262  
                 /**
 263  
                  * Removes duplicated objects.
 264  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 265  
                  * 
 266  
                  * @param          collection         the collection to remove duplicated objects.
 267  
                  * @return         the collection object without duplicated objects.
 268  
                  */
 269  
                 public static function removeDuplicate(collection:ICollection): ICollection
 270  
                 {
 271  1
                         if (!collection || collection.isEmpty()) return collection;
 272  
                         
 273  1
                         var it:IIterator = collection.iterator();
 274  
                         var e:*;
 275  
                         
 276  1
                         if (collection.allEquatable)
 277  
                         {
 278  1
                                 var list:ArrayList = new ArrayList();
 279  
                                 
 280  1
                                 while (it.hasNext())
 281  
                                 {
 282  1
                                         e = it.next();
 283  
                                         
 284  1
                                         if (list.contains(e)) it.remove();
 285  
                                         
 286  1
                                         list.add(e);
 287  
                                 }
 288  
                         }
 289  
                         else
 290  
                         {
 291  1
                                 var arr:Array = [];
 292  
                                 
 293  1
                                 while (it.hasNext())
 294  
                                 {
 295  1
                                         e = it.next();
 296  
                                         
 297  1
                                         if (arr.indexOf(e) != -1) it.remove();
 298  
                                         
 299  1
                                         arr.push(e);
 300  
                                 }
 301  
                         }
 302  
                         
 303  1
                         return collection;
 304  
                 }
 305  
 
 306  
                 /**
 307  
                  * Shuffles the position of the elements of the given <code>collection</code>.
 308  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 309  
                  * 
 310  
                  * @param          collection         the collection to shuffle. May be <code>null</code>.
 311  
                  * @return         the modified collection.
 312  
                  */
 313  
                 public static function shuffle(collection:ICollection): ICollection
 314  
                 {
 315  0
                         var arr:Array = collection.toArray();
 316  
                         
 317  0
                         ArrayUtil.shuffle(arr);
 318  
                         
 319  0
                         collection.clear();
 320  0
                         collection.addAll(new ArrayList(arr));
 321  0
                         return collection;
 322  
                 }
 323  
 
 324  
                 /**
 325  
                  * Sorts the collection of <code>String</code> objects alphabetically.
 326  
                  * <p>This method uses the <code>org.as3coreaddendum.utils.ArrayUtil.sortAlphabetically</code> method.</p>
 327  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 328  
                  * 
 329  
                  * @param          collection                 the collection to sort.
 330  
                  * @param          comparison                indicates which type of comparison will be used.
 331  
                  * @return         the sorted collection.
 332  
                  */
 333  
                 public static function sortAlphabetically(collection:ICollection, comparison:AlphabeticalComparison): ICollection
 334  
                 {
 335  0
                         var arr:Array = collection.toArray();
 336  
                         
 337  0
                         ArrayUtil.sortAlphabetically(arr, comparison);
 338  
                         
 339  0
                         collection.clear();
 340  0
                         collection.addAll(new ArrayList(arr));
 341  0
                         return collection;
 342  
                 }
 343  
 
 344  
                 /**
 345  
                  * Sorts the collection of objects alphabetically through the object's <code>property</code>.
 346  
                  * <p>This method uses the <code>org.as3coreaddendum.utils.ArrayUtil.sortAlphabeticallyByObjectProperty</code> method.</p>
 347  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 348  
                  * 
 349  
                  * @param          collection                 the collection to sort.
 350  
                  * @param          property                 the name of the property to be recovered and compared between the objects.
 351  
                  * @param          comparison                indicates which type of comparison will be used.
 352  
                  * @return         the sorted collection.
 353  
                  */
 354  
                 public static function sortAlphabeticallyByObjectProperty(collection:ICollection, property:String, comparison:AlphabeticalComparison): ICollection
 355  
                 {
 356  0
                         var arr:Array = collection.toArray();
 357  
                         
 358  0
                         ArrayUtil.sortAlphabeticallyByObjectProperty(arr, property, comparison);
 359  
                         
 360  0
                         collection.clear();
 361  0
                         collection.addAll(new ArrayList(arr));
 362  0
                         return collection;
 363  
                 }
 364  
 
 365  
                 /**
 366  
                  * Sorts the collection of <code>Number</code> objects ascending.
 367  
                  * <p>This method uses the <code>org.as3coreaddendum.utils.ArrayUtil.sortAscending</code> method.</p>
 368  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 369  
                  * 
 370  
                  * @param          collection         the collection to sort.
 371  
                  * @return         the sorted collection.
 372  
                  */
 373  
                 public static function sortAscending(collection:ICollection): ICollection
 374  
                 {
 375  0
                         var arr:Array = collection.toArray();
 376  
                         
 377  0
                         ArrayUtil.sortAscending(arr);
 378  
                         
 379  0
                         collection.clear();
 380  0
                         collection.addAll(new ArrayList(arr));
 381  0
                         return collection;
 382  
                 }
 383  
 
 384  
                 /**
 385  
                  * Sorts the collection of objects ascending through the object's property (must be a numeric value).
 386  
                  * <p>This method uses the <code>org.as3coreaddendum.utils.ArrayUtil.sortAscendingByObjectProperty</code> method.</p>
 387  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 388  
                  * 
 389  
                  * @param          collection         the collection to sort.
 390  
                  * @param          property         the name of the property to be recovered and compared between the objects.
 391  
                  * @return         the sorted collection.
 392  
                  */
 393  
                 public static function sortAscendingByObjectProperty(collection:ICollection, property:String): ICollection
 394  
                 {
 395  0
                         var arr:Array = collection.toArray();
 396  
                         
 397  0
                         ArrayUtil.sortAscendingByObjectProperty(arr, property);
 398  
                         
 399  0
                         collection.clear();
 400  0
                         collection.addAll(new ArrayList(arr));
 401  0
                         return collection;
 402  
                 }
 403  
 
 404  
                 /**
 405  
                  * Sorts the array of <code>Number</code> objects descending.
 406  
                  * <p>This method uses the <code>org.as3coreaddendum.utils.ArrayUtil.sortDescending</code> method.</p>
 407  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 408  
                  * 
 409  
                  * @param          collection         the collection to sort.
 410  
                  * @return         the sorted collection.
 411  
                  */
 412  
                 public static function sortDescending(collection:ICollection): ICollection
 413  
                 {
 414  0
                         var arr:Array = collection.toArray();
 415  
                         
 416  0
                         ArrayUtil.sortDescending(arr);
 417  
                         
 418  0
                         collection.clear();
 419  0
                         collection.addAll(new ArrayList(arr));
 420  0
                         return collection;
 421  
                 }
 422  
 
 423  
                 /**
 424  
                  * Sorts the array of objects descending through the object's property (must be a numeric value).
 425  
                  * <p>This method uses the <code>org.as3coreaddendum.utils.ArrayUtil.sortDescendingByObjectProperty</code> method.</p>
 426  
                  * <p>This method modifies the original collection. Be sure that it's not a ready-only collection.</p>
 427  
                  * 
 428  
                  * @param          collection         the collection to sort.         
 429  
                  * @param          property         the name of the property to be recovered and compared between the objects.         
 430  
                  * @return         the sorted collection.
 431  
                  */
 432  
                 public static function sortDescendingByObjectProperty(collection:ICollection, property:String): ICollection
 433  
                 {
 434  0
                         var arr:Array = collection.toArray();
 435  
                         
 436  0
                         ArrayUtil.sortDescendingByObjectProperty(arr, property);
 437  
                         
 438  0
                         collection.clear();
 439  0
                         collection.addAll(new ArrayList(arr));
 440  0
                         return collection;
 441  
                 }
 442  
                 
 443  
                 /**
 444  
                  * Returns the string representation of the <code>collection</code> argument.
 445  
                  * 
 446  
                  * @param          collection         the target collection.
 447  
                  * @return         the string representation of the target collection.
 448  
                   */
 449  
                 public static function toString(collection:ICollection): String 
 450  
                 {
 451  1
                         var s:String = "[";
 452  1
                         var it:IIterator = collection.iterator();
 453  
                         
 454  1
                         while (it.hasNext())
 455  
                         {
 456  1
                                 s += it.next();
 457  1
                                 if (it.hasNext()) s += ",";
 458  
                         }
 459  
                         
 460  1
                         s += "]";
 461  
                         
 462  1
                         return s;
 463  
                 }
 464  
 
 465  
         }
 466  
 
 467  
 }