cnorxz/README.md

71 lines
3.4 KiB
Markdown
Raw Normal View History

2021-08-03 11:20:09 +02:00
# Container with Native Operation Routines by XZ (CNORXZ)
2018-11-26 15:22:52 +01:00
## Description
2023-11-01 18:50:04 +01:00
This library provides a framework for handling multi dimensional containers, their meta data, and several kinds of operations on one or more of them.
2018-11-26 15:22:52 +01:00
## Build instructions
The library can be installed by the following procedure (`gtest` required):
```bash
2021-08-03 11:20:09 +02:00
git clone git@git.f3l.de:chizeta/cnorxz.git <SOURCE_DIR>
2018-11-26 15:22:52 +01:00
cd <BUILD_DIR>
cmake -DCMAKE_INSTALL_PREFIX:PATH=<INSTALL_DIR> <SOURCE_DIR>
make install
```
2023-11-01 18:50:04 +01:00
To build the doxygen:
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
```bash
cd <SOURCE_DIR>/doc/doxy
doxygen Doxyfile
```
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
## Linking
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
To use the features of the libraries one has to include `cnorxz.h` and link against the `libcnorxz.so`.
The tools of the library are accessible within the namespace `CNORXZ`.
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
## Documentation
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
(Also consider doxygen)
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
### Basics
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
This library consists of several building blocks. For simple usage, the most important building blocks are [ranges](#ranges), [indices](#indices) and [array types](#arrays).
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
#### Ranges
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
Basically, a *range* defines a meta data space. There are several range class types, which are derived from the abstract base class `RangeBase`. Ranges can only be created by the corresponding factory and exclusively exist within a shared pointer; they cannot be copied. Available range class types are:
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
* `CRange` : Classic one-dimensional range. The meta data space is simply given by integer numbers running from `0` to `size-1`. The range size is determined at runtime.
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
* `URange<MetaT>` : Generic One-dimensional range. The meta data space is user defined, the meta data type is passed as template argument. The range size is determined at runtime.
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
* `SRange<MetaT,S>` : The same as `URange`, but the range length is fixed at compile time by the template integer variable `S`.
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
* `PRange<RangeT>` : Partial or sub-range, i.e. a user-defined subspace of another range. The type of the range must be known at compile time, the subspace can be specified at runtime.
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
* `MRange<RangeTs...>` : Multi-dimensional range, spanned by a set of ranges. The number of ranges, as well as their types must be known at compile time.
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
* `YRange` : The same as `MRange` but the number of ranges and their types can be specified at runtime.
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
#### Indices
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
For each range type there is a corresponding index type (`CIndex`, `UIndex<MetaT>`, `SIndex<MetaT,S>`, `PIndex<IndexT>`, `MIndex<IndexTs...>`, `YIndex`). They act as const iterators on the ranges and are a crucial component to define operations on containers. In contrast to the ranges, all index types must be known at compile time (static polymorphism, `IndexInterface<Index,MetaT>`).
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
Apart from range specific indices, there exist also special indices:
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
* `DIndex` : Dynamic index wrapper, for the case that the index type cannot be determined at compile time.
2019-01-16 10:23:18 +01:00
2023-11-01 18:50:04 +01:00
* `AIndex<T>` : Array index. Const iterators pointing to the data of an array-type object with data type `T`.
2019-01-16 10:23:18 +01:00
2023-11-01 18:50:04 +01:00
* `BIndex<T>` : The same as `AIndex`, but not const.
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
#### Arrays
2018-11-26 15:22:52 +01:00
2023-11-01 18:50:04 +01:00
Finally, there are the container classes (arrays), which are derived from `CArrayBase<T>` (const) or `ArrayBase<T>` for a given data type `T`. All arrays are defined on a range, their data can be accessed or iterated over using suitable indices. The array-type actually containing data is called `MArray<T>`. Moreover, there exist array-types that do not contain data, but view the data of other arrays or at least parts of the data. These are called `CSlice<T>` (const view) or `Slice`.
2018-11-26 15:22:52 +01:00