read_numeric.m

这是一个关于MATLAB的函数

function resp = read_numeric(nn,index,timeout)
%READ_NUMERIC Retrieves memory area and converts into a numeric array
%  DN = READ_NUMERIC(NN)
%  DN = READ_NUMERIC(NN,[],TIMEOUT) - reads all data from the specified memory 
%  area and converts it into a numeric representation.  Numeric conversion is 
%  controlled by the properties of the NN object.  The output 'DN' will be a 
%  numeric array that has dimensions defined by NN.SIZE, which is the dimensions 
%  array. Each element in the dimensions array contains the size of the array in 
%  that dimension.  If SIZE is a scalar, the output is a column vector of the specified 
%  length. 
%
%  DN = READ_NUMERIC(NN,INDEX)
%  DN = READ_NUMERIC(NN,INDEX,TIMEOUT) - read a subset of the numeric values from
%  the specified numeric array.  Each row of INDEX is applied as a subscript into the 
%  full NN array.  The output DN will be a column vector with one value per entry in the
%  INDEX.  Arrays indices start at 1 and range up the maximum value defined by SIZE.
%  If INDEX is a vector, each row is an single index  that defines one entry
%  from the defined numeric array.  The output DN will be a column vector of values
%  corresponding to the specified indices.   A new TIMEOUT value can be
%  explicitly passed to temporarily modify the default timeout property of the nn object.  
%
% Array properties
% NN.SIZE - Dimensions of output numeric array.  This defines the size of 'DN'
% NN.ARRAYORDER - Defines how sequential memory locations are mapped into matrices.
%   The default is 'col-major', which is the arrangment used by MATLAB.  Alternatively,
%   use 'row-major', which is the memory organization applied in C.
% Numeric representation 
%  NN.REPRESENT - Numeric representation
%    'float' - IEEE floating pointer representation (32 or 64 bits)
%    'signed' - 2's Compliment signed integers
%    'unsigned'- Unsigned binary integer
%    'fract' - Fractional fixed-point, see nn.p
%  NN.WORDSIZE - Number of valid bits in numeric representation.  This
%   property is computed from other properties such as 'storageunitspervalue' and therefore
%   read-only
%  NN.BINARYPT
%  Other properties of NN control the placement and arrangement of
%  the numeric values in memory.
%
%  Changes to the numeric representation are possible by modifying the
%  class properties.  However, the CONVERT method implements the adjusting
%  the properties to implement some common data types.
%
%   See also READ, WRITE, CONVERT, INT32.

%   Copyright 2002 The MathWorks, Inc.
%   $Revision: 1.20 $ $Date: 2002/05/23 21:47:13 $

error(nargchk(1,3,nargin));
if ~ishandle(nn),
    error('First Parameter must be a NUMERIC Handle.');
end

% Call base class (memoryobj) to get unformatted data
resp = [];
if nargin == 1,
    uidata  = read_memoryobj(nn);
    uidata  = reshape(uidata,nn.storageunitspervalue,[]);
    nvalues = prod(nn.size);
elseif nargin == 3 & isempty(index),
    uidata  = read_memoryobj(nn,[],timeout);
    uidata  = reshape(uidata,nn.storageunitspervalue,[]);
    nvalues = prod(nn.size);
