SerialReader.h

Go to the documentation of this file.

#pragma once
 
#pragma region INCLUSIONS
// nothing
#pragma endregion INCLUSIONS
 
// Namespace di protezione dalle inclusioni multiple con nominazione uguale
/*
I valori constexpr, come spiegato appena sopra, equivalgono alla direttiva '#define'. Questo pu� creare problemi nel momento in cui un singolo file viene incluso
in una gerarchia di molti pi� file, dove si potrebbe riscontrare la presenza di constexpr appartenenti a file diversi ma con gli stessi nomi! Questa ripetitivit� dei nomi deriva
dagli standard di nominazione. Per evitare, quindi, conflitti di multipla definizione, andremo ad utilizzare un 'namespace', che, come dice il nome, fornisce uno SPAZIO per i NOMI del nostro
file in cui il 'namespace' � stato dichiarato ed implementato.
Mantieniamo comunque la specificazione 'static', per evitare errori di linker in caso di inclusioni multiple di questa unit� di traslazione [file].
*/
namespace SerialReader__file
{
    // Questo valore rappresenta il valore che viene assegnato agli attributi della classe durante l'inizializzazione.
    static const String _initvalue = "";
 
    // Questo valore rappresenta il valore di assegnazione all'attributo 'm_Invalidator_asString'. Deve essere un valore "impossibile", che non 
    // deve esistere in altri contesti.
    // In questo contesto, qualsiasi dato pu� essere inviato durante la comunicazione. Risulta quindi impossibile individuare un valore "impossibile".
    // Per questo motivo, verr� utilizzata una "stringa campione" che gi� da se specifica di essere un invalidatore.
    // --> String
    static const String _invalidvalue_asString = "------___invalidator___------";
 
    // Questo valore rappresenta il valore di assegnazione all'attributo 'm_Invalidator_asNumber'. Deve essere un valore "impossibile", che non 
    // deve esistere in altri contesti.
    // In questo contesto, qualsiasi dato pu� essere inviato durante la comunicazione. Risulta quindi impossibile individuare un valore "impossibile".
    // Per questo motivo, verr� utilizzata una "stringa campione" che gi� da se specifica di essere un invalidatore.
    // --> int
    static constexpr int _invalidvalue_asNumber = -1;
}
 
class SerialReader
{
    /*Blocco trivial*/
    /*
    Stiamo trattando una classe interamente statica. Per la definizione di staticit�, descritta successivamente, questa classe funger� solamente
    da "contenitore astratto" per organizzare pi� logicamente i dati. In verit�, tutto risieder� principalmente nel Data Segment, quindi sar�
    globale, ma statico (anche questo descritto successivamente).
    Questa staticit� implica la NON necessit� di creare istanze di questa classe, che risulterebbero totalmente inutili dato che tutti gli attributi
    e i metodi esistono nell'ambito globale.
    Per evitare, quindi, inutili istanziamenti, verranno bloccati il costruttore trivial (di default generato dal compilatore) e il distruttore, reso
    inutile dalla non-istanziabilit� della classe stessa.
    */
private:
    // Blocco attraverso privatizzazione del costruttore trivial
    SerialReader() = default;
    // Blocco attraverso privatizzazione del distruttore trivial
    ~SerialReader() = default;
 
    /*Attributi*/
private:
    // Variabile che contiene il valore dell'ultima stringa letta (attraverso la chiamata del metodo 'read')
    static String m_buffer;
 
    // Variabile che contiene il valore del Baud Rate
    static unsigned int m_BaudRate;
 
    // Variabile che segnala se il metodo 'Init' è stato mai chiamato oppure no
    static bool m_hasBeenCalled;
 
    /*Init*/
public:
    // Metodo fondamentale che "da vita" alla classe (anche se in modo differente, infatti, in questo caso, non stiamo trattando una classe WRAPPER)
    /*
    Inizializza la comunicazione seriale con il 'baud rate' specificato.
    Inizializza il buffer al carattere di default definito dalla constexpr '_initvalue'.
    Tutti gli altri metodi appartenenti alla suddetta classe saranno disattivati fino alla chimata del metodo 'Init'.
    */
    static bool Init(const unsigned int& t_BaudRate);
 
    /*Risorse Interne*/
private:
    // Risorsa privata della classe "SerialReader" che effettua la lettura dei singoli valori 'char' eventualmente presenti nel porta seriale 
    // della comunicazione e restituisce una stringa equivalente.
    /*
    Questo metodo fornisce una risorsa per la lettura di valori presenti sulla comunicazione seriale [rx, tx].
    Durante la comunicazione, i dati vengono inviati "char x char". Questo implica la necessit� di implementare manualmente una gestione
    per avere i dati "compattati" in un formato pi� comodo. Questa risorsa fornisce quindi anche una formattazione dei dati, che verranno "compattati"
    in una variabile di tipo 'String' [stringa].
 
    Il metodo, per via della sua logica di funzionamento, ritorna (conclude la sua funzione) solo e solamente quando riceve il carattere ASCII '0x0A',
    che corrisponde a "\nl" (i.e. 'new line'). Una volta effettuata la chiamata, assicurarsi di fornire sempre il carattere di 'new line', altrimenti
    l'esecuzione rimarr� in attesa "per sempre".
    */
    static String read_n_format();
 
