/*
 * 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/vdo-releases/aluminum/src/c++/vdo/kernel/vdoStringUtils.h#1 $
 */

#ifndef VDO_STRING_UTILS_H
#define VDO_STRING_UTILS_H

#include <stdarg.h>
#include <linux/types.h>

/**
 * 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, ...);

/**
 * Variable-arglist helper to append a string to a buffer.
 * If insufficient space is available, the contents are silently truncated.
 *
 * @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
 **/
char *vAppendToBuffer(char       *buffer,
                      char       *bufEnd,
                      const char *fmt,
                      va_list     args);

/**
 * Split the input string into substrings, separated at occurrences of
 * the indicated character, returning a null-terminated list of string
 * pointers.
 *
 * The string pointers and the pointer array itself should both be
 * freed with FREE() when no longer needed. This can be done with
 * freeStringArray (below) if the pointers in the array are not
 * changed. Since the array and copied strings are allocated by this
 * function, it may only be used in contexts where allocation is
 * permitted.
 *
 * Empty substrings are not ignored; that is, returned substrings may
 * be empty strings if the separator occurs twice in a row.
 *
 * @param [in]  string             The input string to be broken apart
 * @param [in]  separator          The separator character
 * @param [out] substringArrayPtr  The NULL-terminated substring array
 *
 * @return  UDS_SUCCESS or -ENOMEM
 **/
int splitString(const char *string, char separator, char ***substringArrayPtr)
  __attribute__((warn_unused_result));

/**
 * Join the input substrings into one string, joined with the indicated
 * character, returning a string.
 *
 * @param [in]  substringArray  The NULL-terminated substring array
 * @param [in]  arrayLength     A bound on the number of valid elements
 *                              in substringArray, in case it is not
 *                              NULL-terminated.
 * @param [in]  separator       The separator character
 * @param [out] stringPtr       A pointer to hold the joined string
 *
 * @return  VDO_SUCCESS or an error
 **/
int joinStrings(char   **substringArray,
                size_t   arrayLength,
                char     separator,
                char   **stringPtr)
  __attribute__((warn_unused_result));

/**
 * Free a list of non-NULL string pointers, and then the list itself.
 *
 * @param stringArray  The string list
 **/
void freeStringArray(char **stringArray);

/**
 * Parse a string as an "unsigned int" value, yielding the value.
 * On overflow, -ERANGE is returned. On invalid number, -EINVAL is
 * returned.
 *
 * @param [in]  input     The string to be processed
 * @param [out] valuePtr  The value of the number read
 *
 * @return  UDS_SUCCESS or -EINVAL or -ERANGE.
 **/
int stringToUInt(const char *input, unsigned int *valuePtr)
  __attribute__((warn_unused_result));

#endif /* VDO_STRING_UTILS_H */