SOURCE FILE: getImage.pseudo

/* ************************************************************ */
/*                           getImage                           */
/* ************************************************************ */
/*
     This function opens the image file and reads two
     integers (imgHeight and imgWidth) that appear at the
     beginning of the file.

     The rest of the file contains an 'ascii image' - an
     image encoded as a series of lines of characters.  The
     number of lines in the image is the value of the
     integer imgHeight.  All the lines comprising the image
     have the same length, which is the value of imgWidth.

     After reading imgHeight and imgWidth, the function
     reads the rest of the file and copies it into the
     square array called buffer.  The first line of the
     image goes into row zero of the array, the second line
     into row 1, and so on like that to the end of the file.
     Each line is copied so its first character goes into
     column 0 of the array, its second into column 1 of the
     array, and so on like that to the end of the line.  (In
     other words, the file is copied 'in order' into the
     'upper left corner' of the array.)

     Finally this function closes the file.
*/

void getImage(char buffer[MAXSIDE][MAXSIDE], string filename,
                int& imgHeight, int& imgWidth)
{
          Declare a file variable, bind it to 'filename' -
	  the name of the desired file in the computer's
	  filesystem, and open the file for reading.

          Input the two integers from the first line of the
	  file in a manner so that their valuea are stored
	  into the reference parameters imgHeight and
	  imgWidth (in that order)

          Skip any white space, in order to position the
	  'file window' so that the next character to be
	  read is the first character on line two of the
	  file.

   FROM ROW i=0 to i=imgHeight-1 IN STEPS OF 1
   {
      FROM COLUMN j=0 to j=imgWidth-1 IN STEPS OF 1
      {

        copy the next character from the file into the
	buffer array, in position row=i, column=j

	[[As a debug statement, to be taken out of the
	  finished program, but left in while the program is
	  in development, here out put the character that
	  was just put into the array by the statment above.
	  (In this way, you will see a 'picture' on the
	  screen of what is going into the array.  You can
	  check to see if it looks correct.]]
      }
      
      Skip any white space, in order to position the 'file
      window' so that the next character to be read is the
      first character on the next line of the file. (There
      is an 'invisible' end-of-line character at the end of
      each line.)

      [[As part of the debugging code to be taken out later,
	write a 'newline' character now to the screen - you
	have come to the end of one of the lines of the
	image you are putting on the screen, so you need to
	start a new line.]]

     Close the file.
}

Notes on C++ syntax:

* If filename is the name of a string variable a statement
  like this:

  ifstream inFile (filename.c_str()) ;

  declares an ifstream variable named inFile, binds it to
  the file having the name stored in the string variable,
  and opens the file for reading.  Thereafter the file
  should be referred to as inFile - that is the name of the
  variable that represents the file internally to the
  program.

* To input integers from the file, you can just use
  statements that are *like* the ones that start with cin >>
  -- except the name of the input stream is inFile.  So for
  example you can input an integer into the variable
  imgHeight with the statement: inFile >> imgHeight ;

* A stream variable has a special 'ignore' method that you
  can use to skip to the beginning of the next line.  You
  can use this form:

inFile.ignore(256, '\n') ;

The effect is to skip characters in the stream up to and
including the next newline ('\n') character.  (The 256 is a
limit - so it won't actually skip any more than 256
characters - for our purposes, the limit is not a problem.)

* You need to program the "FROM" constructs as nested
  for-loops.  The details of the syntax are explained in
  Appendix A.

* You can index the array like this: buffer[i][j].  The
  first index is the row index, and the second is the column
  index.

* The style of input you need when reading the ascii image
  is something with which you may not have experience.  In
  this situation, blank characters are significant parts of
  the image, that you have to read and place into the buffer
  array.  Therefore you can't use input statments that start
  out like this: inFile >>

  Such statements skip over all white space.  Instead use an
  input statement like this:

inFile.get(x)

This employs the 'get' method of the stream variable.  It
does not skip white space, it just reads the next character,
whatever it is, and stores it into the character variable x.
(Instead of x, you need to fill in 'buffer', indexed with
the appropriate designation of row and column number.

* To close a file, you just use the 'close' method of the
  file variable.  For example,

inFile.close() ;

closes the file represented by the ifstream variable inFile.