1

#ifndef STR_H

     2

#define STR_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Miscellaneous string utility functions

     8

 */

     9

#include <sys/types.h>

    10

#include <stdarg.h>

    11

#include "error.h"

    12

    13

/**

    14

 * Error codes

    15

 */

    16

enum str_error_code {

    17

    _ERR_STR_BEGIN = _ERR_STR,

    18

    ERR_STR_FMT_TAG,                ///< invalid parameter tag syntax

    19

    ERR_STR_FMT_NAME_LEN,           ///< invalid parameter name length

    20

    ERR_STR_FMT_NAME,               ///< invalid/unknown parameter name

    21

    ERR_STR_FMT_FLAGS_LEN,          ///< invalid paramter flags length

    22

    ERR_STR_FMT_FLAG,               ///< invalid paramter flag

    23

    ERR_STR_FMT_BUF_LEN,            ///< output buffer ran out

    24

};

    25

    26

/**

    27

 * Writes the given string into the given buffer, reading at most len bytes (or up to NUL if -1), and writing at most

    28

 * buf_size bytes, including the terminating NUL.

    29

 *

    30

 * Returns the number of input bytes that would have been written, not including the terminating NUL.

    31

 */

    32

size_t str_append_num (char *buf, size_t buf_size, const char *str, ssize_t len);

    33

    34

/**

    35

 * Like str_append_num with len = -1.

    36

 *

    37

 * @see str_append_num()

    38

 */

    39

size_t str_append (char *buf, size_t buf_size, const char *str);

    40

    41

/**

    42

 * Like str_append, but only a single char.

    43

 *

    44

 * @see str_append()

    45

 */

    46

size_t str_append_char (char *buf, size_t buf_size, char c);

    47

    48

/**

    49

 * Like str_append, but using formatted input instead.

    50

 *

    51

 * @see str_append()

    52

 */

    53

size_t str_append_fmt (char *buf, size_t buf_size, const char *fmt, ...);

    54

    55

/**

    56

 * Like str_append_fmt, but using a vargs list instead.

    57

 *

    58

 * @see str_append_fmt()

    59

 */

    60

size_t str_append_fmt_va (char *buf, size_t buf_size, const char *fmt, va_list vargs);

    61

    62

/**

    63

 * Use str_append* to write out the quoted char value to the given buffer.

    64

 */

    65

size_t str_quote_char (char *buf, size_t buf_size, char c);

    66

    67

/**

    68

 * Update data_size to add len (if given), then update buf_size to remove to min(buf_size, len), and return len.

    69

 *

    70

 * Intended to be used like:

    71

 * \code

    72

 *  buf += str_advance(&data_size, &buf_size, str_append_fmt(buf, buf_size, "...", ...));

    73

 * \endcode

    74

 */

    75

size_t str_advance (size_t *data_size, size_t *buf_size, size_t len);

    76

    77

/**

    78

 * Copy the given \a str into \buf, surrounding it with quotes and escaping any data inside.

    79

 *

    80

 * At most \a str_len bytes of input will be read, unless given as -1, whereupon str will be read up to the first \0 byte.

    81

 *

    82

 * At most \a buf_size bytes of output will be written, if the output string was truncated, it will end in '...', and a

    83

 * value larger than \a buf_size will be returned.

    84

 *

    85

 * As a special case, if \a str is NULL, only the string "NULL" will be output.

    86

 *

    87

 * @param buf the buffer to write the output to

    88

 * @param buf_size the size of the given output buffer

    89

 * @param str the input string

    90

 * @param str_len number of bytes of input to process, or -1 to use strlen()

    91

 * @return the total number of bytes that would have been written out, may be more than buf_size

    92

 */

    93

size_t str_quote (char *buf, size_t buf_size, const char *str, ssize_t str_len);

    94

    95

/**

    96

 * Callback function used by str_format to look up a value for a parameter.

    97

 *

    98

 * @param name the name of the paramter in the format string

    99

 * @param value returned pointer to param value

   100

 * @param value_len returned param value length, or -1 for strlen

   101

 * @param arg the context arg given to str_format

   102

 * @return the parameter value, or NULL to error out

   103

 */

   104

typedef err_t (*str_format_cb) (const char *name, const char **value, ssize_t *value_len, void *arg);

   105

   106

/**

   107

 * Maximum length of a parameter name

   108

 */

   109

#define STR_FORMAT_PARAM_MAX 32

   110

   111

/**

   112

 * Maximum length of a parameter flags section

   113

 */

   114

#define STR_FORMAT_FLAGS_MAX 8

   115

   116

/**

   117

 * Format an output string based on the given template, filling in parameter values using a callback function.

   118

 */

   119

err_t str_format (char *buf, size_t buf_size, const char *format, str_format_cb func, void *arg);

   120

   121

#endif