ff_i_string

String functions.

Refer to pages Custom Tokens, ff_i_color, and ff_i_token for additional details.

References

ASCII_LOWERCASE

The lowercase letters ‘abcdefghijklmnopqrstuvwxyz’. This value is not locale-dependent and will not change.

ASCII_UPPERCASE

The uppercase letters ‘ABCDEFGHIJKLMNOPQRSTUVWXYZ’. This value is not locale-dependent and will not change.

ASCII_DIGITS

The string ‘0123456789’.

ASCII_PUNCTUATION

String of ASCII characters which are considered punctuation characters in the C locale.

ASCII_PRINTABLE

String of ASCII characters which are considered printable. This is a combination of digits, ascii_letters, punctuation, and whitespace.

ASCII_CODE_ESCAPE

Value of the escape code.

ASCII_CHARS

String of all ASCII characters. First character is “nearest to 00” since we can’t use NUL itself (means you can’t get completely black is all)

string GetStringLeftEx(string sString, int nCount)
Parameters:

  • sString – Input string.

  • nCount – Characters to keep from the left. Negative: counts from the end.

Like GetStringLeft, but negative nCount counts back from the end.

string GetStringLTrim(string sString)
Parameters:

  • sString – Input string.

Trim leading spaces.

string GetStringRTrim(string sString)
Parameters:

  • sString – Input string.

Trim trailing spaces.

string GetStringTrim(string sString)
Parameters:

  • sString – Input string.

Trim leading and trailing spaces.

int GetStringStartsWith(string sString, string sSearch)
Parameters:

  • sString – String to search

  • sSearch – String to find

Returns:

Boolean indicating success or failure

Return TRUE if sString starts with sSearch.

int GetStringEndsWith(string sString, string sSearch)
Parameters:

  • sString – String to search

  • sSearch – String to find

Returns:

Boolean indicating success or failure

Return TRUE if sString ends with sSearch.

string GetSubStringEx(string sString, int nStart = 0, int nCount = -1)
Parameters:

  • sString – Input string.

  • nStart – Start index (0-based). Defaults to 0.

  • nCount – Number of characters. -1 means to end of string. Defaults to -1.

Substring starting at nStart. nStart is 0-based; nCount=-1 returns to end.

string GetStringLeftPad(string sString, int nLength = 1, string nChar = " ")
Parameters:

  • sString – String to pad

  • nLength – Length of output string

  • nChar – Character to pad with

Returns:

Padded string

Left pad the sString to the length of nLength.

GetStringLeftPad(“AB”, 4, “0”) becomes “00AB”

string GetStringRightPad(string sString, int nLength = 1, string nChar = " ")
Parameters:

  • sString – String to pad

  • nLength – Length of output string

  • nChar – Character to pad with

Returns:

Padded string

Right pad the sString to the length of nLength.

GetStringRightPad(“AB”, 4, “0”) becomes “AB00”

string GetStringReplace(string sInput, string sSearch, string sReplace)
Parameters:

  • sInput – String to search

  • sSearch – String to find

  • sReplace – String to replace sSearch with

Returns:

A new string

Replace the sSearch string by sReplace.

int GetStringIsInt(string sString)
Parameters:

  • sString – Input string.

Return TRUE if sString represents an integer (including “0”).

string GetRandomString(string sString, int nLength = -1)
Parameters:

  • sString – String to take characters from. Can be constructed from ASCII_* constants.

  • nLength – Length of output string

Returns:

Randomized string

Return a randomized copy of sString.

string GetASCIIChar(int nCode)
Parameters:

  • nCode – ASCII char index (0-255) The NUL character will never be returned.

Return the ASCII char by index.

string GetASCIIEscape()

Return the ASCII char “esc” (0x1B / 27) The NUL character will never be returned.

json StringSplit(string sInput, string sDelimiter)
Parameters:

  • sInput – Input string

  • sDelimiter – Character to split string according to

Returns:

A JsonArray of strings

Split the string according to sDelimiter.

Source code

// @code

#include "ff_i_maths"


//! @brief The lowercase letters 'abcdefghijklmnopqrstuvwxyz'. This value is not locale-dependent and will not change.
const string ASCII_LOWERCASE = "abcdefghijklmnopqrstuvwxyz";

//! @brief The uppercase letters 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. This value is not locale-dependent and will not change.
const string ASCII_UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";

//! @brief The string '0123456789'.
const string ASCII_DIGITS = "0123456789";

//! @brief String of ASCII characters which are considered punctuation characters in the C locale.
const string ASCII_PUNCTUATION = "!\"#$%&'()*+,-./:;<=>?@[\]^_`{|}~.";

//! @brief String of ASCII characters which are considered printable. This is a combination of digits, ascii_letters, punctuation, and whitespace.
const string ASCII_PRINTABLE = ASCII_LOWERCASE + ASCII_UPPERCASE + ASCII_DIGITS + ASCII_PUNCTUATION + " ";

