Questo sito utilizza cookies solo per scopi di autenticazione sul sito e nient'altro. Nessuna informazione personale viene tracciata. Leggi l'informativa sui cookies.
Username: Password: oppure
Libreria STRCONS - info.h

info.h

Caricato da: AldoBaldo
Scarica il programma completo

  1. /*==============================================================================
  2.  
  3. LIBRERIA STRCONS
  4. di Aldo Carpanelli
  5. v1.1, 13/11 - 6/12 2016
  6.  
  7. Uno dei compiti piu' tediosi che mi capita di affrontare quando scrivo i miei
  8. programmini amatoriali e' gestire l'immissione dei dati nella console del C. La
  9. parte odiosa sta in tutti quei controlli che tocca fare per assicurarsi di non
  10. incorrere nell'infausto e sempre incombente sfondamento del buffer (a meno di
  11. voler allocare buffer con dimensioni da fantascienza). Una seccatura minore ma
  12. comunque concreta e' la verifica di quell'ingombrante carattere di fine riga
  13. ('\n') che a volte viene inserito da fgets(), a volte no. Quando non viene
  14. inserito si ha poi la necessita' di liberare lo stdin dai caratteri "pendenti",
  15. operazione per la quale viene da piu' parti sconsigliato l'uso di flush()
  16. costringendo a inventarsi metodi "fantasiosi".
  17.  
  18. Che menata! Dunque, mi son detto "e basta!" e ho predisposto una piccola
  19. libreria che mi liberi dall'incomodo.
  20.  
  21. Le funzioni della libreria STRCONS (nelle intenzioni) esonerano dalla necessita'
  22. di occuparsi dei dettagli appena elencati. Si inizializza la libreria STRCONS
  23. secondo le dimensioni che si ritengono piu' opportune e si usa la funzione
  24. STRCONS_Chiedi(). Punto.
  25.  
  26. Vediamo com'e' fatta 'sta libreria, va'...
  27.  
  28.  
  29. CODICI DI ERRORE
  30. ================
  31.  
  32. Alcune funzioni della libreria restituiscono codici di errore che possono essere
  33. usati per verificare i problemi eventualmente incontrati nel gestire
  34. l'immissione dei dati da parte dell'utente. Eccoli:
  35.  
  36.     enum {
  37.        STRCONSErr_no_str = -2, // l'input e' una stringa vuota
  38.        STRCONSErr_troncato,    // buffer insufficiente (input troncato)
  39.        STRCONSErr_no_err,      // nessun errore, tutto bene
  40.        STRCONSErr_no_mem,      // memoria insufficiente
  41.        STRCONSErr_enorme,      // dimensioni del buffer insensate
  42.        STRCONSErr_no_fgets,    // errore in fgets()
  43.        STRCONSErr_no_num       // il buffer non rappresenta un numero
  44.     };
  45.  
  46. E' anche definita una costante che indica la quantita' massima delle stringhe
  47. d'errore disponibili:
  48.  
  49.     #define STRCONSErr_MaxIndStrErr    7
  50.  
  51. (MaxIndStrErr = indice maximo delle stringhe d'errore)
  52.  
  53.  
  54. FUNZIONE INIZIALIZZATRICE
  55. =========================
  56.  
  57. STRCONS_Inizializza( size_t dim );
  58.  
  59. Inizializza la libreria allocando un buffer che puo' contenere un massimo di dim
  60. caratteri (il buffer finisce quindi per avere dimensioni pari a dim+1 bytes). Se
  61. anche venisse passato in dim un valore minore, il buffer avra' almeno una
  62. dimensione di 2 byte. Al momento della creazione, il buffer contiene una serie
  63. di '\0'.
  64. Qualora l'allocazione della memoria necessaria non fosse possibile, la funzione
  65. inizializzatrice fallirebbe il suo scopo e restituirebbe un codice d'errore
  66. adeguato, scelto tra quelli gia' elencati.
  67.  
  68. NOTA: l'allocazione avviene per mezzo della funzione standard del C calloc().
  69.  
  70.  
  71. FUNZIONE DI DISMISSIONE
  72. =======================
  73.  
  74. void STRCONS_Dismetti( void );
  75.  
  76. La funzione di dismissione si occupa di liberare la memoria allocata per il
  77. buffer abbinato alla libreria.
  78.  
  79. NOTA: la deallocazione avviene per mezzo della funzione standard del C free().
  80.  
  81.  
  82. FUNZIONI DI MODIFICA DELLO STATO DELLA LIBRERIA
  83. ===============================================
  84.  
  85. int STRCONS_Dimensiona( size_t dim );
  86.  
  87. Cambia le dimensioni del buffer, prevedendo lo spazio per il terminatore '\0'
  88. (dunque, vengono allocati dim+1 byte di memoria).
  89. Se il buffer contiene gia' dei dati, i dati gia' presenti vengono conservati
  90. (nei limiti del possibile).
  91. Se non e' possibile modificare le dimensioni del buffer, il vecchio buffer viene
  92. conservato, cosi' come il suo contenuto.
  93. In caso d'insuccesso restituisce un codice di errore che puo' essere usato per
  94. ricavare informazioni sul tipo di problema riscontrato. Il codice di errore puo'
  95. essere...
  96.  
  97. STRCONSErr_enorme   e' stata richiesta l'allocazione di un buffer dalle
  98.                     dimensioni uguali o superiori a 4GB, il che e' un'assurdita'
  99.  
  100. STRCONSErr_no_mem   l'allocazione della memoria e' fallita; il buffer non e'
  101.                     stato ridimensionato, ma il suo contenuto originale e'
  102.                     rimasto intatto
  103.  
  104. STRCONSErr_no_err   tutto bene, il buffer e' stato ridimensionato e le parti
  105.                     conservabili del suo contenuto sono state conservate
  106.  
  107.                    
  108. int STRCONS_Chiedi( void );
  109.  
  110. Chiede tramite console di inserire un testo. Il testo viene letto fino a un
  111. massimo di caratteri corrispondenti all'attuale capacita' massima del buffer
  112. (impostata tramite STRCONS_Inizializza() oppure STRCONS_Dimensiona()).
  113. Al termine dell'immissione svuota gli eventuali caratteri “pendenti” nello
  114. stdin, “consumandoli” per mezzo della funzione statica STRCONS_SvuotaStdin().
  115. In caso d'insuccesso restituisce un codice di errore che puo' essere usato per
  116. ricavare informazioni sul tipo di problema riscontrato. Il codice di errore puo'
  117. essere...
  118.  
  119. STRCONSErr_no_str     l'utente ha premuto invio senza immettere alcun testo; il
  120.                       buffer contiene solo il carattere terminatore (cioe' una
  121.                       stringa vuota e niente piu')
  122.  
  123. STRCONSErr_troncato   la stringa immessa in console e' parzialmente presente nel
  124.                       buffer, terminata da '\0'; la parte eccedente le
  125.                       dimensioni del buffer e' andata persa
  126.  
  127. STRCONSErr_no_err     tutto bene, la stringa immessa in console e' presente nel
  128.                       buffer (senza il carattere finale '\n'), terminata da '\0'
  129.  
  130. STRCONSErr_no_fgets   c'e' stato un errore non meglio precisato nella chiamata
  131.                       alla funzione standard fgets(); l'oggetto e' nella sua
  132.                       condizione antecedente alla chiamata alla funzione
  133.                       STRCONS_Chiedi()
  134.  
  135.                      
  136. FUNZIONI D'INFORMAZIONE SULLO STATO DELLA LIBRERIA
  137. ==================================================
  138.  
  139. size_t STRCONS_Capacita( void );
  140.  
  141. Fornisce informazioni sulla capacita' massima del buffer della libreria (intesa
  142. come numero di caratteri effettivamente ricevibili, escluso dunque il carattere
  143. terminatore della stringa C).
  144.  
  145.  
  146. size_t STRCONS_Lunghezza( void );
  147.  
  148. Fornisce informazioni sulla lunghezza della stringa C correntemente contenuta
  149. nel buffer della libreria, sempre minore o uguale al valore restituito dalla
  150. funzione STRCONS _Capacita().
  151.  
  152.  
  153. char *STRCONS_PStr( void );
  154.  
  155. Fornisce un puntatore allo spazio di memoria riservato al buffer della libreria,
  156. il che equivale a fornire l'indirizzo della stringa C in esso contenuta e
  157. immessa dall'utente in console.
  158.  
  159. NOTA: e' essenziale che la memoria abbinata al puntatore restituito da
  160.       questa funzione non venga mai liberata direttamente - si usi sempre
  161.       STRCONS_Dismetti().
  162.  
  163.      
  164. int STRCONS_Long( long *l, int base );
  165.  
  166. Converte la stringa contenuta nel buffer in un valore numerico, secondo la
  167. notazione indicata tramite il parametro base.
  168. Immette il risultato della conversione all'indirizzo passato come parametro in
  169. l. Restituisce un codice di errore che puo' essere STRCONSErr_no_err (tutto
  170. bene) oppure STRCONSErr_no_num (conversione non effettuata).
  171.  
  172.  
  173. int STRCONS_UnsignedLong( unsigned long *ul, int base );
  174.  
  175. Converte la stringa contenuta nel buffer in un valore numerico, secondo la
  176. notazione indicata tramite il parametro base.
  177. Immette il risultato della conversione all'indirizzo passato come parametro in
  178. ul. Restituisce un codice di errore che puo' essere STRCONSErr_no_err (tutto
  179. bene) oppure STRCONSErr_no_num (conversione non effettuata).
  180.  
  181.  
  182. int STRCONS_Double( double *d );
  183.  
  184. Converte la stringa contenuta nel buffer in un valore numerico.
  185. Immette il risultato della conversione all'indirizzo passato come parametro in
  186. d. Restituisce un codice di errore che puo' essere STRCONSErr_no_err (tutto
  187. bene) oppure STRCONSErr_no_num (conversione non effettuata).
  188.  
  189.  
  190. FUNZIONI ACCESSORIE
  191. ===================
  192.  
  193. size_t STRCONS_EliminaNewline( char *str, size_t lung );
  194.  
  195. Elimina un carattere '\n' eventualmente presente in coda alla stringa puntata da
  196. str. Restituisce la quantita' dei caratteri presenti nella stringa dopo
  197. l'elaborazione.
  198.  
  199.  
  200. size_t STRCONS_SvuotaStdin();
  201.  
  202. Elimina gli eventuali caratteri “pendenti” nello stream stdin.
  203. In uscita, restituisce la quantita' dei caratteri eliminati dallo stream (ad
  204. esclusione del carattere '\n', che non viene conteggiato).
  205.  
  206.  
  207. void STRCONS_AdattaPuntoDecimale( void );
  208.  
  209. Sostituisce nel buffer ogni occorrenza dei caratteri ',' e '.' con il carattere
  210. impostato come carattere decimale nella localizzazione corrente, rilevato
  211. tramite la funzione standard localeconv().
  212.  
  213.  
  214. FUNZIONI DI GESTIONE DEGLI ERRORI
  215. =================================
  216.  
  217. const char *STRCONSErr_Descrizione( int codice );
  218.  
  219. Restituisce un puntatore a una stringa che descrive uno dei codici d'errore gia'
  220. elencati e restituibili da alcune delle altre funzioni della libreria. Se viene
  221. passato un codice non compreso tra quelli validi, restituisce la stringa "errore
  222. non previsto".
  223.  
  224.     const char *STRCONSErr_d[STRCONSErr_MaxIndStrErr] = {
  225.         "l'input e' una stringa vuota",                     // -2
  226.         "buffer insufficiente, input troncato",             // -1
  227.         "nessun errore",                                    //  0
  228.         "memoria non allocata",                             //  1
  229.         "e' stato richiesto un buffer di 4GB o piu'",       //  2
  230.         "errore in fgets()",                                //  3
  231.         "la stringa non rappresenta un numero"              //  4
  232.     };
  233.  
  234.  
  235. ESEMPIO D'USO
  236. =============
  237.  
  238. #include <stdio.h>
  239. #include <stdlib.h>
  240. #include "stringa_console.h"
  241.  
  242. #define MAX_CARATTERI   7
  243.  
  244. int main() {
  245.     int esito = STRCONS_Inizializza( MAX_CARATTERI );
  246.  
  247.     if( esito == STRCONSErr_no_err ) {
  248.         esito = STRCONS_Chiedi();
  249.  
  250.         if( esito <= 0 )
  251.             printf( "Ho letto \"%s\"\n\n", STRCONS_PStr() );
  252.         printf( "Esito: %s.\n\n", STRCONSErr_Descrizione(esito) );
  253.     }
  254.  
  255.     printf( "Premi \"invio\" per lasciare il programma...\n\n" );
  256.     getchar();
  257.     return 0;
  258. }
  259.  
  260. ==============================================================================*/