[ff-cvs] fenfire/docs/pegboard/swamp_easier_iteration--b...

[Benja Fallenstein]

CVSROOT:        /cvsroot/fenfire
Module name:    fenfire
Branch:         
Changes by:     Benja Fallenstein <address@hidden>      03/09/27 13:03:17

Modified files:
        docs/pegboard/swamp_easier_iteration--benja: peg.rst 

Log message:
        address issues

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/pegboard/swamp_easier_iteration--benja/peg.rst.diff?tr1=1.1&tr2=1.2&r1=text&r2=text

Patches:
Index: fenfire/docs/pegboard/swamp_easier_iteration--benja/peg.rst
diff -u fenfire/docs/pegboard/swamp_easier_iteration--benja/peg.rst:1.1 
fenfire/docs/pegboard/swamp_easier_iteration--benja/peg.rst:1.2
--- fenfire/docs/pegboard/swamp_easier_iteration--benja/peg.rst:1.1     Mon Sep 
22 02:04:43 2003
+++ fenfire/docs/pegboard/swamp_easier_iteration--benja/peg.rst Sat Sep 27 
13:03:17 2003
@@ -22,19 +22,36 @@
 at each iteration step (RDF subject, predicate, and object).
 
 This would be returned by the old ``findN_XXX()`` or the proposed
-``get()`` methods (see other PEG).
+``find()`` methods (see other PEG).
 
-.. Issues
-   ======
+
+Issues
+======
+
+- Name for the ``Iterator``-like thing? Should it be
+  ``Triples`` for short, or ``TripleIter`` for clarity?
+
+  RESOLVED: Clarity. ``TripleIter`` isn't too long.
+
+- What should be the names of the fields of ``TripleIter``,
+  which contain the subject, predicate, and object
+  of the current triple?
+
+  RESOLVED: ``subj``, ``pred``, and ``obj``: Long enough
+  to be descriptive, but not as long as the full names
+  (``subject`` etc.). I prefer ``sub``, ``pred``, ``ob``
+  for pronouncability, but we compromised on the above--
+  Tuomas dislikes ``sub`` and ``ob`` because they are
+  prefixes in English (``subordinate``, ``obstinate``).
 
 
 Changes
 =======
 
-We shall use an iterator-like object, ``Triples``, with the
+We shall use an iterator-like object, ``TripleIter``, with the
 following API::
 
-    Object sub, pred, ob;
+    Object subj, pred, obj;
 
 (These are ``null`` when the object hasn't been
 initialized, i.e., ``next()`` hasn't been called yet.)
@@ -45,14 +62,14 @@
     /** Whether there are any more triples to iterate through. */
     boolean hasNext();
 
-    /** Indicate that this <code>Triples</code> object won't be
+    /** Indicate that this <code>TripleIter</code> object won't be
      *  used any more.
      *  This shall only be called by the code that has requested
      *  this object from <code>ConstGraph</code> (through 
      *  <code>.get()</code>). It's purpose is to tell the
      *  <code>ConstGraph</code> that it can be re-used for the
      *  next <code>get()</code>; <code>ConstGraph</code> can then
-     *  cache <code>Triples</code> objects, making life easier
+     *  cache <code>TripleIter</code> objects, making life easier
      *  for the garbage collector.
      *  <p>
      *  Calling this method is not obligatory. (If you don't,
@@ -73,21 +90,25 @@
 The purpose of ``loop()`` is to enable the common loop
 pattern, ::
 
-    for(Triples t = graph.get(...); t.loop();) {
+    for(TripleIter i = graph.find(...); i.loop();) {
         // ...
     }
 
 which would otherwise have to be written as::
 
-    Triples t;
-    for(t = graph.get(...); t.hasNext(); t.next()) {
+    TripleIter i;
+    for(i = graph.find(...); i.hasNext(); i.next()) {
         // ...
     }
-    t.free();
+    i.free();
 
-This isn't just harder to read, it also scopes ``t``
-wrongly. With the ``loop()`` pattern, the scope of ``t``
+This isn't just harder to read, it also scopes ``i``
+wrongly. With the ``loop()`` pattern, the scope of ``i``
 is the body of the loop, which is exactly the code
 executed before ``free()`` is called.
+
+(This will be expressed in ``TripleIter``'s javadoc.)
+
+\- Benja