elseif nargin >= 2,
    % Re-arrange data as described by object
    if nargin == 2,     dtimeout = nn.timeout;
    else                dtimeout = timeout;
    end
    try    
        index_shaped = round(reshape(index,length(nn.size),[])');
    catch  
        error(['Index Array must be an (N x '  num2str(length(nn.size)) ') vector ' ]);
    end
    for subscript = index_shaped',
        if any(subscript < 1) | any(subscript' > nn.size),
          error(['INDEX has an entry: [' num2str(subscript') '], which exceeds the defined size of object ']);
        end
    end
    addrange = ( index2addr(nn,index_shaped) )';
    uidata   = read_memoryobj(nn,addrange,dtimeout);
    uidata   = reshape(uidata,nn.storageunitspervalue,[]);
    nvalues  = size(uidata);
    nvalues  = nvalues(2);
end

% Endianness swap (if necessary) - must default to 'little' order from this point on 
uidata = ApplyEndianness(nn,uidata);

% Trim pre/post bytes (if necessary)
% For now, limited to increments of bitsperstorageunit
uidata = ApplyPadding(nn,uidata);

% Convert adjusted array of 'valid' au into numeric values
switch (nn.represent), 
case {'fract','signed'}
    fdata = ConvertRaw2SignedInt(nn,uidata,nvalues);
    % If fractional, adjust the binary point
    fdata = AdjustBinaryPoint(fdata,nn.represent,nn.binarypt);
    
case {'ufract','unsigned'}
    fdata = ConvertRaw2UnsignedInt(nn,uidata,nvalues);
    % If fractional, adjust the binary point
    fdata = AdjustBinaryPoint(fdata,nn.represent,nn.binarypt);
    
case 'float',
    if nargin>=2,   bidata = readbin(nn,index);
    else            bidata = readbin(nn);
    end
    fdata = ConvertRaw2IeeeFloatingPt(nn,bidata,nvalues);
    
otherwise  
    error(['Unexpected numeric representation: ''' nn.represent]);
end

% Indexed and regular
if length(nn.size) > 1 & ((nargin == 1) | (nargin == 3 & isempty(index))),  % Non-indexed, arrange according to 'arrayorder' prop
    if strcmp(nn.arrayorder,'row-major'),
        fdata = fdata( GetMatlabIndex(nn) );
    end
    resp = reshape(fdata,nn.size); 
    
else   % Indexed - Don't bother shaping it
    resp = fdata;
end

%-----------------------------------------
function linearindex = GetMatlabIndex(nn)
nsize = nn.size;
subsc = [];
totalnumel = prod(nsize);
len = length(nsize);
subsc = p_ind2sub(nn,nsize,[1:totalnumel],'col-major'); % index in a) C if row-major b) Matlab if col-major
linearindex = p_sub2ind(nn,nsize,subsc,'row-major'); % map indices to native Matlab array order
if ~isequal(unique(linearindex),sort(linearindex))
    error('Error generating linear index. Please report this error to MathWorks.');
end

%-------------------------------------
function uidata = ApplyPadding(nn,uidata)
if nn.prepad > 0 |  nn.postpad > 0,
    preaus  = nn.prepad/nn.bitsperstorageunit;
    postaus = nn.postpad/nn.bitsperstorageunit;
    if preaus + postaus > nn.storageunitspervalue,
        error(' Pre/Post padding exceeds available memory area');
    end    
    uidata = uidata(1+preaus:end-postaus,:); % extract only relevant bits
end 

%------------------------------
function fdata = AdjustBinaryPoint(fdata,represent,binarypt)
if strcmp(represent,'fract') | strcmp(represent,'ufract'),
    fdata = fdata./ 2^(binarypt);
end 

%------------------------------
function uidata = ApplyEndianness(nn,uidata)
if ~strcmp( nn.endianness,'little') & (nn.storageunitspervalue > 1),
    uidata = flipud(uidata);
end

%------------------------------------
function fdata = ConvertRaw2SignedInt(nn,uidata,nvalues)
validaus  = size(uidata);  % Not storageunitspervalue (padding!!)
validaus  = validaus(1);
maxposbit = 2^(nn.bitsperstorageunit-1)-1; 
maxpos    = 2^(nn.bitsperstorageunit)-1;  
scale     = 2.^(0:nn.bitsperstorageunit:nn.bitsperstorageunit*validaus-1)';
for iv=1:nvalues,
   uival = double(uidata(:,iv))';
   if uival(validaus) > maxposbit,  % Negative 
       uival = maxpos-uival; 
       fdata(iv) = uival*scale;
       fdata(iv) = -1*(fdata(iv)+1);
   else % Positive 
      fdata(iv) = uival*scale;
   end 
end 

%------------------------------------
function fdata = ConvertRaw2UnsignedInt(nn,uidata,nvalues)
validaus = size(uidata);  % Not storageunitspervalue (padding!!)
validaus = validaus(1);
scale    = 2.^(0:nn.bitsperstorageunit:nn.bitsperstorageunit*validaus-1)';
for iv=1:nvalues,
   uival = double(uidata(:,iv))';
   fdata(iv) = uival*scale;
end

%-----------------------------
function fdata = ConvertRaw2IeeeFloatingPt(nn,bidata,nvalues)
if nn.wordsize==32,       precision = 'single';
elseif nn.wordsize==64,   precision = 'double';
else    error('Floating point data type limited to 32 and 64 bits on this platform!');
end
for iv = 1:nvalues,        
    fdata(iv) = bin2float(nn,precision, bidata{iv});
end

% [EOF] read_numeric.m