% indexing - 
%
% to access or assign values to only some elements of a matrix
%
% IMPORTANT: matlab uses 1-based indexing. the first element is
%            index 1, not 0 like in most programming languages.
%
% TECHNICAL NOTE: when assigning values to a set of indices, the number
%            of values on the left of the equal sign (being assigned)
%            must equal the number of values on the right (which
%            will be the new values), and the assignment is carried
%            out in 'order' (every subset of indices has a linear 
%            ordering), first value to first value, second to second, 
%            etc.. The only exception is when all the indices are 
%            assigned a single value. 
%
% 1. NUMERIC
%    you can index with integer indices (the integers can be stored
%    in any precision format: double, uint8, etc.)
%
%    => note 1. "end" is a special keyword which means
%       the "maximum allowable index" in its context
%    => note 2. "1:end" can be substituted with ":"
%    => note 3. When you assign values to a set of matrix indices,
%       they will be assigned in the order you name the indices!
%
% 2. LOGICAL
%    you can index with "Logical" (binary/boolean)
%    matrices if they have the same size (# of elements --
%    not necessarily the same dimensions) as 
%    the matrix into which you are indexing.
%    The most common way to get a Logical matrix is as the
%    result of an equality/inequality test
%


% NUMERIC indexing examples
m = zeros(4,4)              % 4 x 4 zero matrix
m(2,3) = 1                  % direct index into sub dimensions
m(1:end,1) = [5 -5 5 -5]    % multitple integer index; "end" is 4 here
m(:,2) = [ -5 : -2 ]        % 1:end is same as :
m(end,[end 3]) = [ 10 11 ]  % general multiple indexing

% LOGICAL indexing examples
n = [ 8 10 ; 11 12 ]  
n(n>10) = [20 30];  % explanation: now n is [ 8 10 ; 20 30 ]
                    % why? n>10 is a Logical matrix
                    % of the same size as n, therefore
                    % it can be used to select elements of n
                    % where the condition is true, the assignment
                    % is made. in this case, we assign 
                    % the third and fourth indices (in order)

n(n<20) = 0;        % but we can also assign multiple indices
                    % to a single value. now 
                    % n = [ 0 0 ; 20 30 ]

o = [ 2 3 4 5 ];    
o(n==0) = 1;        % since n has the same number of indices as o
                    % (namely 4), we can use a logical evaluation 
                    % on n to index o.
                    %
                    % note: in matlab, the 1st row in n consists of the
                    % 1st and 3rd elements of n (in this case b/c n is 2x2).
                    %
                    % explanation: every (row,column) index in a matrix 
                    % corresponds to a single linear index, which is 
                    % arrived at by visiting the matrices first by incrementing
                    % ROW numbers, then by incrementing COLUMN numbers,
                    % so the linear indexes into a 2x2 matrix are:
                    % [ 1 3  
                    %   2 4 ]
                    % This ordering (rows on the 'inside loop')
                    % is known as column-major order, and is how matlab
                    % stores matrices in memory.
                    %
                    % One way to remember this is that rows
                    % come first when specifying (row,column) indexes,
                    % and columns come second. When there is a third 
                    % dimension, that one comes after columns (i.e.,
                    % two matrix entries in the same row and column but
                    % 1 increment apart in the third dimension would be 
                    % row*column entries apart in memory.)