1 This is ../../doc/libbinio.info, produced by makeinfo version 4.3 from
2 ../../doc/libbinio.texi.
4 This manual documents the binary I/O stream class library, version
5 1.4. It was last updated on 18 August 2004.
7 Copyright (C) 2002 - 2004 Simon Peter
9 Permission is granted to copy, distribute and/or modify this
10 document under the terms of the GNU Free Documentation License,
11 Version 1.1 or any later version published by the Free Software
12 Foundation; with no Invariant Sections, with the Front-Cover texts
13 being "A GNU Manual," and with the Back-Cover Texts as in (a)
14 below. A copy of the license is included in the section entitled
15 "GNU Free Documentation License."
17 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
18 modify this GNU Manual, like GNU software. Copies published by
19 the Free Software Foundation raise funds for GNU development."
21 INFO-DIR-SECTION Software Libraries
23 * libbinio: (libbinio) Binary I/O stream class library 1.4
27 File: libbinio.info, Node: Top, Next: Introduction, Up: (dir)
29 Binary I/O stream class library
30 *******************************
32 This manual documents the binary I/O stream class library, version
33 1.4. It was last updated on 18 August 2004.
35 Copyright (C) 2002 - 2004 Simon Peter
37 Permission is granted to copy, distribute and/or modify this
38 document under the terms of the GNU Free Documentation License,
39 Version 1.1 or any later version published by the Free Software
40 Foundation; with no Invariant Sections, with the Front-Cover texts
41 being "A GNU Manual," and with the Back-Cover Texts as in (a)
42 below. A copy of the license is included in the section entitled
43 "GNU Free Documentation License."
45 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
46 modify this GNU Manual, like GNU software. Copies published by
47 the Free Software Foundation raise funds for GNU development."
51 * Introduction:: Introduction to the library.
52 * Usage:: A tutorial to libbinio.
53 * Reference:: The complete reference.
54 * FAQ:: Frequently asked questions.
55 * Copying This Manual:: Your rights and freedoms.
60 * Type Variable and Macro Index::
63 File: libbinio.info, Node: Introduction, Next: Usage, Prev: Top, Up: Top
68 The binary I/O stream class library (libbinio) presents a
69 platform-independent way to access binary data streams in C++.
71 The library is hardware independent in the form that it transparently
72 converts between the different forms of machine-internal binary data
75 It further employs no special I/O protocol and can be used on
76 arbitrary binary data sources.
83 File: libbinio.info, Node: Features, Up: Introduction
88 libbinio implements a generalized binary stream class framework, with
89 the following features:
91 * The ability to read arbitrary-sized integers, as long as the
92 underlying system can hold the final value.
94 * Conversion between Big- and Little-Endian storage.
96 * Reading and writing of IEEE-754 single and double precision
97 floating-point numbers and the conversion to/from any
98 system-internal floating-point representation.
100 libbinio provides classes for streaming access to normal files,
101 arbitrary data strings in memory and a wrapper around standard
102 iostreams from either the ISO standard C++ library, or a "traditional"
103 iostream implementation.
105 In addition, convenience methods for the STL `string' class can be
106 enabled that support reading and writing of arbitrary length strings
107 with dynamic memory allocation.
109 libbinio should compile and run on as much systems as possible. If it
110 doesn't work with your system/compiler combination, please tell me!
113 File: libbinio.info, Node: Usage, Next: Reference, Prev: Introduction, Up: Top
118 This chapter covers common usage of libbinio and mostly everything
119 you need to know to interface with the library. For very advanced usage,
120 refer to *Note Reference::.
122 Since libbinio's class framework is modelled somewhat after the
123 traditional iostream library, it is good if you already have used the
124 C++ iostream facility before.
130 * Reading and Writing::
133 * Alien architectures::
134 * Wrapping around iostream::
139 File: libbinio.info, Node: Basics, Next: Files, Up: Usage
144 The binary stream class framework divides streams into "input-only",
145 "output-only" and "input/output" supporting streams. All derived
146 classes also inherit this partition.
148 All derived classes that come with the library follow a uniform
149 naming scheme. You can identify what I/O facilities a stream provides,
150 by looking at the class name. All class names of libbinio start with
151 `bin' and end with a descriptive name of what they are meant for. In
152 between is at most one character that describes what I/O functionality
153 is provided. If this character is an `i', the class provides input-only
154 streams, `o' means output-only and no character indicates both input
155 and output facilities.
157 For example, `binifstream' is an input-only binary stream for
158 standard file access. `binstream' is the general input and output
162 File: libbinio.info, Node: Files, Next: Reading and Writing, Prev: Basics, Up: Usage
167 For the most part, you will want to use libbinio to access normal
168 binary files on your filesystem.
170 This is what the `binfstream' related classes are for. To use them,
171 you first have to include the file `binfile.h' within your code.
173 This file contains four class declarations - `binfbase',
174 `binifstream', `binofstream' and `binfstream'. `binfbase' is a base
175 class for the others and normally not used by an ordinary libbinio
176 user. This leaves us with three usable classes.
178 To create a binary stream on a file, just instantiate one of the
179 three classes, according to what I/O facilities the stream should
180 provide (see *Note Basics:: for information on the class naming
183 To open a file, you use the `open(FILENAME, [MODE])' method of one
184 of the classes. FILENAME is a string (both C style ASCIIZ strings and
185 STL `string' objects can be passed, if supported by your compiler)
186 containing the name of the file to open. Additionally, you can pass a
187 MODE argument to specify a special way to open the file - this is
188 described later. There's also a special constructor, provided for
189 convenience, that opens up a file automatically when the object is
190 created. It has exactly the same syntax as `open()'.
192 After usage, you can explicitly close the file with the `close()'
193 method. It is always a good idea to do this explicitly, though not
194 needed because the file automatically will be closed on object
198 File: libbinio.info, Node: Reading and Writing, Next: Peeking, Prev: Files, Up: Usage
203 Every binary stream class offers the same set of binary I/O methods,
204 inherited from one of the general stream base classes `binistream',
205 `binostream' or both of them. These, in turn, inherit from the `binio'
206 class, which provides additional general methods, as well as some
207 important type declarations.
209 The binary I/O methods differenciate between integers, floating-point
210 numbers and character strings.
212 To read an integer from a binary stream, you would use
213 `readInt(SIZE)'. The SIZE argument specifies the size of the integer in
214 bytes. The method returns the integer, that has just been read.
216 `readFloat(TYPE)' reads a floating-point number of type TYPE from
217 the stream. As all floating-point formats are well defined, you just
218 have to specify the right floating-point type to this method and it
219 will figure out the correct size by itself. Refer to *Note Reference::
220 for information of what floating-point formats are supported and how to
221 specify them. The method returns the floating-point number, that has
224 A character string can be read by using the `readString()' method.
225 To read a character string into a pre-allocated C style ASCIIZ string
226 buffer, you would use `readString(STRING, MAX-LENGTH, [DELIMITER])' and
227 give a pointer to the string buffer with STRING, the maximum length of
228 the string (_not_ including the final `\0') in MAX-LENGTH and
229 optionally a delimiter character DELIMITER, at which libbinio would
230 stop reading the string, even if it could read more characters. The
231 delimiter is extracted from the stream and then discarded. It will not
232 appear in the final string. If you do not supply a DELIMITER, always up
233 to MAX-LENGTH characters are read from the stream. The method returns
234 the number of characters actually read from the stream.
236 You can also read an STL `string' object from the stream, using an
237 overloaded version of `readString()'. The syntax is
238 `readString([DELIMITER])'. You also do not need to supply a DELIMITER,
239 as it is set to `\0' by default (to prevent you from reading a
240 virtually unlimited number of characters and flood your memory, since
241 you can't supply a MAX-LENGTH argument this time). The method returns
242 a `string' object, containing all characters up to, but not including,
243 DELIMITER or the end of the stream, whichever was encountered first.
245 All the above mentioned "read" methods have a "write" equivalent,
246 with the same options and features. All "write" methods take the data
247 to be written as first argument, as in (for example) `writeInt(VALUE,
248 SIZE)', VALUE is the actual value to be written to the stream.
251 File: libbinio.info, Node: Peeking, Next: Seeking, Prev: Reading and Writing, Up: Usage
256 Analogous to the `readInt()' and `readFloat()' methods are the
257 `peekInt(SIZE)' and `peekFloat(TYPE)' methods, that take the same
258 arguments and also read an integer or a floating-point number from the
259 stream. Unlike their "`read'" counterparts, they don't modify the
260 stream position. The next "real" access (i.e. with one of the `read'
261 methods) to the stream will continue as if the `peek' methods have
265 File: libbinio.info, Node: Seeking, Next: Alien architectures, Prev: Peeking, Up: Usage
270 Sometimes, you need to reposition within your stream. To do this, you
271 use the `seek(POSITION, [OFFSET])' method. POSITION is the new position
272 in the stream, counted byte-wise and starting at `0'. The optional
273 argument OFFSET specifies from where the method should seek. If it is
274 `Set', counting is started at the beginning of the stream. `Add'
275 indicates to seek from the current stream position and `End' means
276 seeking from the end of the stream. Note that POSITION is a signed
277 integer value and you can also seek backwards by inserting a negative
280 You can use the `pos()' method to determine your current position
281 within the stream, which is returned by the method.
284 File: libbinio.info, Node: Alien architectures, Next: Wrapping around iostream, Prev: Seeking, Up: Usage
289 All the above mentioned procedures expect the data to be in the
290 format of your machine's own idea of how the data has to be stored.
291 However, there are situations where you have to read and even write
292 binary data for some other, incompatible architecture.
294 All architectures that are incompatible with the architecture,
295 libbinio is currently running on, are called "alien" architectures.
297 libbinio makes the process of converting between your architecture's
298 and the alien architecture's idea of binary storage completely
299 transparent to you. All you have to do is to specify some
300 characteristics about the stream's binary format, after you have opened
301 it. All newly created streams are initialized with the current system's
302 binary characteristics, so you don't have to do anything if you just
303 want to access data of your own architecture.
305 You use the `setFlag(FLAG, [SET])' and `getFlag(FLAG)' methods to
306 set and read a stream's characteristics. FLAG specifies the flag to be
307 set or read (refer to *Note Reference:: for information on what flags
308 are available and their meaning). The optional argument SET specifies
309 whether the flag should be set (the default) or erased.
311 After you have set up all flags to sufficiently specify the alien
312 architecture, you can proceed to do binary I/O, just as described in
313 the previous chapters and libbinio will do all the necessary conversion
314 between your own and the alien architecture for you.
316 If you ever happen to have binary data of multiple, incompatbile,
317 alien architectures in a single stream (very unlikely), you can re-set
318 any of the flags to any other value, in between any of the other stream
319 access method calls. The stream will adhere to the new flag values
320 instantly with the next data access.
323 File: libbinio.info, Node: Wrapping around iostream, Next: Errors, Prev: Alien architectures, Up: Usage
325 Wrapping around iostream
326 ========================
328 libbinio provides a set of classes, called `binwstream',
329 `biniwstream' and `binowstream', that can be wrapped around an already
330 existing stream from the standard or traditional C++ iostream library.
332 To do this, you just have to pass a pointer to the original stream
333 object from the iostream library to the constructor of the appropriate
334 `binwstream' class. Of course, you have to match an input stream from
335 the iostream library to an input stream from libbinio and analogous for
336 the output-only streams. The class framework will prevent you from
337 mismatching them. You can, however, wrap an unidirectional binary
338 stream around a bidirectional stream from the iostream library.
340 There is one important thing you have to remember: If you plan to
341 wrap a binary stream around an iostream stream, always open the iostream
342 stream with the `ios::bin' mode flag set! This will prevent some
343 operating systems (namely, MS-DOS and Windows) from doing nasty
344 implicit interpretation on the streams. This definitly will impose
345 problems when you try to read or write the binary stream.
347 All other flags, you set when opening the original iostream stream,
348 can indirectly have effect on the operations you do on the wrapped
352 File: libbinio.info, Node: Errors, Next: Examples, Prev: Wrapping around iostream, Up: Usage
357 When doing stream I/O, some unpredictable, erroneus situations can
358 occur at runtime. Binary streams are no exception to this phenomenon.
359 To provide some sort of protection against this, all libbinio stream
360 classes inherit an error reporting method called `error()'.
362 It is a good idea to check the error status of a stream once in a
363 while to see if everything is still in place. `error()' returns a
364 variable of type `Error', which is an integer that holds a bit field of
365 error values for that stream. Refer to *Note Reference:: for
366 information about the possible values of this variable and their
369 A status of no error is always reported with a value of `0', so you
370 can easily check if everything is still okay in a simple `if'
371 construct, like this:
374 // an error occured, do something to cure it...
376 // everything is still okay!
378 Two convenience error reporting methods are also included:
380 `eof()' only checks for the `Eof' error status, indicating whether
381 the end of the stream has just been passed. It returns a boolean value,
382 indicating the past the end of the stream.
384 `ateof()' is like `eof()' but returns true already when the stream
385 pointer is at the last byte of the stream, not past it. This is useful
386 when you want to read an entire file into memory in a `while(!ateof())'
387 loop. This method is only defined on streams that support reading. On
388 write-only streams, it is not defined and not useful.
390 Whenever you call `error()', the internal error variable is reset to
391 the `NoError' state, indicating no error at all, and a subsequent call
392 to any of the error reporting methods will return `NoError' again.
393 `eof()' and `ateof()' do not reset the internal error variable. The
394 last error status of the stream is retained.
397 File: libbinio.info, Node: Examples, Prev: Errors, Up: Usage
402 To read some data (namely integers, floats and strings) from an
403 ordinary binary file on your filesystem, which was also created on your
408 binifstream file("test.dat");
413 // Read a 32-bit integer
416 // Read an IEEE-754 single (32 bits)
417 f = file.readFloat(binio::Single);
419 // Read a string until newline or max. number of chars exceeded
420 file.readString(string, 256, '\n');
422 To do I/O on a file that was created on an x86 machine (i.e. Little
423 Endian, IEEE-754 floats), while your own architecture is something
432 // open the file "x86.dat" for reading and writing, but do not create
433 // it if it's not there.
434 file.open("x86.dat", binfbase::NoCreate);
436 // Check if we could cleanly open the file and bail out, if we
441 // Set Little Endian mode, with IEEE-754 floats.
442 file.setFlag(binio::BigEndian, false); // remove flag
443 file.setFlag(binio::FloatIEEE); // set flag
445 // as we just want a demonstration, we discard all read data right away.
447 // Read a 16-bit integer
450 // Read an IEEE-754 double (64 bits)
451 file.readFloat(binio::Double);
453 // Remember our current position in the stream
456 // Seek to the end of the file
457 file.seek(0, binio::End);
459 // Write our variable i, determining its size using sizeof()
460 file.writeInt(i, sizeof(i));
462 // Seek back to our former position
465 // Read a byte from here
468 // close the file again
471 // and we're finished
474 To wrap around a stream from the iostream library, reading data until
475 the end of the stream:
480 // Open the iostream stream for reading and writing in binary mode.
481 fstream file("test.dat", ios::in | ios::out | ios::bin);
483 // Wrap a binary input-only stream around it.
484 biniwstream bfile(&file);
486 // Read (and immediately discard) 24-bit integers until the end
492 File: libbinio.info, Node: Reference, Next: FAQ, Prev: Usage, Up: Top
497 This chapter comprises a complete reference of all classes, methods,
498 types and variables inside libbinio.
507 * iostream wrappers::
510 File: libbinio.info, Node: Concepts, Next: Configuration, Up: Reference
515 The libbinio stream classes can be divided into two layers of
518 1. The "conversion layer" provides methods for transparently
519 converting the data, that has just been read from or is to be
520 written to a stream, between the current and the alien
521 architecture. The `binistream', `binostream' and `binstream'
522 classes belong to this layer.
524 2. The "stream layer" faciliates functionality on the stream level.
525 It provides methods for byte-by-byte access to the data, seeking,
526 opening and closing a stream and anything else related to the
527 maintenance of a stream. The `binfstream', `binwstream' and
528 `binsstream' related classes belong to this layer.
530 Additionally, there are some administrative and auxiliary classes
531 provided, which do not belong to any of the above defined layers. The
532 `binio' base class belongs here, for example.
535 File: libbinio.info, Node: Configuration, Next: Base classes, Prev: Concepts, Up: Reference
540 libbinio can be configured in various ways at compile time and some
541 parts of the library can be disabled to save disk space and/or
544 In some cases, these configuration options directly change parts of
545 the interface and must thus also be known by the library user.
547 To make these options available to the library user, libbinio defines
548 some C preprocessor macros in `binio.h'. These are:
550 `BINIO_ENABLE_STRING'
551 If this macro expands to `1', STL `string' object support is
552 enabled and can be used instead of traditional C ASCIIZ pointers
553 with all functions that expect a string somewhere. It expands to
556 `BINIO_ENABLE_IOSTREAM'
557 If this macro expands to `1', the iostream wrapper classes are
558 enabled and can be used by the library user. It expands to `0'
559 otherwise and no iostream wrapper classes are present in this case.
562 If this macro expands to `1', libbinio's iostream wrapper classes
563 are taylored for the ISO standard C++ library, instead of a
564 "traditional" iostream implementation. It expands to `0'
565 otherwise. This macro is merely for libbinio's internal use and
566 should not be used by an application programmer.
569 This macro is for libbinio's internal use and should not be used
570 by an application programmer.
572 All macros are _always_ defined. The decision whether a feature is
573 enabled in the library has to be based on the value of these macros,
574 not whether they are defined or not.
577 File: libbinio.info, Node: Base classes, Next: File streams, Prev: Configuration, Up: Reference
582 The base classes provide a common base for all derived libbinio
583 stream classes. They define important methods, types and variables.
585 One general and three stream base classes are defined in the file
586 `binio.h', which make up the libbinio base classes.
596 File: libbinio.info, Node: binio, Next: binistream, Up: Base classes
601 `binio' is the general base class, containing important method, type
602 and variable declarations. As a user, you normally do not need it
603 directly, except for scoping types and variables to it.
605 Header file: `binio.h'
606 ----------------------
617 `void setFlag(Flag f, bool set = true)'
618 Is used to set or erase flags to change the behaviour of the
619 stream. Available flags and their meaning are listed in the types
620 table for this class, below. The optional argument `set' is used
621 to set or erase the specified flag. If it is not specified, it
622 defaults to `true', setting (activating) the specified flag.
624 `bool getFlag(Flag f)'
625 Returns whether the specified flag is set (active) or not. Refer to
626 `setFlag', above, for more information.
629 Returns the current error status of the stream. A status of no
630 error is always indicated with a value of `0', as to allow easy
631 error checks with a simple `if' construct.
634 Returns `true' if the last access to the stream was unsuccessful
635 because the stream pointer was already past the end of the stream.
636 `false' is returned otherwise. Synonymous to checking if the
637 return value of a call to `error()' sets the `Eof' error code flag.
639 `virtual void seek(long, Offset = Set)'
640 Abstract virtual method for seeking into streams. Implemented by
641 the stream layer. The first argument specifies the relative
642 position to seek to. Use a negative value to seek backwards. The
643 optional second argument specifies from where to start seeking.
644 `Set' specifies the beginning of a stream, `Add' specifies the
645 current position and `End' specifies the end of the stream. If it
646 is omitted, it defaults to `Set', seeking from the beginning of
650 Abstract virtual method that returns the current position inside
651 the stream. Implemented by the stream layer.
656 `Float pow(Float base, signed int exp)'
657 Is a stripped-down version of the `pow()' function from the
658 `math.h' standard C math library include file. It is used during
659 conversion between floating-point formats and can calculate powers
660 of a floating-point base argument, using a signed integer exponent.
662 Public data types and variables:
663 --------------------------------
666 Enumeration of all defined stream flags that can be set using the
667 `setFlag()' and `getFlag()' methods. This type defines the
671 If set, sets the stream's byte-ordering to big endian
672 notation. Otherwise, little endian notation is used.
675 If set, all floating-point access to the stream will assume
676 IEEE-754 standardized floating-point numbers. Only this type
677 of data is expected from and written to the stream.
679 If your architecture does not support IEEE-754 floating-point
680 numbers, the value will be converted. Various conversion
681 errors can occur and sometimes the conversion is not possible
682 at all. In this case, the `Unsupported' error is issued and a
683 specific value is returned. The following table summarizes all
684 possible return codes for certain problematic values:
686 Real value Return value
689 `Not a Number (NaN)' `0.0'
691 Both positive and negative zero (`0') are mapped to the same
692 zero value, if your architecture does not support both
693 positive and negative zeroes. There is no way to distinguish
694 between the two values in this case.
697 Enumeration of all possible error values. This type defines the
701 No error at all. This is always mapped to an integer value of
705 An unspecified, fatal error occured. This error is issued
706 only if something really strange happened (i.e. on internal
707 logic errors in the library, or if something else, undefined
708 happens, etc.). It is advised to immediately terminate any
709 binary stream I/O activity and fail with an error message to
710 the application user, maybe even terminate the application
714 You tried to access stream data in an unsupported way. This
715 error is issued whenever an (explicit or implicit) conversion
716 between two types of data storage is requested, that isn't
717 supported by libbinio yet.
720 The stream you tried to access is not open yet.
723 Access to this stream is denied. This error is normally
724 issued when you try to open a file on a filesystem, but you
725 have insufficient rights to access it.
728 The stream you tried to access was not found. This is mostly
729 issued on a file not found error, when accessing normal files
733 The end of the stream has been passed. Issued when you tried
734 to read past the last byte of a stream.
737 Specifies the position inside a stream, from where a seek is
738 started with the `seek()' method. This type defines the following
742 Start seeking at the beginning of the stream.
745 Start seeking from the current position in the stream.
748 Start seeking from the end of the stream.
751 Specifies what type of floating-point number is to be accessed
752 next, using the `readFloat()' or `writeFloat()' methods. Most
753 floating-point formats specify multiple data types to support a
754 broader range of precision. libbinio generalizes the idea by
755 categorizing them only into single and double precision numbers.
756 This type defines the following values:
759 Access a single precision floating-point number.
762 Access a double precision floating-point number.
765 This integer holds a bit field of all error values for a stream.
766 Returned by `error()'. A status of "no error" is always indicated
767 when the whole field is set to `0' (zero), i.e. the integer is
768 `0'. Test for an error by binary or'ing this integer with one of
769 the error values from `ErrorCode'.
771 Protected data types and variables:
772 -----------------------------------
775 The largest integer type supported by the architecture.
778 The largest floating-point type supported by the architecture.
781 This type is always one byte (8 bits) wide.
784 Type to hold a flag variable, containing the status of all flags
788 This variable holds the current status of all flags for the stream.
790 `static const Flags system_flags'
791 This variable holds the status of the flags, defining the standard
792 behaviour of the system. This is determined once at runtime, at
793 startup of the library.
796 This variable holds the error status of a stream.
799 File: libbinio.info, Node: binistream, Next: binostream, Prev: binio, Up: Base classes
804 `binistream' provides an input-only binary stream.
806 Header file: `binio.h'
807 ----------------------
818 `Int readInt(unsigned int size)'
819 Reads an integer of size `size' (in bytes) from the stream and
820 returns it. The return value is undefined if an error occured. The
821 maximum number of bytes that can be read at once equals the size
822 (in bytes) of the largest integer type, supported by the system.
824 `Float readFloat(FType ft)'
825 Reads a floating-point number from the stream and returns it. Takes
826 the floating-point format to read as the argument `ft'. Refer to
827 the list of public types of the `binio' class for information
828 about what floating-point formats are supported. The return value
829 is undefined if an error occured. The value from the stream is
830 always rendered to the biggest floating-point type, supported by
833 If your architecture is incompatible with the floating-point number
834 that has just been read, `readFloat()' tries to convert it. This
835 is sometimes not possible or not as accurate as the original value
836 and an error will be issued in these cases. Refer to the list of
837 public types of the `binio' class for information about what errors
840 `unsigned long readString(char *str, unsigned long maxlen, const char delim)'
841 `std::string readString(const char delim = '\0')'
842 Reads a character string from the stream. Both pre-allocated
843 standard C ASCIIZ strings and STL `string' objects are supported.
845 The ASCIIZ version takes a pointer to the pre-allocated string
846 buffer as the `str' argument. `maxlen' specifies the maximum
847 number of characters to be read from the stream (_not_ including
848 the trailing `\0' that is always appended to the string buffer).
849 The optional argument `delim' is a delimiter character. If this
850 character is encountered in the stream, no more characters will be
851 read. The delimiter character itself is discarded. It will not
852 appear in the final string. If the `delim' argument is omitted,
853 always up to `maxlen' characters are read.
855 The `string' object version just takes one optional argument, the
856 delimiter character, explained above. Characters are always read
857 until the delimiter character or the end of the stream is
858 encountered. If `delim' is omitted, it defaults to `\0'. It
859 returns a `string' object, containing the final string.
861 `Int peekInt(unsigned int size)'
862 Like `readInt()', but doesn't modify the stream position, so any
863 later access to the stream will appear as if `peekInt()' has never
866 `Float peekFloat(FType ft)'
867 Like `readFloat()', but doesn't modify the stream position, so any
868 later access to the stream will appear as if `peekFloat()' has
872 Returns `true' if the current stream position is at the last byte
873 of the stream. `false' is returned otherwise.
875 `void ignore(unsigned long amount = 1)'
876 Reads and then immediately discards the specified amount of bytes
877 from the stream. If the optional argument `amount' is omitted, it
878 defaults to `1', ignoring exactly 1 byte from the stream.
883 `virtual Byte getByte()'
884 Abstract virtual method to extract exactly one byte (8 bits) from
885 the stream and advance stream pointer accordingly. The byte is
886 returned. Implemented by the stream layer.
889 File: libbinio.info, Node: binostream, Next: binstream, Prev: binistream, Up: Base classes
894 `binostream' provides an output-only binary stream.
896 Header file: `binio.h'
897 ----------------------
908 `void writeInt(Int val, unsigned int size);'
909 Writes the integer value `val' of size `size' (in bytes) to the
912 `void writeFloat(Float f, FType ft);'
913 Writes the floating-point value `f' of type `ft' to the stream.
914 Refer to the list of public types of the `binio' class for
915 information about what floating-point formats are supported.
917 If the requested floating-point type is not supported by your
918 architecture, `writeFloat()' tries to convert it. This is not
919 always possible and an `Unsupported' error is issued if the
920 conversion fails and nothing is written to the stream in this case.
922 `unsigned long writeString(const char *str, unsigned long amount = 0);'
923 `unsigned long writeString(const std::string &str);'
924 Writes a character string to the stream. Both standard C ASCIIZ
925 strings and STL `string' objects are supported.
927 The standard C version takes a pointer `str' to the ASCIIZ string
928 to write as first argument and an optional second argument
929 `amount', which specifies the number of characters to write from
930 that string. If it is omitted, the whole string is written to the
933 For the `string' object version, the only argument is the `string'
934 object, containing the string to write.
936 Both methods return the number of characters actually written to
937 the stream (which should only differ from the value you wanted to
938 write when an error occured).
943 `virtual void putByte(Byte)'
944 Abstract virtual method to insert exactly one byte (8 bits) into
945 the stream and advance the stream pointer accordingly. The byte to
946 be written is passed as the only argument. Implemented by the
950 File: libbinio.info, Node: binstream, Prev: binostream, Up: Base classes
955 `binstream' provides a both input and output supporting binary
956 stream. It inherits the interface from both `binistream' and
957 `binostream' and defines no additional methods. Refer to the
958 documentation of these two classes for more information instead.
961 File: libbinio.info, Node: File streams, Next: String streams, Prev: Base classes, Up: Reference
966 File streams provide access to ordinary files on a filesystem. They
967 consist of the classes `binifstream', `binofstream' and `binfstream',
968 which are all derived from the common base class `binfbase'.
973 * File stream classes::
976 File: libbinio.info, Node: binfbase, Next: File stream classes, Up: File streams
981 `binfbase' provides the common base class for all file I/O binary
982 streams. It defines important data types, variables and methods.
984 Header file: `binfile.h'
985 ------------------------
994 The destructor. Automatically closes an eventually open stream.
996 `virtual void open(const char *filename, const Mode mode)'
997 `virtual void open(const std::string &filename, const Mode mode)'
998 Two versions of an abstract virtual method to open a binary file
999 stream. `filename' is the filename of the file to open and `mode'
1000 specifies in which mode to do so. Refer to the list of data types
1001 for this class for more information on this argument. You can
1002 combine multiple mode flags together, using the `|' operator.
1005 Method to explicitly close the stream.
1007 `void seek(long pos, Offset offs = Set)'
1009 Implementation of the abstract virtual methods, inherited from
1010 `binio'. Look there for reference.
1012 Public data types and variables:
1013 --------------------------------
1016 Enumeration of all defined file stream open mode flags, defining
1017 how a file should be opened when the `open()' method is called.
1018 This type defines the following flags:
1021 Open the stream for appending. The stream pointer is
1022 positioned at the end of the stream. Also, do not truncate a
1023 file to zero length, if it already exists.
1026 Do not automatically create a nonexistant file on first
1027 access and fail instead. Also, do not truncate a file to zero
1028 length, if it already exists.
1031 Type of the variable to hold the mode specification flags that are
1032 passed to one of the `open()' methods to open a file stream. Refer
1033 to `enum ModeFlags' above for information on what flags are
1036 Protected data types and variables:
1037 -----------------------------------
1040 Pointer to the currently opened file of this stream.
1043 File: libbinio.info, Node: File stream classes, Prev: binfbase, Up: File streams
1048 The binary file streams consist of the classes `binifstream',
1049 `binofstream' and `binfstream'. They all inherit the interface from
1050 both `binfbase' and `binistream' and/or `binostream'. Refer to the
1051 class reference of these classes for more information on the interface
1054 `binifstream' provides an input-only binary file stream. It is
1055 inherited from `binistream'. The `open()' method of this class ignores
1056 all passed `mode' arguments, the open mode is always `NoCreate'. The
1057 stream pointer is always positioned at the beginning of the stream and
1058 no files will ever be created, if they don't exist.
1060 `binofstream' provides an output-only binary file stream. It is
1061 inherited from `binostream'. The default open mode is `0'. A file is
1062 truncated to zero length or created if it did not exist previously. The
1063 stream is positioned at the beginning of the file. The `NoCreate' mode
1064 flag has no effect with the `open()' method of this class. Only
1065 `Append' is honored, positioning the stream at the end of the file and
1066 not truncating it. The file is still created, if it did not exist.
1068 `binfstream' provides an input and output supporting binary file
1069 stream. It is inherited from both `binifstream' and `binofstream'. The
1070 default open mode is `0'. A file is truncated to zero length or created
1071 if it did not exist previously. The stream is positioned at the
1072 beginning of the file. All `mode' arguments are valid with the `open()'
1073 method of this class. Refer to the list of public data types and
1074 variables of the `binfbase' class for more information on their meaning.
1076 All three classes define an extra convenience constructor that has
1077 the same syntax as the `open()' method and automatically open the
1078 specified file on object construction.
1080 For your information, here is a list of some important redefined
1081 methods of these classes, as explained above:
1083 Header file: `binfile.h'
1084 ------------------------
1092 All standard constructors.
1097 All standard destructors. They all automatically close an
1098 eventually open stream, on object deconstruction.
1100 `binifstream(const char *filename, const Mode mode = NoCreate)'
1101 `binifstream(const std::string &filename, const Mode mode = NoCreate)'
1102 Convenience constructors of the input-only stream class. Refer to
1103 the description of the `open()' method in the list of public
1104 methods of the `binfbase' class for syntax information.
1106 `binofstream(const char *filename, const Mode mode = 0)'
1107 `binofstream(const std::string &filename, const Mode mode = 0)'
1108 Convenience constructors of the output-only stream class. Refer to
1109 the description of the `open()' method in the list of public
1110 methods of the `binfbase' class for syntax information.
1112 `binfstream(const char *filename, const Mode mode = 0)'
1113 `binfstream(const std::string &filename, const Mode mode = 0)'
1114 Convenience constructors of the input and output supporting stream
1115 class. Refer to the description of the `open()' method in the list
1116 of public methods of the `binfbase' class for syntax information.
1119 File: libbinio.info, Node: String streams, Next: iostream wrappers, Prev: File streams, Up: Reference
1124 The string stream classes provide a means of turning arbitrary
1125 strings (or "blocks") in memory into a binary stream, similary to what
1126 `strstream' does in the iostream library.
1128 Unlike `strstream' from the iostream library, these streams _do not_
1129 support automatic enlarging of the memory area. If the user tries to
1130 write beyond the end of the stream, nothing is actually written and an
1131 `Eof' error is issued.
1133 Header file: `binstr.h'
1134 -----------------------
1139 `binsbase(void *str, unsigned long len)'
1141 `binisstream(void *str, unsigned long len)'
1143 `binosstream(void *str, unsigned long len)'
1145 `binsstream(void *str, unsigned long len)'
1146 All constructors take two arguments. `str' is a pointer to a
1147 previously initialized data string in memory. `len' specifies the
1148 length in bytes of the string.
1159 `virtual void seek(long pos, Offset offs = Set)'
1160 `virtual long pos()'
1161 Implementation of the abstract virtual methods, inherited from
1162 `binio'. Refer to the reference of that class for more information.
1164 Protected data types and variables in `binsbase':
1165 -------------------------------------------------
1168 This pointer is always pointing to the beginning of the initialized
1169 data string in memory, passed to the constructor.
1172 This pointer points to the current position in the string stream.
1175 Holds the length in bytes for the whole data string in memory, as
1176 passed to the constructor.
1179 File: libbinio.info, Node: iostream wrappers, Prev: String streams, Up: Reference
1184 The iostream wrapper classes provide a way to "wrap" around an
1185 already existing stream of the standard or traditional C++ iostream
1186 library, thus providing binary access to such a stream. The wrapper
1187 classes consist of `biniwstream', `binowstream' and `binwstream'.
1189 The iostream wrapper classes do not provide any extra methods by
1190 themselves. They just inherit the interface of the general binary
1191 stream classes. Look there for reference. `biniwstream' inherits from
1192 `binistream', `binowstream' inherits from `binostream' and `binwstream'
1193 inherits from both of them.
1195 Remember to _always_ open the iostream stream with the `ios::bin'
1196 flag set, before you wrap it with a binary stream, or else you will get
1197 strange errors on some operating systems.
1199 All other flags you set on the iostream stream will also indirectly
1200 affect the wrapped binary stream, so be careful.
1202 Header file: `binwrap.h'
1203 ------------------------
1208 `biniwstream(istream *istr)'
1209 `binowstream(ostream *ostr)'
1210 `binwstream(iostream *str)'
1211 The constructor. `istr', `ostr' and `str' are pointers to an
1212 appropriate, already existing and open stream from the iostream
1220 `virtual void seek(long pos, Offset offs = Set)'
1221 `virtual long pos()'
1222 Implementation of the abstract virtual methods, inherited from
1223 `binio'. Refer to the reference of that class for more information.
1226 File: libbinio.info, Node: FAQ, Next: Copying This Manual, Prev: Reference, Up: Top
1231 * Q: Why don't you supply general data block I/O methods, taking
1232 `void' pointers as arguments, so i can read all my data into a
1235 * A: This, in general, is a broken idea. It only makes sense if you
1236 plan to write your program for only one architecture and want a
1237 fast way to read your whole data into memory. This is not what
1238 libbinio was meant for, so such methods will never be implemented.
1239 libbinio cannot know what data types your `struct' is made of and
1240 thus cannot do any transparent data conversion. And there's even
1241 more: Most compilers align their `struct's to a special multiple
1242 of bytes (mostly the current architecture's data word size).
1243 libbinio doesn't (and cannot) know about all this and would just
1244 read the data byte by byte, completely ignoring the alignment and
1245 causing you to be unable to read any of your data.
1247 * Q: Why haven't you implemented error reporting using exceptions,
1248 instead of this darn `error()' method polling?
1250 * A: Because exceptions aren't supported on all compiler platforms.
1253 File: libbinio.info, Node: Copying This Manual, Next: Concept Index, Prev: FAQ, Up: Top
1260 * GNU Free Documentation License:: License for copying this manual.