/***************************************************************************************************

  Zyan Disassembler Library (Zydis)

  Original Author : Florian Bernd, Joel Höner

 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.

***************************************************************************************************/

#ifndef ZYDIS_STRING_H
#define ZYDIS_STRING_H

#include <Zydis/CommonTypes.h>
#include <Zydis/Status.h>
#include <Zydis/Internal/LibC.h>

/* ============================================================================================== */
/* Enums and types                                                                                */
/* ============================================================================================== */

/* ---------------------------------------------------------------------------------------------- */
/* String                                                                                         */
/* ---------------------------------------------------------------------------------------------- */

/**
 * @brief   Defines the `ZydisString` struct.
 */
typedef struct ZydisString_ 
{
    /**
     * @brief   The buffer that contains the actual string (0-termination is optional!).
     */
    char *buffer;
    /**
     * @brief   The length of the string (without any optional 0).
     */
    ZydisUSize length;
    /**
     * @brief   The total buffer capacity.
     */
    ZydisUSize capacity;
} ZydisString;

/* ---------------------------------------------------------------------------------------------- */
/* Letter Case                                                                                    */
/* ---------------------------------------------------------------------------------------------- */

/**
 * @brief   Defines the `ZydisLetterCase` datatype.
 */
typedef ZydisU8 ZydisLetterCase;

/**
 * @brief   Values that represent letter cases.
 */
enum ZydisLetterCases
{
    /**
     * @brief   Uses the given text "as is".
     */
    ZYDIS_LETTER_CASE_DEFAULT,
    /**
     * @brief   Converts the given text to lowercase letters.
     */
    ZYDIS_LETTER_CASE_LOWER,
    /**
     * @brief   Converts the given text to uppercase letters.
     */
    ZYDIS_LETTER_CASE_UPPER,

    /**
     * @brief   Maximum value of this enum.
     */
    ZYDIS_LETTER_CASE_MAX_VALUE = ZYDIS_LETTER_CASE_UPPER
};

/* ---------------------------------------------------------------------------------------------- */

/* ============================================================================================== */
/* Macros                                                                                         */
/* ============================================================================================== */

/* ---------------------------------------------------------------------------------------------- */
/* Helper Macros                                                                                  */
/* ---------------------------------------------------------------------------------------------- */

/**
 * @brief   Creates a `ZydisString` struct from a static C-string.
 * 
 * @param   string  The C-string constant. 
 */
#define ZYDIS_MAKE_STRING(string) \
    { (char*)string, sizeof(string) - 1, sizeof(string) - 1 }

/* ---------------------------------------------------------------------------------------------- */

/* ============================================================================================== */
/* Functions                                                                                      */
/* ============================================================================================== */

/* ---------------------------------------------------------------------------------------------- */
/* Basic Operations                                                                               */
/* ---------------------------------------------------------------------------------------------- */

/**
 * @brief   Initializes a `ZydisString` struct with a C-string.
 * 
 * @param   string  The string to initialize.
 * @param   value   The C-string constant. 
 * 
 * @return  A zydis status code.
 */
ZYDIS_NO_EXPORT ZYDIS_INLINE ZydisStatus ZydisStringInit(ZydisString* string, char* value)
{
    if (!string || !value)
    {
        return ZYDIS_STATUS_INVALID_PARAMETER;
    }

    ZydisUSize length = ZydisStrLen(value);
    string->buffer   = value;
    string->length   = length;
    string->capacity = length; 
    
    return ZYDIS_STATUS_SUCCESS;
}

/* ---------------------------------------------------------------------------------------------- */

/**
 * @brief   Appends a `ZydisString` to another `ZydisString`, converting it to the specified
 *          letter-case.
 *
 * @param   string      The string to append to.
 * @param   text        The string to append.
 * @param   letterCase  The letter case to use.
 *
 * @return  @c ZYDIS_STATUS_SUCCESS, if the function succeeded, or 
 *          @c ZYDIS_STATUS_INSUFFICIENT_BUFFER_SIZE, if the size of the buffer was not 
 *          sufficient to append the given @c text.
 */
ZYDIS_NO_EXPORT ZydisStatus ZydisStringAppendEx(ZydisString* string, const ZydisString* text,
    ZydisLetterCase letterCase);

/**
 * @brief   Appends the given C-string to a `ZydisString`, converting it to the specified
 *          letter-case.
 *
 * @param   string      The string to append to.
 * @param   text        The C-string to append.
 * @param   letterCase  The letter case to use.
 *
 * @return  @c ZYDIS_STATUS_SUCCESS, if the function succeeded, or 
 *          @c ZYDIS_STATUS_INSUFFICIENT_BUFFER_SIZE, if the size of the buffer was not 
 *          sufficient to append the given @c text.
 */
ZYDIS_NO_EXPORT ZYDIS_INLINE ZydisStatus ZydisStringAppendExC(ZydisString* string, 
    const char* text, ZydisLetterCase letterCase)
{
    ZydisString other;
    ZYDIS_CHECK(ZydisStringInit(&other, (char*)text));
    
    return ZydisStringAppendEx(string, &other, letterCase);
}

/**
 * @brief   Appends a `ZydisString` to another `ZydisString`.
 *
 * @param   string      The string to append to.
 * @param   text        The string to append.
 *
 * @return  @c ZYDIS_STATUS_SUCCESS, if the function succeeded, or 
 *          @c ZYDIS_STATUS_INSUFFICIENT_BUFFER_SIZE, if the size of the buffer was not 
 *          sufficient to append the given @c text.
 */
