Programming

Writing to a Mapped File

Writing to a mapped file is done with standard MATLAB subscripted assignment commands. To write to a particular location in the file mapped to memmapfile object m, assign the value to the m.data structure array index and field that map to that location.

Call the memmapfile constructor to create the object:

• m = memmapfile('records.dat', 'format', {    ...
                 'uint16' [5 8] 'x';           ...
                 'double' [4 5] 'y' });
  

If you are going to modify the mapped file, be sure that you have write permission, and that you set the writable property of the memmapfile object to true (logical 1):

• m.writable = true;
  

(You do not have to set writable as a separate command, as done here. You can include a writable parameter-value argument in the call to the memmapfile constructor.)

Read from the 5-by-8 matrix x at m.data(2):

• m.data(2).x
  ans =
    11374  11356  11361  11375  11356  11361  11373  11322
    11367  11373  11362  11372  11373  11362  11361  11356
    11323  11361  11356  11362  11361  11356  11380  11373
    11334  11380  11380  11375  11380  11365  11323  11361
    11322  11372  11375  11384  11372  11372  11334  11380
  

Update all values in that matrix using a standard MATLAB assignment statement:

• m.data(2).x = m.data(2).x * 1.5;
  

Verify the results:

• m.data(2).x
  ans =
    17061  17034  17042  17063  17034  17042  17060  16983
    17051  17060  17043  17058  17060  17043  17042  17034
    16985  17042  17034  17043  17042  17034  17070  17060
    17001  17070  17070  17063  17070  17048  16985  17042
    16983  17058  17063  17076  17058  17058  17001  17070
  

Dimensions of the Data Field

The dimensions of a memmapfile object's data field are set at the time you construct the object and cannot be changed. This differs from other MATLAB arrays that have dimensions you can modify using subscripted assignment.

For example, you can add a new column to the field of a MATLAB structure:

• A.s = ones(4,5);
  
  A.s(:,6) = [1 2 3 4];         % Add new column to A.s
  size(A.s)
  ans =
       4     6
  

But not to a similar field of a structure that represents data mapped from a file. The following assignment to m.data(60).y does not expand the size of y, but instead generates an error:

• m.data(60)
  ans = 
      x: [5x8 uint16]
      y: [4x5 double]
  
  m.data(60).y(:,6) = [1 2 3 4];        % Generates an error.
  

If you need to modify the dimensions of data that you have mapped to a memmapfile object, you must either modify the format or repeat properties for the object, or reconstruct the object.

Examples.   Two examples of statements that attempt to modify the dimensions of a mapped data field are shown here. These statements result in an error.

The first example attempts to diminish the size of the array by removing a row from the mapped array m.data.

• m.data(5) = [];
  

The second example attempts to expand the size of a 50-row mapped array x by adding another row to it:

• m.data(2).x(1:51,31) = 1:51;
  

Writing Matrices to a Mapped File

The syntax to use when writing to mapped memory can depend on what format was used when you mapped memory to the file.

• m.data(83).y
  ans =
    1.0e-093 *
      0.0127    0.1511    0.0643    0.0528    0.1511
      0.1093    0.1436    0.0681    0.1168    0.0528
      0.0643    0.0868    0.1436    0.1168    0.1511
      0.0793    0.0208    0.1168    0.0123    0.1168
  
  m.data(84).y(1,1) = 100
  m.data(84).y(6,:) = [1 2 3 4]
  

When Memory Is Mapped in Nonstructure Format.   When you map a file as a sequence of a single data type (e.g., a sequence of uint16), you can use the following syntax to write matrix X to the file:

• m.data = X;
  

This statement is valid only if all of the following conditions are true:

• The file is mapped as a sequence of elements of the same data type, making m.data an array of a nonstructure type.
• The class of X is the same as the class of m.data.
• The number of elements in X equals the number of elements in m.data.

This example maps a file as a sequence of 16-bit unsigned integers, and then uses the syntax shown above to write an entire matrix to the file. Start by constructing the map:

• m = memmapfile('records.dat', 'writable', true', ...
                 'format', 'uint16');
  

Create another matrix X of the same size:

• for k = 1:length(m.data)
     X(k) = uint16(rand * 100);
  end
  

Write matrix X to the mapped file:

• m.data = X;
  

When Memory Is Mapped in Scalar Structure Format.   When you map a file as a sequence of a single data type (e.g., a sequence of uint16), you can use the following syntax to write matrix X to the file:

• m.data.f = X;
  

This statement is valid only if all of the following conditions are true:

