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