K P created COLLECTIONS-704:
-------------------------------
Summary: GrowthList: ambiguity in constructor argument
Key: COLLECTIONS-704
URL: https://issues.apache.org/jira/browse/COLLECTIONS-704
Project: Commons Collections
Issue Type: Improvement
Components: List
Affects Versions: 4.2, 4.0
Reporter: K P
The javadoc of constructor
{{[GrowthList|https://commons.apache.org/proper/commons-collections/apidocs/org/apache/commons/collections4/list/GrowthList.html#GrowthList-int-](int
initialSize)}}
states:
{{initialSize}} - the initial size of the ArrayList
However, this is confusing terminology: As the initialSize argument is passed
directly to the internal ArrayList constructor, this is effectively the initial
+capacity+. The +capacity+ is NOT the same as the actual list +size+. So after
this constructor is called, the actual list.size() is still 0. This is
identical to the normal ArrayList constructor's behavior of course.
However, the GrowthList javadoc is confusing by explicitly claiming this is the
"_initial size_", which may lead the reader to think that this constructor
effectively grows the initial list to an actual given size - size in the sense
the word is used everywhere else in the javadoc of this class. As opposed to
the javadoc of Java's ArrayList, where they clear use the terminology "_the
initial capacity of the list_", to avoid any confusion between the notion of
internal array capacity and the list size.
If, long ago, this GrowthList constructor was once intended to really set the
ini**tial size, then is clearly not what the code does.
However, if this never was the intention, and this was just intended to be an
initial capacity, as the normal ArrayList, then the javadoc of GrowthList
should be slightly reworded, to avoid ambiguity or misunderstanding, and make
clear this is just the initial _capacity_ of the underlying ArrayList; not the
initial _size_ of the list.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
