summaryrefslogtreecommitdiffstatshomepage
path: root/src/lib/util/ioprocsfilter.h
blob: fbe24ab46e999dfab805394296ca6d851d0b6266 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
// license:BSD-3-Clause
// copyright-holders:Vas Crabb
/***************************************************************************

    ioprocs.h

    I/O filters

***************************************************************************/
#ifndef MAME_LIB_UTIL_IOPROCSFILTER_H
#define MAME_LIB_UTIL_IOPROCSFILTER_H

#include "utilfwd.h"

#include <cstdint>
#include <cstdlib>
#include <memory>


namespace util {

/// \addtogroup ioprocs
/// \{

/// \brief Create a read stream filter that fills unused buffer space
///
/// Creates a sequential read stream filter that fills unused buffer
/// space with a specified byte value.  If a read operation does not
/// produce enough data to fill the supplied buffer, the remaining space
/// in the buffer is filled with the specified filler byte value.  Takes
/// ownership of the underlying input stream.
/// \param [in] stream Underlying stream to read from.
/// \param [in] filler Byte value to fill unused buffer space.
/// \return A pointer to a sequential read stream, or nullptr on error.
/// \sa read_stream
std::unique_ptr<read_stream> read_stream_fill(std::unique_ptr<read_stream> &&stream, std::uint8_t filler) noexcept;

/// \brief Create a random access input filter that fills unused buffer
///   space
///
/// Creates a random access input filter that fills unused buffer space
/// with a specified byte value.  If a read operation does not produce
/// enough data to fill the supplied buffer, the remaining space in the
/// buffer is filled with the specified filler byte value.  Takes
/// ownership of the underlying input sequence.
/// \param [in] stream Underlying input sequence to read from.
/// \param [in] filler Byte value to fill unused buffer space.
/// \return A pointer to a random access input sequence, or nullptr on
///   error.
/// \sa random_read
std::unique_ptr<random_read> random_read_fill(std::unique_ptr<random_read> &&stream, std::uint8_t filler) noexcept;

/// \brief Create a read stream filter that fills unused buffer space
///
/// Creates a sequential read stream filter that fills unused buffer
/// space with a specified byte value.  If a read operation does not
/// produce enough data to fill the supplied buffer, the remaining space
/// in the buffer is filled with the specified filler byte value.  Does
/// not take ownership of the underlying input stream.
/// \param [in] stream Underlying stream to read from.
/// \param [in] filler Byte value to fill unused buffer space.
/// \return A pointer to a sequential read stream, or nullptr on error.
/// \sa read_stream
std::unique_ptr<read_stream> read_stream_fill(read_stream &stream, std::uint8_t filler) noexcept;

/// \brief Create a random access input filter that fills unused buffer
///   space
///
/// Creates a random access input filter that fills unused buffer space
/// with a specified byte value.  If a read operation does not produce
/// enough data to fill the supplied buffer, the remaining space in the
/// buffer is filled with the specified filler byte value.  Does not
/// take ownership of the underlying input sequence.
/// \param [in] stream Underlying input sequence to read from.
/// \param [in] filler Byte value to fill unused buffer space.
/// \return A pointer to a random access input sequence, or nullptr on
///   error.
/// \sa random_read
std::unique_ptr<random_read> random_read_fill(random_read &stream, std::uint8_t filler) noexcept;


/// \brief Create a random access output filter that fills unwritten
///   space
///
/// Creates a random access output filter that fills unwritten space
/// with a specified byte value.  If a write operation starts beyond the
/// end of the output, the space between the end of the output and the
/// start of the written data is filled with the specified filler byte
/// value.  Takes ownership of the underlying output sequence.
/// \param [in] stream Underlying output sequence to write to.
/// \param [in] filler Byte value to fill unwritten space.
/// \return A pointer to a random access output sequence, or nullptr on
///   error.
/// \sa random_write
std::unique_ptr<random_write> random_write_fill(std::unique_ptr<random_write> &&stream, std::uint8_t filler) noexcept;

/// \brief Create a random access output filter that fills unwritten
///   space
///
/// Creates a random access output filter that fills unwritten space
/// with a specified byte value.  If a write operation starts beyond the
/// end of the output, the space between the end of the output and the
/// start of the written data is filled with the specified filler byte
/// value.  Does not take ownership of the underlying output sequence.
/// \param [in] stream Underlying output sequence to write to.
/// \param [in] filler Byte value to fill unwritten space.
/// \return A pointer to a random access output sequence, or nullptr on
///   error.
/// \sa random_write
std::unique_ptr<random_write> random_write_fill(random_write &stream, std::uint8_t filler) noexcept;


/// \brief Create a random access I/O filter that fills unused space
///
/// Creates a random access I/O sequence that fills unused read buffer
/// space and unwritten space with a specified byte value.  If a read
/// operation does not produce enough data to fill the supplied buffer,
/// the remaining space in the buffer is filled with the specified
/// filler byte value.  If a write operation starts beyond the end of
/// the output, the space between the end of the output and the start of
/// the written data is filled with the specified filler byte value.
/// Takes ownership of the underlying I/O sequence.
/// \param [in] stream Underlying I/O sequence to read from and write
///   to.
/// \param [in] filler Byte value to fill unused read buffer space and
///   unwritten space.
/// \return A pointer to a random access I/O sequence, or nullptr on
///   error.
/// \sa random_read_write
std::unique_ptr<random_read_write> random_read_write_fill(std::unique_ptr<random_read_write> &&stream, std::uint8_t filler) noexcept;

/// \brief Create a random access I/O filter that fills unused space
///
/// Creates a random access I/O sequence that fills unused read buffer
/// space and unwritten space with a specified byte value.  If a read
/// operation does not produce enough data to fill the supplied buffer,
/// the remaining space in the buffer is filled with the specified
/// filler byte value.  If a write operation starts beyond the end of
/// the output, the space between the end of the output and the start of
/// the written data is filled with the specified filler byte value.
/// Does not take ownership of the underlying I/O sequence.
/// \param [in] stream Underlying I/O sequence to read from and write
///   to.
/// \param [in] filler Byte value to fill unused read buffer space and
///   unwritten space.
/// \return A pointer to a random access I/O sequence, or nullptr on
///   error.
/// \sa random_read_write
std::unique_ptr<random_read_write> random_read_write_fill(random_read_write &stream, std::uint8_t filler) noexcept;


/// \brief Create an input stream filter that decompresses
///   zlib-compressed data
///
/// Creates a read stream that decompresses zlib-compressed (deflated)
/// data read from the underlying input stream.  A read operation will
/// always stop on reaching an end-of-stream marker in the compressed
/// data.  A subsequent read operation will expect to find the beginning
/// of another block of compressed data.  May read past the end of the
/// compressed data in the underlying input stream.  Takes ownership of
/// the underlying input stream.
/// \param [in] stream Underlying input stream to read from.
/// \param [in] read_chunk Size of buffer for reading compressed data in
///   bytes.
/// \return A pointer to an input stream, or nullptr on error.
/// \sa read_stream
std::unique_ptr<read_stream> zlib_read(std::unique_ptr<read_stream> &&stream, std::size_t read_chunk) noexcept;

/// \brief Create an input stream filter that decompresses
///   zlib-compressed data
///
/// Creates a read stream that decompresses zlib-compressed (deflated)
/// data read from the underlying input sequence.  A read operation will
/// always stop on reaching an end-of-stream marker in the compressed
/// data.  A subsequent read operation will expect to find the beginning
/// of another block of compressed data.  If a read operation reads past
/// an end-of-stream marker in the compressed data, it will seek back so
/// the position for the next read from the underlying input sequence
/// immediately follows the end-of-stream marker.  Takes ownership of
/// the underlying input sequence.
/// \param [in] stream Underlying input sequence to read from.  Must
///   support seeking relative to the current position.
/// \param [in] read_chunk Size of buffer for reading compressed data in
///   bytes.
/// \return A pointer to an input stream, or nullptr on error.
/// \sa read_stream random_read
std::unique_ptr<read_stream> zlib_read(std::unique_ptr<random_read> &&stream, std::size_t read_chunk) noexcept;

/// \brief Create an input stream filter that decompresses
///   zlib-compressed data
///
/// Creates a read stream that decompresses zlib-compressed (deflated)
/// data read from the underlying input stream.  A read operation will
/// always stop on reaching an end-of-stream marker in the compressed
/// data.  A subsequent read operation will expect to find the beginning
/// of another block of compressed data.  May read past the end of the
/// compressed data in the underlying input stream.  Does not take
/// ownership of the underlying input stream.
/// \param [in] stream Underlying input stream to read from.
/// \param [in] read_chunk Size of buffer for reading compressed data in
///   bytes.
/// \return A pointer to an input stream, or nullptr on error.
/// \sa read_stream
std::unique_ptr<read_stream> zlib_read(read_stream &stream, std::size_t read_chunk) noexcept;

/// \brief Create an input stream filter that decompresses
///   zlib-compressed data
///
/// Creates a read stream that decompresses zlib-compressed (deflated)
/// data read from the underlying input sequence.  A read operation will
/// always stop on reaching an end-of-stream marker in the compressed
/// data.  A subsequent read operation will expect to find the beginning
/// of another block of compressed data.  If a read operation reads past
/// an end-of-stream marker in the compressed data, it will seek back so
/// the position for the next read from the underlying input sequence
/// immediately follows the end-of-stream marker.  Does not take
/// ownership of the underlying input sequence.
/// \param [in] stream Underlying input sequence to read from.  Must
///   support seeking relative to the current position.
/// \param [in] read_chunk Size of buffer for reading compressed data in
///   bytes.
/// \return A pointer to an input stream, or nullptr on error.
/// \sa read_stream random_read
std::unique_ptr<read_stream> zlib_read(random_read &stream, std::size_t read_chunk) noexcept;


/// \brief Create an output stream filter that writes zlib-compressed
///   data
///
/// Creates an output stream that compresses data using the zlib deflate
/// algorithm and writes it to the underlying output stream.  Calling
/// the \c finalize member function compresses any buffered input,
/// produces an end-of-stream maker, and writes any buffered compressed
/// data to the underlying output stream.  A subsequent write operation
/// will start a new compressed block.  Calling the \c flush member
/// function writes any buffered compressed data to the underlying
/// output stream and calls the \c flush member function of the
/// underlying output stream; it does not ensure all buffered input data
/// is compressed or force the end of a compressed block.  Takes
/// ownership of the underlying output stream.
/// \param [in] stream Underlying output stream for writing compressed
///   data.
/// \param [in] level Compression level.  Use 0 for no compression, 1
///   for fastest compression, 9 for maximum compression, or -1 for the
///   default compression level as defined by the zlib library.  Larger
///   values between 1 and 9 provide higher compression at the expense
///   of speed.
/// \param [in] buffer_size Size of buffer for compressed data in bytes.
/// \return A pointer to an output stream, or nullptr on error.
/// \sa write_stream
std::unique_ptr<write_stream> zlib_write(std::unique_ptr<write_stream> &&stream, int level, std::size_t buffer_size) noexcept;

/// \brief Create an output stream filter that writes zlib-compressed
///   data
///
/// Creates an output stream that compresses data using the zlib deflate
/// algorithm and writes it to the underlying output stream.  Calling
/// the \c finalize member function compresses any buffered input,
/// produces an end-of-stream maker, and writes any buffered compressed
/// data to the underlying output stream.  A subsequent write operation
/// will start a new compressed block.  Calling the \c flush member
/// function writes any buffered compressed data to the underlying
/// output stream and calls the \c flush member function of the
/// underlying output stream; it does not ensure all buffered input data
/// is compressed or force the end of a compressed block.  Does not take
/// ownership of the underlying output stream.
/// \param [in] stream Underlying output stream for writing compressed
///   data.
/// \param [in] level Compression level.  Use 0 for no compression, 1
///   for fastest compression, 9 for maximum compression, or -1 for the
///   default compression level as defined by the zlib library.  Larger
///   values between 1 and 9 provide higher compression at the expense
///   of speed.
/// \param [in] buffer_size Size of buffer for compressed data in bytes.
/// \return A pointer to an output stream, or nullptr on error.
/// \sa write_stream
std::unique_ptr<write_stream> zlib_write(write_stream &stream, int level, std::size_t buffer_size) noexcept;

/// \}

} // namespace util

#endif // MAME_LIB_UTIL_IOPROCSFILTER_H