Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 128 lines (114 sloc) 5.496 kb
14a631a @odersky massive new collections checkin.
odersky authored
1 /* __ *\
2 ** ________ ___ / / ___ Scala API **
807dbe5 @heathermiller Brings all copyrights (in comments) up-to-date, from 2011/12 to 2013
heathermiller authored
3 ** / __/ __// _ | / / / _ | (c) 2003-2013, LAMP/EPFL **
14a631a @odersky massive new collections checkin.
odersky authored
4 ** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ **
5 ** /____/\___/_/ |_/____/_/ | | **
6 ** |/ **
7 \* */
8
9
ea0d891 @paulp More relative path elimination.
paulp authored
10 package scala
11 package collection
4a727f3 @odersky Collections refactoring.
odersky authored
12 package mutable
13
14 import generic._
14a631a @odersky massive new collections checkin.
odersky authored
15
16 /** The base trait of all builders.
53ed9b9 added headers, svn keywords, updated pilib exam...
michelou authored
17 * A builder lets one construct a collection incrementally, by adding
519214d @axel22 docs. no review
axel22 authored
18 * elements to the builder with `+=` and then converting to the required
53ed9b9 added headers, svn keywords, updated pilib exam...
michelou authored
19 * collection type with `result`.
f7ba972 add @since annotations
stepancheg authored
20 *
cb1c0cf @odersky lost of documentation and some small adjustment...
odersky authored
21 * @tparam Elem the type of elements that get added to the builder.
22 * @tparam To the type of collection that it produced.
23 *
f7ba972 add @since annotations
stepancheg authored
24 * @since 2.8
14a631a @odersky massive new collections checkin.
odersky authored
25 */
931d2d4 @odersky Removed redundant type parameter for class Buil...
odersky authored
26 trait Builder[-Elem, +To] extends Growable[Elem] {
14a631a @odersky massive new collections checkin.
odersky authored
27
28 /** Adds a single element to the builder.
cb1c0cf @odersky lost of documentation and some small adjustment...
odersky authored
29 * @param elem the element to be added.
30 * @return the builder itself.
14a631a @odersky massive new collections checkin.
odersky authored
31 */
ca3d31e @odersky separated mutable and immutable maps
odersky authored
32 def +=(elem: Elem): this.type
14a631a @odersky massive new collections checkin.
odersky authored
33
cb1c0cf @odersky lost of documentation and some small adjustment...
odersky authored
34 /** Clears the contents of this builder.
35 * After execution of this method the builder will contain no elements.
14a631a @odersky massive new collections checkin.
odersky authored
36 */
37 def clear()
38
cb1c0cf @odersky lost of documentation and some small adjustment...
odersky authored
39 /** Produces a collection from the added elements.
40 * The builder's contents are undefined after this operation.
41 * @return a collection containing the elements added to this builder.
14a631a @odersky massive new collections checkin.
odersky authored
42 */
43 def result(): To
44
cb1c0cf @odersky lost of documentation and some small adjustment...
odersky authored
45 /** Gives a hint how many elements are expected to be added
46 * when the next `result` is called. Some builder classes
47 * will optimize their representation based on the hint. However,
48 * builder implementations are still required to work correctly even if the hint is
49 * wrong, i.e. a different number of elements is added.
50 *
6441087 Fixed a number of faulty Scaladoc comments in l...
Gilles Dubochet authored
51 * @param size the hint how many elements will be added.
14a631a @odersky massive new collections checkin.
odersky authored
52 */
53 def sizeHint(size: Int) {}
54
bfb4924 @odersky Added sizeHints to operations where it made sense.
odersky authored
55 /** Gives a hint that one expects the `result` of this builder
56 * to have the same size as the given collection, plus some delta. This will
57 * provide a hint only if the collection is known to have a cheap
3bfd818 @paulp This commit is about not calling .length or .si...
paulp authored
58 * `size` method. Currently this is assumed to be the case if and only if
bfb4924 @odersky Added sizeHints to operations where it made sense.
odersky authored
59 * the collection is of type `IndexedSeqLike`.
60 * Some builder classes
61 * will optimize their representation based on the hint. However,
62 * builder implementations are still required to work correctly even if the hint is
63 * wrong, i.e. a different number of elements is added.
64 *
65 * @param coll the collection which serves as a hint for the result's size.
df9f470 @gkossakowski Attempts to improve inlining behavior for map, flatMap.
gkossakowski authored
66 */
67 def sizeHint(coll: TraversableLike[_, _]) {
68 if (coll.isInstanceOf[collection.IndexedSeqLike[_,_]]) {
69 sizeHint(coll.size)
70 }
71 }
72
73 /** Gives a hint that one expects the `result` of this builder
74 * to have the same size as the given collection, plus some delta. This will
75 * provide a hint only if the collection is known to have a cheap
76 * `size` method. Currently this is assumed to be the case if and only if
77 * the collection is of type `IndexedSeqLike`.
78 * Some builder classes
79 * will optimize their representation based on the hint. However,
80 * builder implementations are still required to work correctly even if the hint is
81 * wrong, i.e. a different number of elements is added.
82 *
83 * @param coll the collection which serves as a hint for the result's size.
bfb4924 @odersky Added sizeHints to operations where it made sense.
odersky authored
84 * @param delta a correction to add to the `coll.size` to produce the size hint.
85 */
df9f470 @gkossakowski Attempts to improve inlining behavior for map, flatMap.
gkossakowski authored
86 def sizeHint(coll: TraversableLike[_, _], delta: Int) {
f309513 @paulp A conceivably pretty bad performance bug in bui...
paulp authored
87 if (coll.isInstanceOf[collection.IndexedSeqLike[_,_]]) {
bfb4924 @odersky Added sizeHints to operations where it made sense.
odersky authored
88 sizeHint(coll.size + delta)
89 }
90 }
91
92 /** Gives a hint how many elements are expected to be added
93 * when the next `result` is called, together with an upper bound
94 * given by the size of some other collection. Some builder classes
95 * will optimize their representation based on the hint. However,
96 * builder implementations are still required to work correctly even if the hint is
97 * wrong, i.e. a different number of elements is added.
98 *
99 * @param size the hint how many elements will be added.
100 * @param boundingColl the bounding collection. If it is
101 * an IndexedSeqLike, then sizes larger
102 * than collection's size are reduced.
103 */
104 def sizeHintBounded(size: Int, boundingColl: TraversableLike[_, _]) {
f309513 @paulp A conceivably pretty bad performance bug in bui...
paulp authored
105 if (boundingColl.isInstanceOf[collection.IndexedSeqLike[_,_]])
bfb4924 @odersky Added sizeHints to operations where it made sense.
odersky authored
106 sizeHint(size min boundingColl.size)
107 }
108
cb1c0cf @odersky lost of documentation and some small adjustment...
odersky authored
109 /** Creates a new builder by applying a transformation function to
110 * the results of this builder.
111 * @param f the transformation function.
112 * @tparam NewTo the type of collection returned by `f`.
113 * @return a new builder which is the same as the current builder except
114 * that a transformation function is applied to this builder's result.
14a631a @odersky massive new collections checkin.
odersky authored
115 */
931d2d4 @odersky Removed redundant type parameter for class Buil...
odersky authored
116 def mapResult[NewTo](f: To => NewTo): Builder[Elem, NewTo] =
117 new Builder[Elem, NewTo] with Proxy {
14a631a @odersky massive new collections checkin.
odersky authored
118 val self = Builder.this
ca3d31e @odersky separated mutable and immutable maps
odersky authored
119 def +=(x: Elem): this.type = { self += x; this }
14a631a @odersky massive new collections checkin.
odersky authored
120 def clear() = self.clear()
0c8e219 @paulp TraversableOnce. Review by odersky.
paulp authored
121 override def ++=(xs: TraversableOnce[Elem]): this.type = { self ++= xs; this }
5ebbfdb @axel22 Fix for si-5577.
axel22 authored
122 override def sizeHint(size: Int) = self.sizeHint(size)
123 override def sizeHintBounded(size: Int, boundColl: TraversableLike[_, _]) = self.sizeHintBounded(size, boundColl)
14a631a @odersky massive new collections checkin.
odersky authored
124 def result: NewTo = f(self.result)
125 }
126 }
127
Something went wrong with that request. Please try again.