Issue 96 in google-collections: Lists.transform() documentation unclear on reversibility
codesite...@google.com
http://code.google.com/p/google-collections/issues/detail?id=96
New issue report by dovwas:
I believe the javadoc for Lists.transform() to contains a subtly
misleading statement. It states:
------------------------------------------------------
Returns a list that applies function to each element of fromList. The
returned list is a transformed view of fromList; changes to fromList will
be reflected in the returned list and vice versa.
Since functions are not reversible, the transform is one-way and new items
cannot be stored in the returned list. The add, addAll and set methods are
unsupported in the returned list.
....
------------------------------------------------------
The first paragraph says "changes to fromList will be reflected in the
returned list *and vice versa*". To me "vice-versa" indicates complete and
symmetric reflection, that any changes in one list will be reflected in
the other. As the next paragraph makes clear, this is not true for the
case of changing the contents of the returned list, which cannot be
reverse-transformed back into the fromList.
I think a clearer description would be to state something like:
------------------------------------------------------
Returns a list that applies function to each element of fromList. The
returned list is a transformed view of fromList; removing elements from
the fromList will be reflected in the returned list and vice versa. Any
other changes to the fromList will be reflected in the returned list, but
since functions are not reversible, adding or replacing elements on the
returned list is not supported so the add, addAll and set methods are
unsupported on the returned list.
------------------------------------------------------
Issue attributes:
Status: New
Owner: ----
Labels: Type-Defect Priority-Medium
--
You received this message because you are listed in the owner
or CC fields of this issue, or because you starred this issue.
You may adjust your issue notification preferences at:
http://code.google.com/hosting/settings
codesite...@google.com
http://code.google.com/p/google-collections/issues/detail?id=96
Comment #1 by jared.l.levy:
Thanks for the suggestion, but I prefer the existing phrasing. It resembles
the
analogous Javadoc of JDK methods like Map.keySet(), an excellent standard
to follow:
"Returns a Set view of the keys contained in this map. The set is backed by
the map,
so changes to the map are reflected in the set, and vice-versa. If the map
is
modified while an iteration over the set is in progress (except through the
iterator's own remove operation), the results of the iteration are
undefined. The set
supports element removal, which removes the corresponding mapping from the
map, via
the Iterator.remove, Set.remove, removeAll, retainAll, and clear
operations. It does
not support the add or addAll operations."
Issue attribute updates:
Status: WontFix