1//============================================================================
2//
3// SSSS tt lll lll
4// SS SS tt ll ll
5// SS tttttt eeee ll ll aaaa
6// SSSS tt ee ee ll ll aa
7// SS tt eeeeee ll ll aaaaa -- "An Atari 2600 VCS Emulator"
8// SS SS tt ee ll ll aa aa
9// SSSS ttt eeeee llll llll aaaaa
10//
11// Copyright (c) 1995-2019 by Bradford W. Mott, Stephen Anthony
12// and the Stella Team
13//
14// See the file "License.txt" for information on usage and redistribution of
15// this file, and for a DISCLAIMER OF ALL WARRANTIES.
16//============================================================================
17
18#ifndef SERIALIZER_HXX
19#define SERIALIZER_HXX
20
21#include "bspf.hxx"
22
23/**
24 This class implements a Serializer device, whereby data is serialized and
25 read from/written to a binary stream in a system-independent way. The
26 stream can be either an actual file, or an in-memory structure.
27
28 Bytes are written as characters, shorts as 2 characters (16-bits),
29 integers as 4 characters (32-bits), long integers as 8 bytes (64-bits),
30 strings are written as characters prepended by the length of the string,
31 boolean values are written using a special character pattern.
32
33 @author Stephen Anthony
34*/
35class Serializer
36{
37 public:
38 enum class Mode { ReadOnly, ReadWrite, ReadWriteTrunc };
39
40 public:
41 /**
42 Creates a new Serializer device for streaming binary data.
43
44 If a filename is provided, the stream will be to the given
45 filename. Otherwise, the stream will be in memory.
46
47 If a file is opened readonly, we can never write to it.
48
49 The valid() method must immediately be called to verify the stream
50 was correctly initialized.
51 */
52 Serializer(const string& filename, Mode m = Mode::ReadWrite);
53 Serializer();
54
55 public:
56 /**
57 Answers whether the serializer is currently initialized for reading
58 and writing.
59 */
60 explicit operator bool() const { return myStream != nullptr; }
61
62 /**
63 Resets the read/write location to the beginning of the stream.
64 */
65 void rewind();
66
67 /**
68 Returns the current write pointer location.
69 */
70 size_t size() const;
71
72 /**
73 Reads a byte value (unsigned 8-bit) from the current input stream.
74
75 @result The byte value which has been read from the stream.
76 */
77 uInt8 getByte() const;
78
79 /**
80 Reads a byte array (unsigned 8-bit) from the current input stream.
81
82 @param array The location to store the bytes read
83 @param size The size of the array (number of bytes to read)
84 */
85 void getByteArray(uInt8* array, size_t size) const;
86
87 /**
88 Reads a short value (unsigned 16-bit) from the current input stream.
89
90 @result The short value which has been read from the stream.
91 */
92 uInt16 getShort() const;
93
94 /**
95 Reads a short array (unsigned 16-bit) from the current input stream.
96
97 @param array The location to store the shorts read
98 @param size The size of the array (number of shorts to read)
99 */
100 void getShortArray(uInt16* array, size_t size) const;
101
102 /**
103 Reads an int value (unsigned 32-bit) from the current input stream.
104
105 @result The int value which has been read from the stream.
106 */
107 uInt32 getInt() const;
108
109 /**
110 Reads an integer array (unsigned 32-bit) from the current input stream.
111
112 @param array The location to store the integers read
113 @param size The size of the array (number of integers to read)
114 */
115 void getIntArray(uInt32* array, size_t size) const;
116
117 /**
118 Reads a long int value (unsigned 64-bit) from the current input stream.
119
120 @result The long int value which has been read from the stream.
121 */
122 uInt64 getLong() const;
123
124 /**
125 Reads a double value (signed 64-bit) from the current input stream.
126
127 @result The double value which has been read from the stream.
128 */
129 double getDouble() const;
130
131 /**
132 Reads a string from the current input stream.
133
134 @result The string which has been read from the stream.
135 */
136 string getString() const;
137
138 /**
139 Reads a boolean value from the current input stream.
140
141 @result The boolean value which has been read from the stream.
142 */
143 bool getBool() const;
144
145 /**
146 Writes an byte value (unsigned 8-bit) to the current output stream.
147
148 @param value The byte value to write to the output stream.
149 */
150 void putByte(uInt8 value);
151
152 /**
153 Writes a byte array (unsigned 8-bit) to the current output stream.
154
155 @param array The bytes to write
156 @param size The size of the array (number of bytes to write)
157 */
158 void putByteArray(const uInt8* array, size_t size);
159
160 /**
161 Writes a short value (unsigned 16-bit) to the current output stream.
162
163 @param value The short value to write to the output stream.
164 */
165 void putShort(uInt16 value);
166
167 /**
168 Writes a short array (unsigned 16-bit) to the current output stream.
169
170 @param array The short to write
171 @param size The size of the array (number of shorts to write)
172 */
173 void putShortArray(const uInt16* array, size_t size);
174
175 /**
176 Writes an int value (unsigned 32-bit) to the current output stream.
177
178 @param value The int value to write to the output stream.
179 */
180 void putInt(uInt32 value);
181
182 /**
183 Writes an integer array (unsigned 32-bit) to the current output stream.
184
185 @param array The integers to write
186 @param size The size of the array (number of integers to write)
187 */
188 void putIntArray(const uInt32* array, size_t size);
189
190 /**
191 Writes a long int value (unsigned 64-bit) to the current output stream.
192
193 @param value The long int value to write to the output stream.
194 */
195 void putLong(uInt64 value);
196
197 /**
198 Writes a double value (signed 64-bit) to the current output stream.
199
200 @param value The double value to write to the output stream.
201 */
202 void putDouble(double value);
203
204 /**
205 Writes a string to the current output stream.
206
207 @param str The string to write to the output stream.
208 */
209 void putString(const string& str);
210
211 /**
212 Writes a boolean value to the current output stream.
213
214 @param b The boolean value to write to the output stream.
215 */
216 void putBool(bool b);
217
218 private:
219 // The stream to send the serialized data to.
220 unique_ptr<iostream> myStream;
221
222 static constexpr uInt8 TruePattern = 0xfe, FalsePattern = 0x01;
223
224 private:
225 // Following constructors and assignment operators not supported
226 Serializer(const Serializer&) = delete;
227 Serializer(Serializer&&) = delete;
228 Serializer& operator=(const Serializer&) = delete;
229 Serializer& operator=(Serializer&&) = delete;
230};
231
232#endif
233