=====
CS 111 - Week 15 Lecture 1 - 2025-12-09
=====

=====
TODAY WE WILL:
=====
*   announcements
*   example of a void function
*   example using the getline function
*   example of reading everything from a file
*   bit more on ++ and --
*   file stream method fail
*   hopefully: a waffle example!
*   prep for next class

=====
*   SHOULD be working on Homework 12 -
    at-least-1st-attempts due by 11:59 pm
    Friday, December 12!!!

=====
UPCOMING SCHEDULE NOTES!!!
=====
*   THURSDAY, DEC 11 - will be FINAL EXAM review

*   FRIDAY, DEC 12 -
    *   no lab exercise
    *   BUT! will be LA-run FINAL REVIEW SESSIONS during
        the lab times,
	*   4.5 bonus clicker points for participating in
	    either of these
	*   (and I will be there to help with Homework 12
	    as well)

    *  Friday - December 12 - 11:59 pm - remember
       that at-least-1st-attempts at Homework 12 are due

************
*   SUNDAY, DEC 14 - 11:59 pm - any improved parts of HOMEWORKS 10-12
    are due!!
************

*   ....so that...

*   MONDAY, DEC 15 - 12:01 am - example solutions for Homeworks 10-12
    will be AVAILABLE on Canvas!

*   THURSDAY, DEC 18 - ******* 8:00 am ******** is when Final Exam starts!
    *   8:00 am - 9:50 am
    *   NR 101

======
difference between prefix and postfix ++ and --
======
*   int quant = 410;

*   prefix?   means before its operand
    ++quant;

*   postfix?  means after its operand
    quant++;

    *   BOTH have a side-effect -- they make the value in
        quant 1 bigger than it was
	(or one smaller for --)

    *   BUT -- an expression using ++ or -- IS a
        compound expression with a value,
	and so it can be used within a larger compound
	expression;

        THAT's where you see the difference between
	prefix and postfix ++ and --!

    int quant = 410;
    int value;
    value = 3 + (quant++);
    cout << "value: " << value << endl
         << "quant: " << quant << endl;

    *   prints:
quant: 411
value: 413

    quant = 410;
    value = 3 + (++quant);
    cout << "value: " << value << endl
         << "quant: " << quant << endl;    

    *   prints:
quant: 411
value: 414

    WHY?

*   BECAUSE: the value of the expression:

    quant++

    ...is the value is of quant BEFORE it
    is added to!!

    (could think: "use quant, THEN add 1 to quant")

*   BECAUSE: the value of the expression:

    ++quant

    ...is the value of quant AFTER it
    is added to!!

    (could think: "add 1 to quant, THEN use quant")

*   SO keep this in mind IF you choose to use
    ++ and -- in sub-expressions within larger
    compound expressions!

=====
void functions
=====
*   you CAN write a C++ program that does not return anything --
    you give such a function a return type of void

    void assn_header(string course, int assn_num)
    ^^^^
    |||| means this function does NOT return a value

    *   good for a function that is intended to JUST have
        side-effects

*   note: your void function should NOT try to return a
    value!
    *   (you CAN have
        return;
	and that stops the function when that is executed
	and returns to the caller;

        but you CANNOT have
	return expr;
	)

*   note: a call to a void function is not
    an expression with a value --
    you CANNOT put it in a cout
    or within a larger compound expression
    or on the right-hand-side of an assignment statement!

*   (your tests may need to be... more creative...)
    describing the side effect or checking if it happened!)

*   see function assn_header in posted 111lect15-1.cpp

=====
getline function
=====
*   [corrected after class!!]
    ACTUALLY provided by the string library!

*   expects an input stream and a string variable or string
    that can be set (such as an expression representing an
    array element),
    
    has the side effect of reading the next things in the
    input stream until it encounters a newline,
    
    then treats what was read as a string and stores it into
    the second argument,

    and returns whether it succeeded!

*   so: you can use getline to read info that includes
    blanks and tabs!
    (which you cannot with >> and a string variable!)

*   note that the 2nd argument MUST be of type string --
    cannot be a char*, or int, or char, or double, or bool, etc.!

*   side note: if you use >> to read from an input stream,
    and THEN use getline to read from that input stream,
    you MAY need an extra getline to read "past" the newline
    that may have been left from reading using >> ...

    *   there's an example of this in 111lect15-1.cpp

=====
reading everything from a file
=====
*   FUN FACT: in modern versions of C++,
    reading something using >> is an expression
    that returns true if it succeeded!

*   This allows for a convenient while loop to
    read everything from a file!

*   For example, say that you have:

    ifstream my_fin;
    my_fin.open("desired_file.txt");

    desired_type next;

    while (my_fin >> next)
    {
        statement(s) perhaps using next;
    }

    *   if something is successfully read from my_fin input file
        stream into variable next, (my_fin >> next) is true,

        so you enter the loop and can use the newly-read value in
	variable next!

    *   but, when you reach the end of the file that my_fin is
        attached to, (my_fin >> next) will fail and have the
	value false, and you will properly exit the while loop
	at that point!

*   in modern versions of C++, getline likewise returns true
    if something is read from its given input stream into its
    given string variable --

    SO this, similarly, can be used to read everything in a
    file, one string at a time:    

*   For example, say that you have:

    ifstream my_fin;
    my_fin.open("desired_file.txt");

    string next_line;

    while (getline(my_fin, next_line))
    {
        statement(s) perhaps using next_line;
    }

    *   if something is successfully read from my_fin input file
        stream into string variable next_line,
	(getline(my_fin, next_line)) is true,

        so you enter the loop and can use the newly-read value in
	variable next_line!

    *   but, when you reach the end of the file that my_fin is
        attached to, (getline(my_fin, next_line)) will fail and have the
	value false, and you will properly exit the while loop
	at that point!

=====
added AFTER class: file stream method fail
=====
*   method fail can be used with an ifstream or ofstream,
    with no arguments, after you have attempted to open
    that file stream,

    and method fail will return true if the open of that
    file stream failed.

*   this allows you to write a bool expression to double-check
    that the file stream opening succeeded before trying to
    use it!

*   SO, you can write code such as the following:

    ifstream my_fin;
    string desired_file;

    cout << "What file would you like to read from? " << endl;
    cin >> desired_file;

    my_fin.open(desired_file);

    if (my_fin.fail() == true)
    {
        cout << "OH NO! Could not open file: "
	     << desired_file << endl;
	     
        // from a main, might choose to:
	// return EXIT_FAILURE;

        // from a non-main function, might choose to:
	// return;
	// return desired_expr;
    }