Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/martinmoene/array_view2d

A simple 2D view on an array or vector for C++98 and C++11
https://github.com/martinmoene/array_view2d
Last synced: 2 months ago
JSON representation
A simple 2D view on an array or vector for C++98 and C++11
Host: GitHub
URL: https://github.com/martinmoene/array_view2d
Owner: martinmoene
License: bsl-1.0
Created: 2015-05-07T06:01:20.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2015-05-15T09:31:16.000Z (over 9 years ago)
Last Synced: 2023-03-25T16:01:03.565Z (almost 2 years ago)
Language: C++
Homepage:
Size: 391 KB
Stars: 5
Watchers: 2
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE_1_0.txt
Awesome Lists containing this project

README

        array_view2d – 2D view on array or vector for C++98 and C++11 [![Build Status](https://travis-ci.org/martinmoene/array_view2d.png?branch=master)](https://travis-ci.org/martinmoene/array_view2d)

=========================================================================

*array_view2d* is a two-file header-only library to provide a two-dimensional view on a one-dimensional array or vector. The library is inspired on array_view [1] and can be used with C++98 and later and with Visual C++ 6 (VC6). With C++11 *array_view2d* provides a unified way to reference an array or vector (see [example](example/02-reference-c++11.cpp)).  

**Contents**  

- [Example usage](#example-usage)

- [In a nutshell](#in-a-nutshell)

- [License](#license)

- [Dependencies](#dependencies)

- [Installation](#installation)

- [Synopsis](#synopsis)

- [Reported to work with](#reported-to-work-with)

- [C++ standard proposals on array views](#c-standard-proposals-on-array-views)

- [Notes and references](#notes-and-references)

Example usage

-------------

```C++

#include "array_view2d.hpp"

#include "array_view2d_output.hpp"

#include 

struct packet

{

    std::size_t dim;

    std::vector data;

};

packet produce()

{

    return { 3, { 0,0, 1,1, 2,2 } };

}

int main()

{

    auto pack = produce();

    auto view = nonstd::make_view2d( pack.data, pack.dim );

    for ( auto pos : view.as_rows() )

    {

        std::cout << pos << "\n";

    }

}

```

### Compile and run

```

prompt>g++ -Wall -std=c++11 -o example.exe example.cpp && example

{ 0, 0 }

{ 1, 1 }

{ 2, 2 }

```

Here is [the same example expressed in C++98](example/01-iterate-c++98.cpp).

In a nutshell

-------------

**array_view2d** ...

**Features and properties of array_view2d** are ease of installation (single header), ...

**Not provided** are ...

License

-------

*array_view2d* uses the [Boost Software License](LICENSE_1_0.txt).

 

Dependencies

------------

*array_view2d* has no other dependencies than the [C++ standard library](http://en.cppreference.com/w/cpp/header).

Installation

------------

*array_view2d* is a two-file header-only library. Put `array_view2d.hpp` and `array_view2d_output.hpp` directly into the project source tree or somewhere reachable from your project.

Synopsis

--------

**Contents**  

[Types in namespace nonstd](#types-in-namespace-nonstd)  

[Interface of *array_view2d*](#interface-of-array_view2d)  

[Algorithms for *array_view2d*](#algorithms-for-array_view2d)  

[Macros to control error reporting](#macros-to-control-error-reporting)  

### Types in namespace nonstd

| Purpose          | Type | Object |

|------------------|------|--------|

| View             | template< typename T >
class array_view2d; | |

| Bound checking   | struct check_bound_t; | check_bound_t check_bound; |

| Error reporting  | see [this section](#macros-to-control-error-reporting) |   |

### Interface of *array_view2d*

| Kind              | Method                                       | Result |

|-------------------|----------------------------------------------|--------|

| Construction      | **array_view2d**() | A blind eye |

|              | **array_view2d**(...)
C-array, std::array, std::vector, std::initializer_list | A view |

| Iteration         | **begin**(), **end**() | An iterator |

|              | **cbegin**(), **cend()** |   |

| Iteration,reverse | **rbegin**(), **rend**() |   |

|              | **crbegin**(), **crend**() |   |

| Iteration, row    | **as_rows**() | [A forward-iteratable](https://www.sgi.com/tech/stl/ForwardIterator.html) |

| Access            | **empty**() | True if no elements |

|              | **size**(), **length**() | Number of elements |

|              | **max_size**() | Number of elements |

|              | **row_size**() | Number of elements in a row |

|              | **rows**() | Number of rows |

| Access, content   | **operator[]**( n ) | Element|

|              | **at**( n ) | Element, bound checked |

|              | **data**() | Pointer to first element |

|              | **front**() | First element |

|              | **back**() | Last element |

| Slicing           | **slice**( index, count ) | [A subview](http://en.wikipedia.org/wiki/Array_slicing) |

|              | **slice_before**( index ) |   |

|              | **slice_from**( index ) |   |

| Slicing, iterator | **slice**( first, last ) |   |

|              | **slice_before**( pos ) |   |

|              | **slice_from**( pos ) |   |

| Slicing, checked  | **slice**( check_bound, index, count ) |   |

|              | **slice_before**( check_bound, index ) |   |

|              | **slice_from**( check_bound, index ) |   |

| Slicing, iterator | **slice**( check_bound, first, last ) |   |

|              | **slice_before**( check_bound, pos ) |   |

|              | **slice_from**( check_bound, pos ) |   |

| Row access        | **row**( n ) | A view on row elements |

| Row, checked      | **row**( check_bound, n ) |   |

### Algorithms for array_view2d

| Kind              | Function                          | Result |

|-------------------|-----------------------------------|--------|

| Equality          |                              |   | 

| ==                | **operator==**( view1, view2 )    | True if equal | 

|              | **operator==**( view, container ) |   | 

|              | **operator==**( container, view ) |   | 

| !=                | **operator!=**( view1, view2 )    | True if not equal | 

|              | **operator!=**( view, container ) |   | 

|              | **operator!=**( container, view ) |   | 

| Other algorithms  |   |   | 

| Create            | **make_view2d**(...)
C-array, pointer and count, iterator pair, 
std::array, std::vector, std::initializer_list | A view | 

| Convert           | **to_vector**(...)
view and optional allocator | A std::vector  | 

### Macros to control error reporting

*array_view2d* can perform sanity checks on construction and perform bound checking on methods such as `row()`. Sanity checks in constructors use the same mechanism as implicit bound checks explained below.

*array_view2d* provides two approaches to bound checking: 

- explicitly when calling `row(check_bound, n)` and 

- implicitly when using `row(n)`.

The explicit variants with the `check_bound_t` parameter throw a `std::out_of_range` exception when a parameter is out of bound.

The implicit variants without the `check_bound_t` parameter, behave in the following way:

- Assert that a parameter is within bounds; this is the default for debug builds.

- Throw an exception when a parameter violates its bounds, see `av_FEATURE_EXPECT_THROWS`.

- Do not check for bound violation; this is the default for release build, see `av_FEATURE_EXPECT_NOP`.

- Perform a user-specified action, see `av_EXPECT`.

The following macros control boundary checking behaviour for methods that don't use **check_bound_t**.

-Dav_FEATURE_EXPECT_NOP=0  

Define this to 1 to turn off boundary checking assertions. Default is 0.

-Dav_FEATURE_EXPECT_ASSERTS=1  

At default, boundary checks assert. Default is 1.  

Turn it off by defining av_FEATURE_EXPECT_NOP.  

Use exceptions instead by defining av_FEATURE_EXPECT_THROWS.  

Note that the assertion mechanism is active in debug builds, not in release builds.

-Dav_FEATURE_EXPECT_THROWS=0  

Define this to 1 to activate boundary checking exceptions. Default is 0.  

When an out of bounds error occurs, a `std::out_of_range` exception is thrown.  

When a sanity check fails, a `std::runtime_error` exception is thrown.

-Dav_EXPECT( expr, excpt, note )  

Define this macro to specify boundary checking behaviour, e.g.:  

```

#define av_EXPECT( expr, excpt, note )  assert( ( expr ) && note )

```

Defining av_EXPECT deactivates macros av_FEATURE_EXPECT_NOP, av_FEATURE_EXPECT_ASSERTS and av_FEATURE_EXPECT_THROWS.

Reported to work with

---------------------

*array_view2d* is reported to work with the following compilers: 

- Visual C++ 6 SP6 (VS6), VC10, (VS2010), VC11 (VS2012), VC12 (VS2013)

- GNUC 4.8.1 with -std=c++98, -std=c++03, -std=c++11, -std=c++1y 

- clang 3.4 with -std=c++03, -std=c++11 (on Travis)

C++ standard proposals on array views

-------------------------------------

At the time of writing there are two proposals for the C++ standard on providing multidimensional views on arrays [2-4]. These proposals take a general approach to dimensionality, whereas *array_view2d* restricts itself to unstrided rows and slices.

Notes and references

--------------------

[1] [array_view](https://github.com/rhysd/array_view).  

[2] [N3851: Multidimensional bounds, index and array_view](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3851.pdf) (PDF).  

[3] [N4346: Multidimensional bounds, index and array_view, revision 6](https://isocpp.org/files/papers/N4494.html).  

[4] [N4355: Shared Multidimensional Array with Polymorphic Layout](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4355.pdf) (PDF).