If I am getting a packet of information under the very narrow condition, it means that while the system at the other end knows I am not in a condition to get information, it still tries to send it. The other end should know better then to talk to me, because I haven't finished processing the last message it sent and I haven't told it "I got the message".
So, how are you going to get rid if the data that has not yet arrived when you execute your new flush() function? I don't see any use for a flush() function EXCEPT to dump the rest of a packet. And, the only way to do that is to read each character and see if it is the end of the packet. If so, the next packet might be good. If not, you still only want to (or, you should only want to) dump the rest of that packet.
Because I'm not in the midle of a packet.
I'm between packets.
I got a packet, actually, a command is how I view it in my setup.
This command may require more then 1 iteration of the loop, because of the way my firmware is constructed.
The board is NOT supposed to get another command until it as told the computer "I finished what you asked", as from the computer's perspective, the board can only carry out 1 command at a time. (This is by design)
But here I am, getting serial input when I am not supposed to. So, I complain and flush what I got.
Before someone asks, the reason I work this way is that serial communication in my setup is very low (not that much chatter) and actually acting on it is supposed to take a back-seat to more important functions in many cases.
Which might be the rest of a packet/command, some part of the rest of a packet/command, or the rest of the packet/command AND part of the next packet/command.
I really don't see the value in throwing away random amounts of unread data. I only see the value in throwing away the rest of a packet or throwing away whole packets. The old flush() function did not do that. Yours, which you could have written in less time than this thread has taken, CAN do that.
Except you missed the part where I said it can't. I already got a full command. I know that command is good and I'm working on it. I'm just not done. And it can't be the next command because the computer isn't supposed to send it until I say "I'm done".
Edit: As for the flush, someone already posted a very good one I am now using. Just trying to make it clear why I wanted it, partially to make sure I'm not making a mistake using it.
I had a re-look at the logic of my code and found something funny. Retrolefty was right, I'm ditching the flush. The fact that Serialevent isn't an interrupt as I was thinking, but runs at the end of the loop, removes the need for it and I end up with a much smaller puzzle to fit together.
Not sure where I got the idea it was an interupt. Perhaps from the deceptively short description in the doc. Some things are starting to make a lot more sence now ...
Coming in late to this thread, I just want to comment that flush flushes the output (all sorts of images spring to mind when I write that) but not perfectly. A byte in the USART might still be in progress, so you can't call flush and then shut down Serial, unfortunately.
As for flushing input, I agree with almost everyone above that indiscriminately discarding data is not a good idea. Reading until you get a "start packet" is a more useful scenario. You aren't saving time by "flushing" after all.
As for the documentation, I have a rule of thumb that the better the documentation, the less queries you get. However there will always be people who won't read it, no matter how good it is.
Well lets give them the benefit of the doubt and say that many people read what they understand and discard the rest and there are those that understand what they read and discard nothing...