What is the Matrix - Part 3 - Streaming

this article was originally posted on CodeGuru in 2003 and has been copied here for archival purposes (and to fix some broken links and tidy up the code formatting)

Introduction #

The Matrix is a small C++ utility class that is distributed in a single header file. It simplifies working with arrays. Source code and a small demo project in GitHub.

This is the third and last article on the different features of the Matrix. In the previous article, I described how to use the Matrix to simplify COM marshalling with VARIANTs and SAFEARRAYs. In this article, I will explain how to use stream operators to insert data into a Matrix.

Streaming #

The following code shows how to create a basic two-dimensional array

CMatrix<int> matrix ;
matrix.cell(0,0)=100 ;
matrix.cell(1,0)=200;
matrix.cell(0,1)=300;
matrix.cell(1,1)=400;

This code looks a little verbose. I'm sure you will agree that the following code is a much preferable way of inserting data...

CMatrix<int> matrix ;
matrix << move ( 0,0 ) << 100
       << move (1,0 ) << 200
       << move (0,1 ) << 300
       << move (1,1 ) << 400 ;

Here, the 'move' is an internal stream operator. It simply moves the internal cursor of the matrix so that the next item streamed in will be placed at this location. The 'move (0,0)' moves the cursor to 0,0 in the Matrix and the value '100' is inserted in the cell.

Similar to 'move' is 'offset'. Here is an example of its use...


CMatrix<int> matrix ;
matrix << move ( 5,5 ) << 100
       << move (1,0 )  << 200
       << move (0,1 )  << 300
       << move (1,1 )  << 400 ;
 
matrix << move(5,5 )    << "cell: 5,5"
       << offset(-1,-1) << "cell: 4,4"
       << offset(2,2)   << "cell: 6,6" ;

Offset simply offsets the internal cursor by the amount specific (in x,y format).

Bookmarks #

Bookmarks allow you to set an anchor within the Matrix. All operations performed after setting a bookmark are relative to that bookmark. A bookmark's properties are its name and its X & Y co-ordinates. Imagine you had a 10 by 10 Matrix and wanted the centre of the Matrix to be the point from which all references are made...

matrix.addMarker(L"middle", 5,5 ) ;
matrix  << bookmark(L"middle")  << "middle"
        << move (1,1)           << "cell: 6,6" ;

The move to position 1x and 1y in the above code will actually move to position 6x and 6y. All operations are relative to the last bookmark.

One important thing to remember when using bookmarks is to clear the bookmark when you've finished with it. If you were to share your Matrix or pass it to a function to read data, the read operations would be performed relative to the last bookmark. To clear the bookmark, simply stream in an empty bookmark like so...

matrix << bookmark() ;

Extensibility #

It is possible to extend the basic stream operators found in the Matrix. For example, you could 'plug-in' an operator that performs a calculation on each number you stream in, for example...

matrix << multiplier(2) << 4 ; // would store 8
matrix << multiplier(5) << 2 ; // would store 10

An article describing how to extend the operators and the Matrix itself could be the topic of a future article. I'll base this decision on the feedback and comments that are left.

Conclusion #

Hopefully, this article has shown you how to use stream operators with the Matrix class.

utilities c++ matrix-utility

🙏🙏🙏

Since you've made it this far, sharing this article on your favorite social media network would be highly appreciated 💖! For feedback, please 🦋 ping me on Bluesky! 🦋

Leave a comment

Comments are moderated, so there may be a short delays before you see it.

Published