Formatted Output


Functions

void TRACE (char *sz_format[, argument]...)
int cprintf (char *sz_format[, argument]...)
int sprintf (char *ptr_buffer, char *sz_format[, argument]...)
int vsprintf (char *ptr_buffer, char *sz_format, va_list argv_list)

Detailed Description

With the help of these functions you can output data to either console or string buffer.

Function Documentation

void TRACE ( char *sz_format...[, argument] )
 

Traces to the system console.
Specifies a variable number of arguments that are used in exactly the same way that a variable number of arguments are used in the run-time function cprintf. Use format and variable arguments to format your message and make it readable and informative. Please keep in mind that it adds a Thread/timers prefix to the line, as well as necessary line ends.

Parameters:
sz_format   format control(see sprintf() for the full format description).
argument   optional arguments.
Returns:
none. 
       #include <cybiko.h>
       ...
       TRACE( "Hello, World!" );
       ...
See also:
cprintf, sprintf.

int cprintf ( char *sz_format...[, argument] )
 

Formats and prints the string to the Cybiko console.

Parameters:
sz_format   format control(see sprintf() for the full format description).
argument   optional arguments.
Returns:
the number of characters printed. 
       #include <cybiko.h>
       ...
       int nVal;
       nVal = 54;
       ...
       cprintf( "nVal = %d", nVal );
       ...
See also:
TRACE, sprintf.

int sprintf ( char * ptr_buffer,
char *sz_format...[, argument] )
 

Writes formatted data to a string.
This function works almost exactly like standard C one, but it does not support all format tags and specifiers. If you've never heard about printf routines, here's the general idea: you specify a format line with some text that may contain format tags. For each format tag found, sprintf() takes a parameter for the stack. This method does not allow a compile time check, but it does give you enormous flexibility and effectiveness. So, you code it this way: 

  sprintf( buffer_ptr, "My number is %-10d",123);
Here '-10d' is a format tag that says, "there is a decimal value to be printed with left justification in the 10 characters field."

The following format specifiers are allowed:

%[-][0][<size>][{l|L}]{i|d|x|X|s|c|%}

Their meaning is standard:

  • leading '-' sets left justification (the default is right)
  • if leading zero is specified, leading zeroes will be printed for numbers.
  • optional <size> (decimal number) sets the size of the output field
  • optional 'l' or 'L' prefix means that number is long
  • 'i' and 'd' causes a decimal integer to be printed
  • 'x' and 'X' causes a hexadecimal number (with small or capital letters, respectively) to be printed
  • 's' refers to a character string (might be UNICODE or bytes)
  • 'c' means single character
  • '%' means "just put out a percent character without taking arguments."
All other characters in the format line will be just printed out as is. Remember, it is up to you to handle the arguments list and the format line in the correct correspondence.
Parameters:
ptr_buffer   a storage location for output.
sz_format   format-control string. @argument optional arguments.
Returns:
the number of characters written, not including the terminating null character, or a negative value if an output error occurs. 
       #include <cybiko.h>
       #define FIRST_PLAYER_WINS            0
       #define SECOND_PLAYER_WINS           1
       ...
       const char* sz_format = "%s player WINS!";
       const char* sz_player_name[2] = {
                                         "First",
                                         "Second"
                                       };
       int game_result;
       char sz_result_string[24];
       ...
       sprintf( sz_result_string, sz_format, sz_player_name[ game_result ] );
       ...

int vsprintf ( char * ptr_buffer,
char * sz_format,
va_list argv_list )
 

Writes formatted output using a pointer to a list of arguments.

Parameters:
ptr_buffer   a storage location for output.
sz_format   format-control string(see sprintf() for the full format description).
argv_list   a pointer to a list of arguments.
Returns:
the number of characters written, not including the terminating null character, or a negative value if an output error occurs. 
      #include <cybiko.h>
      ...
      //  Logs errors to the file.
      void trace2logfile(char* sz_format, ...)
      {
        va_list parameters;
        char sz_buffer[64];
        struct FileOutput* ptr_log_file;

        //  Formats string.
        va_start( parameters, sz_format );
        vsprintf( sz_buffer, sz_format, parameters );
        va_end( parameters );

        //  Writes it to file "error.log".
        ptr_log_file = (struct FileOutput*)malloc( sizeof( struct FileOutput ) );
        FileOutput_ctor_Ex( ptr_log_file, "error.log", TRUE );
        FileOutput_seekp( ptr_log_file, 0, SEEK_END );
        FileOutput_write( ptr_log_file, sz_buffer, strlen(sz_buffer) );
        FileOutput_dtor( ptr_log_file, FREE_MEMORY );
      }
      ...
See also:
va_start, va_end, va_arg.