• The file is mapped as containing multiple data types that do not repeat, making m.data a scalar structure.
• The class of X is the same as the class of m.data.f.
• The number of elements in X equals that of m.data.f.

This example maps a file as a 300-by-8 matrix of type uint16 followed by a 200-by-5 matrix of type double, and then uses the syntax shown above to write a matrix to the file.

• m = memmapfile('records.dat', 'format', {    ...
                 'uint16' [300 8] 'x';         ...
                 'double' [200 5] 'y' },       ...
                 'repeat', 1, 'writable', true);
  
  m.data.x = ones(300,8,'uint16');
  

When Memory Is Mapped in Nonscalar Structure Format.   When you map a file as a repeating sequence of multiple data types, you can use the following syntax to write matrix X to the file, providing that k is a scalar index:

• m.data(k).field = X;
  

To do this, the following conditions must be true:

• The file is mapped as containing multiple data types that can repeat, making m.data a nonscalar structure.
• k is a scalar index.
• The class of X is the same as the class of m.data(k).field.
• The number of elements in X equals that of m.data(k).field.

This example maps a file as a matrix of type uint16 followed by a matrix of type double that repeat 20 times, and then uses the syntax shown above to write a matrix to the file.

• m = memmapfile('records.dat', 'format', {    ...
                 'uint16' [25 8] 'x';          ...
                 'double' [15 5] 'y' },        ...
                 'repeat', 20, 'writable', true);
  
  m.data(12).x = ones(25,8,'uint16');
  

You can write to specific elements of field x as shown here:

• m.data(12).x(3:5,1:end) = uint16(500);
  m.data(12).x(3:5,1:end)
  ans =
      500    500    500    500    500    500    500    500
      500    500    500    500    500    500    500    500
      500    500    500    500    500    500    500    500
  

Selecting Appropriate Data Types

All of the usual MATLAB indexing and data type rules apply when assigning values to data via a memory map. The data type that you assign to must be big enough to hold the value being assigned. For example,

• m = memmapfile('records.dat', 'format', 'uint8', ...
                 'writable', true);
  m.data(5) = 300;
  

saturates the x variable because x is defined as an 8-bit integer:

• m.data(5)
  ans =
     255
  

Working with Copies of the Mapped Data

In the following code, the data in variable block2 is a copy of the file data mapped by m.data(2). Because it is a copy, modifying array data in block2 does not modify the data contained in the file:

• m = memmapfile('records.dat', 'format', {    ...
                 'uint16' [5 8] 'x';           ...
                'double' [4 5] 'y' });
   
  block2 = m.data(2);
  
  block2.x(1:5,1:8) = 0;
  
  block2.x
  ans =
        0      0      0      0      0      0      0      0
        0      0      0      0      0      0      0      0
        0      0      0      0      0      0      0      0
        0      0      0      0      0      0      0      0
        0      0      0      0      0      0      0      0
  

Verify that the data in the mapped file has not changed even though the copy of m.data(2).x has been written with zeros:

• m.data(2).x
  ans =
    17061  17034  17042  17063  17034  17042  17060  16983
    17051  17060  17043  17058  17060  17043  17042  17034
    16985  17042  17034  17043  17042  17034  17070  17060
    17001  17070  17070  17063  17070  17048  16985  17042
    16983  17058  17063  17076  17058  17058  17001  17070
  

Invalid Syntax for Writing to Mapped Memory

Although you can expand the dimensions of a typical MATLAB array by assigning outside its current dimensions, this does not apply to the data property of a memmapfile object. The following operation is invalid if m.data has only 100 elements:

• m.data(120) = x;
  

If you need to expand the size of the mapped data region, first extend the map by updating the format or repeat property of the memmapfile object to reflect the new structure of the data in the mapped file.

Example -- Writing Multiple Data Types

Create a memory map, mapping the data as 100 doubles, followed by 400 int16s, followed by 1000 doubles. The mapped segments are named obj.data.x, obj.data.y, and obj.data.z:

• m = memmapfile('datafile.bin',                   ...
                 'offset', 4095, 'format', {       ...
                 'double' [100 1] 'x';             ...
                 'int16' [400 1] 'y';              ...
                 'double' [1000 1] 'z'},           ...
                 'writable', true, 'repeat', 1);
  

Change the data on disk:

• m.data.y = int16(1:400);
  

Plot the results:

• plot(m.data.y)
  

Reading a Mapped File

Methods of the memmapfile Class

© 1994-2005 The MathWorks, Inc.