//! @brief Value of the escape code.
const int ASCII_CODE_ESCAPE = 0x1B;

//! @brief String of all ASCII characters.
//! First character is "nearest to 00" since we can't use NUL itself (means you can't get completely black is all)
const string ASCII_CHARS = "\x01\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F\x20\x21\x22\x23\x24\x25\x26\x27\x28\x29\x2A\x2B\x2C\x2D\x2E\x2F\x30\x31\x32\x33\x34\x35\x36\x37\x38\x39\x3A\x3B\x3C\x3D\x3E\x3F\x40\x41\x42\x43\x44\x45\x46\x47\x48\x49\x4A\x4B\x4C\x4D\x4E\x4F\x50\x51\x52\x53\x54\x55\x56\x57\x58\x59\x5A\x5B\x5C\x5D\x5E\x5F\x60\x61\x62\x63\x64\x65\x66\x67\x68\x69\x6A\x6B\x6C\x6D\x6E\x6F\x70\x71\x72\x73\x74\x75\x76\x77\x78\x79\x7A\x7B\x7C\x7D\x7E\x7F\x80\x81\x82\x83\x84\x85\x86\x87\x88\x89\x8A\x8B\x8C\x8D\x8E\x8F\x90\x91\x92\x93\x94\x95\x96\x97\x98\x99\x9A\x9B\x9C\x9D\x9E\x9F\xA0\xA1\xA2\xA3\xA4\xA5\xA6\xA7\xA8\xA9\xAA\xAB\xAC\xAD\xAE\xAF\xB0\xB1\xB2\xB3\xB4\xB5\xB6\xB7\xB8\xB9\xBA\xBB\xBC\xBD\xBE\xBF\xC0\xC1\xC2\xC3\xC4\xC5\xC6\xC7\xC8\xC9\xCA\xCB\xCC\xCD\xCE\xCF\xD0\xD1\xD2\xD3\xD4\xD5\xD6\xD7\xD8\xD9\xDA\xDB\xDC\xDD\xDE\xDF\xE0\xE1\xE2\xE3\xE4\xE5\xE6\xE7\xE8\xE9\xEA\xEB\xEC\xED\xEE\xEF\xF0\xF1\xF2\xF3\xF4\xF5\xF6\xF7\xF8\xF9\xFA\xFB\xFC\xFD\xFE\xFF";


// -----------------------------------------------------------------------------

//! @brief Like GetStringLeft, but negative nCount counts back from the end.
//! @param sString Input string.
//! @param nCount Characters to keep from the left. Negative: counts from the end.
string GetStringLeftEx(string sString, int nCount);
string GetStringLeftEx(string sString, int nCount)
{
  if (nCount > 0)
    return GetStringLeft(sString, nCount);
  if (nCount < 0)
    return GetStringLeft(sString, GetStringLength(sString) + nCount);
  return sString;
}


// -----------------------------------------------------------------------------

//! @brief Trim leading spaces.
//! @param sString Input string.
string GetStringLTrim(string sString);
string GetStringLTrim(string sString)
{
  while (GetStringLeft(sString, 1) == " ")
    sString = GetStringRight(sString, GetStringLength(sString) - 1);
  return sString;
}


// -----------------------------------------------------------------------------

//! @brief Trim trailing spaces.
//! @param sString Input string.
string GetStringRTrim(string sString);
string GetStringRTrim(string sString)
{
  while (GetStringRight(sString, 1) == " ")
    sString = GetStringLeft(sString, GetStringLength(sString) - 1);
  return sString;
}


// -----------------------------------------------------------------------------

//! @brief Trim leading and trailing spaces.
//! @param sString Input string.
string GetStringTrim(string sString);
string GetStringTrim(string sString)
{
  return GetStringRTrim(GetStringLTrim(sString));
}


// -----------------------------------------------------------------------------

//! @brief Return TRUE if sString starts with sSearch
//! @param sString String to search
//! @param sSearch String to find
//! @return Boolean indicating success or failure
int GetStringStartsWith(string sString, string sSearch);
int GetStringStartsWith(string sString, string sSearch)
{
  return GetStringLeft(sString, GetStringLength(sSearch)) == sSearch;
}


// -----------------------------------------------------------------------------

//! @brief Return TRUE if sString ends with sSearch
//! @param sString String to search
//! @param sSearch String to find
//! @return Boolean indicating success or failure
int GetStringEndsWith(string sString, string sSearch);
int GetStringEndsWith(string sString, string sSearch)
{
  return GetStringRight(sString, GetStringLength(sSearch)) == sSearch;
}


// -----------------------------------------------------------------------------

//! @brief Substring starting at nStart. nStart is 0-based; nCount=-1 returns to end.
//! @param sString Input string.
//! @param nStart Start index (0-based). Defaults to 0.
//! @param nCount Number of characters. -1 means to end of string. Defaults to -1.
string GetSubStringEx(string sString, int nStart = 0, int nCount = -1);
string GetSubStringEx(string sString, int nStart = 0, int nCount = -1)
{
  if (nCount == -1)
    nCount = GetStringLength(sString) + 1;
  return GetSubString(sString, nStart, nCount);
}


