WHERE returns byte offsets to the variables in a -v6 MAT-file.
The output from WHERE is similar to that of WHOS but can be used to map
variables in a a MAT-file and therefore to read/write to them using
fread/fwrite or memmapfile.
WHERE can be used on Level 5 & 7 MAT-files but only maps those variables
stored in Level 5 format up to -v6.
Gzip compressed data saved with SAVE -v7 will be skipped over and not
mapped.
Files saved with SAVE -v7.3 (introduced in R2006b) presently
cause WHERE to terminate.
Examples:
WHERE(FILENAME),
WHERE(FILENAME, VARNAME)
and WHERE(FILENAME, VARNAME, FIELD1/PROP1, FIELD2/PROP2....)
display the results
S=WHERE(FILENAME)
S=WHERE(FILENAME, VARNAME, FIELD1/PROP1, FIELD2/PROP2....)
S=WHERE(FILENAME, VARNAME)
[S,SWAP]=WHERE(FILENAME)
[S,SWAP]=WHERE(FILENAME, VARNAME)
[S,SWAP]=WHERE(FILENAME, VARNAME, FIELD1/PROP1, FIELD2/PROP2....)
SWAP is set to 1 if the endian order of the file is different from that
of the host computer (0 otherwise).
S=WHERE(FILENAME, TAGOFFSET)
[S, SWAP]=WHERE(FILENAME, TAGOFFSET)
return information about the variable at the supplied tag offset. The
tag offset would normally be derived from a previous call to WHERE.
FILENAME and VARNAME are strings
If VARNAME is specified, only information relating to that variable will
be returned. If field/property names are not specified, wildcards ('*')
can be used as with WHOS.
WHERE produces a structure output (S) similar to WHOS but with
additional fields as described below
For a standard MATLAB matrix class:
S = WHERE(...) returns a structure with the fields:
name -- variable name
size -- variable size
bytes -- number of bytes allocated for the array
class -- class of variable
global -- logical indicating whether variable is global
sparse -- logical indicating whether value is sparse
complex -- logical indicating whether value is complex
nesting -- struct with the following two fields:
function -- name of function where variable is defined
level -- nesting level of the function
flags -- 8 bit uint: currently indicates complex, global, logical
and persistent data - see MAT-file documentation
TagOffset -- the offset into the file to the Tag for this
variable
DataOffset -- a cell containing a structure with a field
'.DiscOffset' which specifies the offset into the
file for the data area of this variable.
For complex data,DiscOffset is a 1x2 vector with
offsets to both real and imaginary parts. For a
structure or object, DataOffset is a cell array
with one element for each field/property. Each
element will contain a set of ields describing
each field/property variable name, size, bytes etc
as for a standard matrix (including a DataOffset
field).
DiscClass -- a cell containing the storage format for the variable
on disc - which may be different from class -
as a string or 1x2 cell array of strings for
complex data with the DiscClass for both real and
imaginary parts
Flags, TagOffset, DataOffset and DiscFormat are supplied by WHERE. The
remaining fields are derived from a call to WHOS by WHERE (and will vary
according to the version of WHOS being used).
For structures and objects
If the variable is a structure or object, DataOffset will be a cell array
of structures describing each field or property of the variable as above.
With a double precision float variable var=1:10 saved
to file myfile.mat with the MATLAB 'SAVE MYFILE VAR -V6' command
WHERE('myfile','var') then produces:
----------------------------------------------------------------------
Name Size Bytes Class TagOffset DataOffset
----------------------------------------------------------------------
var 1x10 80 uint8=>double 128 184
Note that to save disc space, MATLAB stores var as uint8 and it needs to
be cast to double (hence uint8=>double i.e. DiscClass=>Class).
If var is a structure the output might look as follows:
-------------------------------------------------------------------------
Name Size Bytes Class TagOffset DataOffset
-------------------------------------------------------------------------
var 1x1 1068 struct=>struct 128
.field1 1x1 48 uint8=>double 224 276
.field2 1x6 64 uint16=>char 280 336
.field3 1x10 64 uint8=>double 352 408
.field4 1x1 280 struct=>struct 424 NaN
A TagOffset is returned for the structure, and for each field. Names,
DataOffsets and formats are supplied for each field. However, structures
within structures (as for field4) are not analyzed further and
DataOffsets are returned as NaN. To analyze these fields further use the
WHERE(FILENAME,VARNAME, FIELD1/PROP1, FIELD2/PROP2....) form e.g for a
structure S containing a structure A containing a structure B containing
a matrix C use where(filename,'S','A','B','C'). This form recursively calls
WHERE(FILENAME, TAGOFFSET) to dig through the nest.
Details for objects are returned as above for structures.
If 'unknown' appears in a class field it indicates that the variable has
not been fully analyzed by WHERE. In this case, DiscOffset will be NaN.
This will be the case for custom variables, functions, structure arrays,
cells and sparse arrays (TagOffsets will be returned for these if they are
fields/properties of a structure/object).With compressed data
(v7) all offsets will be NaNs.
Example: using with memmapfile to map a standard matlab matrix:
s=where('myfile.mat','A');
map=memmapfile('myfile.mat','Format',{s.class s.size 'mydata'},...
'Repeat',1,'Offset',s.DataOffset{1}.DiscOffset);
See also WHOS, memmmapfile, fread
Revisions: 16.09.06 WHERET functionality incorporated into WHERE
Coding generally tidied - global variables removed.
WHERET obsolete and deleted.
21.09.06 Now works with big-endian files on Windows
03.11.06 Now platform independent - Works on both big-endian
and little-endian platforms with both big-endian
and little-endian MAT-files. Tested on Windows XP
and Mac OS X (4.4.8 on a PowerMac G4).
04.11.06 Size now consistently returned as row vector (column
vector returned for fields/props previously)
08.11.06 Matrix size now prints correctly.
16.11.06 The output .bytes field now consistently contains the
number of bytes for a matrix when loaded. For a
structure/object .bytes contains the size on disc.
(This is consistent with the builtin WHOS)
A .DiscBytes field has been introduced. This is the
size of the variable on disc (for all data types)i.e.
the size of the header + data.
28.11.06 DataOffset changed to include a DataOffset subfield
for each field/property - previously the DiscOffset
was placed directly in DataOffset. The new
arrangment allows elements of DataOffset to be used
in the same way as those from standard variables,
e.g. s=where(filename, structname);
ws=s(1).DataOffset{5};
will return ws with a ws.DataOffset field of its own.
28.11.06 .size now contains trailing singleton dimensions. This
is unlike whos, but is needed after using
AddDimension with the AppendXXXX functions
29.11.06 Sort output fields alphabetically
26.06.07-26.08.07 Further formating improvements
21.01.10 R2010a compatible
__________________________________________________________________________
This program is distributed without any warranty,
without even the implied warranty of fitness for a particular purpose.
__________________________________________________________________________
Author: Malcolm Lidierth Updated 11/06
Copyright © The Author & King's College London 2006
__________________________________________________________________________