WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation

FILEs and Streams

Back in the days of C the concept of a FILE was conceived. A FILE was a variable that could be used to either read data from and/or send data to a file on a disk or to a console (ie screen and keyboard). Where a 'read' would read typed characters from the keyboard and a 'write' would write characters to the screen.
For those familiar with WebbotLib then a FILE is the combination of a Reader and/or a Writer.
C defines three FILEs by default:
1. stdout - a FILE that is used to write output to the standard output device (normally some kind of screen)
2. stdin - a FILE that is used to read input from the standard input device (normally some kind of keyboard)
3. stderr - a FILE that is used to write error messages to the standard error device. This is typically a log file on disk or may be a screen. It can be the same destination as stdout.
These FILE variables can then be used by the commands in stdio.h (which comes with your compiler) such as: fgetc, fputs, fprintf etc.
WebbotLib V2 allows you to use all of these commands and also adds the macro PRINTF(stream,format, args...) which places the format string in program memory to save space. This method is now preferred over the 'old' rprintf routines.
When generating your code from Project Designer you specify the device where the default output goes, and the device where any error messages go. Project Designer then sets 'stdout' and 'stdin' to the first device and 'stderr' to go to the second.
When C++ came along the concept of a FILE was extended into a class called a 'Stream'. The stream versions of stdout, stdin and stderr are called cout, cin and cerr respectively. WebbotLib provides support for streams via the class Stream.
This means you can print something to the standard out, in C++, using for example:
cout.print(12);
cout.print(1234);
cout.print("Hello World");
You will see how the 'print' function automatically copes with different types of data and, unlike rprintf or PRINTF, you don't need to remember the correct format string for the type of variable you are printing.
You can also keep calling the print routine on the same line ie:
cout.print("The answer to 4*8 = ").print(4*8).print('\n');
You may also use the '<<' operator to write data to a stream. So you could also write the previous code as:
cout << "The answer to 4*8 = " << 4*8 << '\n';
The choice is up to you. However: if you want to minimise the amount of RAM used by your program then you should place any fixed strings into program memory by using PSTR and then use the print_P function to print from program memory:
cout.print_P( PSTR("The answer to 4*8 =") ).print(4*8).print('\n');
There is no equivalent way of doing this using the '<<' operator.
As well as the cin, cout and cerr streams there are various things you can add to your project in Project Designer which also support streams. For example: uarts, displays and disk files on an sdCard. If you have added a uart in Project Designer called 'uart3' then you can send data to it in exactly the same way i.e.:
uart3.print("The answer to 4*8 = ").print(4*8).print('\n');

Valid XHTML 1.0 Transitional