File: intro.texi

package info (click to toggle)
libmatio 1.5.2-3
  • links: PTS, VCS
  • area: main
  • in suites: jessie-kfreebsd
  • size: 24,336 kB
  • ctags: 775
  • sloc: sh: 101,115; ansic: 22,148; makefile: 222
file content (117 lines) | stat: -rw-r--r-- 6,606 bytes parent folder | download
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
@c Copyright (C) 2011-2013   Christopher C. Hulbert
@c
@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,
@c       this list of conditions and the following disclaimer.
@c
@c    2. Redistributions in binary form must reproduce the above copyright
@c       notice, this list of conditions and the following disclaimer in the
@c       documentation and/or other materials provided with the distribution.
@c
@c THIS SOFTWARE IS PROVIDED BY CHRISTOPHER C. HULBERT ``AS IS'' AND ANY EXPRESS
@c OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
@c OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
@c EVENT SHALL CHRISTOPHER C. HULBERT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
@c INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
@c (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
@c LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
@c ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
@c (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
@c 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 2011-2013 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 CHRISTOPHER C. HULBERT ``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 CHRISTOPHER C. HULBERT 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 compatability 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 *
@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 compatability with this
version.

@subsection Type Change for Dimensions Array
The existing dims field of the @code{matvar_t} structure was an @code{int *}
which limited the maximum size of a dimension to @math{2^{31}}. In version 1.5,
the type was changed to @code{size_t *} 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}).