xprintf - Embedded String Functions

Application Interface

The Embedded String Functions provides following functions.

Output

/*----------------------------------------------/
/  xputc - Put a character
/----------------------------------------------*/

void xputc (
    int chr           /* A character to be output (0-255) */
);

void xfputc (
    void(*func)(int), /* Pointer to the output function */
    int chr           /* Character to be output (0-255) */
);

/*----------------------------------------------/
/  xputs - Put a null-terminated string
/----------------------------------------------*/

void xputs (
    const char* str   /* Pointer to the null-terminated string to be output */
);

void xfputs (
    void(*func)(int), /* Pointer to the output function */
    const char* str   /* Pointer to the null-terminated string to be output */
);

/*----------------------------------------------/
/  xprintf - Formatted string output
/----------------------------------------------*/

void xprintf (        /* Put a formatted string to the default device */
    const char* fmt,  /* Pointer to the null-terminated format string */
    ...               /* Optional arguments... */
);

void xfprintf (       /* Put a formatted string to the specified device */
    void(*func)(int), /* Pointer to the output function */
    const char* fmt,  /* Pointer to the null-terminated format string */
    ...               /* Optional arguments... */
);

void xsprintf (       /* Put a formatted string to the memory */
    char* buff,       /* Pointer to the buffer to store output string */
    const char* fmt,  /* Pointer to the null-terminated format string */
    ...               /* Optional arguments... */
);

/*----------------------------------------------/
/  put_dump - Put a line of binary dump
/----------------------------------------------*/

void put_dump (
    const void* buff,   /* Pointer to the data to be displayed */
    unsigned long adr,  /* Heading address */
    int cnt,            /* Number of items to be displayed */
    int width           /* Size of item (1, 2 or 4) */
);

The format control directive is a sub-set of standard library shown as follows:

    %[flag][width][precision][size]type

flag

Padding options. A - specifies left-aligned. A 0 specifies zero padded. The default setting is in right-aligned and space padded.

width

Minimum width of the field, 1-99 or *. If the width of generated string is less than the specified value, rest field is padded with spaces or zeros. An * specifies the value comes from an argument in int type.

precision

Specifies number of fractional digits or maximum width of string, .0-.99 or .*. If number is omitted, it will be same as .0. Default setting is 6 for number and no limit for string.

size

Specifies size of integer argument, l(long) and ll(long long). If sizeof (long) == sizeof (int) is true (this is typical of 32-bit systems), prefix l can be omitted for long integer argument. The default size is int for integer arrument and floating point argument is always assumed double.

type

Specifies type of the output format and the argument as shown below. The length of generated string is in assumtion of int is 32-bit.

Type	Format	Argument	Length
d	Signed decimal	int, long, long long	1 to 11 (20 for ll) characters.
u	Unsigned decimal		1 to 10 (20 for ll) characters.
o	Unsigned octal		1 to 11 (22 for ll) characters.
x X	Unsigned hexdecimal		1 to 8 (16 for ll) characters.
b	Unsigned binary		1 to 32 characters. Limited to lower 32 digits when ll is specified.
c	Character	int	1 character.
s	String	char*	As input string. If the maximum length of input string is unkown, precision should be specified to avoid output buffer overflow. Null pointer generates a null string.
f	Floating point (decimal)	double	1 to 31 characters. If the number of characters exceeds 31, it generates "±OV". Not a number and infinite generate "NaN" and "±INF".
e E	Floating point (e notation)		4 to 31 characters. If the number of characters exceeds 31 or exponent exceeds +99, it generates "±OV".

