Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8175371

java.util.RandomAccess API documentation incorrect

    Details

    • Type: Bug
    • Status: Closed
    • Priority: P4
    • Resolution: Not an Issue
    • Affects Version/s: 8
    • Fix Version/s: None
    • Component/s: core-libs

      Description

      A DESCRIPTION OF THE PROBLEM :
      The following description in the API documentation of java.util.RandomAccess is incorrect since Iterator implementation internally is optimized based on actual type of the collection implementation :

      As a rule of thumb, a List implementation should implement this interface if, for typical instances of the class, this loop:
           for (int i=0, n=list.size(); i < n; i++)
               list.get(i);
       
      runs faster than this loop:
           for (Iterator i=list.iterator(); i.hasNext(); )
               i.next();
       

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      The above documentation is misleading and should be removed since Iterator.next() should be optimized based on the type of implementation. i.e. the Iterator implementation for a list whose type is LinkedList is different that the one whose type is ArrayList and in both cases they are optimized to return sequentially in case of LinkedList and indexed in case of ArrayList.
      ACTUAL -
      As a rule of thumb, a List implementation should implement this interface if, for typical instances of the class, this loop:
           for (int i=0, n=list.size(); i < n; i++)
               list.get(i);
       
      runs faster than this loop:
           for (Iterator i=list.iterator(); i.hasNext(); )
               i.next();


      URL OF FAULTY DOCUMENTATION :
      https://docs.oracle.com/javase/8/docs/api/java/util/RandomAccess.html

        Attachments

          Activity

            People

            • Assignee:
              smarks Stuart Marks
              Reporter:
              webbuggrp Webbug Group
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: