|
|
| |
|
|
|
String/Memory Utility Functions
20.1 Overview
This chapter defines string and memory utility functions. The first section lists general string/memory functions. The second section lists udi_snprintf and related formatting functions.
20.2 General String/Memory Functions
UDI defines several string and memory operator functions. These functions parallel their ISO 9899 (ISO C) counterparts but are specifically designed to be used from a UDI driver perspective. Most of these routines are chosen and optimized for processing speed and are fully reentrant (i.e. no global writable storage is involved).
NAME udi_strlen
Determine string length
#include <udi.h>udi_size_t udi_strlen ( const char *s );ARGUMENTS s is a pointer to a null-terminated string.
DESCRIPTION The udi_strlen function scans the specified string to locate the null-terminator and returns the number of bytes in the string (not including the terminator).
RETURN VALUES The udi_strlen function returns the number of bytes in the string s.
NAME udi_strcat, udi_strncat
String concatenation
#include <udi.h>char *udi_strcat ( char *s1, const char *s2 ); char *udi_strncat ( char *s1, const char *s2, udi_size_t n );ARGUMENTS s1 is a pointer to the destination string.
s2 is a pointer to the source string.
n is the destination string maximum length (in bytes).
DESCRIPTION The udi_strcat and udi_strncat functions are used to append the contents of string s2 to the end of the existing string s1, overwriting the null-terminator character at the end of s1 and ending with a new null-terminator character. The strings must not overlap and the s1 string must have enough space for the result.
The udi_strncat form may be used to limit the size of the result: this function will stop copying bytes from s2 to s1 once the length of s1 has reached n-1 bytes; a null-terminator will be supplied as the n'th byte if the end of s2 has not been reached.
RETURN VALUES The udi_strcat and udi_strncat functions return a pointer to the resulting null-terminated string s1.
NAME udi_strcmp, udi_strncmp,
String/memory comparison
udi_memcmp
#include <udi.h>udi_sbit8_t udi_strcmp ( const char *s1, const char *s2 ); udi_sbit8_t udi_strncmp ( const char *s1, const char *s2, udi_size_t n ); udi_sbit8_t udi_memcmp ( const void *s1, const void *s2, udi_size_t n );ARGUMENTS s1 is a pointer to the first character string or memory area.
s2 is a pointer to the second character string or memory area.
n is the maximum size to be compared (in bytes).
DESCRIPTION The udi_strcmp and udi_strncmp functions are used to compare the contents of two null-terminated character strings. The strings are compared on a byte-by-byte basis and a comparison value is returned when the first differing character or the end of the strings is reached.
For the udi_strncmp function, comparison halts after comparing n characters unless the end of either string has already been reached. If both strings are identical throughout the first n characters, the udi_strncmp function return value indicates that the strings are equal, regardless of any remaining content.
The udi_memcmp function operates in a similar manner as udi_strncmp except that null characters do not terminate the comparison, which will always continue until the specified n bytes have been compared or a difference has been reached.
RETURN VALUES These functions return an integer value less than, equal to, or greater than zero if s1 (or the first n bytes thereof) is lexicographically less than, equal, to, or greater than s2. This comparison is made by comparing each unsigned byte value until there is a mismatch or all bytes compare equal.
NAME udi_strcpy, udi_strncpy,
String/memory copy
udi_memcpy, udi_memmove
#include <udi.h>char *udi_strcpy ( char *s1, const char *s2 ); char *udi_strncpy ( char *s1, const char *s2, udi_size_t n ); void *udi_memcpy ( void *s1, const void *s2, udi_size_t n ); void *udi_memmove ( void *s1, const void *s2, udi_size_t n );ARGUMENTS s1 is a pointer to the destination string or memory area.
s2 is a pointer to the source string or memory area.
n is the number of bytes to copy from s2 to s1.
DESCRIPTION The udi_strcpy and udi_strncpy functions copy the character array string pointed to by s2 (including the null-terminator character) to the character array string pointed to by s1. The strings must not overlap and the destination string s1 must be large enough to receive the copy.
The udi_strncpy function will stop copying once the specified n number of bytes has been copied or when a null terminator is encountered in the s2 string, whichever comes first. If there is no null byte encountered among the first n bytes of the s2 string, the result in s1 will not be null terminated. In the case where the length of s2 is less than n, the remainder of s1 will be padded with null characters.
The udi_memcpy function will operate in the same manner as the udi_strncpy function except that null characters (`\0') will be ignored and n bytes will always be copied into the s1 string. The memory areas must not overlap.
The udi_memmove function is similar to udi_memcpy but allows overlapping regions; it operates as if the contents of the s2 area were first copied to a temporary area and then copied back to the s1 area.
RETURN VALUES These functions return a pointer to the destination string s1.
NAME udi_strncpy_rtrim
Copy char array to string, removing trailing spaces
#include <udi.h>char *udi_strncpy_rtrim ( char *s1, const char *s2, udi_size_t n );ARGUMENTS s1 is a pointer to the destination character array string.
s2 is a pointer to the source character array, which must be at least n-bytes in size.
n is the number of bytes in s2 to be operated on (i.e., trailing spaces removed and the remaining bytes copied).
DESCRIPTION The udi_strncpy_rtrim function copies the first n bytes of the character array pointed to by s2, with trailing spaces removed, to the character array string pointed to by s1. The resulting s1 will be null terminated, with a null character (`\0') appended if necessary. The character arrays pointed to by s1 and s2 must not overlap and the destination array s1 must be large enough to receive the copy (i.e., up to n+1 bytes in size).
The source array pointed to by s2 is operated on as an n-byte character array; any embedded null characters will be copied along with other non-trailing blank characters. For example, if s2 is a 10-byte array containing the 4 characters "abcd", followed by `\0', followed by "efghi", the resulting s1 will contain the same 10 characters with an additional `\0' appended at the end. Similarly, if s2 is a 10-byte array containing the 9 characters "abcdefghi" followed by `\0', the resulting s1 will contain these 10 characters followed by an additional `\0'.
NAME udi_strchr, udi_strrchr,
String/memory searching
udi_memchr
#include <udi.h>char *udi_strchr ( const char *s, char c ); char *udi_strrchr ( const char *s, char c ); void *udi_memchr ( const void *s, udi_ubit8_t c, udi_size_t n );ARGUMENTS s is a pointer to the string or memory area to be searched.
c is the character to search for.
n is the maximum number of bytes to search.
DESCRIPTION The udi_strchr function returns a pointer to the first occurrence of the character c in the null-terminated string s.
The udi_strrchr function return a pointer to the last occurrence of the character c in the null-terminated string s.
The udi_memchr function returns a pointer to the first occurrence of the (unsigned character) byte c in the specified memory region, regardless of null bytes.
RETURN VALUES These functions return a pointer to the matched character or NULL if the character is not found.
NAME udi_memset
Memory initialization
#include <udi.h>void *udi_memset ( void *s, udi_ubit8_t c, udi_size_t n );ARGUMENTS s is a pointer to the memory area to be initialized.
c is the unsigned 8-bit value to use for initialization.
n is the size of the memory area (in bytes).
DESCRIPTION The udi_memset function is used to fill in the first n bytes of the memory area pointed to by the s argument with the unsigned byte value of c.
RETURN VALUES This function returns a pointer to the memory area s.
NAME udi_strtou32
Convert string to unsigned 32-bit value
#include <udi.h>udi_ubit32_t udi_strtou32 ( const char *s, char **endptr, int base );ARGUMENTS s is a pointer to the null-terminated string to be converted.
endptr optionally points to a character pointer in which a pointer to the first unconverted character is stored.
base is the base radix for interpretation of the numeric string.
DESCRIPTION The udi_strtou32 function is similar to its ISO C strtoul counterpart in that it converts the string pointed to by s to an unsigned 32-bit integer value according to the given base radix which must be between 2 and 36 inclusive, or be the special value of 0.
The string must begin with an arbitrary amount of whitespace (zero or more space, tab, carriage-return, or line-feed characters in any order) followed by a single optional `+' or `-' sign.
If base is between 2 and 36, inclusive, it is used as the base for conversion. After an optional leading sign, leading zeros are ignored, and "0x" or "0X" is ignored if base is 16.
If base is zero, the string itself determines the base as follows: After an optional leading sign, one or more leading zeros indicates octal conversion, and a leading "0x" or "0X" indicates hexadecimal conversion. Otherwise, decimal conversion is used.
The remainder of the string is converted to an unsigned 32-bit integer value in the obvious manner, stopping at the first character that is not a valid digit in the given base. (In bases above 10, the letter `A' in either upper or lower case represents 10, `B' represents 11, and so forth, with `Z' representing 35.)
If endptr is not NULL, udi_strtoul stores a pointer to the first invalid character into *endptr. (Thus, if *s is not `\0' but **endptr is `\0' on return, the entire string was a valid numeric.)
RETURN VALUE The udi_strtoul function returns the result of the conversion as an unsigned 32-bit value. If the input string contained a leading minus sign (`-'), the result will be as the appropriate negative number cast to a udi_ubit32_t unsigned type.
If the numeric string would cause a 32-bit integer overflow then the resulting value is unspecified.
20.3 String Formatting Functions
The functions described in this section assist in formatting strings with embedded parameters. The functions described here parallel their ISO C counterparts, but are not identical.
NAME udi_snprintf
Format printable string
#include <udi.h>udi_size_t udi_snprintf ( char *s, udi_size_t max_bytes, const char *format, ... );ARGUMENTS s is a pointer to the target buffer for the formatted output, which is a null-terminated printable string.
max_bytes is the maximum number of bytes to be written to s, including the null terminator.
format is the format string, which controls the formatting of the output string.
... are the remaining arguments, which provide the values used for the formatting codes.
DESCRIPTION The udi_snprintf routine is used to generate a formatted string from a set of input arguments and values. The operation of this utility is comparable to the ISO snprintf function with the exceptions noted and supporting only the format codes and modifiers documented below.
All format specifications are of the form %mf where m is an optional modifier of the form [[ 0, - ] nn] and f is one or more format codes.
The following format modifiers are defined
The udi_snprintf function supports the following format codes chosen to provide fast execution and common utility:
Once formatting has reached the specified max_bytes output length for s, this function returns without processing the remainder of the format or other arguments. A null terminator character will always be placed at the end of the generated string in s.RETURN VALUES The number of bytes in s, not including the null terminator.
EXAMPLES The following code segment:
udi_snprintf(s, 256, "%s %-2c %d: 0x%08x " "%<15=Active,14=DMA Ready,13=XMIT,"
"~13=RCV,0-2=Mode:0=HDX:1=FDX"
":2=Sync HDX:3=Sync FDX:4=Coded,"
"3-6=TX Threshold,7-10=RX Threshold>",
"Register", `#', 0, 0xc093, 0xc093);would result in the following contents of string s (without line breaks):
"Register # 0: 0x0000c093 <Active, DMA Ready, RCV, Mode=Sync FDX, TX Threshold=2, RX Threshold=1>"
The following code segment will produce different output based on the architecture on which it is run:
udi_snprintf(s, 256, "Stored at 0x%p", &var);
will produce one of the following output strings, depending on pointer size:
16-bit (e.g. 8086): "Stored at 0x801c"
32-bit (e.g. PA-RISC): "Stored at 0x505d806f"
64-bit (e.g. Alpha): "Stored at 0x300040cc6069f0c0"NAME udi_vsnprintf
Format printable string with varargs
#include <udi.h>udi_size_t udi_vsnprintf ( char *s, udi_size_t max_bytes, const char *format, va_list ap );ARGUMENTS s is a pointer to the target buffer for the formatted output, which is a null-terminated printable string.
max_bytes is the maximum number of bytes to be written to s, including the null terminator.
format is the format string, which controls the formatting of the output string.
ap is the varags argument list. (The va_list type definition is provided by the udi.h header file.)
DESCRIPTION The udi_vsnprintf routine is used to generate a formatted string from a set of input varargs arguments. This utility operates in the same manner as the udi_snprintf utility routine except that it uses a previously obtained varargs argument list instead of a sequence of actual arguments as parameters to this routine.
This routine is useful if the string formatting is to be done from within a routine that has already been passed the actual sequence of arguments and can only refer to those arguments via the varargs functionality.
RETURN VALUES The number of bytes in s, not including the null terminator.
udi_size_t mydriver_snprintf(char *s,
udi_size_t max_bytes, const char *format, ...)
{
static char prefix_str[] = "From MYDRIVER: ";
#define PREFIX_LEN (sizeof(prefix_str)-1)
va_list arglist;
udi_size_t retval;
va_start(arglist, format);
udi_assert(max_bytes > PREFIX_LEN);
udi_strcpy(s, prefix_str);
retval = udi_vsnprintf(s + PREFIX_LEN,
max_bytes - PREFIX_LEN,
format, arglist);
va_end(arglist);
return retval;
}l = mydriver_snprintf("Byte 1 = %02bX, "
"pktlen = %hu\n", *pkt->data, pkt->len);
| |
|
|
|