/[glob2]/glob2/doc/Streams.txt
ViewVC logotype

Contents of /glob2/doc/Streams.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1.2.2 - (show annotations) (download)
Sat Oct 1 14:20:33 2005 UTC (18 years, 6 months ago) by andrew_sayers
Branch: map-rewrite
Changes since 1.1.2.1: +14 -14 lines
File MIME type: text/plain
More iostream work, some bugfixes

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

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26