296 lines
12 KiB
C
296 lines
12 KiB
C
/*
|
|
Formatted file input utility, function prototypes
|
|
|
|
Copyright (c) 2021 by Michael E. Leverington
|
|
|
|
Code is free for use in whole or in part and may be modified for other
|
|
non-commercial use as long as the above copyright statement is included.
|
|
*/
|
|
/*
|
|
Rev 0.0: 30 June 2021, Initial creation of file
|
|
|
|
UTILITY USAGE INSTRUCTIONS:
|
|
|
|
1) This utility contains functions that may be used for file input operations
|
|
using the C programming language with text files.
|
|
The utility must be linked with the program code with which
|
|
it will be used.
|
|
|
|
2) Specifications for all the functions
|
|
are provided in a standardized format below.
|
|
|
|
3) Use this code at your own risk. There is no guarantee of any performance,
|
|
implied or otherwise, for any part of this code
|
|
|
|
END OF INSTRUCTIONS
|
|
*/
|
|
|
|
// PreProcessor test
|
|
#ifndef FILE_INPUT_UTILITY_H
|
|
#define FILE_INPUT_UTILITY_H
|
|
|
|
// header files
|
|
#include <stdbool.h>
|
|
#include <stdio.h>
|
|
#include "StandardConstants.h"
|
|
|
|
// constants shared with other files
|
|
|
|
// non printable flag, used in getStringConfigured
|
|
static const char NON_PRINTABLE = (char)(127);
|
|
|
|
// constant used for zero character return
|
|
static const char ZERO_CHAR = '0';
|
|
|
|
// constant used for zero int/double value return
|
|
static const char ZERO_VALUE = 0;
|
|
|
|
// function prototypes
|
|
|
|
/*
|
|
Name: accessEndOfInputFileFlag
|
|
process: allows accessing or modifying end of file flag state;
|
|
note: flag is maintained (static) value initialized to false
|
|
Function input/parameters: control code (int), flag state (bool)
|
|
Function output/parameters: none
|
|
Function output/returned: result of flag state (bool)
|
|
Device input/file: none
|
|
Device output/monitor: none
|
|
Dependencies: none
|
|
*/
|
|
bool accessEndOfInputFileFlag( int ctrlCode, bool setFlag );
|
|
|
|
/*
|
|
Name: accessInputFilePointer
|
|
process: allows setting or accessing file pointer;
|
|
note: pointer is maintained (static) value initialized to NULL
|
|
Function input/parameters: control code (int), file pointer (FILE *)
|
|
DUMMY_INPUT_FILE_PTR used
|
|
if not setting file pointer
|
|
Function output/parameters: none
|
|
Function output/returned: file pointer (FILE *)
|
|
Device input/file: none
|
|
Device output/monitor: none
|
|
Dependencies: none
|
|
*/
|
|
FILE *accessInputFilePointer( int ctrlCode, const FILE *filePtr );
|
|
|
|
/*
|
|
Name: checkForEndOfInputFile
|
|
process: checks to see if end of file flag has been encountered,
|
|
returns true if EOF has been encountered, false otherwise
|
|
Function input/parameters: none
|
|
Function output/parameters: none
|
|
Function output/returned: result of specified test (bool)
|
|
Device input/file: none
|
|
Device output/monitor: none
|
|
Dependencies: accessEndOfInputFileFlag
|
|
*/
|
|
bool checkForEndOfInputFile();
|
|
|
|
/*
|
|
Name: checkForInputFileOpen
|
|
process: checks to see if file is currently open
|
|
returns true if file pointer not null, false otherwise
|
|
Function input/parameters: none
|
|
Function output/parameters: none
|
|
Function output/returned: result of specified test (bool)
|
|
Device input/file: none
|
|
Device output/monitor: none
|
|
Dependencies: accessInputFilePointer
|
|
*/
|
|
bool checkForInputFileOpen();
|
|
|
|
/*
|
|
Name: clearLeadingWhiteSpace
|
|
process: captures non printable characters,
|
|
and space if flag set,
|
|
returns first non white space value found as integer
|
|
Function input/parameters: file pointer (FILE *), clear space flag (bool)
|
|
Function output/parameters: none
|
|
Function output/returned: first non WS character as integer
|
|
Device input/file: value captured from file
|
|
Device output/monitor: none
|
|
Dependencies: fgetc
|
|
*/
|
|
int clearLeadingWhiteSpace( FILE *filePtr, bool clearSpace );
|
|
|
|
/*
|
|
Name: closeInputFile
|
|
process: closes input file, returns true if successful, false otherwise
|
|
Function input/parameters: none
|
|
Function output/parameters: none
|
|
Function output/returned: none
|
|
Device input/file: file closed
|
|
Device output/monitor: none
|
|
Dependencies: accessInputFilePointer, fclose, accessEndOfInputFileFlag
|
|
*/
|
|
bool closeInputFile();
|
|
|
|
/*
|
|
Name: openInputFile
|
|
process: opens input file, sets file pointer and unsets end of file flag,
|
|
returns true if successful, false otherwise
|
|
Function input/parameters: file name (c-string)
|
|
Function output/parameters: none
|
|
Function output/returned: success of operation (bool)
|
|
Device input/file: file opened
|
|
Device output/monitor: none
|
|
Dependencies: fopen, accessInputFilePointer, accessEndOfInputFileFlag
|
|
*/
|
|
bool openInputFile( const char *fileName );
|
|
|
|
/*
|
|
Name: readCharacterFromFile
|
|
process: ignores leading unprintable characters, including space,
|
|
captures first printable character
|
|
Function input/parameters: allow space capture (bool)
|
|
Function output/parameters: none
|
|
Function output/returned: character found if successful, ZERO_CHAR otherwise
|
|
Device input/file: character(s) captured from file as needed
|
|
Device output/monitor: none
|
|
Dependencies: readCharacterFromFileConfigured
|
|
*/
|
|
char readCharacterFromFile();
|
|
|
|
/*
|
|
Name: readCharacterFromFileConfigured
|
|
process: ignores leading unprintable characters,
|
|
captures first printable character,
|
|
including space if allowed
|
|
Function input/parameters: allow space capture (bool)
|
|
Function output/parameters: none
|
|
Function output/returned: character found if successful, ZERO_CHAR otherwise
|
|
Device input/file: character(s) captured from file as needed
|
|
Device output/monitor: none
|
|
Dependencies: checkForInputFileOpen, checkForEndOfInputFile,
|
|
accessInputFilePointer, clearLeadingWhiteSpace,
|
|
accessEndOfInputFileFlag
|
|
*/
|
|
char readCharacterFromFileConfigured( bool captureSpace );
|
|
|
|
/*
|
|
Name: readDoubleFromFile
|
|
process: ignores leading unprintable characters,
|
|
captures first contiguous double value
|
|
Function input/parameters: none
|
|
Function output/parameters: none
|
|
Function output/returned: double value found if successful (double)
|
|
Device input/file: double value captured from file
|
|
Device output/monitor: none
|
|
Dependencies: checkForInputFileOpen, checkForEndOfInputFile,
|
|
accessInputFilePointer, fscanf, accessEndOfInputFileFlag
|
|
*/
|
|
double readDoubleFromFile();
|
|
|
|
/*
|
|
Name: readIntegerFromFile
|
|
process: ignores leading unprintable characters,
|
|
captures first contiguous integer
|
|
Function input/parameters: none
|
|
Function output/parameters: none
|
|
Function output/returned: integer found if successful, ZERO_VALUE otherwise
|
|
Device input/file: character(s) captured from file as needed
|
|
Device output/monitor: none
|
|
Dependencies: checkForInputFileOpen, checkForEndOfInputFile,
|
|
accessInputFilePointer, fscanf, accessEndOfInputFileFlag
|
|
*/
|
|
int readIntegerFromFile();
|
|
|
|
/*
|
|
Name: readLongFromFile
|
|
process: ignores leading unprintable characters,
|
|
captures first contiguous long int
|
|
Function input/parameters: none
|
|
Function output/parameters: none
|
|
Function output/returned: long integer found if successful,
|
|
ZERO_VALUE otherwise
|
|
Device input/file: long value captured from file
|
|
Device output/monitor: none
|
|
Dependencies: checkForInputFileOpen, checkForEndOfInputFile,
|
|
accessInputFilePointer, fscanf, accessEndOfInputFileFlag
|
|
*/
|
|
long readLongFromFile();
|
|
|
|
/*
|
|
Name: readRawCharFromFile
|
|
process: captures first character in file stream including non-printable
|
|
Function input/parameters: none
|
|
Function output/parameters: none
|
|
Function output/returned: character found if successful, ZERO_CHAR otherwise
|
|
Device input/file: character captured from file
|
|
Device output/monitor: none
|
|
Dependencies: checkForInputFileOpen, checkForEndOfInputFile,
|
|
accessInputFilePointer, fgetc, accessEndOfInputFileFlag
|
|
*/
|
|
char readRawCharFromFile();
|
|
|
|
/*
|
|
Name: readStringConfiguredFromFile
|
|
Process: captures string with options:
|
|
- clear leading non printable (bool)
|
|
- clear leading space character (bool)
|
|
- adquires characters up to any non-printable (bool)
|
|
- adquires characters up to any printable delimiter (char)
|
|
- use constant NON_PRINTABLE if no delimiter
|
|
- also stops capture when full (MAX_STR_LEN)
|
|
Note: This function consumes the last character input,
|
|
including the space, delimiter, or non-printable character
|
|
Function input/parameters: see process above
|
|
Function output/parameters: captured string (char *), EMPTY_STRING otherwise
|
|
Function output/returned: success of operation (bool)
|
|
Device input/file: character(s) captured from file as needed
|
|
Device output/monitor: none
|
|
Dependencies: checkForInputFileOpen, checkForEndOfInputFile,
|
|
clearLeadingWhiteSpace, fgetc, accessEndOfInputFileFlag
|
|
*/
|
|
bool readStringConfiguredFromFile( bool clearLeadingNonPrintable,
|
|
bool clearLeadingSpace,
|
|
bool stopAtNonPrintable,
|
|
char delimiter,
|
|
char *capturedString );
|
|
|
|
/*
|
|
Name: readStringSegmentFromFile
|
|
process: ignores leading white space, including space character,
|
|
captures series of characters up to first space,
|
|
or end of line, or full string
|
|
Function input/parameters: none
|
|
Function output/parameters: captured string (char *), EMPTY_STRING otherwise
|
|
Function output/returned: success of operation (bool)
|
|
Device input/file: character(s) captured from file as needed
|
|
Device output/monitor: none
|
|
Dependencies: readStringConfigured with appropriate parameters
|
|
*/
|
|
bool readStringSegmentFromFile( char *capturedString );
|
|
|
|
/*
|
|
Name: readStringToLineEndFromFile
|
|
process: ignores leading white space, including space character,
|
|
captures series of characters up to end of current line
|
|
or full string
|
|
Function input/parameters: none
|
|
Function output/parameters: captured string (char *), EMPTY_STRING otherwise
|
|
Function output/returned: string found if successful
|
|
Device input/file: character(s) captured from file as needed
|
|
Device output/monitor: none
|
|
Dependencies: readStringConfigured with appropriate parameters
|
|
*/
|
|
bool readStringToLineEndFromFile( char *capturedString );
|
|
|
|
/*
|
|
Name: readStringToDelimiterFromFile
|
|
process: ignores leading white space, including space character,
|
|
captures series of characters up to specified character
|
|
Function input/parameters: none
|
|
Function output/parameters: captured string (char *), EMPTY_STRING otherwise
|
|
Function output/returned: string found if successful
|
|
Device input/file: character(s) captured from file as needed
|
|
Device output/monitor: none
|
|
Dependencies: readStringConfigured with appropriate parameters
|
|
*/
|
|
bool readStringToDelimiterFromFile( char delimiter, char *capturedString );
|
|
|
|
#endif // FILE_INPUT_UTILITY_H
|
|
|
|
|