Coverage Report - org.as3collections.ICollection
 
Classes in this File Line Coverage Branch Coverage Complexity
ICollection
0%
0/1
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  0
 package org.as3collections
 31  
 {
 32  
         import org.as3collections.IIterable;
 33  
         import org.as3coreaddendum.system.ICloneable;
 34  
         import org.as3coreaddendum.system.IEquatable;
 35  
 
 36  
         /**
 37  
          * The root interface in the <em>collection hierarchy</em>.
 38  
          * A collection represents a group of objects, known as its <em>elements</em>.
 39  
          * <p>Some collections allow duplicate elements and others do not. Some are ordered and others unordered.</p>
 40  
          * <p>This interface is typically used to pass collections around and manipulate them where maximum generality is desired.</p>
 41  
          * <p>The methods that modify the collection are specified to throw org.as3coreaddendum.errors.UnsupportedOperationError if the collection does not support the operation.
 42  
          * These methods are documented as "optional operation".</p>
 43  
          * <p>This documentation is partially based in the <em>Java Collections Framework</em> JavaDoc documentation.
 44  
          * For further information see <a href="http://download.oracle.com/javase/6/docs/technotes/guides/collections/index.html" target="_blank">Java Collections Framework</a></p>
 45  
          * 
 46  
          * @see         org.as3collections.AbstractArrayCollection AbstractArrayCollection
 47  
          * @see         org.as3collections.IIterable IIterable
 48  
          * @see         org.as3collections.IList IList
 49  
          * @see         http://as3coreaddendum.org/en-us/documentation/asdoc/org/as3coreaddendum/system/IEquatable.html        org.as3coreaddendum.system.IEquatable
 50  
          * @see         http://as3coreaddendum.org/en-us/documentation/asdoc/org/as3coreaddendum/system/ICloneable.html        org.as3coreaddendum.system.ICloneable
 51  
          * @author Flávio Silva
 52  
          */
 53  
         public interface ICollection extends IIterable, ICloneable, IEquatable
 54  
         {
 55  
                 /**
 56  
                  * Indicates whether all elements in this collection implement the interface <code>org.as3coreaddendum.system.IEquatable</code>.
 57  
                  */
 58  
                 function get allEquatable(): Boolean;
 59  
 
 60  
                 /**
 61  
                  * Ensures that this collection contains the specified element (optional operation). 
 62  
                  * <p>Collections that support this operation may place limitations on what elements may be added to this collection.
 63  
                  * In particular, some collections will refuse to add <code>null</code> elements, and others will impose restrictions on the type of elements that may be added.
 64  
                  * Collection classes should clearly specify in their documentation any restrictions on what elements may be added.</p>
 65  
                  * <p>If a collection refuses to add a particular element for any reason other than that it already contains the element, it <em>must</em> throw an error (rather than returning <code>false</code>).
 66  
                  * This preserves the invariant that a collection always contains the specified element after this call returns.</p>
 67  
                  * 
 68  
                  * @param          element         the element to be added.
 69  
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>add</code> operation is not supported by this collection.
 70  
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the class of the specified element prevents it from being added to this collection.
 71  
                  * @throws         ArgumentError                                                                                           if the specified element is <code>null</code> and this collection does not permit <code>null</code> elements.
 72  
                  * @return         <code>true</code> if this collection changed as a result of the call. Returns <code>false</code> if this collection does not permit duplicates and already contains the specified element.
 73  
                  */
 74  
                 function add(element:*): Boolean;
 75  
 
 76  
                 /**
 77  
                  * Adds all of the elements in the specified collection to this collection (optional operation).
 78  
                  * 
 79  
                  * @param          collection         collection containing elements to be added to this collection.
 80  
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>addAll</code> operation is not supported by this collection.
 81  
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the class of an element of the specified collection prevents it from being added to this collection.
 82  
                  * @throws         ArgumentError                                                                                           if the specified collection contains a <code>null</code> element and this collection does not permit <code>null</code> elements, or if the specified collection is <code>null</code>. 
 83  
                  * @return         <code>true</code> if this collection changed as a result of the call.
 84  
                  */
 85  
                 function addAll(collection:ICollection): Boolean;
 86  
 
 87  
                 /**
 88  
                  * Removes all of the elements from this collection (optional operation).
 89  
                  * The collection will be empty after this method returns.
 90  
                  * 
 91  
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>clear</code> operation is not supported by this collection.
 92  
                  */
 93  
                 function clear(): void;
 94  
 
 95  
                 /**
 96  
                  * Returns <code>true</code> if this collection contains the specified object.
 97  
                  * 
 98  
                  * @param          o         object whose presence in this collection is to be tested.
 99  
                  * @throws         org.as3coreaddendum.errors.ClassCastError                  if the type of the specified object is incompatible with this collection (optional).
 100  
                  * @throws         ArgumentError          if the specified object is <code>null</code> and this collection does not permit <code>null</code> elements (optional).
 101  
                  * @return         <code>true</code> if this collection contains the specified object.
 102  
                  */
 103  
                 function contains(o:*): Boolean;
 104  
 
 105  
                 /**
 106  
                  * Returns <code>true</code> if this collection contains all of the elements in the specified collection. 
 107  
                  * 
 108  
                  * @param          collection         the collection to be checked for containment in this collection.
 109  
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the types of one or more elements in the specified collection are incompatible with this collection (optional).
 110  
                  * @throws         ArgumentError                           if the specified collection contains one or more <code>null</code> elements and this collection does not permit <code>null</code> elements (optional), or if the specified collection is <code>null</code>.
 111  
                  * @return         <code>true</code> if this collection contains all of the elements in the specified collection.
 112  
                  */
 113  
                 function containsAll(collection:ICollection): Boolean;
 114  
 
 115  
                 /**
 116  
                  * Returns <code>true</code> if this collection contains no elements.
 117  
                  * 
 118  
                  * @return         <code>true</code> if this collection contains no elements.
 119  
                   */
 120  
                 function isEmpty(): Boolean;
 121  
 
 122  
                 /**
 123  
                  * Removes a single instance (only one occurrence) of the specified object from this collection, if it is present (optional operation).
 124  
                  * 
 125  
                  * @param          o         the object to be removed from this collection, if present.
 126  
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>remove</code> operation is not supported by this collection.
 127  
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the type of the specified object is incompatible with this collection (optional).
 128  
                  * @throws         ArgumentError                                                                                           if the specified object is <code>null</code> and this collection does not permit <code>null</code> elements (optional).
 129  
                  * @return         <code>true</code> if an object was removed as a result of this call.
 130  
                  * @see         org.as3collections.utils.CollectionUtil#removeAllOccurances()         CollectionUtil.removeAllOccurances()
 131  
                  */
 132  
                 function remove(o:*): Boolean;
 133  
 
 134  
                 /**
 135  
                  * Removes all elements of this collection that are also contained in the specified collection (optional operation).
 136  
                  * After this call returns, this collection will contain no elements in common with the specified collection.
 137  
                  * 
 138  
                  * @param          collection         the collection containing elements to be removed from this collection.
 139  
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>removeAll</code> operation is not supported by this collection.
 140  
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the types of one or more elements in this collection are incompatible with the specified collection (optional).
 141  
                  * @throws         ArgumentError                                                                                           if the specified collection contains a <code>null</code> element and this collection does not permit <code>null</code> elements (optional), or if the specified collection is <code>null</code>.
 142  
                  * @return         <code>true</code> if this collection has changed as a result of the call.
 143  
                  */
 144  
                 function removeAll(collection:ICollection): Boolean;
 145  
 
 146  
                 /**
 147  
                  * Retains only the elements in this collection that are contained in the specified collection (optional operation).
 148  
                  * In other words, removes from this collection all of its elements that are not contained in the specified collection.
 149  
                  * 
 150  
                  * @param          collection         the collection containing elements to be retained in this collection.
 151  
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>retainAll</code> operation is not supported by this collection.
 152  
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the types of one or more elements in this collection are incompatible with the specified collection (optional).
 153  
                  * @throws         ArgumentError                                                                                           if the specified collection contains a <code>null</code> element and this collection does not permit <code>null</code> elements (optional), or if the specified collection is <code>null</code>.
 154  
                  * @return         <code>true</code> if this collection changed as a result of the call.         
 155  
                  */
 156  
                 function retainAll(collection:ICollection): Boolean;
 157  
 
 158  
                 /**
 159  
                  * Returns the number of elements in this collection.
 160  
                  * 
 161  
                  * @return         the number of elements in this collection.
 162  
                   */
 163  
                 function size(): int;
 164  
 
 165  
                 /**
 166  
                  * Returns an array containing all of the elements in this collection.
 167  
                  * <p>If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.</p>
 168  
                  * <p>The returned array will be "safe" in that no references to it are maintained by this collection.
 169  
                  * (In other words, this method must allocate a new array even if this collection is backed by an array).
 170  
                  * The caller is thus free to modify the returned array.</p>
 171  
                  * 
 172  
                  * @return         a new array object containing all of the elements in this collection.
 173  
                   */
 174  
                 function toArray(): Array;
 175  
         }
 176  
 
 177  
 }