    /*Metodi*/
public:
    // Metodo per effettuare la lettura di dati in comunicazione seriale [rx, tx]
    static String read();
 
    // Ritorna il valore del buffer (contiene il valore dell'ultima stringa letta (attraverso la chiamata al metodo 'read')
    static inline String get_buffer();
 
    // Ritorna il valore del Baud Rate utilizzato
    static inline const unsigned int& get_BaudRate();
 
    /*Invalidator*/
    /*
    L'invalidatore consiste in quel valore che viene ritornato ogni qualvolta una chiamata da parte dell'utente ai metodi non produce il risultato atteso.
    E' importante specificare che, l'invalidatore, pur essendo costante, non deve essere dichiarato come 'constexpr' perch� NON deve seguire le regole di
    comportamento della direttiva '#define'. Il compilatore NON deve sostituire il nome dell'attributo con un valore numerico costante --> i.e. RVALUE!!
    L'invalidatore deve essere un vero e proprio attributo della classe, che per� non deve mai appartenere ad uno specifico oggetto. Per questo deve essere sempre
    specificato come statico. Ovviamente, avr� una locazione nel Data Segment, sar� quindi globale ma statico (valido sono in questa unit� di traslazione (file)) e utilizzabile
    solamente nell'ambito della classe di dichiarazione.
    */
    /*Attributo*/
private:
    // Valore costante che viene ritornato in caso di invalidit� riscontrata nell'oggetto durante il dereferenziamento
    // per la chiamata dei metodi.
    // Il valore invalido utilizzato � un valore impossibile, cio� che non potrebbe essere mai rilevato naturalmente dal sensore.
    static const String m_Invalidator_asString;
 
    // Valore costante che viene ritornato in caso di invalidit� riscontrata nell'oggetto durante il dereferenziamento
    // per la chiamata dei metodi.
    // Il valore invalido utilizzato � un valore impossibile, cio� che non potrebbe essere mai rilevato naturalmente dal sensore.
    static const int m_Invalidator_asNumber;
 
    /*getter*/
public:
    // Metodo per il ritorno del valore dell'Invalidatore. Verr� ritornata una referenza [reference --> '&'] costante, in modo tale da ottimizzare il processo e,
    // allo stesso tempo evitare modifiche inappropriate.
    /*
    Un'altra particolarit� di questo metodo sta nel fatto che � definita come 'inline'. Questa keyword comunica al compilatore, ovunque trovi una chiamata
    a questo metodo, di NON effettuare una vera e propria chiamata, ma di sostituire la porzione del codice per la chiamata con il BODY del metodo (la implementazione stessa).
    Questa tecnica risulta molto utile per funzioni che effettuano pochissime operazioni e sono sottoposte a frequenti chiamate.
    Anche qua, per via della staticit�, viene applicata la gestione analizzata prima.
    */
    static inline const String& get_Invalidator_asString();
 
    // Metodo per il ritorno del valore dell'Invalidatore. Verr� ritornata una referenza [reference --> '&'] costante, in modo tale da ottimizzare il processo e,
    // allo stesso tempo evitare modifiche inappropriate.
    /*
    Un'altra particolarit� di questo metodo sta nel fatto che � definita come 'inline'. Questa keyword comunica al compilatore, ovunque trovi una chiamata
    a questo metodo, di NON effettuare una vera e propria chiamata, ma di sostituire la porzione del codice per la chiamata con il BODY del metodo (la implementazione stessa).
    Questa tecnica risulta molto utile per funzioni che effettuano pochissime operazioni e sono sottoposte a frequenti chiamate.
    Anche qua, per via della staticit�, viene applicata la gestione analizzata prima.
    */
    static inline const int& get_Invalidator_asNumber();
};
 
// Dichiarazione delle variabili GLOBALI STATICHE 
// Risiederanno nel Data Segment
/*
Essendo statiche in classe, tutti gli attributi non sono altro che variabili GLOBALI STATICHE.
Per questo � richiesta la dichiarazione globale. Non � necessario specificare 'static' essendo gi� stato specificato nella dichiarazione degli
attributi nella classe stessa.
*/
String SerialReader::m_buffer;
unsigned int SerialReader::m_BaudRate;
bool SerialReader::m_hasBeenCalled = false;
const String SerialReader::m_Invalidator_asString = SerialReader__file::_invalidvalue_asString;
const int SerialReader::m_Invalidator_asNumber = SerialReader__file::_invalidvalue_asNumber;
 
//////////////////////////////////////////////////////////////////////////