libdeng2|Reader: Added a convenient method for reading a line of text

The readLine() methods reads a line of text. It is useful when dealing
with files whose content is in UTF-8 encoding.

Also added atEnd(), which determines if a reader has reached the end
of the source data.

doomsday/libdeng2/include/de/data/reader.h

@@ -166,20 +166,45 @@ class DENG2_PUBLIC Reader
     Reader &operator >> (IReadable &readable);
 
     /**
-     * Reads bytes from the source buffer until a specified delimiter
-     * value is encountered. The delimiter is included as part of
-     * the read data.
+     * Reads bytes from the source buffer until a specified delimiter value is
+     * encountered. The delimiter is included as part of the read data. The end
+     * of the source data is also considered a valid delimiter; no exception
+     * will be thrown if the source data ends.
      *
      * @param byteArray  Destination buffer.
      * @param delimiter  Delimiter value.
      */
     Reader &readUntil(IByteArray &byteArray, IByteArray::Byte delimiter = 0);
 
+    /**
+     * Reads a line of text ending in a '\n' character. The source data is
+     * expected to be UTF-8 encoded text. All carriage returns ('\r') are
+     * removed from the string.
+     *
+     * @param string  The read line is returned here. It includes the
+     *                terminating newline character.
+     */
+    Reader &readLine(String &string);
+
+    /**
+     * Equivalent to readLine(String), but returns the read string.
+     */
+    String readLine();
+
     /**
      * Returns the source byte array of the reader.
      */
     IByteArray const *source() const;
 
+    /**
+     * Determines if the reader's position is at the end of the source data;
+     * i.e., there is nothing more to read, and attempting to do so would
+     * produce an exception.
+     *
+     * @return @c true, iff at end of source.
+     */
+    bool atEnd() const;
+
     /**
      * Returns the offset used by the reader.
      */

doomsday/libdeng2/src/data/reader.cpp

@@ -180,6 +180,20 @@ struct Reader::Instance
             marking = false;
         }
     }
+
+    bool atEnd()
+    {
+        if(source)
+        {
+            return offset == source->size();
+        }
+        if(stream || constStream)
+        {
+            update();
+            return incoming.size() > 0;
+        }
+        return true;
+    }
 };
 
 Reader::Reader(const Reader &other) : d(new Instance(*other.d))
@@ -360,17 +374,43 @@ Reader &Reader::readUntil(IByteArray &byteArray, IByteArray::Byte delimiter)
     int pos = 0;
     IByteArray::Byte b = 0;
     do {
+        if(atEnd()) break;
         *this >> b;
         byteArray.set(pos++, &b, 1);
     } while(b != delimiter);
     return *this;
 }
 
+Reader &Reader::readLine(String &string)
+{
+    string.clear();
+
+    Block utf;
+    readUntil(utf, '\n');
+
+    string = String::fromUtf8(utf);
+    string.replace("\r", ""); // strip carriage returns
+
+    return *this;
+}
+
+String Reader::readLine()
+{
+    String s;
+    readLine(s);
+    return s;
+}
+
 IByteArray const *Reader::source() const
 {
     return d->source;
 }
 
+bool Reader::atEnd() const
+{
+    return d->atEnd();
+}
+
 IByteArray::Offset Reader::offset() const
 {
     return d->offset;