Main Content

Write to Mapped File

This example shows how to create three different memory maps, and then write to each of the maps using the appropriate syntax. Then, it shows how to work with copies of your mapped data.

You can write to a file using the same MATLAB® commands you use to access variables in the MATLAB workspace. By accessing the Data property of the memory map, the contents of the mapped file appear as an array in the currently active workspace. Simply index into this array to write data to the file. The syntax to use when writing to mapped memory depends on the format of the Data property of the memory map.

Write to Memory Mapped as Numeric Array

First, create a sample file named records.dat, in your current folder.

rng('default')
myData = rand([5000,1]);

fileID = fopen('records.dat','w');
fwrite(fileID, myData,'double');
fclose(fileID);

Map the file as a sequence of 16-bit-unsigned integers. Use the Format name-value pair argument to specify that the values are of type uint16.

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

Because the file is mapped as a sequence of a single class (uint16), Data is a numeric array.

Ensure that you have write permission to the mapped file. Set the Writable property of the memory map, m, to true.

m.Writable = true;

Create a matrix X that is the same size as the Data property, and write it to the mapped part of the file. 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.

X = uint16(1:1:15);
m.Data = X;

X is a 1-by-15 vector of integer values ranging from 1 to 15.

Verify that new values were written to the file. Specify an Offset value of 0 to begin reading from the beginning of the file. Specify a Repeat value of 35 to view a total of 35 values. Use the reshape function to display the values as a 7-by-5 matrix.

m.Offset = 0;
m.Repeat = 35;
reshape(m.Data,5,7)'
ans = 7x5 uint16 matrix

   47739   26762    4663   16362    3197
   24407   64575   16364   31612   40832
       1       2       3       4       5
       6       7       8       9      10
      11      12      13      14      15
   12673   53994   16337   46560   44024
   32781   16353   24667   24572   41957

The values in X have been written to the file, records.dat.

Write to Memory Mapped as Scalar Structure

Map a region of the file, records.dat, as a 300-by-8 matrix of type uint16 that can be referenced by the field name, x, followed by a 200-by-5 matrix of type double that can be reference by the field name, y. Specify write permission to the mapped file using the Writable name-value pair argument.

m = memmapfile('records.dat',     ...
      'Format', {                 ...
         'uint16' [300 8] 'x';    ...
         'double' [200 5] 'y' },  ...
      'Repeat', 1, 'Writable', true);

View the Data property

m.Data
ans = struct with fields:
    x: [300x8 uint16]
    y: [200x5 double]

Data is a scalar structure array. This is because the file, records.dat, is mapped as containing multiple data types that do not repeat.

Replace the matrix in the field, x, with a matrix of all ones.

m.Data.x = ones(300,8,'uint16');

Write to Memory Mapped as Nonscalar Structure

Map the file, records.dat, as a 25-by-8 matrix of type uint16 followed by a 15-by-5 matrix of type double. Repeat the pattern 20 times.

 m = memmapfile('records.dat',    ...
      'Format', {                ...
         'uint16' [5 4] 'x';    ...
         'double' [15 5] 'y' },  ...
      'Repeat', 20, 'Writable', true);

View the Data property.

m.Data
ans=20×1 struct array with fields:
    x
    y

Data is a nonscalar structure array, because the file is mapped as a repeating sequence of multiple data types.

Write an array of all ones to the field named x in the 12th element of Data.

  m.Data(12).x = ones(5,4,'uint16');

For the 12th element of Data, write the value, 50, to all elements in rows 3 to 5 of the field, x.

  m.Data(12).x(3:5,1:end) = 50;

View the field, x, of the 12th element of Data.

m.Data(12).x
ans = 5x4 uint16 matrix

    1    1    1    1
    1    1    1    1
   50   50   50   50
   50   50   50   50
   50   50   50   50

Syntaxes for Writing to Mapped File

The syntax to use when writing to mapped memory depends on the format of the Data property of the memory map. View the properties of the memory map by typing the name of the memmapfile object.

This table shows the syntaxes for writing a matrix, X, to a memory map, m.

Format of the Data PropertySyntax for Writing to Mapped File

Numeric array

Example: 15x1 uint16 array

m.Data = X;

Scalar (1-by-1) structure array

Example: 

1x1 struct array with fields:
                x
                y

m.Data.fieldname = X;

fieldname is the name of a field.

Nonscalar (n-by-1) structure array

Example: 

20x1 struct array with fields:
                x
                y

m.Data(k).fieldname = X;

k is a scalar index and fieldname is the name of a field.

The class of X and the number of elements in X must match those of the Data property or the field of the Data property being accessed. You cannot change the dimensions of the Data property after you have created the memory map using the memmapfile function. For example, you cannot diminish or expand the size of an array by removing or adding a row from the mapped array, m.Data.

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 memory map, m, you must either modify the Format or Repeat properties for m, or recreate m using the memmapfile function.

Note

To successfully modify a mapped file, you must have write permission for that file. If you do not have write permission, attempting to write to the file generates an error, even if the Writable property is true.

Work with Copies of Your Mapped Data

This part of the example shows how to work with copies of your mapped data. 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.

Create a sample file named double.dat.

myData = rand([5000,1])*100;
fileID = fopen('double.dat','w');
fwrite(fileID,myData,'double'); 
fclose(fileID);

Map the file as a series of double matrices.

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

View the values in m.Data(2).x.

m.Data(2).x
ans = 5×5

   95.0545   54.7696   15.6697   97.2605   85.0706
   53.2131   60.9054    5.8124   60.5319   25.6792
   24.7686   86.3135   33.9707   33.8236   28.5496
   43.7276   38.0696   81.7176   92.7984   77.9947
   66.9088   74.8956   37.7548   89.8425   70.1395

Copy the contents of m.Data to the variable, d.

d = m.Data;

Write all zeros to the field named x in the copy.

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

Verify that zeros are written to d(2).x.

d(2).x
ans = 5×5

     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.

m.Data(2).x
ans = 5×5

   95.0545   54.7696   15.6697   97.2605   85.0706
   53.2131   60.9054    5.8124   60.5319   25.6792
   24.7686   86.3135   33.9707   33.8236   28.5496
   43.7276   38.0696   81.7176   92.7984   77.9947
   66.9088   74.8956   37.7548   89.8425   70.1395

See Also

Related Topics