Coverage Report

Coverage Report - org.as3collections.ICollection

Classes in this File

0/1

 ﻿/*
  * Licensed under the MIT License
  * 
  * Copyright 2010 (c) Flávio Silva, http://flsilva.com
  *
  * Permission is hereby granted, free of charge, to any person
  * obtaining a copy of this software and associated documentation
  * files (the "Software"), to deal in the Software without
  * restriction, including without limitation the rights to use,
  * copy, modify, merge, publish, distribute, sublicense, and/or sell
  * copies of the Software, and to permit persons to whom the
  * Software is furnished to do so, subject to the following
  * conditions:
  *
  * The above copyright notice and this permission notice shall be
  * included in all copies or substantial portions of the Software.
  *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  * OTHER DEALINGS IN THE SOFTWARE.
  * 
  * http://www.opensource.org/licenses/mit-license.php
  */
 
 package org.as3collections
 {
         import org.as3collections.IIterable;
         import org.as3coreaddendum.system.ICloneable;
         import org.as3coreaddendum.system.IEquatable;
 
         /**
          * The root interface in the <em>collection hierarchy</em>.
          * A collection represents a group of objects, known as its <em>elements</em>.
          * <p>Some collections allow duplicate elements and others do not. Some are ordered and others unordered.</p>
          * <p>This interface is typically used to pass collections around and manipulate them where maximum generality is desired.</p>
          * <p>The methods that modify the collection are specified to throw org.as3coreaddendum.errors.UnsupportedOperationError if the collection does not support the operation.
          * These methods are documented as "optional operation".</p>
          * <p>This documentation is partially based in the <em>Java Collections Framework</em> JavaDoc documentation.
          * 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>
          * 
          * @see         org.as3collections.AbstractArrayCollection AbstractArrayCollection
          * @see         org.as3collections.IIterable IIterable
          * @see         org.as3collections.IList IList
          * @see         http://as3coreaddendum.org/en-us/documentation/asdoc/org/as3coreaddendum/system/IEquatable.html        org.as3coreaddendum.system.IEquatable
          * @see         http://as3coreaddendum.org/en-us/documentation/asdoc/org/as3coreaddendum/system/ICloneable.html        org.as3coreaddendum.system.ICloneable
          * @author Flávio Silva
          */
         public interface ICollection extends IIterable, ICloneable, IEquatable
         {
                 /**
                  * Indicates whether all elements in this collection implement the interface <code>org.as3coreaddendum.system.IEquatable</code>.
                  */
                 function get allEquatable(): Boolean;
 
                 /**
                  * Ensures that this collection contains the specified element (optional operation). 
                  * <p>Collections that support this operation may place limitations on what elements may be added to this collection.
                  * 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.
                  * Collection classes should clearly specify in their documentation any restrictions on what elements may be added.</p>
                  * <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>).
                  * This preserves the invariant that a collection always contains the specified element after this call returns.</p>
                  * 
                  * @param          element         the element to be added.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>add</code> operation is not supported by this collection.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the class of the specified element prevents it from being added to this collection.
                  * @throws         ArgumentError                                                                                           if the specified element is <code>null</code> and this collection does not permit <code>null</code> elements.
                  * @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.
                  */
                 function add(element:*): Boolean;
 
                 /**
                  * Adds all of the elements in the specified collection to this collection (optional operation).
                  * 
                  * @param          collection         collection containing elements to be added to this collection.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>addAll</code> operation is not supported by this collection.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the class of an element of the specified collection prevents it from being added to this collection.
                  * @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>. 
                  * @return         <code>true</code> if this collection changed as a result of the call.
                  */
                 function addAll(collection:ICollection): Boolean;
 
                 /**
                  * Removes all of the elements from this collection (optional operation).
                  * The collection will be empty after this method returns.
                  * 
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>clear</code> operation is not supported by this collection.
                  */
                 function clear(): void;
 
                 /**
                  * Returns <code>true</code> if this collection contains the specified object.
                  * 
                  * @param          o         object whose presence in this collection is to be tested.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                  if the type of the specified object is incompatible with this collection (optional).
                  * @throws         ArgumentError          if the specified object is <code>null</code> and this collection does not permit <code>null</code> elements (optional).
                  * @return         <code>true</code> if this collection contains the specified object.
                  */
                 function contains(o:*): Boolean;
 
                 /**
                  * Returns <code>true</code> if this collection contains all of the elements in the specified collection. 
                  * 
                  * @param          collection         the collection to be checked for containment in this collection.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the types of one or more elements in the specified collection are incompatible with this collection (optional).
                  * @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>.
                  * @return         <code>true</code> if this collection contains all of the elements in the specified collection.
                  */
                 function containsAll(collection:ICollection): Boolean;
 
                 /**
                  * Returns <code>true</code> if this collection contains no elements.
                  * 
                  * @return         <code>true</code> if this collection contains no elements.
                   */
                 function isEmpty(): Boolean;
 
                 /**
                  * Removes a single instance (only one occurrence) of the specified object from this collection, if it is present (optional operation).
                  * 
                  * @param          o         the object to be removed from this collection, if present.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>remove</code> operation is not supported by this collection.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the type of the specified object is incompatible with this collection (optional).
                  * @throws         ArgumentError                                                                                           if the specified object is <code>null</code> and this collection does not permit <code>null</code> elements (optional).
                  * @return         <code>true</code> if an object was removed as a result of this call.
                  * @see         org.as3collections.utils.CollectionUtil#removeAllOccurances()         CollectionUtil.removeAllOccurances()
                  */
                 function remove(o:*): Boolean;
 
                 /**
                  * Removes all elements of this collection that are also contained in the specified collection (optional operation).
                  * After this call returns, this collection will contain no elements in common with the specified collection.
                  * 
                  * @param          collection         the collection containing elements to be removed from this collection.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>removeAll</code> operation is not supported by this collection.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the types of one or more elements in this collection are incompatible with the specified collection (optional).
                  * @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>.
                  * @return         <code>true</code> if this collection has changed as a result of the call.
                  */
                 function removeAll(collection:ICollection): Boolean;
 
                 /**
                  * Retains only the elements in this collection that are contained in the specified collection (optional operation).
                  * In other words, removes from this collection all of its elements that are not contained in the specified collection.
                  * 
                  * @param          collection         the collection containing elements to be retained in this collection.
                  * @throws         org.as3coreaddendum.errors.UnsupportedOperationError          if the <code>retainAll</code> operation is not supported by this collection.
                  * @throws         org.as3coreaddendum.errors.ClassCastError                                  if the types of one or more elements in this collection are incompatible with the specified collection (optional).
                  * @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>.
                  * @return         <code>true</code> if this collection changed as a result of the call.         
                  */
                 function retainAll(collection:ICollection): Boolean;
 
                 /**
                  * Returns the number of elements in this collection.
                  * 
                  * @return         the number of elements in this collection.
                   */
                 function size(): int;
 
                 /**
                  * Returns an array containing all of the elements in this collection.
                  * <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>
                  * <p>The returned array will be "safe" in that no references to it are maintained by this collection.
                  * (In other words, this method must allocate a new array even if this collection is backed by an array).
                  * The caller is thus free to modify the returned array.</p>
                  * 
                  * @return         a new array object containing all of the elements in this collection.
                   */
                 function toArray(): Array;
         }
 
 }

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		}