[Flex-help] Why yyrestart after scanning begins and before an EOF has been encountered?

[Peng Yu <pen...@gm...>]

According to http://flex.sourceforge.net/manual/User-Values.html,

FILE *yyin
    is the file which by default flex reads from. It may be redefined
but doing so only makes sense before scanning begins or after an EOF
has been encountered. Changing it in the midst of scanning will have
unexpected results since flex buffers its input; use yyrestart()
instead.

Based on the above description, I infer that yyrestart() not only sets
yyin but also flushes the buffer.

I'm wondering in what situations it is necessary to yyrestart() after
scanning begins and before an EOF has been encountered. The fact that
yyrestart() is defined indicates that there might be such situations,
because, otherwise, we can just directly change yyin without using
yyrestart, right?