/*
 * 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 <code>UDS_SUCCESS</code> or <code>error</code>
 **/
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 */