bytefluo


0  PURPOSE

bytefluo is a C++ class for reading simple integer scalar values with
specified byte order from a buffer, regardless of the native byte
order of the computer on which the code is running. It will throw an
exception if any attempt is made to access data beyond the specified
bounds of the buffer.

The class was created to simplify the low-level parsing of binary
data structures and to avoid having to write code such as

 uint16_t foo = static_cast<uint16_t>(*bar++) << 8;
 foo |= static_cast<uint16_t>(*bar++);

or

 uint16_t foo = ntohs(*(uint16_t *)bar);
 bar += 2;

and instead just write

 uint16_t foo;
 bar >> foo;

(where this bar is a bytefluo object rather than the raw pointer of
the previous examples). So, given some raw data, and a bytefluo
object through which we will access the data, such as

 unsigned char bytes[7] = { 0x99,0xAA,0xBB,0xCC,0xDD,0xEE,0xFF };
 bytefluo buf(bytes, bytes + sizeof(bytes), bytefluo::big);

we can then do things like this

 uint16_t a;
 uint8_t b;
 uint32_t c;

 buf >> a >> b >> c;

 assert(a == 0x99AA);
 assert(b == 0xBB);
 assert(c == 0xCCDDEEFF);


1  BUILDING

bytefluo is a C++ header-only library file; there are no other source
files to compile and no libs to link with. Just include bytefluo.h in
your code and start using it.


2  TESTING

The bytefluo library is distributed with a self-contained unit test in
the file bytefluo_test.cpp. Compile this file and run it.

OS X
 $ clang++ -std=c++11 -stdlib=libc++ -O3 -Wall -I. bytefluo_test.cpp
 $ ./a.out
 tests executed N, tests failed 0

Alternatively, use the makefile in build/clang

 $ cd build/clang/
 $ make test
 clang++ -std=c++11 -stdlib=libc++ -O3 -Wall -I../.. ../../bytefluo_test.cpp
  -o bytefluo_test
 ./bytefluo_test
 tests executed N, tests failed 0

Windows
 C:\test> cl /EHsc /W4 /O2 /nologo bytefluo_test.cpp
 C:\test> bytefluo_test
 tests executed N, tests failed 0

Alternatively, double-click the project file in build/msvc2013.

(Where N is the number of tests in the current version of test suite.)

The bytefluo library has been tested by the author under the following
compilers

 - clang++ 3.9.0 on OS X
 - Microsoft Visual C++ 2013 community edition on Windows


3  USING

The unit test source, bytefluo_test.cpp, contains many examples of use.
Here is another:

 #include "bytefluo.h"

 int main()
 {
     const unsigned char bytes[8] = {
         0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77
     };
     bytefluo buf(bytes, bytes + sizeof(bytes), bytefluo::big);
     uint32_t x;
     buf >> x;  // x = 0x00112233
     buf.set_byte_order(bytefluo::little);
     buf >> x;  // x = 0x77665544
 }


3.1  OVERVIEW

The important things to know about bytefluo are

 - When you create a bytefluo object you tell it what data it will
   provide access to, and the initial byte order for any scalar
   reads that will be performed.
 - The bytefluo object does not hold a copy of the given data; it
   merely manages access to that data.
 - The bytefluo object maintains a cursor, which is set initially
   at the start of the managed data. All reads begin at the current
   cursor location and advance the cursor by the size of the data
   read.
 - If a requested read or seek would take the cursor outside the
   bounds of the managed data the read or seek does not take place,
   the state of the bytefluo object remains unchanged and the
   bytefluo object throws a bytefluo_exception object, which is
   derived from std::runtime_error.
 - Assuming that the bytefluo object is managing access to valid
   memory, we provide either the strong guarantee or the nothrow
   guarantee for all operations.
 - The bytefluo implementation is entriely within the header file,
   bytefluo.h. To use the class just #include "bytefluo.h".


3.2  DETAIL

3.2.1  CONSTRUCTION

 bytefluo(const void * begin, const void * end, byte_order bo)

The bytefluo object will manage access to the bytes in the half open
range [begin, end). Multi-byte scalars will be read assuming the given
byte order 'bo'. 'bo' must be one of

 bytefluo::big     most-significant byte has lowest address
 bytefluo::little  least-significant byte has lowest address

Throws bytefluo_exception if begin > end or if 'bo' is neither big
nor little.

Example:
 uint8_t foo[99];
 bytefluo buf(foo, foo + sizeof(foo), bytefluo::big);


3.2.2  DEFAULT CONSTRUCTION

 bytefluo()

The bytefluo object will manage access to the empty half open range
[0, 0), with scalar reads defaulting to big-endian. Throws nothing.

Example:
 bytefluo buf;
 size_t siz = buf.size(); // siz = 0
 bool at_end = buf.eos(); // at_end = true


3.2.3  CONSTRUCTION FROM VECTOR

 template <class item_type>
 bytefluo bytefluo_from_vector(
    const std::vector<item_type> & vec,
    bytefluo::byte_order bo)

This free function is provided as a convenient shorthand for
bytefluo(&vec[0], &vec[0] + vec.size(), bo) for a non-empty vector
and bytefluo(0, 0, bo) for an empty vector.

NOTE that any operations on the vector that might change the value
of &vec[0] or vec.size() (e.g. adding elements to the vector may
cause the vector to reallocate its buffer) will silently invalidate
the associated bytefluo object so that attempts to read the vector
contents via that bytefluo object may cause a CRASH.

Example:
 std::vector<uint8_t> vec(99);
 bytefluo buf(bytefluo_from_vector(vec, bytefluo::big));