// -----------------------------------------------------------------------------

//! @brief Left pad the sString to the length of nLength.
//! @brief GetStringLeftPad("AB", 4, "0") becomes "00AB"
//! @param sString String to pad
//! @param nLength Length of output string
//! @param nChar Character to pad with
//! @return Padded string
string GetStringLeftPad(string sString, int nLength = 1, string nChar = " ");
string GetStringLeftPad(string sString, int nLength = 1, string nChar = " ")
{
  string sOutput = "";

  int i;
  for (i = 1; i <= nLength; i++)
    sOutput += nChar;

  return GetStringRight(sOutput + sString, nLength);
}


// -----------------------------------------------------------------------------

//! @brief Right pad the sString to the length of nLength.
//! @brief GetStringRightPad("AB", 4, "0") becomes "AB00"
//! @param sString String to pad
//! @param nLength Length of output string
//! @param nChar Character to pad with
//! @return Padded string
string GetStringRightPad(string sString, int nLength = 1, string nChar = " ");
string GetStringRightPad(string sString, int nLength = 1, string nChar = " ")
{
  string sOutput = "";

  int i;
  for (i = 1; i <= nLength; i++)
    sOutput += nChar;

  return GetStringLeft(sString + sOutput, nLength);
}


// -----------------------------------------------------------------------------

//! @brief Replace the sSearch string by sReplace
//! @param sInput String to search
//! @param sSearch String to find
//! @param sReplace String to replace sSearch with
//! @return A new string
string GetStringReplace(string sInput, string sSearch, string sReplace);
string GetStringReplace(string sInput, string sSearch, string sReplace)
{
  sqlquery query = SqlPrepareQueryObject(GetModule(), "SELECT REPLACE(@sInput, @sSearch, @sReplace)");
  SqlBindString(query, "@sInput", sInput);
  SqlBindString(query, "@sSearch", sSearch);
  SqlBindString(query, "@sReplace", sReplace);
  SqlStep(query);
  return SqlGetString(query, 0);
}


// -----------------------------------------------------------------------------

//! @brief Return TRUE if sString represents an integer (including "0").
//! @param sString Input string.
int GetStringIsInt(string sString);
int GetStringIsInt(string sString)
{
  if (GetStringTrim(sString) == "")
    return FALSE;

  if (StringToInt(sString) != 0)
    return TRUE;

  // Detect if zero
  if (StringToInt(sString + "1") == 1)
    return TRUE;

  return FALSE;
}


// -----------------------------------------------------------------------------

//! @brief Return a randomized copy of sString.
//! @param sString String to take characters from. Can be constructed from ASCII_* constants.
//! @param nLength Length of output string
//! @return Randomized string
string GetRandomString(string sString, int nLength = -1)
{
  string sRetval = "";
  int nInputLength = GetStringLength(sString);
  if (nLength < 0)
    nLength = nInputLength;

  int i, nIndex;
  for (i = 1; i <= nLength; i++)
  {
    nIndex = Random(nInputLength);
    sRetval += GetSubString(sString, nIndex, 1);
  }
  return sRetval;
}


// -----------------------------------------------------------------------------

//! @brief Return the ASCII char by index.
//! @param nCode ASCII char index (0-255)
//! The NUL character will never be returned.
string GetASCIIChar(int nCode);
string GetASCIIChar(int nCode)
{
  nCode = clamp(nCode, 0, 255);
  return GetSubString(ASCII_CHARS, nCode, 1);
}


// -----------------------------------------------------------------------------

//! @brief Return the ASCII char "esc" (0x1B / 27)
//! The NUL character will never be returned.
string GetASCIIEscape();
string GetASCIIEscape()
{
  return GetASCIIChar(ASCII_CODE_ESCAPE);
}


// -----------------------------------------------------------------------------

//! @brief Split the string according to sDelimiter
//! @param sInput Input string
//! @param sDelimiter Character to split string according to
//! @return A JsonArray of strings
json StringSplit(string sInput, string sDelimiter);
json StringSplit(string sInput, string sDelimiter)
{
  if (GetStringRight(sInput, 1) != sDelimiter)
    sInput += sDelimiter;

  string sMatch = "[^" + sDelimiter + "]*" + sDelimiter;
  json jArray = RegExpIterate(sMatch, sInput);

  // Flatten the array
  int nIndex, nLength = JsonGetLength(jArray);
  for (nIndex = 0; nIndex < nLength; nIndex++)
  {
    string sItem = JsonGetString(JsonArrayGet(JsonArrayGet(jArray, nIndex), 0));
    sItem = GetStringLeftEx(sItem, -1);
    JsonArraySetInplace(jArray, nIndex, JsonString(sItem));
  }
  return jArray;
}