.tutorial

git-svn-id: svn://ultimatepp.org/upp/trunk@11527 f0d560ea-af0d-0410-9eb7-867de7ffcac7

tutorial/CoreTutorial/Stream.cpp

@@ -13,8 +13,8 @@ void Stream()
 		return;
 	}
 	
-	/// The most basic operations of streams are Put and Get. Get works in the same ways as
-	/// good old C getc - it returns negative number on eof or error:
+	/// The most basic operations of streams are `Put` and `Get`. `Get` works in the same ways
+	/// as good old C getc - it returns negative number on eof or error:
 
 	String h;
 	int c;
@@ -26,28 +26,47 @@ void Stream()
 	/// but they have some unique features. U++ does not distinguish between 'text' and
 	/// 'binary' mode streams, methods are well suited to work with both in common mode.
 	
-	/// GetLine returns String of single line read (lines separator being '\n', '\r' is
+	/// `GetLine` returns `String` of single line read (lines separator being '\n', '\r' is
 	/// ignored):
 
 	in.Seek(0);
 	while(!in.IsEof())
 		DUMP(in.GetLine());
+	
+	/// `Peek` can be used to look at the next character without actually moving on to the next
+	/// one:
+	
+	in.Seek(0);
+	DDUMP((char)in.Peek());
+	DDUMP(in.GetLine());
 
-	/// Get method reads at most specified number of bytes from the stream and returns them as
-	/// String:
+	/// `Get` method reads at most specified number of bytes from the stream and returns them as
+	/// `String`:
 
 	in.Seek(0);
 	DUMP(in.Get(10));
 	
+	/// If there is not enough characters in the Stream as required by Get, everything till EOF
+	/// is returned:
 	
 	in.Seek(0);
 	DUMP(in.Get(999999).GetCount());
+	
+	/// In contrast, `GetAll` method fails when there is not enough characters in the Stream and
+	/// returns Void `String` if Stream is not in `LoadThrowing` mode:
 
 	in.Seek(0);
 	h = in.GetAll(100);
 	DUMP(h.GetCount());
+	
+	///
+	
 	h = in.GetAll(999999);
 	DUMP(h.IsVoid());
+	
+	/// In `LoadThrowing` mode, `Stream` throws `LoadingError` exception when there is problem with
+	/// input `Stream`:
+	
 	in.LoadThrowing();
 	try {
 		in.GetAll(999999);
@@ -55,8 +74,10 @@ void Stream()
 	catch(LoadingError) {
 		LOG("Loading error");
 	}
+	
+	/// Template variant of `Stream::operator<<` is using `AsString` to convert data to text:
 
-	String fn = GetHomeDirFile("test");
+	String fn = GetHomeDirFile("test.txt");
 	FileOut out(fn);
 	if(!out) {
 		LOG("Failed to open the file");
@@ -64,27 +85,39 @@ void Stream()
 	}
 	out << "Some number " << 321 << " and Point " << Point(1, 2);
 	out.Close();
+	
+	/// When writing to the `Stream`, the good way to check for errors is to write all data,
+	/// close the stream and then check for `IsError`:
+	
 	if(out.IsError()) { // check whether file was properly written
 		LOG("Error");
 		return;
 	}
 	DUMP(LoadFile(fn));
 	
+	/// `FileAppend` can be used to append data to the file:
+	
 	FileAppend out2(fn);
 	out2 << "\nSomething more";
 	out2.Close();
 	DUMP(LoadFile(fn));
 	
+	/// Important and often used type of `Stream` is `StringStream` which works with `String` as
+	/// input/output.
+	
+	/// `Stream` also provides methods to store/load primitive types, in both
+	/// little-endian and big-endian modes:
+	
 	StringStream ss;
 	ss.Put32le(0x12345678);
 	ss.Put32be(0x12345678);
-	
-	StringStream ss2(ss.GetResult());
-	DUMP(ss.Get32le());
-	DUMP(ss.Get32be());
 	DUMPHEX(ss.GetResult());
-	
-	
 
 	///
-}
+
+	StringStream ss2(ss.GetResult());
+	DUMPHEX(ss2.Get32le());
+	DUMPHEX(ss2.Get32be());
+
+	///
+}