Examples:
    xprintf("%d", 1234);             /* "1234" */
    xprintf("%6d,%3d%%", -200, 5);   /* "  -200,  5%" */
    xprintf("%-6u", 100);            /* "100   " */
    xprintf("%ld", 12345678);        /* "12345678" */
    xprintf("%llu", 0x100000000);    /* "4294967296"   <XF_USE_LLI> */
    xprintf("%lld", -1LL);           /* "-1"           <XF_USE_LLI> */
    xprintf("%04x", 0xA3);           /* "00a3" */
    xprintf("%08lX", 0x123ABC);      /* "00123ABC" */
    xprintf("%016b", 0x550F);        /* "0101010100001111" */
    xprintf("%*d", 6, 100);          /* "   100" */
    xprintf("%s", "abcdefg");        /* "abcdefg" */
    xprintf("%5s", "abc");           /* "  abc" */
    xprintf("%-5s", "abc");          /* "abc  " */
    xprintf("%.5s", "abcdefg");      /* "abcde" */
    xprintf("%-5.2s", "abcdefg");    /* "ab   " */
    xprintf("%c", 'a');              /* "a" */
    xprintf("%12f", 10.0);           /* "   10.000000" <XF_USE_FP> */
    xprintf("%.4E", 123.45678);      /* "1.2346E+02"   <XF_USE_FP> */

Input

/*----------------------------------------------/
/  xgets - Get a line from the input device
/----------------------------------------------*/

int xgets (     /* 0:End of stream, 1:A line arrived */
    char* buff, /* Pointer to the buffer to input */
    int len     /* Buffer length */
);

/*----------------------------------------------/
/  xatoi - Get a value of integer string
/----------------------------------------------*/
/* "123 -5    0x3ff 0b1111 0377 1.5 "
       ^                            1st call returns 123 and next ptr
          ^                         2nd call returns -5 and next ptr
                   ^                3rd call returns 1023 and next ptr
                          ^         4th call returns 15 and next ptr
                               ^    5th call returns 255 and next ptr
                                 ^  6th call fails and returns 0
*/

int xatoi (      /* 0:Failed, 1:Succeeded */
    char** str,  /* Pointer to pointer to the string */
    long* res    /* Pointer to the valiable to store the value */
);

/*----------------------------------------------/
/  xatof - Get a value of floating point string
/----------------------------------------------*/
/* "123 -5.75 .6   +8.88E+5 1e-6  .  "
       ^                              1st call returns 1.23e2 and next ptr
             ^                        2nd call returns -5.75e0 and next ptr
                ^                     3rd call returns 6e-1 and next ptr
                           ^          4th call returns 8.88e5 and next ptr
                                ^     5th call returns 1e-6 and next ptr
                                   ^  6th call fails and returns 0
*/

int xatof (      /* 0:Failed, 1:Succeded */
    char** str,  /* Pointer to pointer to the string */
    double* res  /* Pointer to the valiable to store the value */
);

Device I/O functions

The output function is a user provided call-back function to write a byte to the output device. Its address should be set to the function pointer xfunc_output in the module, default output device. Typically, this function puts the byte to UART, LCD or some output device. The output function is called-back from xputc(). There is a macro to set it easy. For example, when attach void uart1_putc (uint8_t chr); to the module, xdev_out(uart1_putc); will do. If the output function has multiple arguments or simple output function is not available, a glue function will be needed. xfputc(), xfputs(), xfprintf() and xsprintf() override the default output device with its argument.

The input function is a user provided call-back function to read a byte from the input device. Its address should be set to the function pointer xfunc_input, default input device. There is a macro xdev_in() to set it easy. e.g. xdev_in(uart1_getc); The xfgets() function override the default input device with its argument. The input function is called-back from the xgets() function. Typically, input function reads a byte from input device or file. When the input device reported end of stream, the input function should return -1. The xgets() function aborts with zero and the application will able to detect it.

/* Write a byte to the output dechvice */

void output_func (
    int chr  /* A byte to be written */
);

/* Read a byte from the input device */

int input_func (void);  /* Returns 0 to 255 as a read character, -1 as EOF */

Downloads

• Embedded String Functions source files July 31, 2021
• Example to use the Embedded String Functions