orxString.h

Go to the documentation of this file.

/* Orx - Portable Game Engine
 *
 * Copyright (c) 2008-2022 Orx-Project
 *
 * This software is provided 'as-is', without any express or implied
 * warranty. In no event will the authors be held liable for any damages
 * arising from the use of this software.
 *
 * Permission is granted to anyone to use this software for any purpose,
 * including commercial applications, and to alter it and redistribute it
 * freely, subject to the following restrictions:
 *
 *    1. The origin of this software must not be misrepresented; you must not
 *    claim that you wrote the original software. If you use this software
 *    in a product, an acknowledgment in the product documentation would be
 *    appreciated but is not required.
 *
 *    2. Altered source versions must be plainly marked as such, and must not be
 *    misrepresented as being the original software.
 *
 *    3. This notice may not be removed or altered from any source
 *    distribution.
 */

#ifndef _orxSTRING_H_
#define _orxSTRING_H_


#include "orxInclude.h"

#include "math/orxVector.h"
#include "memory/orxMemory.h"

#ifdef __orxMSVC__

  #pragma warning(disable : 4996)

  #define strtoll   _strtoi64
  #define strtoull  _strtoui64

#endif /* __orxMSVC__ */

#define STRTO_CAST (int)

#include <stdio.h>
#include <stdarg.h>
#include <string.h>
#include <stdlib.h>

#ifndef __orxWINDOWS__
  #include <strings.h>
#endif /* !__orxWINDOWS__ */

#include "debug/orxDebug.h"


#define orxSTRING_KC_VECTOR_START                         '('
#define orxSTRING_KC_VECTOR_START_ALT                     '{'
#define orxSTRING_KC_VECTOR_SEPARATOR                     ','
#define orxSTRING_KC_VECTOR_END                           ')'
#define orxSTRING_KC_VECTOR_END_ALT                       '}'



#define orxString_ToCRC                                   orxString_Hash


/* *** String inlined functions *** */


static orxINLINE const orxSTRING                          orxString_SkipWhiteSpaces(const orxSTRING _zString)
{
  const orxSTRING zResult;

  /* Non null? */
  if(_zString != orxNULL)
  {
    /* Skips all white spaces */
    for(zResult = _zString; (*zResult == ' ') || (*zResult == '\t') || (*zResult == orxCHAR_CR) || (*zResult == orxCHAR_LF); zResult++);

    /* Empty? */
    if(*zResult == orxCHAR_NULL)
    {
      /* Updates result */
      zResult = orxSTRING_EMPTY;
    }
  }
  else
  {
    /* Updates result */
    zResult = orxNULL;
  }

  /* Done! */
  return zResult;
}

static orxINLINE const orxSTRING                          orxString_SkipPath(const orxSTRING _zString)
{
  const orxSTRING zResult;

  /* Non null? */
  if(_zString != orxNULL)
  {
    const orxCHAR *pc;

    /* Updates result */
    zResult = _zString;

    /* For all characters */
    for(pc = _zString; *pc != orxCHAR_NULL; pc++)
    {
      /* Is a directory separator? */
      if((*pc == orxCHAR_DIRECTORY_SEPARATOR_LINUX) || (*pc == orxCHAR_DIRECTORY_SEPARATOR_WINDOWS))
      {
        orxCHAR cNextChar = *(pc + 1);

        /* Non terminal and not a directory separator? */
        if((cNextChar != orxCHAR_NULL) && (cNextChar != orxCHAR_DIRECTORY_SEPARATOR_LINUX) && (cNextChar != orxCHAR_DIRECTORY_SEPARATOR_WINDOWS))
        {
          /* Updates result */
          zResult = pc + 1;
        }
      }
    }
  }
  else
  {
    /* Updates result */
    zResult = orxNULL;
  }

  /* Done! */
  return zResult;
}

static orxINLINE orxU32                                   orxString_GetLength(const orxSTRING _zString)
{
  /* Checks */
  orxASSERT(_zString != orxNULL);

  /* Done! */
  return((orxU32)strlen(_zString));
}

static orxINLINE orxBOOL                                  orxString_IsCharacterASCII(orxU32 _u32CharacterCodePoint)
{
  /* Done! */
  return((_u32CharacterCodePoint < 0x80) ? orxTRUE : orxFALSE);
}

