Merged revisions 32879,32883,32895,32899,32902-32904,32910-32912,32923-32924,32930-32931,32938,32940,32948-32949,32951,32960-32964,32966-32970,32972-32974,32976,32978,32983,32986-32990,32992,32994,33002-33004,33006-33007,33009-33010,33014,33017,33021-33023,33030,33033,33052-33053,33056-33058,33061-33064,33068,33070,33072,33075,33078-33079,33083,33086-33087,33089,33094-33096,33098-33099,33104,33108-33109,33114-33117,33120,33135-33146,33160,33162,33165,33167-33169 via svnmerge from

https://scummvm.svn.sourceforge.net/svnroot/scummvm/scummvm/trunk

svn-id: r33185

1 files changed, 27 insertions, 0 deletions

diff --git a/common/stream.h b/common/stream.h
index 313a695e82..4cf5fae114 100644
--- a/common/stream.h
+++ b/common/stream.h
@@ -304,13 +304,40 @@ public:
 	 * Read one line of text from a CR or CR/LF terminated plain text file.
 	 * This method is a rough analog of the (f)gets function.
 	 *
+	 * @bug A main difference (and flaw) in this function is that there is no
+	 * way to detect that a line exceeeds the length of the buffer.
+	 * Code which needs this should use the new readLine_NEW() method instead.
+	 *
 	 * @param buf	the buffer to store into
 	 * @param bufSize	the size of the buffer
 	 * @return a pointer to the read string, or NULL if an error occurred
+	 *
 	 * @note The line terminator (CR or CR/LF) is stripped and not inserted
 	 *       into the buffer.
 	 */
 	virtual char *readLine(char *buf, size_t bufSize);
+
+	/**
+	 * Reads at most one less than the number of characters specified
+	 * by bufSize from the and stores them in the string buf. Reading
+	 * stops when the end of a line is reached (CR, CR/LF or LF), at
+	 * end-of-file or error.  The newline, if any, is retained (CR and
+	 * CR/LF are translated to LF = 0xA = '\n').  If any characters are
+	 * read and there is no error, a `\0' character is appended to end
+	 * the string.
+	 *
+	 * Upon successful completion, return a pointer to the string. If
+	 * end-of-file occurs before any characters are read, returns NULL
+	 * and the buffer contents remain unchanged.  If an error occurs,
+	 * returns NULL and the buffer contents are indeterminate.
+	 * This method does not distinguish between end-of-file and error;
+	 * callers muse use ioFailed() or eos() to determine which occurred.
+	 *
+	 * @param buf	the buffer to store into
+	 * @param bufSize	the size of the buffer
+	 * @return a pointer to the read string, or NULL if an error occurred
+	 */
+	virtual char *readLine_NEW(char *s, size_t bufSize);
 };
 
 /**