write_matrix_bin( filename, matrix, varargin )

function write_matrix_bin( filename, matrix, varargin )
%WRITE_MATRIX_BIN write_matrix_bin(f,m) saves the matrix "m" in a binary 
% file "f". write_matrix_bin is a lot fast than the built in save(), and 
% takes up much less diskspace than "save -v6 which doesn't use compression.
%
% write_matrix_bin also includes an option for compression with dzip 
% (http://www.mathworks.com/matlabcentral/fileexchange/8899). However, this 
% is only for convinience, and not because it's superior than the built in save()
%
% Limitations: Think before you use write_matrix_bin() instead of save().
%  * Since write_matrix_bin() as default saves values as float32 it will approximate your data.
%  * you can't save a large matrix with compression turned on. java will urn of out heap space. This is a problem with dzip.
%
% Here's a real life example (8000000 bytes = 7.6MB):
%
% >> whos data_matrix
%  Name               Size                   Bytes  Class     Attributes
%
%  data_matrix      100x100x100            8000000  double              
%
%
% %% Writing data to the disk
%
% write_matrix_bin('write.compressed.test', data_matrix, 'compress', 1) => 0.509179 seconds. Filesize: 884K
% save('write.save.test', 'data_matrix')                                => 0.582949 seconds. Filesize: 996K
% write_matrix_bin('write.uncompressed.test', data_matrix)              => 0.082440 seconds. Filesize: 3.9M
% save -v6 'write.savev6.test' 'data_matrix'                            => 0.292839 seconds. Filesize: 7.7M
%
% %% Reading data from the disk
%
% read_matrix_bin('write.compressed.test', 'compress', 1)               => 0.349878 seconds.
% read_matrix_bin('write.uncompressed.test')                            => 0.103816 seconds.
% load('write.save.test') % the compressed file                         => 0.088620 seconds.
% load('write.savev6.test') % the uncompressed file                     => 0.061182 seconds.

compress = 0;
format = 'float32';

for ind = 1:2:length(varargin)
    name = varargin{ind};
    value = varargin{ind+1};
    
    switch name
        
        case 'compress'
            compress = value;
            
        case 'format'
            format = value;
    end
end


one_d_matrix = reshape(matrix, 1, length(matrix(:)));
matrix_size = size(matrix);
dimensions = size(matrix_size,2);
matrix = cat(2, dimensions, matrix_size, one_d_matrix);

if compress
    format = 'uint8';
    matrix = dzip(matrix);
end

fid = fopen(filename, 'wb');
fwrite(fid, matrix, format);
fclose(fid); 

end