static orxINLINE orxBOOL                                  orxString_IsCharacterAlphaNumeric(orxU32 _u32CharacterCodePoint)
{
  /* Done! */
  return(((_u32CharacterCodePoint >= 'a') && (_u32CharacterCodePoint <= 'z'))
      || ((_u32CharacterCodePoint >= 'A') && (_u32CharacterCodePoint <= 'Z'))
      || ((_u32CharacterCodePoint >= '0') && (_u32CharacterCodePoint <= '9'))) ? orxTRUE : orxFALSE;
}

static orxINLINE orxU32                                   orxString_GetUTF8CharacterLength(orxU32 _u32CharacterCodePoint)
{
  orxU32 u32Result;

  /* 1-byte long? */
  if(_u32CharacterCodePoint < 0x80)
  {
    /* Updates result */
    u32Result = 1;
  }
  else if(_u32CharacterCodePoint < 0x0800)
  {
    /* Updates result */
    u32Result = 2;
  }
  else if(_u32CharacterCodePoint < 0x00010000)
  {
    /* Updates result */
    u32Result = 3;
  }
  else if(_u32CharacterCodePoint < 0x00110000)
  {
    /* Updates result */
    u32Result = 4;
  }
  else
  {
    /* Updates result */
    u32Result = orxU32_UNDEFINED;
  }

  /* Done! */
  return u32Result;
}

static orxU32 orxFASTCALL                                 orxString_PrintUTF8Character(orxSTRING _zDstString, orxU32 _u32Size, orxU32 _u32CharacterCodePoint)
{
  orxU32 u32Result;

  /* Gets character's encoded length */
  u32Result = orxString_GetUTF8CharacterLength(_u32CharacterCodePoint);

  /* Enough room? */
  if(u32Result <= _u32Size)
  {
    /* Depending on character's length */
    switch(u32Result)
    {
      case 1:
      {
        /* Writes character */
        *_zDstString = (orxCHAR)_u32CharacterCodePoint;

        break;
      }

      case 2:
      {
        /* Writes first character */
        *_zDstString++ = (orxCHAR)(0xC0 | ((_u32CharacterCodePoint & 0x07C0) >> 6));

        /* Writes second character */
        *_zDstString = (orxCHAR)(0x80 | (_u32CharacterCodePoint & 0x3F));

        break;
      }

      case 3:
      {
        /* Writes first character */
        *_zDstString++ = (orxCHAR)(0xE0 | ((_u32CharacterCodePoint & 0xF000) >> 12));

        /* Writes second character */
        *_zDstString++ = (orxCHAR)(0x80 | ((_u32CharacterCodePoint & 0x0FC0) >> 6));

        /* Writes third character */
        *_zDstString = (orxCHAR)(0x80 | (_u32CharacterCodePoint & 0x3F));

        break;
      }

      case 4:
      {
        /* Writes first character */
        *_zDstString++ = (orxCHAR)(0xF0 | ((_u32CharacterCodePoint & 0x001C0000) >> 18));

        /* Writes second character */
        *_zDstString++ = (orxCHAR)(0x80 | ((_u32CharacterCodePoint & 0x0003F000) >> 12));

        /* Writes third character */
        *_zDstString++ = (orxCHAR)(0x80 | ((_u32CharacterCodePoint & 0x00000FC0) >> 6));

        /* Writes fourth character */
        *_zDstString = (orxCHAR)(0x80 | (_u32CharacterCodePoint & 0x3F));

        break;
      }

      default:
      {
        /* Logs message */
        orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Can't print invalid unicode character <0x%X> to string.", _u32CharacterCodePoint);

        /* Updates result */
        u32Result = orxU32_UNDEFINED;

        break;
      }
    }
  }
  else
  {
    /* Logs message */
    orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Can't print unicode character <0x%X> to string as there isn't enough space for it.", _u32CharacterCodePoint);

    /* Updates result */
    u32Result = orxU32_UNDEFINED;
  }

  /* Done! */
  return u32Result;
}