ZYDIS_NO_EXPORT ZYDIS_INLINE ZydisStatus ZydisStringAppend(ZydisString* string, 
    const ZydisString* text)
{
    return ZydisStringAppendEx(string, text, ZYDIS_LETTER_CASE_DEFAULT);
}

/**
 * @brief   Appends the given C-string to a `ZydisString`.
 *
 * @param   string      The string to append to.
 * @param   text        The C-string to append.
 *
 * @return  @c ZYDIS_STATUS_SUCCESS, if the function succeeded, or 
 *          @c ZYDIS_STATUS_INSUFFICIENT_BUFFER_SIZE, if the size of the buffer was not 
 *          sufficient to append the given @c text.
 */
ZYDIS_NO_EXPORT ZYDIS_INLINE ZydisStatus ZydisStringAppendC(ZydisString* string, const char* text)
{
    ZydisString other;
    ZYDIS_CHECK(ZydisStringInit(&other, (char*)text));
    
    return ZydisStringAppendEx(string, &other, ZYDIS_LETTER_CASE_DEFAULT);
}

/* ---------------------------------------------------------------------------------------------- */
/* Formatting                                                                                     */
/* ---------------------------------------------------------------------------------------------- */

/**
 * @brief   Formats the given unsigned ordinal @c value to its decimal text-representation and  
 *          appends it to @c s.
 *
 * @param   string          A pointer to the string.
 * @param   value           The value.
 * @param   paddingLength   Padds the converted value with leading zeros, if the number of chars is
 *                          less than the @c paddingLength.
 *
 * @return  @c ZYDIS_STATUS_SUCCESS, if the function succeeded, or 
 *          @c ZYDIS_STATUS_INSUFFICIENT_BUFFER_SIZE, if the size of the buffer was not 
 *          sufficient to append the given @c value.
 *          
 * The string-buffer pointer is increased by the number of chars written, if the call was 
 * successfull.
 */
ZYDIS_NO_EXPORT ZydisStatus ZydisPrintDecU(ZydisString* string, ZydisU64 value, 
    ZydisU8 paddingLength);

/**
 * @brief   Formats the given signed ordinal @c value to its decimal text-representation and   
 *          appends it to @c s.
 *
 * @param   string          A pointer to the string.
 * @param   value           The value.
 * @param   paddingLength   Padds the converted value with leading zeros, if the number of chars is
 *                          less than the @c paddingLength (the sign char is ignored).
 *
 * @return  @c ZYDIS_STATUS_SUCCESS, if the function succeeded, or 
 *          @c ZYDIS_STATUS_INSUFFICIENT_BUFFER_SIZE, if the size of the buffer was not 
 *          sufficient to append the given @c value.
 *          
 * The string-buffer pointer is increased by the number of chars written, if the call was 
 * successfull.
 */
ZYDIS_NO_EXPORT ZydisStatus ZydisPrintDecS(ZydisString* string, ZydisI64 value, 
    ZydisU8 paddingLength);

/**
 * @brief   Formats the given unsigned ordinal @c value to its hexadecimal text-representation and 
 *          appends it to the @c buffer.
 *
 * @param   string          A pointer to the string.
 * @param   value           The value.
 * @param   paddingLength   Padds the converted value with leading zeros, if the number of chars is
 *                          less than the @c paddingLength.
 * @param   uppercase       Set @c TRUE to print the hexadecimal value in uppercase letters instead 
 *                          of lowercase ones.
 * @param   prefix          The string to use as prefix or `NULL`, if not needed.
 * @param   suffix          The string to use as suffix or `NULL`, if not needed.
 *
 * @return  @c ZYDIS_STATUS_SUCCESS, if the function succeeded, or 
 *          @c ZYDIS_STATUS_INSUFFICIENT_BUFFER_SIZE, if the size of the buffer was not 
 *          sufficient to append the given @c value.
 *          
 * The string-buffer pointer is increased by the number of chars written, if the call was 
 * successfull.
 */
ZYDIS_NO_EXPORT ZydisStatus ZydisPrintHexU(ZydisString* string, ZydisU64 value,
    ZydisU8 paddingLength, ZydisBool uppercase, const ZydisString* prefix, 
    const ZydisString* suffix);

/**
 * @brief   Formats the given signed ordinal @c value to its hexadecimal text-representation and 
 *          appends it to the @c buffer.
 *
 * @param   string          A pointer to the string.
 * @param   value           The value.
 * @param   paddingLength   Padds the converted value with leading zeros, if the number of chars is
 *                          less than the @c paddingLength (the sign char is ignored).
 * @param   uppercase       Set @c TRUE to print the hexadecimal value in uppercase letters instead 
 *                          of lowercase ones.
 * @param   prefix          The string to use as prefix or `NULL`, if not needed.
 * @param   suffix          The string to use as suffix or `NULL`, if not needed.
 *
 * @return  @c ZYDIS_STATUS_SUCCESS, if the function succeeded, or 
 *          @c ZYDIS_STATUS_INSUFFICIENT_BUFFER_SIZE, if the size of the buffer was not 
 *          sufficient to append the given @c value.
 *          
 * The string-buffer pointer is increased by the number of chars written, if the call was 
 * successfull.
 */
ZYDIS_NO_EXPORT ZydisStatus ZydisPrintHexS(ZydisString* string, ZydisI64 value, 
    ZydisU8 paddingLength, ZydisBool uppercase, const ZydisString* prefix, 
    const ZydisString* suffix);

/* ---------------------------------------------------------------------------------------------- */

/* ============================================================================================== */

#endif // ZYDIS_STRING_H