Tweaks to the iterator use guides for hssf

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@618690 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/src/documentation/content/xdocs/hssf/quick-guide.xml b/src/documentation/content/xdocs/hssf/quick-guide.xml
index b2f729fedc3bc6fb65db862b55ed3c75a0a57528..69850afe88920777845d608f71989228a8e8a18d 100644 (file)
--- a/src/documentation/content/xdocs/hssf/quick-guide.xml
+++ b/src/documentation/content/xdocs/hssf/quick-guide.xml
@@ -236,16 +236,51 @@
                     </source>
                 </section>
                 <anchor id="Iterator"/>
-                <section><title>Iterate over rows and cells (including Java 5 foreach loops)</title>
+                <section><title>Iterate over rows and cells</title>
                                <p>Sometimes, you'd like to just iterate over all the rows in
-                               a sheet, or all the cells in a row. If you are using Java
-                               5 or later, then this is especially handy, as it'll allow the
-                               new foreach loop support to work.</p>
+                               a sheet, or all the cells in a row. This is possible with
+                               a simple for loop.</p>
                                <p>Luckily, this is very easy. HSSFRow defines a 
                                <em>CellIterator</em> inner class to handle iterating over 
                                the cells (get one with a call to <em>row.cellIterator()</em>),
                                and HSSFSheet provides a <em>rowIterator()</em> method to
                                give an iterator over all the rows.</p>
+                               <p>(Unfortunately, due to the broken and
+                               backwards-incompatible way that Java 5 foreach loops were
+                               implemented, it isn't possible to use them on a codebase
+                               that supports Java 1.4, as POI does)</p>
+                               <source>
+       HSSFSheet sheet = wb.getSheetAt(0);
+       for (Iterator rit = sheet.rowIterator(); rit.hasNext(); ) {
+               HSSFRow row = (HSSFRow)rit.next();
+               for (Iterator cit = row.cellIterator(); cit.hasNext(); ) {
+                       HSSFCell cell = (HSSFCell)cit.next();
+                       // Do something here
+               }
+       }
+                               </source>
+                               <source>
+       HSSFSheet sheet = wb.getSheetAt(0);
+       for (Iterator&lt;HSSFRow&gt; rit = (Iterator&lt;HSSFRow&gt;)sheet.rowIterator(); rit.hasNext(); ) {
+               HSSFRow row = rit.next();
+               for (Iterator&lt;HSSFCell&gt; cit = (Iterator&lt;HSSFCell&gt;)row.cellIterator(); cit.hasNext(); ) {
+                       HSSFCell cell = cit.next();
+                       // Do something here
+               }
+       }
+                               </source>
+                </section>
+                <section><title>Iterate over rows and cells using Java 1.5 foreach loops - OOXML Branch Only</title>
+                               <p>Sometimes, you'd like to just iterate over all the rows in
+                               a sheet, or all the cells in a row. If you are using Java
+                               5 or later, then this is especially handy, as it'll allow the
+                               new foreach loop support to work.</p>
+                               <p>Luckily, this is very easy. Both HSSFSheet and HSSFRow
+                               implement <em>java.lang.Iterable</em> to allow foreach
+                               loops. For HSSFRow this allows access to the 
+                               <em>CellIterator</em> inner class to handle iterating over 
+                               the cells, and for HSSFSheet gives the 
+                               <em>rowIterator()</em> to iterator over all the rows.</p>
                                <source>
        HSSFSheet sheet = wb.getSheetAt(0);
        for (HSSFRow row : sheet.rowIterator()) {
@@ -254,6 +289,7 @@
                }
        }
                                </source>
+                               <note>This only works on the OOXML branch of POI</note>
                 </section>
                 <anchor id="TextExtraction"/>
                 <section><title>Text Extraction</title>