static orxU32 orxFASTCALL                                 orxString_GetFirstCharacterCodePoint(const orxSTRING _zString, const orxSTRING *_pzRemaining)
{
  const orxU8  *pu8Byte;
  orxU32        u32Result;

  /* Checks */
  orxASSERT(_zString != orxNULL);

  /* Gets the first byte */
  pu8Byte = (const orxU8 *)_zString;

  /* ASCII? */
  if(*pu8Byte < 0x80)
  {
    /* Updates result */
    u32Result = *pu8Byte;
  }
  /* Invalid UTF-8 byte sequence */
  else if(*pu8Byte < 0xC0)
  {
    /* Logs message */
    orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: multi-byte sequence non-leading byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

    /* Updates result */
    u32Result = orxU32_UNDEFINED;
  }
  /* Overlong UTF-8 2-byte sequence */
  else if(*pu8Byte < 0xC2)
  {
    /* Logs message */
    orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: overlong 2-byte sequence starting with byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

    /* Updates result */
    u32Result = orxU32_UNDEFINED;
  }
  /* 2-byte sequence */
  else if(*pu8Byte < 0xE0)
  {
    /* Updates result with first character */
    u32Result = *pu8Byte++ & 0x1F;

    /* Valid second character? */
    if((*pu8Byte & 0xC0) == 0x80)
    {
      /* Updates result */
      u32Result = (u32Result << 6) | (*pu8Byte & 0x3F);
    }
    else
    {
      /* Logs message */
      orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: 2-byte sequence non-trailing byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

      /* Updates result */
      u32Result = orxU32_UNDEFINED;
    }
  }
  /* 3-byte sequence */
  else if(*pu8Byte < 0xF0)
  {
    /* Updates result with first character */
    u32Result = *pu8Byte++ & 0x0F;

    /* Valid second character? */
    if((*pu8Byte & 0xC0) == 0x80)
    {
      /* Updates result */
      u32Result = (u32Result << 6) | (*pu8Byte++ & 0x3F);

      /* Valid third character? */
      if((*pu8Byte & 0xC0) == 0x80)
      {
        /* Updates result */
        u32Result = (u32Result << 6) | (*pu8Byte & 0x3F);
      }
      else
      {
        /* Logs message */
        orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: 3-byte sequence non-trailing byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

        /* Updates result */
        u32Result = orxU32_UNDEFINED;
      }
    }
    else
    {
      /* Logs message */
      orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: 3-byte sequence non-trailing byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

      /* Updates result */
      u32Result = orxU32_UNDEFINED;
    }
  }
  /* 4-byte sequence */
  else if(*pu8Byte < 0xF5)
  {
    /* Updates result with first character */
    u32Result = *pu8Byte++ & 0x07;

    /* Valid second character? */
    if((*pu8Byte & 0xC0) == 0x80)
    {
      /* Updates result */
      u32Result = (u32Result << 6) | (*pu8Byte++ & 0x3F);

      /* Valid third character? */
      if((*pu8Byte & 0xC0) == 0x80)
      {
        /* Updates result */
        u32Result = (u32Result << 6) | (*pu8Byte++ & 0x3F);

        /* Valid fourth character? */
        if((*pu8Byte & 0xC0) == 0x80)
        {
          /* Updates result */
          u32Result = (u32Result << 6) | (*pu8Byte & 0x3F);
        }
        else
        {
          /* Logs message */
          orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: 4-byte sequence non-trailing byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

          /* Updates result */
          u32Result = orxU32_UNDEFINED;
        }
      }
      else
      {
        /* Logs message */
        orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: 4-byte sequence non-trailing byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

        /* Updates result */
        u32Result = orxU32_UNDEFINED;
      }
    }
    else
    {
      /* Logs message */
      orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: 4-byte sequence non-trailing byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

      /* Updates result */
      u32Result = orxU32_UNDEFINED;
    }
  }
  else
  {
    /* Logs message */
    orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF-8 string at <0x%X>: invalid out-of-bound byte '%c' (0x%2X) at index %d.", _zString, *pu8Byte, *pu8Byte, pu8Byte - (orxU8 *)_zString);

    /* Updates result */
    u32Result = orxU32_UNDEFINED;
  }

  /* Asks for remaining string? */
  if(_pzRemaining != orxNULL)
  {
    /* Stores it */
    *_pzRemaining = (orxSTRING)(pu8Byte + 1);
  }

  /* Done! */
  return u32Result;
}

static orxINLINE orxU32                                   orxString_GetCharacterCount(const orxSTRING _zString)
{
  const orxCHAR  *pc;
  orxU32          u32Result;

  /* Checks */
  orxASSERT(_zString != orxNULL);

  /* For all characters */
  for(pc = _zString, u32Result = 0; *pc != orxCHAR_NULL; u32Result++)
  {
    /* Invalid current character ID */
    if(orxString_GetFirstCharacterCodePoint(pc, &pc) == orxU32_UNDEFINED)
    {
      /* Updates result */
      u32Result = orxU32_UNDEFINED;

      /* Logs message */
      orxDEBUG_PRINT(orxDEBUG_LEVEL_SYSTEM, "Invalid or non-UTF8 string <%s>, can't count characters.", _zString);

      break;
    }
  }

  /* Done! */
  return u32Result;
}

