From 6249ef08f780813309bd2fa609a649b77e0c75c1 Mon Sep 17 00:00:00 2001 From: Elaine Chandler Date: Mon, 9 May 2022 17:00:58 -0500 Subject: [PATCH] Added doxygen comments to epicsString.h --- modules/libcom/src/misc/epicsString.h | 132 +++++++++++++++++++++++++- 1 file changed, 128 insertions(+), 4 deletions(-) diff --git a/modules/libcom/src/misc/epicsString.h b/modules/libcom/src/misc/epicsString.h index 24f1efb62..823c09207 100644 --- a/modules/libcom/src/misc/epicsString.h +++ b/modules/libcom/src/misc/epicsString.h @@ -13,6 +13,12 @@ * Mark Rivers, Andrew Johnson, Ralph Lange */ +/** + * \file epicsString.h + * + * \brief Collection of string utility functions + */ + #ifndef INC_epicsString_H #define INC_epicsString_H @@ -24,20 +30,107 @@ extern "C" { #endif +/** \brief Converts C-style escape sequences to their binary form + * + * Copies characters from string to an output buffer and converts C-style escape sequences to + * their binary form. Since the output string can never be longer than the source, it is legal for + * @p inbuf and @p outbuf to point to the same buffer and @p outsize and @p inlen + * be equal, thus performing the character translation in-place. + * + * \param outbuf buffer to copy string to. The resulting string will be zero-terminated as long as + * @p outsize is non-zero. + * \param outsize length of output buffer not including the null-terminator. + * \param inbuf buffer to copy from. Null byte terminates the string. + * \param inlen maximum number of characters to copy from input buffer. + * + * \return number of characters that were written into output buffer, not counting the null terminator. +**/ LIBCOM_API int epicsStrnRawFromEscaped(char *outbuf, size_t outsize, const char *inbuf, size_t inlen); + +/** \brief Converts non-printable characters into C-style escape sequences + * + * Copies characters from the string into a output buffer converting non-printable characters into C-style + * escape sequences. In-place translations are not allowed since the escaped results will usually be larger + * than the input string. + * + * The following escaped character constants will be used in the output: + * \a \b \f \n \r \t \v \\ \’ \" \0 + * All other non-printable characters appear in form \xHH where HH are two hex digits. + * Non-printable characters are determined by the C runtime library’s isprint() function. + * + * \param outbuf buffer to copy string to. The resulting string will be zero-terminated as long as + * @p outsize is non-zero. + * \param outsize length of output buffer not including the null-terminator. + * \param inbuf buffer to copy from. Null byte will not terminates the string. + * \param inlen Number of characters to copy from input buffer. + * + * \return number of characters that would have been stored in the output buffer if it were large enough, + * or a negative value if dst == src. + * + */ LIBCOM_API int epicsStrnEscapedFromRaw(char *outbuf, size_t outsize, const char *inbuf, size_t inlen); + +/** \brief Scans string and returns size of output buffer needed to escape that string + * + * Scans up to \p len characters of the string that may contain non-printable characters, and returns + * the size of the output buffer that would be needed to escape that string. + * This routine is faster than calling epicsStrnEscapedFromRaw with a zero length output buffer; both + * should return the same result. + * + *\param buf string to scan + *\param len length of input string + * + *\return size of the output buffer that would be needed for converting to escape characters, not + * including the null terminator. + */ LIBCOM_API size_t epicsStrnEscapedFromRawSize(const char *buf, size_t len); + +/** \brief Does case-insensitive comparison of two strings + * + * Implements strcmp from the C standard library, except is case insensitive + */ LIBCOM_API int epicsStrCaseCmp(const char *s1, const char *s2); + +/** \brief Does case-insensitive comparision of two strings + * + * Implements strncmp from the C standard library, except is case insensitive + */ LIBCOM_API int epicsStrnCaseCmp(const char *s1, const char *s2, size_t len); + +/** \brief Duplicates a string + * + * Implements strdup from the C standard library. Calls mallocMustSucceed to allocate memory + */ LIBCOM_API char * epicsStrDup(const char *s); + +/** \brief Duplicates a string + * + * implements strndup from the C standard library. Calls mallocMustSucceed to allocate memory + */ LIBCOM_API char * epicsStrnDup(const char *s, size_t len); + +/** \brief Prints escaped version of string + * + * Prints the contents of its input buffer to given file descriptor, substituting escape sequences + * for non-printable characters. + * + * \param fp File descriptor to print to + * \param s String to print + * \param n Length of string + */ LIBCOM_API int epicsStrPrintEscaped(FILE *fp, const char *s, size_t n); + #define epicsStrSnPrintEscaped epicsStrnEscapedFromRaw + +/** \brief Calculates length of string + * + * Implements strnlen from the C standard library. + */ LIBCOM_API size_t epicsStrnLen(const char *s, size_t maxlen); -/** Matches a string against a pattern. +/** \brief Matches a string against a pattern. * * Checks if str matches the glob style pattern, which may contain ? or * wildcards. * A ? matches any single character. @@ -49,7 +142,7 @@ LIBCOM_API size_t epicsStrnLen(const char *s, size_t maxlen); */ LIBCOM_API int epicsStrGlobMatch(const char *str, const char *pattern); -/** Matches a string against a pattern. +/** \brief Matches a string against a pattern. * * Like epicsStrGlobMatch but with limited string length. * If the length of str is less than len, the full string is matched. @@ -60,11 +153,40 @@ LIBCOM_API int epicsStrGlobMatch(const char *str, const char *pattern); */ LIBCOM_API int epicsStrnGlobMatch(const char *str, size_t len, const char *pattern); + /** \brief Extract tokens from string + * + * Implements strtok_r from the C standard library + */ LIBCOM_API char * epicsStrtok_r(char *s, const char *delim, char **lasts); + +/** \brief Calculates a hash of a null-terminated string + * + * Calculates a hash of a null-terminated string. Initial seed may be provided which + * permits multiple strings to be combined into a single hash result. + * + *\param str null-terminated string + *\param seed Optionally provide seed to combine multiple strings in a single hash. Otherwise + * set to 0. + * + *\return Hash value for string + */ LIBCOM_API unsigned int epicsStrHash(const char *str, unsigned int seed); + + /** \brief Calculates a hash of a memory buffer + * + * Calculates a hash of a memory buffer that may contain null values. Initial seed may be provided which + * permits multiple buffers to be combined into a single hash result. + * + *\param str buffer + *\param length size of buffer + *\param seed Optionally provide seed to combine multiple buffers in a single hash. Otherwise + * set to 0. + * + *\return Hash value for buffer + */ LIBCOM_API unsigned int epicsMemHash(const char *str, size_t length, unsigned int seed); -/** Compare two strings and return a number in the range [0.0, 1.0] or -1.0 on error. +/** \brief Compare two strings and return a number in the range [0.0, 1.0] or -1.0 on error. * * Computes a normalized edit distance representing the similarity between two strings. * @@ -75,7 +197,9 @@ LIBCOM_API unsigned int epicsMemHash(const char *str, size_t length, */ LIBCOM_API double epicsStrSimilarity(const char *A, const char *B); -/* dbTranslateEscape is deprecated, use epicsStrnRawFromEscaped instead */ +/** \brief DEPRECATED + * \deprecated dbTranslateEscape is deprecated, use epicsStrnRawFromEscaped instead + */ LIBCOM_API int dbTranslateEscape(char *s, const char *ct); #ifdef __cplusplus