1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
@c Copyright (c) 2015-2026, The matio contributors
@c Copyright (c) 2011-2014, Christopher C. Hulbert
@c All rights reserved.
@c
@c Redistribution and use in source and binary forms, with or without
@c modification, are permitted provided that the following conditions are met:
@c
@c 1. Redistributions of source code must retain the above copyright notice, this
@c list of conditions and the following disclaimer.
@c
@c 2. Redistributions in binary form must reproduce the above copyright notice,
@c this list of conditions and the following disclaimer in the documentation
@c and/or other materials provided with the distribution.
@c
@c THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
@c AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
@c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
@c DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
@c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
@c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
@c SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
@c CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
@c OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
@c OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@chapter Introduction
@section About and Licensing
The @emph{matio} software contains a library for reading and writing MATLAB MAT
files. The @emph{matio} library (@emph{libmatio}) is the primary interface for
creating/opening MAT files, and writing/ reading variables.
This @emph{matio} software is provided with the Simplified BSD License
reproduced below. The license allows for commercial, proprietary, and open
source derivative works.
@verbatim
Copyright (c) 2015-2026, The matio contributors
Copyright (c) 2011-2014, 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.
@end verbatim
@section Incompatible Changes from 1.3
This version has changes that break compatibility with the 1.3 versions of the
@emph{matio} software. This section lists these changes and how existing code
should be modified to handle these changes.
@enumerate
@item dims field of matvar_t structure changed to size_t@tie{}*
@item MEM_CONSERVE preprocessor definition removed
@item BY_NAME and BY_INDEX renamed
@item Added @code{MAT_} prefix to enumerations of @code{matio_compression}
@item Changed name of structure for complex split-format data from
@code{struct ComplexSplit} to @code{struct mat_complex_split_t}
@item Changed name of sparse data structure from @code{sparse_t} to
@code{mat_sparse_t}.
@item Changed meaning of memory conservation for cell arrays and structures
@end enumerate
Each of these changes are described in the remaining sections, and as necessary
include recommendations to upgrade existing code for compatibility with this
version.
@subsection Type Change for Dimensions Array
The existing dims field of the @code{matvar_t} structure was an @code{int@tie{}*}
which limited the maximum size of a dimension to @math{2^{31}}. In version 1.5,
the type was changed to @code{size_t@tie{}*} which allows a variable of length
@math{2^{31}} on 32-bit systems, but @math{2^{64} - 1} on 64-bit system. To
upgrade to version 1.5, all existing code should ensure the use of @code{dims}
allows for @code{size_t}, and that any use of the @code{Mat_VarCreate} function
passes an array of type @code{size_t} and not @code{int}. Not upgrading to
@code{size_t} is likely to produce segmentation faults on systems where
@code{sizeof(size_t) != sizeof(int)}.
@subsection Removed Preprocessor Flag to Conserve Memory
Previous versions of the @emph{matio} library had a preprocessor macro
@code{MEM_CONSERVE} that was passed as an option to @code{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 @code{MAT_F_DONT_COPY_DATA}. A quick search/replace can
quickly upgrade any references to @code{MEM_CONSERVE}. Alternatively, since
@code{MAT_F_DONT_COPY_DATA} has the same value as @code{MEM_CONSERVE}, software
using @emph{matio} can simply define @code{MEM_CONSERVE} to 1.
@subsection Renamed Structure Field Lookup Enumerations
The @code{BY_NAME} and @code{BY_INDEX} enumerations are used by
@code{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 @emph{matio}
namespace and hopefully avoid conflicts, these have been renamed to
@code{MAT_BY_NAME} and @code{MAT_BY_INDEX}. A quick search/replace operation
should be able to correct existing code that uses the old names.
@subsection Memory Conservation with Cells and Structures
Previous versions of @emph{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 @emph{matio}, the fields/cell elements are not free'd if
the structure was created with the @code{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. @code{Mat_VarGetStructs},
@code{Mat_VarGetStructsLinear}).
|