static orxINLINE orxSTRING                                orxString_NCopy(orxSTRING _zDstString, const orxSTRING _zSrcString, orxU32 _u32CharNumber)
{
  /* Checks */
  orxASSERT(_zDstString != orxNULL);
  orxASSERT(_zSrcString != orxNULL);
  orxASSERT(_u32CharNumber > 0);

  /* Done! */
  return(strncpy(_zDstString, _zSrcString, (size_t)_u32CharNumber));
}

static orxINLINE orxSTRING                                orxString_Duplicate(const orxSTRING _zSrcString)
{
  orxU32    u32Size;
  orxSTRING zResult;

  /* Checks */
  orxASSERT(_zSrcString != orxNULL);

  /* Gets string size in bytes */
  u32Size = (orxString_GetLength(_zSrcString) + 1) * sizeof(orxCHAR);

  /* Allocates it */
  zResult = (orxSTRING)orxMemory_Allocate(u32Size, orxMEMORY_TYPE_TEXT);

  /* Valid? */
  if(zResult != orxNULL)
  {
    /* Copies source to it */
    orxMemory_Copy(zResult, _zSrcString, u32Size);
  }

  /* Done! */
  return zResult;
}

static orxINLINE orxSTATUS                                orxString_Delete(orxSTRING _zString)
{
  /* Checks */
  orxASSERT(_zString != orxNULL);
  orxASSERT(_zString != orxSTRING_EMPTY);

  /* Frees its memory */
  orxMemory_Free(_zString);

  /* Done! */
  return orxSTATUS_SUCCESS;
}

static orxINLINE orxS32                                   orxString_Compare(const orxSTRING _zString1, const orxSTRING _zString2)
{
  /* Checks */
  orxASSERT(_zString1 != orxNULL);
  orxASSERT(_zString2 != orxNULL);

  /* Done! */
  return(strcmp(_zString1, _zString2));
}

static orxINLINE orxS32                                   orxString_NCompare(const orxSTRING _zString1, const orxSTRING _zString2, orxU32 _u32CharNumber)
{
  /* Checks */
  orxASSERT(_zString1 != orxNULL);
  orxASSERT(_zString2 != orxNULL);

  /* Done! */
  return(strncmp(_zString1, _zString2, (size_t)_u32CharNumber));
}

static orxINLINE orxS32                                   orxString_ICompare(const orxSTRING _zString1, const orxSTRING _zString2)
{
  /* Checks */
  orxASSERT(_zString1 != orxNULL);
  orxASSERT(_zString2 != orxNULL);

#ifdef __orxWINDOWS__

  /* Done! */
  return(stricmp(_zString1, _zString2));

#else /* __orxWINDOWS__ */

  /* Done! */
  return(strcasecmp(_zString1, _zString2));

#endif /* __orxWINDOWS__ */
}

static orxINLINE orxS32                                   orxString_NICompare(const orxSTRING _zString1, const orxSTRING _zString2, orxU32 _u32CharNumber)
{
  /* Checks */
  orxASSERT(_zString1 != orxNULL);
  orxASSERT(_zString2 != orxNULL);

#ifdef __orxWINDOWS__

  /* Done! */
  return(strnicmp(_zString1, _zString2, (size_t)_u32CharNumber));

#else /* __orxWINDOWS__ */

  /* Done! */
  return(strncasecmp(_zString1, _zString2, _u32CharNumber));

#endif /* __orxWINDOWS__ */
}

static orxINLINE orxU32                                   orxString_ExtractBase(const orxSTRING _zString, const orxSTRING *_pzRemaining)
{
  const orxSTRING zString;
  orxU32          u32Result, u32Offset;

  /* Checks */
  orxASSERT(_zString != orxNULL);

  /* Skips white spaces */
  zString = orxString_SkipWhiteSpaces(_zString);

  /* Default result and offset: decimal */
  u32Result = 10;
  u32Offset = 0;

  /* Depending on first character */
  switch(zString[0])
  {
    case '0':
    {
      /* Depending on second character */
      switch(zString[1] | 0x20)
      {
        case 'x':
        {
          /* Updates result and offset: hexadecimal */
          u32Result = 16;
          u32Offset = 2;

          break;
        }

        case 'b':
        {
          /* Updates result and offset: binary */
          u32Result = 2;
          u32Offset = 2;

          break;
        }

        default:
        {
          /* Octal? */
          if((zString[1] >= '0')
          && (zString[1] <= '9'))
          {
            /* Updates result and offset: octal */
            u32Result = 8;
            u32Offset = 1;
          }

          break;
        }
      }

      break;
    }

    case '#':
    {
      /* Updates result and offset: hexadecimal */
      u32Result = 16;
      u32Offset = 1;

      break;
    }

    default:
    {
      break;
    }
  }

  /* Asks for remaining string? */
  if(_pzRemaining != orxNULL)
  {
    /* Stores it */
    *_pzRemaining = zString + u32Offset;
  }

  /* Done! */
  return u32Result;
}