3.2.4  SET DATA RANGE

 bytefluo & set_data_range(const void * begin, const void * end)

The bytefluo object will manage access to the bytes in the half open
range [begin, end). Throws bytefluo_exception if begin > end.

The cursor is set to the beginning of the range. The current
byte-order setting is unaffected. Returns *this.

Example:
 bytefluo buf;
 size_t siz = buf.size(); // siz = 0
 uint8_t foo[99];
 buf.set_data_range(foo, foo + sizeof(foo));
 siz = buf.size(); // siz = 99


3.2.5  SET BYTE ORDER

 bytefluo & set_byte_order(byte_order bo)

Specify the byte arrangement to be used on subsequent scalar reads.
'bo' must be one of

 bytefluo::big     most-significant byte has lowest address
 bytefluo::little  least-significant byte has lowest address

Throws bytefluo_exception if 'bo' is neither big nor little. The
current data range and cursor position are unaffected. Returns *this.

Example:
 bytefluo buf(...);
 buf.set_byte_order(bytefluo::big);


3.2.6  READ INTEGER SCALAR VIA operator>>()

 template <typename scalar_type>
 bytefluo & operator>>(scalar_type & out)

Read an integer scalar value from buffer at current cursor position.
The scalar is read assuming the byte order set at construction or
at the last call to set_byte_order(). [Cf. read_le() and read_be().]
The cursor is advanced by the size of the scalar read. Returns *this.

Throws bytefluo_exception if the read would move the cursor after
the end of the managed data range.

Example:
 bytefluo buf(...);
 uint16_t foo, bar;
 buf >> foo >> bar;  // read two successive shorts, foo followed by bar


3.2.7  READ INTEGER SCALAR VIA read_be() AND read_le() FUNCTIONS

 template <typename scalar_type>
 bytefluo & read_be(scalar_type & out)

 template <typename scalar_type>
 bytefluo & read_le(scalar_type & out)

Read an integer scalar value from buffer at current cursor position.
The scalar is read assuming big-endian byte order for read_be() and
little-endian byte order for read_le(), *regardless* of the byte order
set at construction or at the last call to set_byte_order(). [Cf.
operator>>().] The cursor is advanced by the size of the scalar read.
Returns *this.

Throws bytefluo_exception if the read would move the cursor after
the end of the managed data range.

Example:
 bytefluo buf(...);
 uint16_t foo, bar;
 // read big-endian foo followed by little-endian bar
 buf.read_be(foo).read_le(bar);


3.2.8  READ ARBITRARY NUMBER OF BYTES

 bytefluo & read(void * dest, size_t len)

Copy 'len' bytes from buffer at current cursor position to given
'dest' location. The cursor is advanced by the number of bytes
copied. The current byte order setting has no affect on this
operation. Returns *this.

Throws bytefluo_exception if the read would move the cursor after
the end of the managed data range.

Example:
 bytefluo buf(...);
 uint8_t foo[23];
 buf.read(foo, sizeof(foo));


3.2.9  MOVE THE CURSOR

 size_t seek_begin(size_t pos)
 size_t seek_current(long pos)
 size_t seek_end(size_t pos)

These functions move the cursor 'pos' bytes from stream beginning,
the current cursor location and the stream end respectively. They
all return the distance from buffer start to new cursor location.
seek_begin() and seek_end() require pos to be positive; seek_current()
may have a positive (move cursor toward end) or negative (move cursor
toward begin) actual parameter.

Throws bytefluo_exception if the move would put the cursor before
the beginning or after the end of the managed data range.

Example:
 bytefluo buf(...);
 size_t pos = buf.seek_end(3);  // cursor is 3 bytes from buffer end


3.2.10  TEST FOR END OF STREAM

 bool eos() const

Returns true if and only if the cursor is at the end of the stream.
Throws nothing.

Example:
 bytefluo buf(...);
 buf.seek_end(0);
 bool at_end = buf.eos();  // at_end = true


3.2.11  GET STREAM SIZE

 size_t size() const

Returns the number of bytes in the stream. Throws nothing.

Example:
 std::vector<unsigned char> v(99);
 bytefluo buf(bytefluo_from_vector(v, bytefluo::big));
 size_t siz = buf.size(); // siz = 99


3.2.12  GET CURSOR POSITION

 size_t tellg() const

Returns the distance from the buffer start to the current cursor
location. Throws nothing.

Example:
 bytefluo buf(...);
 buf.seek_begin(13);
 buf.seek_current(-3);
 size_t pos = buf.tellg();  // pos = 10


3.2.13 THE EXCEPTIONS

If something goes wrong the bytefluo object will throw a bytefluo_exception
object. You can catch this via the exception base class with

 catch (const std::runtime_error & e) {
   std::clog << e.what() << '\n';
 }

or directly with

 catch (const bytefluo_exception & e) {
   std::clog << e.what() << '\n';
 }

If you do the latter you can get access to the bytefluo exception id,
for example:

 catch (const bytefluo_exception & e) {
   std::clog << e.what() << '\n';
   if (e.id() == bytefluo_exception::attempt_to_read_past_end)
     . . .
 }

The exception ids and their symbolic names are

 1 null_begin_non_null_end
 2 null_end_non_null_begin
 3 end_precedes_begin
 4 invalid_byte_order
 5 attempt_to_read_past_end
 6 attempt_to_seek_after_end
 7 attempt_to_seek_before_beginning


4  LICENSE
 
 Distributed under the MIT License:

    MIT License

    Copyright (c) 2008,2009,2010,2016,2017 Anthony C. Hay

    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.

5  AUTHOR

 Anthony C. Hay
 March 2017
 anthony.hay.1@gmail.com