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_NONE,

    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

    24

    ERR_STR_FMT_BUF_LEN,            ///< output buffer ran out

    25

};

    26

    27

/**

    28

 * Error list

    29

 */

    30

const struct error_list str_errors;

    31

    32

/**

    33

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

    34

 * buf_size bytes, including the terminating NUL.

    35

 *

    36

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

    37

 */

    38

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

    39

    40

/**

    41

 * Like str_append_num with len = -1.

    42

 *

    43

 * @see str_append_num()

    44

 */

    45

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

    46

    47

/**

    48

 * Like str_append, but only a single char.

    49

 *

    50

 * @see str_append()

    51

 */

    52

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

    53

    54

/**

    55

 * Like str_append, but using formatted input instead.

    56

 *

    57

 * @see str_append()

    58

 */

    59

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

    60

    61

/**

    62

 * Like str_append_fmt, but using a vargs list instead.

    63

 *

    64

 * @see str_append_fmt()

    65

 */

    66

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

    67

    68

/**

    69

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

    70

 */

    71

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

    72

    73

/**

    74

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

    75

 *

    76

 * Intended to be used like:

    77

 * \code

    78

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

    79

 * \endcode

    80

 */

    81

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

    82

    83

/**

    84

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

    85

 *

    86

 * 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.

    87

 *

    88

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

    89

 * value larger than \a buf_size will be returned.

    90

 *

    91

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

    92

 *

    93

 * @param buf the buffer to write the output to

    94

 * @param buf_size the size of the given output buffer

    95

 * @param str the input string

    96

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

    97

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

    98

 */

    99

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

   100

   101

/**

   102

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

   103

 *

   104

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

   105

 * @param value returned pointer to param value

   106

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

   107

 * @param arg the context arg given to str_format

   109

 */

   111

   112

/**

   113

 * Maximum length of a parameter name

   114

 */

   115

#define STR_FORMAT_PARAM_MAX 32

   116

   117

/**

   118

 * Maximum length of a parameter flags section

   119

 */

   120

#define STR_FORMAT_FLAGS_MAX 8

   121

   122

/**

   123

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

   124

 */

   125

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

   126

   127

#endif