static orxINLINE orxSTATUS                                orxString_ToS32Base(const orxSTRING _zString, orxU32 _u32Base, orxS32 *_ps32OutValue, const orxSTRING *_pzRemaining)
{
  orxCHAR    *pcEnd;
  orxSTATUS   eResult;

  /* Checks */
  orxASSERT(_ps32OutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Convert */
  *_ps32OutValue = (orxS32)strtol(_zString, &pcEnd, STRTO_CAST _u32Base);

  /* Valid conversion ? */
  if((pcEnd != _zString) && (_zString[0] != orxCHAR_NULL))
  {
    /* Updates result */
    eResult = orxSTATUS_SUCCESS;
  }
  else
  {
    /* Updates result */
    eResult = orxSTATUS_FAILURE;
  }

  /* Asks for remaining string? */
  if(_pzRemaining != orxNULL)
  {
    /* Stores it */
    *_pzRemaining = pcEnd;
  }

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToS32(const orxSTRING _zString, orxS32 *_ps32OutValue, const orxSTRING *_pzRemaining)
{
  const orxSTRING zValue;
  orxU32          u32Base;
  orxSTATUS       eResult;

  /* Checks */
  orxASSERT(_ps32OutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Extracts base */
  u32Base = orxString_ExtractBase(_zString, &zValue);

  /* Gets value */
  eResult = orxString_ToS32Base(zValue, u32Base, _ps32OutValue, _pzRemaining);

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToU32Base(const orxSTRING _zString, orxU32 _u32Base, orxU32 *_pu32OutValue, const orxSTRING *_pzRemaining)
{
  orxCHAR    *pcEnd;
  orxSTATUS   eResult;

  /* Checks */
  orxASSERT(_pu32OutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Convert */
  *_pu32OutValue = (orxU32)strtoul(_zString, &pcEnd, STRTO_CAST _u32Base);

  /* Valid conversion ? */
  if((pcEnd != _zString) && (_zString[0] != orxCHAR_NULL))
  {
    /* Updates result */
    eResult = orxSTATUS_SUCCESS;
  }
  else
  {
    /* Updates result */
    eResult = orxSTATUS_FAILURE;
  }

  /* Asks for remaining string? */
  if(_pzRemaining != orxNULL)
  {
    /* Stores it */
    *_pzRemaining = pcEnd;
  }

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToU32(const orxSTRING _zString, orxU32 *_pu32OutValue, const orxSTRING *_pzRemaining)
{
  const orxSTRING zValue;
  orxU32          u32Base;
  orxSTATUS       eResult;

  /* Checks */
  orxASSERT(_pu32OutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Extracts base */
  u32Base = orxString_ExtractBase(_zString, &zValue);

  /* Gets value */
  eResult = orxString_ToU32Base(zValue, u32Base, _pu32OutValue, _pzRemaining);

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToS64Base(const orxSTRING _zString, orxU32 _u32Base, orxS64 *_ps64OutValue, const orxSTRING *_pzRemaining)
{
  orxCHAR    *pcEnd;
  orxSTATUS   eResult;

  /* Checks */
  orxASSERT(_ps64OutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Convert */
  *_ps64OutValue = (orxS64)strtoll(_zString, &pcEnd, STRTO_CAST _u32Base);

  /* Valid conversion ? */
  if((pcEnd != _zString) && (_zString[0] != orxCHAR_NULL))
  {
    /* Updates result */
    eResult = orxSTATUS_SUCCESS;
  }
  else
  {
    /* Updates result */
    eResult = orxSTATUS_FAILURE;
  }

  /* Asks for remaining string? */
  if(_pzRemaining != orxNULL)
  {
    /* Stores it */
    *_pzRemaining = pcEnd;
  }

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToS64(const orxSTRING _zString, orxS64 *_ps64OutValue, const orxSTRING *_pzRemaining)
{
  const orxSTRING zValue;
  orxU32          u32Base;
  orxSTATUS       eResult;

  /* Checks */
  orxASSERT(_ps64OutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Extracts base */
  u32Base = orxString_ExtractBase(_zString, &zValue);

  /* Gets signed value */
  eResult = orxString_ToS64Base(zValue, u32Base, _ps64OutValue, _pzRemaining);

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToU64Base(const orxSTRING _zString, orxU32 _u32Base, orxU64 *_pu64OutValue, const orxSTRING *_pzRemaining)
{
  orxCHAR    *pcEnd;
  orxSTATUS   eResult;

  /* Checks */
  orxASSERT(_pu64OutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Convert */
  *_pu64OutValue = (orxU64)strtoull(_zString, &pcEnd, STRTO_CAST _u32Base);

  /* Valid conversion ? */
  if((pcEnd != _zString) && (_zString[0] != orxCHAR_NULL))
  {
    /* Updates result */
    eResult = orxSTATUS_SUCCESS;
  }
  else
  {
    /* Updates result */
    eResult = orxSTATUS_FAILURE;
  }

  /* Asks for remaining string? */
  if(_pzRemaining != orxNULL)
  {
    /* Stores it */
    *_pzRemaining = pcEnd;
  }

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToU64(const orxSTRING _zString, orxU64 *_pu64OutValue, const orxSTRING *_pzRemaining)
{
  const orxSTRING zValue;
  orxU32          u32Base;
  orxSTATUS       eResult;

  /* Checks */
  orxASSERT(_pu64OutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Extracts base */
  u32Base = orxString_ExtractBase(_zString, &zValue);

  /* Gets signed value */
  eResult = orxString_ToU64Base(zValue, u32Base, _pu64OutValue, _pzRemaining);

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToFloat(const orxSTRING _zString, orxFLOAT *_pfOutValue, const orxSTRING *_pzRemaining)
{
  orxCHAR    *pcEnd;
  orxSTATUS   eResult;

  /* Checks */
  orxASSERT(_pfOutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Linux / Mac / iOS / Android / MSVC? */
#if defined(__orxLINUX__) || defined(__orxMAC__) || defined (__orxIOS__) || defined(__orxMSVC__) || defined(__orxANDROID__)

  /* Converts it */
  *_pfOutValue = (orxFLOAT)strtod(_zString, &pcEnd);

#else /* __orxLINUX__ || __orxMAC__ || __orxIOS__ || __orxMSVC__ || __orxANDROID__ */

  /* Converts it */
  *_pfOutValue = strtof(_zString, &pcEnd);

#endif /* __orxLINUX__ || __orxMAC__ || __orxIOS__ || __orxMSVC__ || __orxANDROID__ */

  /* Valid conversion ? */
  if((pcEnd != _zString) && (_zString[0] != orxCHAR_NULL))
  {
    /* Updates result */
    eResult = orxSTATUS_SUCCESS;
  }
  else
  {
    /* Updates result */
    eResult = orxSTATUS_FAILURE;
  }

  /* Asks for remaining string? */
  if(_pzRemaining != orxNULL)
  {
    /* Stores it */
    *_pzRemaining = pcEnd;
  }

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToVector(const orxSTRING _zString, orxVECTOR *_pvOutValue, const orxSTRING *_pzRemaining)
{
  orxVECTOR       stValue;
  const orxSTRING zString;
  orxSTATUS       eResult = orxSTATUS_FAILURE;

  /* Checks */
  orxASSERT(_pvOutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Skips all white spaces */
  zString = orxString_SkipWhiteSpaces(_zString);

  /* Is a vector start character? */
  if((*zString == orxSTRING_KC_VECTOR_START)
  || (*zString == orxSTRING_KC_VECTOR_START_ALT))
  {
    orxCHAR cEndMarker;

    /* Gets end marker */
    cEndMarker = (*zString == orxSTRING_KC_VECTOR_START) ? orxSTRING_KC_VECTOR_END : orxSTRING_KC_VECTOR_END_ALT;

    /* Skips all white spaces */
    zString = orxString_SkipWhiteSpaces(zString + 1);

    /* Gets X value */
    if(orxString_ToFloat(zString, &(stValue.fX), &zString) != orxSTATUS_FAILURE)
    {
      /* Skips all white spaces */
      zString = orxString_SkipWhiteSpaces(zString);

      /* Is a vector separator character? */
      if(*zString == orxSTRING_KC_VECTOR_SEPARATOR)
      {
        /* Skips all white spaces */
        zString = orxString_SkipWhiteSpaces(zString + 1);

        /* Gets Y value */
        if(orxString_ToFloat(zString, &(stValue.fY), &zString) != orxSTATUS_FAILURE)
        {
          /* Skips all white spaces */
          zString = orxString_SkipWhiteSpaces(zString);

          /* Is a vector separator character? */
          if(*zString == orxSTRING_KC_VECTOR_SEPARATOR)
          {
            /* Skips all white spaces */
            zString = orxString_SkipWhiteSpaces(zString + 1);

            /* Gets Z value */
            if(orxString_ToFloat(zString, &(stValue.fZ), &zString) != orxSTATUS_FAILURE)
            {
              /* Skips all white spaces */
              zString = orxString_SkipWhiteSpaces(zString);

              /* Has a valid end marker? */
              if(*zString == cEndMarker)
              {
                /* Updates result */
                eResult = orxSTATUS_SUCCESS;
              }
            }
          }
          /* Has a valid end marker? */
          else if(*zString == cEndMarker)
          {
            /* Clears Z component */
            stValue.fZ = orxFLOAT_0;

            /* Updates result */
            eResult = orxSTATUS_SUCCESS;
          }
        }
      }
    }
  }

  /* Valid? */
  if(eResult != orxSTATUS_FAILURE)
  {
    /* Updates vector */
    orxVector_Copy(_pvOutValue, &stValue);

    /* Asks for remaining string? */
    if(_pzRemaining != orxNULL)
    {
      /* Stores it */
      *_pzRemaining = zString + 1;
    }
  }

  /* Done! */
  return eResult;
}

static orxINLINE orxSTATUS                                orxString_ToBool(const orxSTRING _zString, orxBOOL *_pbOutValue, const orxSTRING *_pzRemaining)
{
  orxS32    s32Value;
  orxSTATUS eResult;

  /* Checks */
  orxASSERT(_pbOutValue != orxNULL);
  orxASSERT(_zString != orxNULL);

  /* Tries numeric value */
  eResult = orxString_ToS32Base(_zString, 10, &s32Value, _pzRemaining);

  /* Valid? */
  if(eResult != orxSTATUS_FAILURE)
  {
    /* Updates boolean */
    *_pbOutValue = (s32Value != 0) ? orxTRUE : orxFALSE;
  }
  else
  {
    orxU32 u32Length;

    /* Gets length of false */
    u32Length = orxString_GetLength(orxSTRING_FALSE);

    /* Is false? */
    if(orxString_NICompare(_zString, orxSTRING_FALSE, u32Length) == 0)
    {
      /* Updates boolean */
      *_pbOutValue = orxFALSE;

      /* Has remaining? */
      if(_pzRemaining != orxNULL)
      {
        /* Updates it */
        *_pzRemaining += u32Length;
      }

      /* Updates result */
      eResult = orxSTATUS_SUCCESS;
    }
    else
    {
      /* Gets length of true */
      u32Length = orxString_GetLength(orxSTRING_TRUE);

      /* Is true? */
      if(orxString_NICompare(_zString, orxSTRING_TRUE, u32Length) == 0)
      {
        /* Updates boolean */
        *_pbOutValue = orxTRUE;

        /* Has remaining? */
        if(_pzRemaining != orxNULL)
        {
          /* Updates it */
          *_pzRemaining += u32Length;
        }

        /* Updates result */
        eResult = orxSTATUS_SUCCESS;
      }
    }
  }

  /* Done! */
  return eResult;
}

static orxINLINE orxSTRING                                orxString_LowerCase(orxSTRING _zString)
{
  orxCHAR *pc;

  /* Checks */
  orxASSERT(_zString != orxNULL);

  /* Converts the whole string */
  for(pc = _zString; *pc != orxCHAR_NULL; pc++)
  {
    /* Needs to be converted? */
    if((*pc >= 'A') && (*pc <= 'Z'))
    {
      /* Lower case */
      *pc |= 0x20;
    }
  }

  return _zString;
}

static orxINLINE orxSTRING                                orxString_UpperCase(orxSTRING _zString)
{
  orxCHAR *pc;

  /* Checks */
  orxASSERT(_zString != orxNULL);

  /* Converts the whole string */
  for(pc = _zString; *pc != orxCHAR_NULL; pc++)
  {
    /* Needs to be converted? */
    if((*pc >= 'a') && (*pc <= 'z'))
    {
      /* Upper case */
      *pc &= ~0x20;
    }
  }

  return _zString;
}

static orxINLINE const orxSTRING                          orxString_SearchString(const orxSTRING _zString1, const orxSTRING _zString2)
{
  /* Checks */
  orxASSERT(_zString1 != orxNULL);
  orxASSERT(_zString2 != orxNULL);

  /* Returns result */
  return(strstr(_zString1, _zString2));
}

static orxINLINE const orxSTRING                          orxString_SearchChar(const orxSTRING _zString, orxCHAR _cChar)
{
  /* Checks */
  orxASSERT(_zString != orxNULL);

  /* Returns result */
  return(strchr(_zString, _cChar));
}

static orxINLINE orxS32                                   orxString_SearchCharIndex(const orxSTRING _zString, orxCHAR _cChar, orxS32 _s32Position)
{
  orxS32          s32Index, s32Result = -1;
  const orxCHAR  *pc;

  /* Checks */
  orxASSERT(_zString != orxNULL);
  orxASSERT(_s32Position <= (orxS32)orxString_GetLength(_zString));

  /* For all characters */
  for(s32Index = _s32Position, pc = _zString + s32Index; *pc != orxCHAR_NULL; pc++, s32Index++)
  {
    /* Found? */
    if(*pc == _cChar)
    {
      /* Updates result */
      s32Result = s32Index;

      break;
    }
  }

  /* Done! */
  return s32Result;
}

static orxINLINE orxS32 orxCDECL                          orxString_NPrint(orxSTRING _zDstString, orxU32 _u32CharNumber, const orxSTRING _zSrcString, ...)
{
  va_list stArgs;
  orxS32  s32Result;

  /* Checks */
  orxASSERT(_zDstString != orxNULL);
  orxASSERT(_zSrcString != orxNULL);
  orxASSERT(_u32CharNumber > 0);

  /* Gets variable arguments & prints the string */
  va_start(stArgs, _zSrcString);
  s32Result = vsnprintf(_zDstString, (size_t)_u32CharNumber, _zSrcString, stArgs);
  va_end(stArgs);

  /* Overflow? */
  if(s32Result <= 0)
  {
    /* Updates result */
    s32Result = (orxS32)_u32CharNumber - 1;
  }
  else
  {
    /* Clamps result */
    s32Result = orxCLAMP(s32Result, 0, (orxS32)_u32CharNumber - 1);
  }

  /* Enforces terminating null character */
  _zDstString[s32Result] = orxCHAR_NULL;

  /* Done! */
  return s32Result;
}

static orxINLINE orxS32 orxCDECL                          orxString_Scan(const orxSTRING _zString, const orxSTRING _zFormat, ...)
{
  va_list stArgs;
  orxS32  s32Result;

  /* Checks */
  orxASSERT(_zString != orxNULL);

  /* Gets variable arguments & scans the string */
  va_start(stArgs, _zFormat);
  s32Result = vsscanf(_zString, _zFormat, stArgs);
  va_end(stArgs);

  /* Clamps result */
  s32Result = orxMAX(s32Result, 0);

  /* Done! */
  return s32Result;
}

static orxINLINE const orxSTRING                          orxString_GetExtension(const orxSTRING _zFileName)
{
  orxS32          s32Index, s32NextIndex;
  const orxSTRING zResult;

  /* Checks */
  orxASSERT(_zFileName != orxNULL);

  /* Finds last '.' */
  for(s32Index = orxString_SearchCharIndex(_zFileName, '.', 0);
      (s32Index >= 0) && ((s32NextIndex = orxString_SearchCharIndex(_zFileName, '.', s32Index + 1)) > 0);
      s32Index = s32NextIndex);

  /* Updates result */
  zResult = (s32Index >= 0) ? _zFileName + s32Index + 1 : orxSTRING_EMPTY;

  /* Done! */
  return zResult;
}

/* *** String module functions *** */

extern orxDLLAPI void orxFASTCALL                         orxString_Setup();

extern orxDLLAPI orxSTATUS orxFASTCALL                    orxString_Init();

extern orxDLLAPI void orxFASTCALL                         orxString_Exit();


extern orxDLLAPI orxSTRINGID orxFASTCALL                  orxString_NHash(const orxSTRING _zString, orxU32 _u32CharNumber);

extern orxDLLAPI orxSTRINGID orxFASTCALL                  orxString_Hash(const orxSTRING _zString);

extern orxDLLAPI orxSTRINGID orxFASTCALL                  orxString_GetID(const orxSTRING _zString);

extern orxDLLAPI const orxSTRING orxFASTCALL              orxString_GetFromID(orxSTRINGID _stID);

extern orxDLLAPI const orxSTRING orxFASTCALL              orxString_Store(const orxSTRING _zString);


#ifdef __orxMSVC__

  #pragma warning(default : 4996)

#endif /* __orxMSVC__ */

#endif /* _orxSTRING_H_ */