Skip to Main Content Skip to Search
Product Documentation

Writing to a Mapped File

On this page…

Example — Writing to a Mapped File

Dimensions of the Data Field

Writing Matrices to a Mapped File

Selecting Appropriate Data Types

Working with Copies of the Mapped Data

Example — 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.

If you haven't done so already, generate a test data file for use in the following examples by executing the gendatafile function defined under Constructing a memmapfile Object:

gendatafile('records.dat', 5000);

Now 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;

View the 5-by-8 matrix x at m.Data(2):

m.Data(2).x

ans =
  35330   4902  31861  16877  23791  61500  52748  16841
  51314  58795  16860  43523   8957   5182  16864  60110
  18415  16871  59373  61001  52007  16875  26374  28570
  16783   4356  52847  53977  16858  38427  16067  33318
  65372  48883  53612  16861  18882  39824  61529  16869

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 =
  52995   7353  47792  25316  35687  65535  65535  25262
  65535  65535  25290  65285  13436   7773  25296  65535
  27623  25307  65535  65535  65535  25313  39561  42855
  25175   6534  65535  65535  25287  57641  24101  49977
  65535  65535  65535  25292  28323  59736  65535  25304

Back to Top

Dimensions of the Data Field

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 dimensions of a memmapfile object's Data field are set at the time you construct the object and cannot be changed.

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

However, you cannot add a new column 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.

Thus, if you map an entire file and then append to that file after constructing the map, the appended data is not included in the mapped region. 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 of Invalid Syntax

Several 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;

Similarly, if m.Data has only 100 elements, the following operation is invalid:

m.Data(120) = x;

Back to Top

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.

When Memory Is Mapped in Nonstructure Format

When you map a file as a sequence of a single class (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:

This example maps a file as a sequence of 16-bit unsigned integers, and then uses the syntax shown above to write a matrix to the file. Map only a small part of the file, using a uint16 format for this segment:

m = memmapfile('records.dat', 'Writable', true', ...
    'Offset', 2000, 'Format', 'uint16', 'Repeat', 15);

Create a matrix X of the same size and write it to the mapped part of the file:

X = uint16(5:5:75);    % Sequence of 5 to 75, counting by fives.
m.data = X;

Verify that new values were written to the file:

m.offset = 1980;   m.repeat = 35;
reshape(m.data,5,7)'
ans =
  29158  16841  32915  37696    421      % <== At offset 1980
  16868  51434  17455  30645  16871
      5     10     15     20     25      % <== At offset 2000
     30     35     40     45     50
     55     60     65     70     75
  16872  50155  51100  26469  16873
  56776   6257  28746  16877  34374

When Memory Is Mapped in Scalar Structure Format

When you map a file as a sequence of a single class (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:

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 classes, 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:

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

Back to Top

Selecting Appropriate Data Types

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

m = memmapfile('records.dat', 'Format', 'uint8', ...
      'Writable', true);

d = m.Data;
d(5) = 300;

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

d(5)
ans =
   255

Back to Top

Working with Copies of the Mapped Data

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

First, destroy the memmapfile object and restore the test file records.dat, since you modified it by running the previous examples:

clear m
gendatafile('records.dat',50000);

Map the file as a series of uint16 and double matrices and make a copy of m.Data(2) in d:

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

Write all zeros to the copy:

d(2).x(1:5,1:8) = 0;

d(2).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 is not changed even though the copy of m.Data(2).x is written with zeros:

m.Data(2).x
ans =
  35330   4902  31861  16877  23791  61500  52748  16841
  51314  58795  16860  43523   8957   5182  16864  60110
  18415  16871  59373  61001  52007  16875  26374  28570
  16783   4356  52847  53977  16858  38427  16067  33318
  65372  48883  53612  16861  18882  39824  61529  16869

Back to Top

  

Reading a Mapped FileReading a Mapped File Deleting a Memory MapDeleting a Memory Map

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit

 © 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS