BinaryIO

A class used to easily write and read bytes to and from a Stream.

This is useful for encoding data into a binary format.

Notes: Functions are marked as either Easy or Advanced.

Easy functions are designed to be easy to use, and should be fine for general cases.

Advanced functions are a bit less "automatic" or perform some other function, and are best used when the binary data needs to be a bit more customised.

final

class BinaryIO {

this(Stream stream, Endian endian);

ubyte[] readBytes(size_t amount);

size_t readLengthBytes();

T read();

void writeBytes(ubyte[] data);

void writeLengthBytes(size_t length);

void write(T value);

void write(T[] value);

inout(S) stream [@property getter];

inout(Endian) endian [@property getter];

Endian endian [@property setter];

}

Constructors

this this(Stream stream, Endian endian): Assertions: stream must not be null.

Members

Functions

read T read(): Easy Reads in a single numeric value.
read T read(): Easy Reads in an array of numeric values.
read T read(): Easy Reads in a string.
readBytes ubyte[] readBytes(size_t amount): Advanced Reads a certain amount of bytes.
readLengthBytes size_t readLengthBytes(): Advanced Reads in a length of something in a compact format.
write void write(T value): Easy Writes a single numeric value.
write void write(T[] value): Easy Writes an array of numeric values.
write void write(T[] value): Easy Writes a string.
writeBytes void writeBytes(ubyte[] data): Advanced Writes out a series of bytes into the stream.
writeLengthBytes void writeLengthBytes(size_t length): Advanced Writes out a length in a compact format.

Properties

endian inout(Endian) endian [@property getter]: Sets the endianess of the numbers written/read by the high level functions.
endian Endian endian [@property setter]
stream inout(S) stream [@property getter]

Throws

All read functions except readBytes will throw a StreamException if they suddenly reach the end of the stream when reading.

All write functions will throw a StreamException if they couldn't write out all of their bytes.

Examples

1 import std.algorithm : reverse;
2 import jaster.stream.memory;
3 
4 void doTest(Endian endian)
5 {
6     auto stream = new BinaryIO(new MemoryStreamGC());
7     stream.endian = endian;
8 
9     // # Test numeric writes #
10     stream.write!short(cast(short)0xFEED);
11     stream.write!int(0xDEADBEEF);
12     assert(stream.stream.length == 6);
13 
14     auto expected1 = (endian == Endian.bigEndian)
15                      ? [0xFE, 0xED, 0xDE, 0xAD, 0xBE, 0xEF]
16                      : [0xED, 0xFE, 0xEF, 0xBE, 0xAD, 0xDE];
17 
18     stream.stream.position = 0;
19     assert(stream.readBytes(6) == expected1);
20 
21     stream.stream.position = 0;
22     assert(stream.read!short == cast(short)0xFEED);
23     assert(stream.read!int   == 0xDEADBEEF);
24 
25     // # Test length byte writes #
26     stream = new BinaryIO(new MemoryStreamGC());
27     stream.endian = endian;
28 
29     stream.writeLengthBytes(60);       // One byte
30     stream.writeLengthBytes(16_000);   // Two bytes
31     stream.writeLengthBytes(17_000);   // Four bytes
32 
33     auto expected2 = 
34     (endian == Endian.bigEndian)
35     ? [0b0011_1100,
36        0b0111_1110, 0b1000_0000,
37        0b1000_0000, 0b0000_0000, 0b0100_0010, 0b0110_1000]
38     : [0b1111_0000,
39        0b0000_0001, 0b1111_1010,
40        0b1010_0010, 0b0000_1001, 0b0000_0001, 0b0000_0000];
41 
42     stream.stream.position = 0;
43     assert(stream.readBytes(7) == expected2);
44 
45     stream.stream.position = 0;
46     assert(stream.readLengthBytes() == 60);
47     assert(stream.readLengthBytes() == 16_000);
48     assert(stream.readLengthBytes() == 17_000);
49 
50     // # Test array writes #
51     stream = new BinaryIO(new MemoryStreamGC());
52     stream.endian = endian;
53 
54     stream.write!ushort([0xAABB, 0xCCDD, 0xEEFF]);
55 
56     auto expected3 = 
57     (endian == Endian.bigEndian)
58     ? [0x03, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF]
59     : [0x0C, 0xBB, 0xAA, 0xDD, 0xCC, 0xFF, 0xEE];
60 
61     stream.stream.position = 0;
62     assert(stream.readBytes(7) == expected3);
63 
64     stream.stream.position = 0;
65     assert(stream.read!(ushort[]) == [0xAABB, 0xCCDD, 0xEEFF]);
66 
67     // # Test string writes #
68     stream = new BinaryIO(new MemoryStreamGC());
69     stream.endian = endian;
70 
71     stream.write("Gurl");
72 
73     auto expected4 = (endian == Endian.bigEndian) ? 0x04 : 0x04 << 2;
74     stream.stream.position = 0;
75     assert(stream.readBytes(stream.stream.length) == [expected4, 'G', 'u', 'r', 'l']);
76 
77     stream.stream.position = 0;
78     assert(stream.read!string() == "Gurl");
79 }
80 
81 doTest(Endian.bigEndian);
82 doTest(Endian.littleEndian);