neaten

c/containers/lrec.h

@@ -97,6 +97,23 @@ lrec_t* lrec_csvlite_alloc(char* data_line);
 lrec_t* lrec_csv_alloc(char* data_line);
 lrec_t* lrec_xtab_alloc(slls_t* pxtab_lines);
 
+// The only difference between lrec_put and lrec_prepend is that the latter
+// adds to the end of the record, while the former adds to the beginning.
+//
+// For both, the key/value respectively will be freed by lrec_free if the
+// corresponding bits are set in the free_flags.
+//
+// * If a string literal or other non-allocated pointer (e.g. mmapped memory
+//   from a file reader) is passed in, the free flag should not be set.
+//
+// * If dynamically allocated pointers are passed in, then either:
+//
+//   o The respective free_flag(s) should be set and the caller should be sure
+//     not to also free (else, there will be heap corruption due to
+//     double-free), or
+//
+//   o The respective free_flag(s) should not be set and the caller should
+//     free the memory (else, there will be a memory leak).
 void  lrec_put(lrec_t* prec, char* key, char* value, char free_flags);
 void  lrec_prepend(lrec_t* prec, char* key, char* value, char free_flags);
 

c/containers/rslls.h

@@ -8,8 +8,22 @@
 // of fields (say N), so using slls, the CSV reader would be allocating and
 // freeing N nodes on every line. Mingled in with other mallocs and frees, this
 // results in needless heap fragmentation. Here, by contrast, as a performance
-// optimization, the CSV reader can keep and reuse an N-node list, only
+// optimization, the CSV reader can keep and reuse the nodes of a list, only
 // changing the value-pointers on each CSV line.
+//
+// This means that while an slls iteration looks like
+//
+//   for (sllse_t* pe = plist->phead; pe != NULL; pe = pe->pnext) {
+//     ...
+//   }
+//
+// an rslls iteration must also check length:
+//
+//   int i = 0;
+//   for (rsllse_t* pe = plist->phead; i < plist->length && pe != NULL; pe = pe->pnext, i++) {
+//     ...
+//   }
+//
 // ================================================================
 
 #ifndef RSLLS_H

c/todo.txt

@@ -24,7 +24,6 @@ TOP OF LIST
   - EOF_STRIDX <-> p>=e in mmap-csv reader
   - mainly xxxes
   - look for others
-  - cmt i<n needed in rslls iterator, at the .h
 
 * compressed I/O:
   - libs ...
@@ -42,8 +41,6 @@ NEATEN:
 
 * in mmap-csv, try harder to not use the psb even in the dquoted case
 * big thick warning in lrec.h about the semantics
-* cmt the csv readers x 2 re free-flags handoffs
-* char[] -> int[] for parser delimiters and full int EOF
 
 ----------------------------------------------------------------
 COOKBOOK/FAQ/ETC.: