In this video, we're going to walk through an example
of using a very convenient function called getline.
We begin in main,
and there are several local variables we need to initialize to getline.
We have a size variable,
a length variable, and a line variable.
We're going to be reading lines from a file one by one,
and line will always point to a buffer
containing each line currently being read from a file.
The size variable will tell us how large the buffer is,
and the length variable will tell us how long
the actual string is that we've stored in the line buffer.
We also need to open the file itself in read mode.
We can see that the file contains three names that we're going to read from it.
Now, we're going to start reading these lines one by one using the getline function.
Usually for a library call,
we abstract away the details.
But in this case, we want you to learn what getline does.
So, we are going to create a stack frame for it,
where you can see it's three parameters.
The first one is a pointer to the line buffer.
So, we've passed in the address of line,
we haven't actually allocated memory for this buffer.
So, line P is pointing to a pointer that has the value null,
and that's fine, getline can handle that.
The second parameter is a pointer to the size.
So, we've passed in the address of size.
This tells us how large the buffer is,
and since we haven't allocated the buffer, it's zero.
The reason getline takes a pointer to the size variable not the size variable itself,
is so getline can change the size once it allocates a buffer of appropriate size.
The third parameter is a pointer to the file to be read.
So, we've passed in F. Now,
we're going to call getline,
making note of the call site location,
and moving our execution arrow into getline.
We're not going to show you the actual code for getline,
rather we're going to use an appropriate amount of abstraction,
and list of four primary tasks that you should know about them.
The first thing getline does is allocate memory if necessary.
In this case, the buffer we've hasten is null,
so getline will allocate space on the heap,
where it can write to the first line it's going to read from this file.
In this case, it allocated eight bytes.
It's getline's prerogative to decide how much memory it's going to allocate,
but we will find out exactly how much was allocated,
because the next thing getline does is update the size variable.
After creating a buffer and updating the size,
it then reads the line of the file,
and stores it into the string.
As you can see, we've read in a word as well as
the backslash in or newline character which indicated the interval line,
as well as a backslide zero which indicates the end of the string inside of the buffer.
The final thing getline does is return the length of that string,
which is four back to the calling function.
Keep in mind the newline character,
but not the null terminator is counted in the link.
Next in this assignment statement,
length will be updated from zero to four,
and we go inside the while loop where we print out the line.
Notice that we didn't have to include a newline character in the print statement,
since it was included in the string itself.
Now, we're ready to read the next line.
Once again, we create a stack frame per getline,
passing in a pointer to the buffer,
a pointer to the size,
and a pointer to the file that we're reading.
We note the call site location,
and step into the function.
When it's time to allocate memory,
line actually points to something,
a buffer of size eight.
So, we don't actually need to allocate more memory,
we also don't need to update size.
Now, we read a line from the file into the string.
Notice that we overwrote
the original buffer because we gave
getline the same buffer that we had been using before.
If we had wanted to maintain the first string,
we would have had to store it somewhere else.
Now, we can return the length of the new string into the calling function,
where we complete the assignment statement,
updating length to six,
and enter the while loop,
where we printed the new name.
Now, we are ready to read the next name from the file.
We place another call to getline,
it doesn't need to allocate memory, or update size.
So, it reads into the string,
but the buffer has insufficient size to read the whole line.
It is important to realize that getline might need to reallocate
memory in which case it allocates a longer buffer,
copies the existing data,
frees the old buffer,
and updates line to point at the new buffer and update size.
Now, it can continue reading into the string.
This time there is sufficient space.
So, we return the length 10,
and go back to the call site.
We complete the assignment statement,
enter the while loop and print the name,
returning to the top of the while loop.
We place one more call to getline.
We don't need to allocate memory or update size.
However, this time when we read into this string,
it reaches EOF and returns negative one.
So, we leave the function without executing the other steps,
complete the assignment statement,
and skip the while loop since length is not greater than or equal to zero.
Since we're done with the memory allocated on the heap,
we need to remember to free it.
Finally, we can exit our program.
Note that in a real program,
you would also want to close the file.
Andrew D. HiltonAssociate Professor of the Practice
Anne BracySenior Lecturer
Genevieve M. LippAdjunct Professor
