1 |
Streams are the way data is input to, and output from, C++ programs. |
2 |
Globulation 2's stream implementation is based on C++ iostreams. This |
3 |
document assumes a basic understanding of iostreams, and documents the |
4 |
nuances of Glob2's implementation. |
5 |
|
6 |
First, some example code: |
7 |
|
8 |
BEGIN EXAMPLE |
9 |
|
10 |
#include <Fstream.h> |
11 |
#include <Sstream.h> |
12 |
|
13 |
// Put MyClass to any type of basic_ostream |
14 |
template<class Ch, class Tr> |
15 |
std::basic_ostream<Ch, Tr>& operator<<(std::basic_ostream<Ch, Tr>& out, const MyClass& m) |
16 |
{ |
17 |
return out |
18 |
<< enterSection("MyClass") |
19 |
<< title("var1") << m.var1 |
20 |
<< title("var2") << m.var2 |
21 |
// ... |
22 |
<< leaveSection(); |
23 |
} |
24 |
|
25 |
// Get MyClass from any type of basic_istream |
26 |
template<class Ch, class Tr> |
27 |
std::basic_ostream<Ch, Tr>& MyClass::operator>>(std::basic_istream<Ch, Tr>& in, const MyClass& m) |
28 |
{ |
29 |
return in |
30 |
>> enterSection("MyClass") |
31 |
>> title("var1") >> m.var1 |
32 |
>> title("var2") >> m.var2 |
33 |
// ... |
34 |
>> leaveSection(); |
35 |
} |
36 |
|
37 |
MyClass foo, bar; |
38 |
|
39 |
obfstream binaryOutput("BinaryFile.txt", std::ios::binary); |
40 |
binaryOutput << foo << bar; |
41 |
|
42 |
itstringstream textInput("var1\nvar2\netc.\n"); |
43 |
textInput >> foo >> bar; |
44 |
|
45 |
std::cin >> foo; |
46 |
|
47 |
if (errorCondition) |
48 |
debugOut(MyClass) << bar; |
49 |
|
50 |
END EXAMPLE |
51 |
|
52 |
In case you haven't delved that deeply into the internals of the STL, |
53 |
the normal "istream", "ostream" and "iostream" classes are special |
54 |
cases of basic_istream, basic_ostream and basic_iostream. All the |
55 |
classes in the basic_stream family work in the normal way, but have |
56 |
important internal differences - for example, they might be based on |
57 |
wide characters. With the template definition in the above examples, |
58 |
you can write a single function that accepts any type of basic_stream. |
59 |
|
60 |
Globulation 2's stream classes belong to the basic_stream family, and |
61 |
they're designed so that you *shouldn't* need to know any more than |
62 |
that about them. If you find your code misbehaving when faced with a |
63 |
Glob2 stream, but accepting an STL stream, please report it as a bug. |
64 |
|
65 |
Globulation 2 uses three special functions to mark positions in files: |
66 |
enterSection(name) |
67 |
- marks the entry to a section in the file (these can be |
68 |
nested). For example, new instances of a class or new |
69 |
positions in a grid tend to get their own section. |
70 |
This is a template function - "name" can be any type with an |
71 |
output function specified. |
72 |
|
73 |
leaveSection() |
74 |
- exit the innermost section in the file. |
75 |
|
76 |
title(name) |
77 |
- A title for an individual variable. |
78 |
This is a template function - "name" can be any type with an |
79 |
output function specified. |
80 |
|
81 |
Although these functions can be very useful during debugging, they |
82 |
should be viewed as purely decorative - no promises are made that the |
83 |
section and title you specify will be written to, or checked against, |
84 |
the actual data in the file. |
85 |
|
86 |
Globulation 2 defines two types of stream: text and binary. Their |
87 |
classes are named after their STL equivalents: a binary output stream |
88 |
is an obstream, a text input stream is an itstream, and so on. The |
89 |
headers also mimic their STL counterparts: Istream.h, Ostream.h etc. |
90 |
|
91 |
Most Globulation 2 I/O is done with binary streams, which are written |
92 |
in an architecture-neutral way, so that you can write data to a stream |
93 |
on a PC and it will read back correctly on a Mac. |
94 |
|
95 |
Text streams are mostly used for debugging purposes - for example, if |
96 |
your code is failing mysteriously, you can save your game as a text |
97 |
file, edit it in a text editor and reload it again. The exact format |
98 |
of text streams is currently being discussed, but should be fairly |
99 |
self-explanatory. |
100 |
|
101 |
The functions enterSection(), leaveSection() and title() are treated |
102 |
differently by different types of stream: |
103 |
|
104 |
* Binary streams just ignore them |
105 |
* Text streams store them and make sure the right variable is read at |
106 |
the right time when data is being read back in |
107 |
* Ordinary output streams print the information as best they can |
108 |
* Ordinary input streams print the information to their tied output |
109 |
stream (if there is one), but don't do any checking |