function shuffled_matrix = matshuffle(m)
%
%  shuffled_matrix = matshuffle(matrice_input)
%
% Riordina casualmente gli elementi di una 
% matrice. La funzione accetta una matrice NxM come
% argomento e restituisca una matrice di indentiche
% dimensioni i cui elementi sono gli stessi della
% matrice di input, ma riordinati in modo casuale
%


% prima di tutto stabiliamo la dimensione della matrice
% usand size. Questa funzione ritorna un vettore riga
% contenente il numero di righe e di colonne della matrice

    matrix_size = size(m);

% numel(A) è una funzione che ritorna il numero di elementi
% della matrice A. Quindi equivale alla funzione
%
% numero_elementi = prod(size(m));
%
% la funzione 'prod' ritorna il prodotto degli elementi di 
% un array. Se l'argomento è una matrice ritorna un array
% contenente i prodotti per colonne. 

    numero_elementi = numel(m);

% collochiamo gli elementi della matrice in un vettore riga

    elementi = transpose(m(:));

% con la funzione randperm generiamo un vettore che contiene
% la permutazione casuale della sequenza 1:numero_elementi

    indici_random = randperm(numero_elementi);

% Quindi riordiniamo gli elementi usando il vettore con
% la permutazione casuale degli indici

    elementi_riordinati = elementi(indici_random);

% ricreiamo la matrice con le stesse dimensioni di quella
% di partenza usando la funzione reshape.
% reshape ristruttura una matrice in una nuova matrice
% avente dimensioni specificate. La funzione ammette
% una forma 
%
%   reshape(matrix,n,m)
%
% dove le nuove dimensioni n ed m sono argomenti separati
% oppure nella forma
%
%  reshape(matrix,[n m])
%
% dove le nuove dimensioni sono contenute in un array riga 
% 
% reshape rimodella una matrice ridisponendo in modo ordinato
% gli NxM elementi in una nuova matrice PxQ per le quali
% NxM=PxQ

    shuffled_matrix = reshape (elementi_riordinati,matrix_size);

end
