Michele De Stefano's C++ Utilities
Michele De Stefano's C++ Utilities Documentation

Introduction

This library contains a collection of several C++ utilities for pure C++ development as well as for building Python extensions.

Starting from the 2.0.0 release, a C++ 2011 conforming compiler is needed. Any build with the previous C++ standard is not supported anymore. An mds_utils Python package is also provided; it exposes some Boost uBLAS matrices and vectors to Python. It can be built and installed using the standard setuptools. It requires SWIG to be present on your system (the package has been developed and tested with SWIG 2.0.11). Actually, SWIG is the recommended tool to use when using the mds-utils library for building Python extensions. The objects exported by the mds_utils package can be easily reused by other extension modules. An example is shown in file ublas_pkg_usage.i. The documentation of the Python package is in docstrings. Once imported, type 

   help(mds_utils)

That will be your starting point into the documentation.

Features summary

MDS-UTILS provides:

  1. a tool for detecting machine endianity.
  2. utilities for the Boost uBLAS library. Amongst them, some type traits for detecting different uBLAS matrix types.
  3. some useful classes that allow to treat the old C FILE pointer as a C++ stream.
  4. C++ wrappers of the main Python objects, independent of those in Boost Python. Wrappers are provided also for NumPy arrays.
  5. C++ classes that help on treating Python file objects as C++ streams.
  6. a review and refactor of the indexing support in Python extensions. Now access in write mode is supported too.
  7. new C++ to-Python and from-Python converters for some Boost uBlas objects and for standard Python objects. These converters do not depend on Boost Python.
  8. a new sequence iterator that is able to wrap Python sequences and allows also to modify them. This feature does not depend on Boost.Python.
  9. the NDArrayIterator class, that wraps the Numpy C-API iterator and allows easy management of conversions to/from Numpy arrays.
  10. some SWIG interface files, for easy integration with SWIG extensions for Python.

Each class is a well-documented, small, easy to use and it should never be too difficult to learn to use it.
A large percentage of this library makes a heavy usage of the Boost C++ libraries: so, they must be installed on the system. It is assumed that the user is familiar with them.

How to use this documentation

This documentation is organized in modules. If you select the "Modules" link (either in the top tabs or into the side browser) you will find the list of the modules. Each module link expands into a list of files.

Each file is aimed to the solution of a particular group of problems and brings with it an entire group of classes and functions. Clicking on a file name gives access to the specific documentation and to the classes the file defines.

Generally, for each class or function, there is a brief usage example. It is strongly suggested first, to read the general description of a class, second, to jump directly to the usage example (just to have an idea of what can be done with the class), and, only as a last step, to go back and read the whole documentation of the methods and attributes, looking again at the example for a better understanding. This seems to be the fastest method for learning to use this library.

Release Notes

Release 2.1.1

  • FIxes small problems with the setup.py script for the mds_utils Python package: now NumPy include directory is automatically detected also when NumPy was manually installed.
  • Fixes bug into the mds_utils::python::numpy::NDArrayIterator class. When the array was composed by only one element, the check for equality between the start and past-the-end iterators returned true even if the two iterators were not equal by definition. Now the problem is fixed.

Release 2.1.0

  • Added a new wrapper class for NumPy 1D arrays (NumPy1DArray), that allows to treat a NumPy array as if it was a boost::numeric::ublas::vector.

Release 2.0.0:

  • The utilities for Python have completely been rewritten and are independent of Boost Python.
  • Support for random access of containers in Python extesions now allows write mode.
  • Added SWIG interface files for several C++ files.
  • Added a Python package exporting some Boost uBLAS objects.

Release 1.3.0:

  • Added python/sequence_iterator.hpp and python/conversion.hpp; sequence_iterator.hpp provides an iterator that is capable to scan Python sequences of homogeneous elements. It allows the developer to treat Python sequences as STL containers and allows also to modify the original Python sequence.
  • Added fixes to support Python versions greater or equal to 2.5.

Release 1.2.0:

  • Improved python/fileobj.hpp: now there are 3 helper file objects and they are copy-constructible. Derivation from boost::python::object has been mantained.
  • Added utilities for simple indexing support in Python extensions.
  • Added boost::python converters for some boost::numeric::ublas classes.

Release 1.1.0:

  • flush support added to FILE* devices.
  • added a new "python" namespace. Contains an object derived from boost::python::object that helps in using python file objects within python extensions written with Boost.Python.

Download

You can download mds-utils at the following link:

https://sourceforge.net/projects/mds-utils/

Installation Instructions

Basically, there is nothing to build, because this library is completely template based. All that you need is to place the mds_utils folder (within the include folder) where you prefer.
For Unix/Linux users, installation is facilitated by the GNU build system. So, basically, the usual sequence configure, make, make install will properly install the library.
Have a look at the INSTALL file.

If you have downloaded the development version from the repository and you use a Linux OS you first have to issue "autoreconf -i" into the main folder. This will create the proper configure and Makefile.in files. Then you will be able to follow the previous steps.

If you want to build the mds_utils Python package you have to enter the python directory and issue the command 

   python setup.py build

The previous command uses SWIG, so it needs to be installed on the system. The package has been developed and tested with SWIG 2.0.11 and I don't know how it behaves with other SWIG versions. The mds_utils Python package uses also NumPy and SciPy, so these packages must be present on the system together with their development headers. For installing the package issue 

   python setup.py install

For detailed instructions on the build process, from within the python directory, issue the command 

   python setup.py --help

and you will be able to see build and installation instructions. It is recommended to perform the installation of this Python package in two steps, as explained above. First run the setup.py script with the build option. Then run it again with the install option. This two-stage installation is required for working around a bug in Python distutils.

If you have manually installed the Boost C++ libraries, you can export the BOOST_DIR environment variable on the shell, assigning to it the full path to the Boost root installation. The setup.py script will detect the BOOST_DIR variable and use it.

Building the documentation

To build documentation you need doxygen (so, install it if you don't have). Go into the sources root directory and type 

   doxygen

this will create the "doc" directory, containing the whole documentation.

License

mds_utils is distributed under the MIT license (see the LICENSE file).

Author
Michele De Stefano
Date
October 2nd, 2016