/*

 * Copyright (c) 2020 Red Hat, Inc.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 * 

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 * 

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA

 * 02110-1301, USA. 

 *

 * $Id: //eng/uds-releases/jasper/src/uds/stringUtils.h#2 $

 */

#ifndef STRING_UTILS_H

#define STRING_UTILS_H

#include <stdarg.h>

#ifdef __KERNEL__

#include <linux/kernel.h>

#include <linux/string.h>

#else

#include <stdio.h>   // for vsnprintf

#include <stdlib.h>  // for strtol

#include <string.h>

#include <strings.h>

#endif

#include "compiler.h"

#include "typeDefs.h"

/**

 * Convert a boolean value to its corresponding "true" or "false" string.

 *

 * @param value  The boolean value to convert

 *

 * @return "true" if value is true, "false" otherwise.

 **/

static INLINE const char *boolToString(bool value)

{

  return (value ? "true" : "false");

}

/**

 * Allocate a string built according to format (our version of asprintf).

 *

 * @param [in]  what    A description of what is being allocated, for error

 *                      logging; if NULL doesn't log anything.

 * @param [out] strp    The pointer in which to store the allocated string.

 * @param [in]  fmt     The sprintf format parameter.

 *

 * @return UDS_SUCCESS, or the appropriately translated asprintf error

 **/

int allocSprintf(const char *what, char **strp, const char *fmt, ...)

  __attribute__((format(printf, 3, 4), warn_unused_result));

/**

 * Write a printf-style string into a fixed-size buffer, returning

 * errors if it would not fit. (our version of snprintf)

 *

 * @param [in]  what    A description of what is being written, for error

 *                      logging; if NULL doesn't log anything.

 * @param [out] buf     The target buffer

 * @param [in]  bufSize The size of buf

 * @param [in]  error   Error code to return on overflow

 * @param [in]  fmt     The sprintf format parameter.

 * @return UDS_SUCCESS or error

 **/

int fixedSprintf(const char *what, char *buf, size_t bufSize,

                 int error, const char *fmt, ...)

  __attribute__((format(printf, 5, 6), warn_unused_result));

/**

 * Write printf-style string into an existing buffer, returning a specified

 * error code if it would not fit, and setting ``needed`` to the amount of

 * space that would be required.

 *

 * @param [in]  what    A description of what is being written, for logging.

 * @param [in]  buf     The buffer in which to write the string, or NULL to

 *                      merely determine the required space.

 * @param [in]  bufSize The size of buf.

 * @param [in]  error   The error code to return for exceeding the specified

 *                      space, UDS_SUCCESS if no logging required.

 * @param [in]  fmt     The sprintf format specification.

 * @param [in]  ap      The variable argument pointer (see <stdarg.h>).

 * @param [out] needed  If non-NULL, the actual amount of string space

 *                      required, which may be smaller or larger than bufSize.

 *

 * @return UDS_SUCCESS if the string fits, the value of the error parameter if

 *         the string does not fit and a buffer was supplied, or

 *         UDS_UNEXPECTED_RESULT if vsnprintf fails in some other undocumented

 *         way.

 **/

int wrapVsnprintf(const char *what, char *buf, size_t bufSize,

                  int error, const char *fmt, va_list ap, size_t *needed)

  __attribute__((format(printf, 5, 0), warn_unused_result));

/**

 * Helper to append a string to a buffer.

 *

 * @param buffer        the place at which to append the string

 * @param bufEnd        pointer to the end of the buffer

 * @param fmt           a printf format string

 *

 * @return      the updated buffer position after the append

 *

 * if insufficient space is available, the contents are silently truncated

 **/

char *appendToBuffer(char *buffer, char *bufEnd, const char *fmt, ...)

  __attribute__((format(printf, 3, 4)));

/**

 * Variable-arglist helper to append a string to a buffer.

 *

 * @param buffer  the place at which to append the string

 * @param bufEnd  pointer to the end of the buffer

 * @param fmt     a printf format string

 * @param args    printf arguments

 *

 * @return the updated buffer position after the append

 *

 * if insufficient space is available, the contents are silently truncated

 **/

char *vAppendToBuffer(char       *buffer,

                      char       *bufEnd,

                      const char *fmt,

                      va_list     args)

  __attribute__((format(printf, 3, 0)));

/**

 * Our version of strtok_r, since some platforma apparently don't define it.

 *

 * @param str           On first call, the string to tokenize. On subsequent

 *                      calls, NULL.

 * @param delims        The set of delimiter characters.

 * @param statePtr      The address of a variable which holds the state of

 *                      the tokenization between calls to nextToken.

 *

 * @return the next token if any, or NULL

 **/

char *nextToken(char *str, const char *delims, char **statePtr);

/**

 * Parse a string representing a decimal uint64_t.

 *

 * @param str           The string.

 * @param num           Where to put the number.

 *

 * @return UDS_SUCCESS or the error UDS_INVALID_ARGUMENT if the string

 *         is not in the correct format.

 **/

int parseUint64(const char *str, uint64_t *num)

  __attribute__((warn_unused_result));

/**

 * Attempt to convert a string to an integer (base 10)

 *

 * @param nptr  Pointer to string to convert

 * @param num   The resulting integer

 *

 * @return UDS_SUCCESS or an error code

 **/

int stringToSignedInt(const char *nptr, int *num)

  __attribute__((warn_unused_result));

/**

 * Attempt to convert a string to a long integer (base 10)

 *

 * @param nptr  Pointer to string to convert

 * @param num   The resulting long integer

 *

 * @return UDS_SUCCESS or an error code

 **/

int stringToSignedLong(const char *nptr, long *num)

  __attribute__((warn_unused_result));

/**

 * Attempt to convert a string to an unsigned integer (base 10).

 *

 * @param nptr  Pointer to string to convert

 * @param num   The resulting unsigned integer

 *

 * @return UDS_SUCCESS or an error code

 **/

int stringToUnsignedInt(const char *nptr, unsigned int *num)

  __attribute__((warn_unused_result));

/**

 * Attempt to convert a string to an unsigned long integer (base 10).

 *

 * @param nptr  Pointer to string to convert

 * @param num   The resulting long unsigned integer

 *

 * @return UDS_SUCCESS or an error code

 **/

int stringToUnsignedLong(const char *nptr, unsigned long *num)

  __attribute__((warn_unused_result));

#endif /* STRING_UTILS_H */