210 lines
7.9 KiB
C
210 lines
7.9 KiB
C
/*************************************************************************\
|
||
* Copyright (c) 2009 Helmholtz-Zentrum Berlin fuer Materialien und Energie.
|
||
* Copyright (c) 2009 UChicago Argonne LLC, as Operator of Argonne
|
||
* National Laboratory.
|
||
* Copyright (c) 2002 The Regents of the University of California, as
|
||
* Operator of Los Alamos National Laboratory.
|
||
* SPDX-License-Identifier: EPICS
|
||
* EPICS BASE is distributed subject to a Software License Agreement found
|
||
* in file LICENSE that is included with this distribution.
|
||
\*************************************************************************/
|
||
|
||
/* Authors: Jun-ichi Odagiri, Marty Kraimer, Eric Norum,
|
||
* Mark Rivers, Andrew Johnson, Ralph Lange
|
||
*/
|
||
|
||
/**
|
||
* \file epicsString.h
|
||
*
|
||
* \brief Collection of string utility functions
|
||
*/
|
||
|
||
#ifndef INC_epicsString_H
|
||
#define INC_epicsString_H
|
||
|
||
#include <stdio.h>
|
||
#include "epicsTypes.h"
|
||
#include "libComAPI.h"
|
||
|
||
#ifdef __cplusplus
|
||
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:
|
||
* \verbatim \a \b \f \n \r \t \v \\ \’ \" \0 \endverbatim
|
||
* 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 \p outbuf == \p inbuf.
|
||
*
|
||
*/
|
||
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);
|
||
|
||
/** \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.
|
||
* A * matched any sub-string.
|
||
*
|
||
* @returns 1 if str matches the pattern, 0 if not.
|
||
*
|
||
* @since EPICS 3.14.7
|
||
*/
|
||
LIBCOM_API int epicsStrGlobMatch(const char *str, const char *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.
|
||
*
|
||
* @returns 1 if the first len characters of str match the pattern, 0 if not.
|
||
*
|
||
* @since 7.0.6
|
||
*/
|
||
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);
|
||
/** \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.
|
||
*
|
||
* @returns 1.0 when A and B are identical, down to 0.0 when A and B are unrelated,
|
||
* or < 0.0 on error.
|
||
*
|
||
* @since EPICS 7.0.5
|
||
*/
|
||
LIBCOM_API double epicsStrSimilarity(const char *A, const char *B);
|
||
|
||
/** \brief DEPRECATED
|
||
* \deprecated dbTranslateEscape is deprecated, use epicsStrnRawFromEscaped() instead
|
||
*/
|
||
LIBCOM_API int dbTranslateEscape(char *s, const char *ct);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* INC_epicsString_H */
|