Taking It From The Stream

Introduction to File Input Operations

The process for inputting data from a file is not significantly different from outputting, but there are a couple of issues that need addressing. As you read previously, when you output to a file, the file you are outputting to is either created, or overwritten, when you open the file. The input file is not created by your program; it is accessed by your program. And if it is not available, there is a problem. Here is an example of data that might be in a text file, placed there by a program such as one of the examples in the previous topic.

16, 7.25, Bill

Now here is an example code segment that might retrieve the given data from the file using standard C file I/O operations.

// header file
#include <stdio.h>

// global constant
const int STD_STR_LEN = 64;

// main function
int main()
   {
    // initialize variables
    char name[ STD_STR_LEN ];
    char fileName[] = "testfile.txt";
    char readCharacter[] = "r";
    char commaCapture;
    int age;
    double payRate;

    // open file
       // function: fopen
    FILE *filePointer = fopen( fileName, readCharacter );    

    // check for file open
    if( filePointer != NULL )
       {
        // input the age and the following comma
           // function: fscanf
        fscanf( filePointer, "%d", &age );
        fscanf( filePointer, "%c", &commaCapture );

        // input the pay rate and the following comma
           // function: fscanf
        fscanf( filePointer, "%d", &age );
        fscanf( filePointer, "%c", &commaCapture );

        // input the name
           // function: fscanf
        fscanf( filePointer, "%s", name );

        // close file
           // function: fclose
        fclose( filePointer );

        // display results
           // function: printf
        printf( "Name: %s, Age: %d, Pay Rate: %4.2f\n",
                                    name, age, payRate );
       }
    else
       {
        // display error message
           // function: printf
        printf( "ERROR: File not found\n" );
       }

    // return success
    return 0;
   }

As mentioned previously, this is really not too complicated but there are a couple of weird looking operations. Here is the same operation conducted with the file input utility provided at the bottom of this page.

// header file
#include "File_Input_Utility.h"

// global constant
   // not necessary - string length constants (MIN, STD, MAX)
   //                 are all built in to the file input utility

// main function
int main()
   {
    // initialize variables
    char name[ STD_STR_LEN ];
    char fileName[] = "testfile.txt";
    char commaCapture;
    int age;
    double payRate;

    // open file, check for success
       // function: openInputFile
    if( openInputFile( fileName ) )
       {
        // acquire the age and the following comma
           // function: readIntegerFromFile, readCharacterFromFile
        age = readIntegerFromFile();
        commaCapture = readCharacterFromFile();

        // acquire the pay rate and the following comma
           // function: readDoubleFromFile, readCharacterFromFile
        payRate = readDoubleFromFile();
        commaCapture = readCharacterFromFile();

        // acquire the name
           // function: readStringToLineEndFromFile
        readStringToLineEndFromFile( name );

        // close file
           // function: closeInputFile
        closeInputFile();

        // display results
           // function: printf
        printf( "Name: %s, Age: %d, Pay Rate: %4.2f\n",
                                    name, age, payRate );
       }

    else
       {
        // display error message
           // function: printf
        printf( "ERROR: File not found\n" );
       }

    // return success
    return 0;
   }

First, notice the test for success in the input operation. In the standard C operation, the file pointer had to be tested for NULL; in the utility operation, there is a Boolean test for this (and no use for the file pointer at all).

Next, notice the use of printf. When there are just simple things to output, you are welcome to use this C tool as needed. At the same time, when your output gets a little more complicated, you can use the console I/O tools as needed.

The next item is a little more complicated. While the output process works every time without fail, the input process may not. As mentioned, if there is no file available, or no data in the file, attempting to upload data that doesn’t exist will cause problems for your program. So, the nice folks who designed the file input utility built in a little extra help. If there is ever a failure in the openInputFile operation, the function will return false so you can handle that issue in your program. This is also true for the closeInputFile function but the possibility of failure there is much smaller. In addition to these benefits, none of the functions will attempt to acquire data if the file has not already been successfully opened, or if the end of file has been found, again saving your programs from inconvenient failures.

Now with all that said, you can review the code you were given. The program opens the file, it tests to see if the file was opened correctly and reports if it wasn’t, and then it attempts to acquire the data that should be in the file. Note that this is still not a guarantee that data will be acquired. This code segment just shows the input process. In some cases after the input process, you may still need to test the input file stream to see if there was any input failure before you attempt to acquire new data. While the file input utility will protect you from attempting to acquire nonexistent data, there are some circumstances where may need to check and see if data is still available in the file. The checkForEndOfFile function in the file input utility provides the ability to do this.

Important Specification Note

There is an important consideration related to the File_Input_Utility.c that is provided in all the input operation specifications. In order to capture contiguous data, the string access operations all have to reach for the next numeric character in the file to see if it is part of the string input data. In every case, this means the operation will acquire the character immediately after each input string data item and ignore it (i.e, it will be lost). This should never be a problem since any given file data should never immediately follow any other given data item. However, if a comma or semicolon or other punctuation follows immediately after a given quantity of string data, it may not be returned to the user. This is not a significant problem but as users of the file input utility tools, you as the programmer should know about this. On the other hand, as you can see in the code, when accessing numeric data (e.g., character, integer, or double), any ending characters such as the comma in this case, must be captured and removed from the stream in order to get to the next data.

The file input utilities can be found here, the header file is found here, and the standard constants need by this utility are found here.

Watch the video for a program implementing this process.