README for cxx-useful

#+Last Update: 2014-12-22@13:37

1. What’s this?

The main purpose of this repository is for me to play around with C++ class designs, and other goof-off type stuff.

1-1. Can I edit your stuff?

Sure, go ahead. Hopefully, it is useful for you; I’m doubtful though.

1-2. Is this in the public domain?

Each file will clearly state if it is public domain or not. I won’t blanket release things. If a file does NOT, assume BSD license.

2. Install

Generally, I try to make these kinds of files header-only so just make them available in your include path.

2-1. Requirements

A C++ compiler; I use GCC 4.6+.

3. Features

3-1. Cyclic Iterator

The Cyclic Iterator is a wrapper for a region of iterable data, and circulates through the region in a familiar fashion (ie: from beginning to end-1, ad infinitum). It provides many of the familiar iterator constructs (operator+, operator*, operator-, operator++, operator–, etc.), and provides various iterator traits and typedefs making it suitable for use in various standard library functions. It does not conform perfectly to all of the iterator requirements, so YMMV.

An important note is that the cyclic iterator assumes that the beginning and end iterators are always valid. If either one could become invalid (via, for instance, an insert or erase on the underlying container), then the cyclic_iterator is also invalidated.

using cxx_utils::iterator::cyclic_iterator;

3-1-1. Ring Buffers

Because of the way the cyclic_iterator works, it is possible to pre-allocate a certain sized std::vector or std::list, and use the cyclic_iterator to create either a forward ring buffer (using .begin() and .end()) or a reverse ring buffer (using .rbegin() and .rend()). Effectively, any container which offers these kinds of semantics can be used (including a map, if you can figure out how the semantics on that would work).

Since the cyclic_iterator does not modify the structure of the underlying container, it should be safe to use with any standard based container (but, again, YMMV). Included is an example in the ring_buffer_ex.cpp file.

3-1-2. Moving Average ‘filter’

Since we can actually create a ring buffer, it’s possible to make a ring-buffer of a certain size, and use a std::accumulate, plus simple division to create a quick ‘n dirty (albeit, probably not optimally efficient) moving average filter.

This is detailed in the moving_average.cpp file.

3-2. Print Vector

Print vector is a handy utility function for printing a simple vector to the screen using nothing more than the std::ostream_iterator. Additionally, the print vector function includes a handy ability to change the delimiter using setdelim() with a character value.

The print vector tries very hard to make the output look smooth.

using namespace cxx_utils::io;

3-3. Saturation Iterator

The Saturation Iterator is a wrapper for a region of iterable data, and will ‘saturate’ by failing to advance when reaching the end() or begin() container region. Because the saturation iterator takes the range of [ =begin= .. =end= ) it can be used on sub-region of a particular container. Be mindful that it does not check the validity of the underlying iterators / container; anything which would invalidate an iterator will invalidate any corresponding saturation iterator.

using cxx_utils::iterator::saturation_iterator;

3-4. File Descriptor streambuf

The fd_streambuf provides a POSIX-to-stdc++ bridge by providing a way of accessing a standard C file descriptor (which is somehow not part of standard C++… go figure)

Since different operating systems treat things like sockets differently, this won’t be the best way of hooking a TCP/SCTP stream up to a standard C++ stream. On the otherhand, it does work and allows extension for a socket streambuf.

using cxx_utils::io::fd_buffer;

3-4-1. Process Input Stream

A pistream is creating by opening a process via the appropriate popen call and hooking up to the underlying file number. The pistream allows reading process output data.

using cxx_utils::io::pistream;