From a4513253186998e2980cf840f396d8493821c29a Mon Sep 17 00:00:00 2001 From: leitner Date: Thu, 22 Aug 2013 23:41:37 +0000 Subject: [PATCH] add better comments add fmt_copybytes --- fmt.h | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/fmt.h b/fmt.h index 4249880..cf5aea7 100644 --- a/fmt.h +++ b/fmt.h @@ -8,6 +8,8 @@ #include /* for time_t: */ #include +/* for byte_copy */ +#include "byte.h" #ifdef __cplusplus extern "C" { @@ -19,27 +21,51 @@ extern "C" { #define FMT_XLONG 33 /* enough space to hold 2^128 - 1 in hexadecimal, plus \0 */ #define FMT_LEN ((char *) 0) /* convenient abbreviation */ -/* The formatting routines do not append \0! - * Use them like this: buf[fmt_ulong(buf,number)]=0; */ - -/* convert signed src integer -23 to ASCII '-','2','3', return length. +/* This file declares routines for formatting strings and numbers in + * various forms or encodings, either binary or text based. + * + * The first argument is always the destination buffer, the second + * argument is always the value to be formatted/encoded. The return + * value is always the number of bytes written in the output buffer. + * + * If you don't know how large the output will be, call the function + * first with NULL as destination buffer and use the length it returns + * to allocate the destination buffer. + * + * Note that none of these routines append a 0 terminator. If you need + * 0 termination, call the functions like this: + + buf[fmt_ulong(buf,number)]=0; + + */ + +/* convert signed src integer -23 to ASCII '-','2','3', return number of + * bytes of value in output format (3 in this example). * If dest is not NULL, write result to dest */ size_t fmt_long(char *dest,signed long src); -/* convert unsigned src integer 23 to ASCII '2','3', return length. +/* convert unsigned src integer 23 to ASCII '2','3', return number of + * bytes of value in output format (2 in this example). * If dest is not NULL, write result to dest */ size_t fmt_ulong(char *dest,unsigned long src); -/* convert unsigned src integer 0x23 to ASCII '2','3', return length. +/* convert unsigned src integer 0x23 to ASCII '2','3', return number of + * bytes of value in output format (2 in this example). * If dest is not NULL, write result to dest */ size_t fmt_xlong(char *dest,unsigned long src); -/* convert unsigned src integer 023 to ASCII '2','3', return length. +/* convert unsigned src integer 023 to ASCII '2','3', return number of + * bytes of value in output format (2 in this example). * If dest is not NULL, write result to dest */ size_t fmt_8long(char *dest,unsigned long src); +/* like fmt_long but for long long */ size_t fmt_longlong(char *dest,signed long long src); + +/* like fmt_ulong but for unsigned long long */ size_t fmt_ulonglong(char *dest,unsigned long long src); + +/* like fmt_xlong but for unsigned long long */ size_t fmt_xlonglong(char *dest,unsigned long long src); #define fmt_uint(dest,src) fmt_ulong(dest,src) @@ -49,6 +75,8 @@ size_t fmt_xlonglong(char *dest,unsigned long long src); /* Like fmt_ulong, but prepend '0' while length is smaller than padto. * Does not truncate! */ +/* fmt_ulong0(buf,23,4) -> '0','0','2','3' return 4 */ +/* fmt_ulong0(buf,234,2) -> '2','3','4', return 3 */ size_t fmt_ulong0(char *,unsigned long src,size_t padto); #define fmt_uint0(buf,src,padto) fmt_ulong0(buf,src,padto) @@ -67,12 +95,27 @@ size_t fmt_plusminus(char *dest,int src); size_t fmt_minus(char *dest,int src); /* copy str to dest until \0 byte, return number of copied bytes. */ +/* fmt_str(NULL,str) == strlen(str) */ +/* fmt_str(buf,str) == strcpy(buf,str), return strlen(str) */ +/* strcat(strcpy(buf,"foo"),"bar") can be written as + * i=fmt_str(buf,"foo"); + * i+=fmt_str(buf+i,"bar"); + * buf[i]=0; + * This is more efficient because strcat needs to scan the string to + * find the end and append. + */ size_t fmt_str(char *dest,const char *src); /* copy str to dest until \0 byte or limit bytes copied. * return number of copied bytes. */ size_t fmt_strn(char *dest,const char *src,size_t limit); +/* copy n bytes from src to dest, return n */ +static inline size_t fmt_copybytes(char* dest,const char* src,size_t n) { + byte_copy(dest,n,src); + return n; +} + /* "foo" -> " foo" * write padlen-srclen spaces, if that is >= 0. Then copy srclen * characters from src. Truncate only if total length is larger than @@ -102,6 +145,13 @@ size_t fmt_utf8(char* dest,uint32_t n); /* can store 0-0x7fffffff */ size_t fmt_asn1derlength(char* dest,unsigned long long l); /* 0-0x7f: 1 byte, above that 1+bytes_needed bytes */ size_t fmt_asn1dertag(char* dest,unsigned long long l); /* 1 byte for each 7 bits; upper bit = more bytes coming */ +/* '&' -> '&', '<' -> '<' + * 0 is rejected + * control characters except \t \r \n are written in escaped form + * characters from d780 to dfff and fffe and ffff and everything above 10ffff are also rejected. + * everything else is passed through encoded as UTF-8 */ +size_t fmt_xmlescape(char* dest,uint32_t ch); + /* internal functions, may be independently useful */ char fmt_tohex(char c);