Using the C++ Math Library

Stream I/O Format Definitions 

The MATLAB C++ Math Library input and output formats strongly resemble their interpreted MATLAB counterparts. The array output format conforms to the rules for array input, which means that arrays written to a stream using << can be read in from a stream using >>.

Note    The >> and << operator implementations do not read and write MAT-files. Use the functions load() and save() to read and write MAT-files. See the section Importing and Exporting MAT-File Data for more information.

In the MATLAB C++ Math Library, special input characters describe the shape of the array. The [ and ] characters (brackets) enclose an array definition. The { and } characters (braces) enclose a cell array definition. Within the brackets or braces, the contents of the array appear in row-major order. A semicolon (;) separates rows.

The following table lists the syntax elements in the format definition.

Note    The >> operator implementation cannot read cell arrays, sparse arrays, and structures.

Table 8-1: Elements of mwArray Input/Output Syntax 

Syntax Element	Definition	Example
[]	Encloses array definition	[ 1 2 ]
{}	Encloses a cell array definition	{[1 2] 'Eric'}
e	Indicates scientific notation	1e7
.	Indicates floating-point number	1.879
-	Indicates negative number or exponent	-1.3e-8
+	Separates complex and imaginary parts	1+2i
i	Indicates complex number	1+2i
'	Encloses a string	'abcd'
.fieldname	Identifies a field in a structure
;	Separates rows	[ 1 2 ; 3 4 ]
*	Separates optional scaling factor from array	1e-10 * [ 1 2 ]
whitespace	Separates array elements	[ 1 2 ]

Legal Array Elements

• Integers
• Floating-point numbers
• Complex numbers
• Strings

You can also specify a scaling factor that modifies the values in an mwArray containing integers, floating-point numbers, or complex numbers. A scaling factor applies equally to all elements in the array and is used to enter very small or very large values.

Length of Input Array

The only restriction on the length of the input array is the amount of memory available; the input mechanism imposes no restrictions of its own.

How Whitespace Is Interpreted

• The input operator ignores additional space and tab characters between array elements.
• The input operator ignores whitespace between array definitions.

Characteristics of Input Files

Input files must be in ASCII rather than binary format. An input file may contain multiple array definitions. Whitespace between array definitions is ignored.

Differences between MATLAB and the C++ Math Library

There are differences between the input accepted by MATLAB and the MATLAB C++ Math Library. MATLAB input files permit the use of MATLAB mathematical expressions in array definitions. The MATLAB C++ Math Library does not support the use of functions or operators in input streams.

For example, the MATLAB C++ Math Library does not support this:

[ (1 + 2) 7; 4 5]

MATLAB does.

Specifying an Array for Input 

1. Begin the array with a left bracket [.
2. List the elements in the first row of the array in row-major order.
3. Separate the first row from the second row with a semicolon (;).
4. Repeat steps 2 and 3 for each row in your array.
5. Close the array with a right bracket ]. However, do not end the last row with a semicolon.
   
   

   Table 8-2: Input Syntax for an mwArray Containing Integers

   Input	Array	Array Type
   [ 1 2 ; 3 4 ]	1 2 3 4	2-by-2 square array
   [ 1 2; 3 4; 5 6 ]	1 2 3 4 5 6	3-by-2 rectangular array

Table 8-3: Input Syntax for an mwArray Containing Floating Point Numbers 

Input	Array	Array Type
[ 1.4 2.5 3.2 ]	1.4 2.5 3.2	1-by-3 vector
[ 3.14e2 2.73e4; 1.73e3 1.41e2 ]	314 27300 1730 141	2-by-2 square array. Note use of scientific notation in input.

Table 8-4: Input Syntax for an mwArray Containing Complex Numbers 

Input	Array	Array Type
[ 1+3i 2+7i ; 9-5i 8+4i ]	1+3i 2+7i 9-5i 8+4i	2-by-2 complex square array

Table 8-5: Input Syntax for an mwArray Containing Strings 

Input	Array	Array Type
'abcd'	abcd	1-by-4 character array Equivalent to ['abcd']
[ 'abcd'; 'efgh'; ]	abcd efgh	2-by-4 character array
'it''s'	it's	1-by-4 character array that includes an escaped ' character. This array is written out as 'it''s'.

Table 8-6: Input Syntax that Includes a Scaling Factor 

Input	Array	Array Type
1.0e-7 * [ 0.1 0.2 ; 0.3 0.4 ]	0.00000001 0.00000002 0.00000003 0.00000004	2-by-2 square array. Note use of scaling factor in input.

Table 8-7: Illegal Input Syntax 

Input	Array	Array Type
[ 1 ; 2 3 ]	Illegal. All rows must be same length.	Invalid array
[ (1 + 2) 7; 4 5]	Illegal. Using mathematical expressions in input files is not supported.	Invalid array

Using a Data File As Input

Let an input data file, data, contain the following array definition:

[ 1 2 3 ; 4 5 6 ]

Assume that a program called "io" reads an array from standard input and then writes it to standard output.

Passing the file data to the program io

io < data

produces this output:

[
    1 2 3 ;
    4 5 6
]

Example - Array Stream I/O (ex1.cpp)

Using Stream I/O to Files