1. /*
  2. * $Header: /home/cvs/jakarta-commons/primitives/src/java/org/apache/commons/collections/primitives/DoubleCollection.java,v 1.3 2003/10/16 20:49:36 scolebourne Exp $
  3. * ====================================================================
  4. * The Apache Software License, Version 1.1
  5. *
  6. * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
  7. * reserved.
  8. *
  9. * Redistribution and use in source and binary forms, with or without
  10. * modification, are permitted provided that the following conditions
  11. * are met:
  12. *
  13. * 1. Redistributions of source code must retain the above copyright
  14. * notice, this list of conditions and the following disclaimer.
  15. *
  16. * 2. Redistributions in binary form must reproduce the above copyright
  17. * notice, this list of conditions and the following disclaimer in
  18. * the documentation and/or other materials provided with the
  19. * distribution.
  20. *
  21. * 3. The end-user documentation included with the redistribution, if
  22. * any, must include the following acknowledgement:
  23. * "This product includes software developed by the
  24. * Apache Software Foundation (http://www.apache.org/)."
  25. * Alternately, this acknowledgement may appear in the software itself,
  26. * if and wherever such third-party acknowledgements normally appear.
  27. *
  28. * 4. The names "The Jakarta Project", "Commons", and "Apache Software
  29. * Foundation" must not be used to endorse or promote products derived
  30. * from this software without prior written permission. For written
  31. * permission, please contact apache@apache.org.
  32. *
  33. * 5. Products derived from this software may not be called "Apache"
  34. * nor may "Apache" appear in their names without prior written
  35. * permission of the Apache Software Foundation.
  36. *
  37. * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  38. * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  39. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  40. * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  41. * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  42. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  43. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  44. * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  45. * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  46. * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  47. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  48. * SUCH DAMAGE.
  49. * ====================================================================
  50. *
  51. * This software consists of voluntary contributions made by many
  52. * individuals on behalf of the Apache Software Foundation. For more
  53. * information on the Apache Software Foundation, please see
  54. * <http://www.apache.org/>.
  55. *
  56. */
  57. package org.apache.commons.collections.primitives;
  58. /**
  59. * A collection of <code>double</code> values.
  60. *
  61. * @see org.apache.commons.collections.primitives.adapters.DoubleCollectionCollection
  62. * @see org.apache.commons.collections.primitives.adapters.CollectionDoubleCollection
  63. *
  64. * @since Commons Primitives 1.0
  65. * @version $Revision: 1.3 $ $Date: 2003/10/16 20:49:36 $
  66. *
  67. * @author Rodney Waldhoff
  68. */
  69. public interface DoubleCollection {
  70. /**
  71. * Ensures that I contain the specified element
  72. * (optional operation). Returns <code>true</code>
  73. * iff I changed as a result of this call.
  74. * <p/>
  75. * If a collection refuses to add the specified
  76. * element for any reason other than that it already contains
  77. * the element, it <i>must</i> throw an exception (rather than
  78. * simply returning <tt>false</tt>). This preserves the invariant
  79. * that a collection always contains the specified element after
  80. * this call returns.
  81. *
  82. * @param element the value whose presence within me is to be ensured
  83. * @return <code>true</code> iff I changed as a result of this call
  84. *
  85. * @throws UnsupportedOperationException when this operation is not
  86. * supported
  87. * @throws IllegalArgumentException may be thrown if some aspect of the
  88. * specified element prevents it from being added to me
  89. */
  90. boolean add(double element);
  91. /**
  92. * {@link #add Adds} all of the elements in the
  93. * specified collection to me (optional operation).
  94. *
  95. * @param c the collection of elements whose presence within me is to
  96. * be ensured
  97. * @return <code>true</code> iff I changed as a result of this call
  98. *
  99. * @throws UnsupportedOperationException when this operation is not
  100. * supported
  101. * @throws IllegalArgumentException may be thrown if some aspect of some
  102. * specified element prevents it from being added to me
  103. */
  104. boolean addAll(DoubleCollection c);
  105. /**
  106. * Removes all my elements (optional operation).
  107. * I will be {@link #isEmpty empty} after this
  108. * method successfully returns.
  109. *
  110. * @throws UnsupportedOperationException when this operation is not
  111. * supported
  112. */
  113. void clear();
  114. /**
  115. * Returns <code>true</code> iff I contain
  116. * the specified element.
  117. *
  118. * @param element the value whose presence within me is to be tested
  119. * @return <code>true</code> iff I contain the specified element
  120. */
  121. boolean contains(double element);
  122. /**
  123. * Returns <code>true</code> iff I {@link #contains contain}
  124. * all of the elements in the given collection.
  125. *
  126. * @param c the collection of elements whose presence within me is to
  127. * be tested
  128. * @return <code>true</code> iff I contain the all the specified elements
  129. */
  130. boolean containsAll(DoubleCollection c);
  131. /**
  132. * Returns <code>true</code> iff I contain no elements.
  133. * @return <code>true</code> iff I contain no elements.
  134. */
  135. boolean isEmpty();
  136. /**
  137. * Returns an {@link DoubleIterator iterator} over all my elements.
  138. * This base interface places no constraints on the order
  139. * in which the elements are returned by the returned iterator.
  140. * @return an {@link DoubleIterator iterator} over all my elements.
  141. */
  142. DoubleIterator iterator();
  143. /**
  144. * Removes all of my elements that are contained in the
  145. * specified collection (optional operation).
  146. * The behavior of this method is unspecified if
  147. * the given collection is modified while this method
  148. * is executing. Note that this includes the case
  149. * in which the given collection is this collection,
  150. * and it is not empty.
  151. *
  152. * @param c the collection of elements to remove
  153. * @return <code>true</code> iff I contained the at least one of the
  154. * specified elements, in other words, returns <code>true</code>
  155. * iff I changed as a result of this call
  156. *
  157. * @throws UnsupportedOperationException when this operation is not
  158. * supported
  159. */
  160. boolean removeAll(DoubleCollection c);
  161. /**
  162. * Removes a single occurrence of the specified element
  163. * (optional operation).
  164. *
  165. * @param element the element to remove, if present
  166. * @return <code>true</code> iff I contained the specified element,
  167. * in other words, iff I changed as a result of this call
  168. *
  169. * @throws UnsupportedOperationException when this operation is not
  170. * supported
  171. */
  172. boolean removeElement(double element);
  173. /**
  174. * Removes all of my elements that are <i>not</i> contained in the
  175. * specified collection (optional operation).
  176. * (In other words, retains <i>only</i> my elements that are
  177. * contained in the specified collection.)
  178. * The behavior of this method is unspecified if
  179. * the given collection is modified while this method
  180. * is executing.
  181. *
  182. * @param c the collection of elements to retain
  183. * @return <code>true</code> iff I changed as a result
  184. * of this call
  185. *
  186. * @throws UnsupportedOperationException when this operation is not
  187. * supported
  188. */
  189. boolean retainAll(DoubleCollection c);
  190. /**
  191. * Returns the number of elements I contain.
  192. * @return the number of elements I contain
  193. */
  194. int size();
  195. /**
  196. * Returns an array containing all of my elements.
  197. * The length of the returned array will be equal
  198. * to my {@link #size size}.
  199. * <p/>
  200. * The returned array will be independent of me,
  201. * so that callers may modify that
  202. * returned array without modifying this collection.
  203. * <p/>
  204. * When I guarantee the order in which
  205. * elements are returned by an {@link #iterator iterator},
  206. * the returned array will contain elements in the
  207. * same order.
  208. *
  209. * @return an array containing all my elements
  210. */
  211. double[] toArray();
  212. /**
  213. * Returns an array containing all of my elements,
  214. * using the given array if it is large
  215. * enough. When the length of the given array is
  216. * larger than the number of elements I contain,
  217. * values outside of my range will be unchanged.
  218. * <p/>
  219. * The returned array will be independent of me,
  220. * so that callers may modify that
  221. * returned array without modifying this collection.
  222. * <p/>
  223. * When I guarantee the order in which
  224. * elements are returned by an {@link #iterator iterator},
  225. * the returned array will contain elements in the
  226. * same order.
  227. *
  228. * @param a an array that may be used to contain the elements
  229. * @return an array containing all my elements
  230. */
  231. double[] toArray(double[] a);
  232. }