Introduction
************

About and Licensing
===================

The matio software contains a library for reading and writing MATLAB MAT files. The matio library (libmatio) is the primary interface for creating/opening MAT files, and writing/ reading variables.

This matio software is provided with the Simplified BSD License reproduced below. The license allows for commercial, proprietary, and open source derivative works.

Copyright (c) 2011-2021, Christopher C. Hulbert
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

Incompatible Changes from 1.3
=============================

This version has changes that break compatibility with the 1.3 versions of the matio software. This section lists these changes and how existing code should be modified to handle these changes.

 1. dims field of matvar_t structure changed to size_t *

 2. MEM_CONSERVE preprocessor definition removed

 3. BY_NAME and BY_INDEX renamed

 4. Added MAT_ prefix to enumerations of matio_compression

 5. Changed name of structure for complex split-format data from struct ComplexSplit to struct mat_complex_split_t

 6. Changed name of sparse data structure from sparse_t to mat_sparse_t.

 7. Changed meaning of memory conservation for cell arrays and structures

Each of these changes are described in the remaining sections, and as necessary include recommendations to upgrade existing code for compatibility with this version.

Type Change for Dimensions Array
--------------------------------

The existing dims field of the matvar_t structure was an int * which limited the maximum size of a dimension to 2^31. In version 1.5, the type was changed to size_t * which allows a variable of length 2^31 on 32-bit systems, but 2^64 - 1 on 64-bit system. To upgrade to version 1.5, all existing code should ensure the use of dims allows for size_t, and that any use of the Mat_VarCreate function passes an array of type size_t and not int. Not upgrading to size_t is likely to produce segmentation faults on systems where sizeof(size_t) != sizeof(int).

Removed Preprocessor Flag to Conserve Memory
--------------------------------------------

Previous versions of the matio library had a preprocessor macro MEM_CONSERVE that was passed as an option to Mat_VarCreate to tell the library to only store a pointer to the data variable instead of creating a copy of the data. Copies of scalars or small arrays are not critical, but for large arrays is necessary. In version 1.5, this macro has been changed to the enumeration value MAT_F_DONT_COPY_DATA. A quick search/replace can quickly upgrade any references to MEM_CONSERVE. Alternatively, since MAT_F_DONT_COPY_DATA has the same value as MEM_CONSERVE, software using matio can simply define MEM_CONSERVE to 1.

Renamed Structure Field Lookup Enumerations
-------------------------------------------

The BY_NAME and BY_INDEX enumerations are used by Mat_VarGetStructField to indicate if the field is retrieved by its name, or by its index in the list of fields. To bring these into a matio namespace and hopefully avoid conflicts, these have been renamed to MAT_BY_NAME and MAT_BY_INDEX. A quick search/replace operation should be able to correct existing code that uses the old names.

Memory Conservation with Cells and Structures
---------------------------------------------

Previous versions of matio would still free fields of structures and elements of cell arrays even if created with memory conservation flag set. In the latest version of matio, the fields/cell elements are not free'd if the structure was created with the MAT_F_DONT_COPY_DATA flag. This is useful if the fields/elements are referenced by another variable such as the case when they are indices of a larger array (i.e. Mat_VarGetStructs, Mat_VarGetStructsLinear).