String Handling   (hApi unit)

Format_Float

Formats a floating-point value into a string based on a specified format mask.
It supports two types of formatting: Delphi-native and a custom format unique to this implementation. 
function Format_Float(CONST Format: String; Value: Double): String;

Parameters

  • Format: String; Defines the formatting style:
    • Delphi-native format: Uses
      `#`, `0`, and `,`
      for digit placeholders and grouping.
    • Custom format:
      '8,.4z2' equals to delphis '##,###,##0.00##'
      • `/`
        : Stop formatting in case of zero Value
      • `8`
        : Specifies the number of digits in integer part.
      • `,`
        : Thousand separator - indicate that thousand separators are wanted on output string.
      • `.`
        : Separates the integer and fractional parts.
      • `4`
        : Specifies the number of digits in fractional part (4).
      • `z2`
        : Specifies the number of required digits in fractional part (2).
  • Value: Double; The numeric value to format.

Return Value

Returns a string representation of the formatted value according to the FormatMask.

SaveInt

Converts a string into an integer while filtering non-numeric characters.
It is designed to handle input strings robustly, returning `0` in case of errors.
Floating-point values in the input string are truncated. 
function SaveInt(const St: String): Int64;

Parameters

  • St: String; The input string to be converted into an integer. Non-numeric characters are filtered, and floating-point values are truncated to the integer part.

Return Value

Returns the integer value extracted from the input string. If the conversion fails, the function returns `0`.

StrtoInt_FreeTextBox

Converts a string from a free-text box to a non-negative integer.
Trims spaces and ignores non-numeric characters that may trail the actual number.
Function StrtoInt_FreeTextBox(FreeTextBox: String): Cardinal;

Parameters

  • FreeTextBox: String; the raw text input, possibly containing trailing non-numeric characters or whitespace.

Return Value

Returns the numeric portion (as Cardinal) parsed from the input string, or 0 if parsing fails.

Save_Real_Filter

Extracts and converts a string into a floating-point number while filtering out non-numeric characters.
It is designed to handle malformed input gracefully, ensuring robustness.
function Save_Real_Filter(CONST St: String; Filter_All_But_Digits: Boolean = False): Double;

Parameters

  • St: String; The input string to be converted into a floating-point number.
    Non-numeric characters are ignored, and valid numerical segments are processed into a real value.
  • Filter_All_But_Digits: Boolean; If True, strips all characters except digits and numeric separators.

Return Value

Returns the numeric value extracted from the input string.
If the conversion fails, the function returns `0.0`.

Save_Date_Filter

Converts a string into a date while filtering non-date characters.
It supports multiple date formats, including separated and non-separated values.
The function intelligently detects missing components and fills them using the current date when possible.
function Save_Date_Filter(St: String; DateMask: ThDateMask = he_AutoDetect): Integer;

Parameters

  • St: String; The input string to be parsed into a date value.
    Non-date characters are ignored, and valid components are processed.
  • DateMask: ThDateMask; Determines the date format. Available options:
    • he_AutoDetect: Automatically detects the date format.
    • he_MM_DD_YYYY: Parses the input as MM/DD/YYYY.
    • he_DD_MM_YYYY: Parses the input as DD/MM/YYYY.
    • he_YYYY_MM_DD: Parses the input as YYYY-MM-DD.

Return Value

Returns an integer representing the encoded date value.
If the conversion fails, the function returns `0`.

Save_Time_Filter

Converts a string into a time value, filtering non-time characters.
Separation characters can include colons (`:`), dashes (`-`), or dots (`.`).
The function intelligently identifies and converts the string into an encoded time value.
If the
`_Add_Filled_Flag`
parameter is set to `True`, the result will include a flag indicating successful conversion. We need this parameter for indicate for our tables that field is not empty (midnight is 00:00 - zero value)
In case of failure, the function returns `0`.
function Save_Time_Filter(St: String; _Add_Filled_Flag: Boolean): Double;

Parameters

  • St: String; The input string representing time, including valid time characters.
  • _Add_Filled_Flag: Boolean; If `True`, appends a flag to indicate successful conversion.

Return Value

Returns an encoded `Double` representing the time value.
Returns `0` if the conversion fails.

Save_FixDT_Filter

Combines the results of `Save_Date_Filter` and `Save_Time_Filter` to convert a string into a DateTime value.
This function is specifically designed to handle strings that include both date and time components.
Supported date-time separators include spaces (` `) and the letter `T`.
function Save_FixDT_Filter(CONST St: String; DateMask: ThDateMask = he_AutoDetect): Double;

Parameters

  • St: String; The input string containing both date and time.
  • DateMask: ThDateMask; Defines the format of the date in the input string. Available options:
    • he_AutoDetect: Automatically detects the format.
    • he_MM_DD_YYYY: Month-Day-Year format.
    • he_DD_MM_YYYY: Day-Month-Year format.
    • he_YYYY_MM_DD: Year-Month-Day format.
    Default is he_AutoDetect.

Return Value

Returns an encoded `Extended` value representing the DateTime.
Returns `0` in case of failure.

Save_Month_Filter

Converts a string into the first day of a specified month.
It supports various input formats, including month names, month/year combinations, and standalone month numbers.
function Save_Month_Filter(St: String): Integer;

Parameters

  • St: String; The input string containing the month and optionally the year.
    Supported formats include:
    • Month name in English or a local language (for example 'Jan', 'Aug').
    • Month name and year, separated by a space.
    • MM/YYYY format.
    • Standalone month number (1-12).
    If the year is omitted, the current year is assumed.

Return Value

Returns an `Integer` representing the encoded first day of the month.
Returns `0` in case of failure.

Save_Week_Filter

Converts a string into the first day of the specified week based on ISO 8601 standards.
The function assumes Monday as the first day of the week.
function Save_Week_Filter(const St: String): Integer;

Parameters

  • St: String; The input string containing the week number and optionally the year.
    Supported formats include:
    • WW/YYYY: Week number and year.
    • WW: Week number only (defaults to the current year).
    Valid week numbers range from 1 to 53.

Return Value

Returns an `Integer` representing the encoded first day of the specified week.
Returns `0` in case of failure.

Web_Timezone_Offset_To_Delphi

Converts a timezone offset string into a numerical value in Delphi TDateTime format.
It supports offsets such as `+02:00` or `-0800`.
function Web_Timezone_Offset_To_Delphi(Text: String): Double;

Parameters

  • Text: String; The input string representing the timezone offset.

Return Value

Returns a `Double` representing the converted offset in TDateTime format.
If the input format is invalid, the function returns `0`.

Digits_Filter

Removes non-numeric characters from a string.
It is useful for processing strings such as credit card numbers or other digit-based data.
function Digits_Filter(const St: String; const ExtChars: String = ''): String;

Parameters

  • St: String; The input string to filter.
  • ExtChars: String; Optional additional characters to include in the output.

Return Value

Returns a string containing only digits and any allowed characters specified by `ExtChars`.

Name_Filter

Processes a string to ensure it contains only valid name characters, such as letters and spaces.
Invalid characters are replaced with a single space to maintain formatting.
function Name_Filter(const St: String): String;

Parameters

  • St: String; The input string to filter.

Return Value

Returns a string containing only valid name characters.
Extra spaces and invalid characters are reduced to a single space.

AlphaNum_Filter

Removes all non-alphanumeric characters from a string.
Additional allowed characters can be specified through the `ExtChars` parameter.
function AlphaNum_Filter(const St: String; const ExtChars: String = ''): String;

Parameters

  • St: String; The input string to filter.
  • ExtChars: String; Additional characters to include as valid in the filtered string.

Return Value

Returns a string containing only alphanumeric characters and any characters specified in `ExtChars`.

Day_Of_Week

Calculates the day of the week for a given TDateTime value.
The function returns 1 for Sunday through 7 for Saturday.
function Day_Of_Week(const DateTime: TDateTime; AllowZero: Boolean = False): Integer;

Parameters

  • DateTime: TDateTime; The input date value.
  • AllowZero: Boolean; If `True`, allows a return value of 0 for invalid input.

Return Value

Returns an integer from 1 to 7 indicating the day of the week.
Returns 0 if `AllowZero` is enabled and the input is invalid.

_Date_To_Str

Formats a TDateTime value as a date string in either standard or ISO 8601 format.
function _Date_To_Str(const TimeVal: Double; YYYY_MM_DD_Format: Boolean = False): String;

Parameters

  • TimeVal: Double; The input date value to format.
  • YYYY_MM_DD_Format: Boolean; If `True`, formats the date as `YYYY-MM-DD`.
    If `False`, the format depends on regional settings.

Return Value

Returns a formatted date string based on the specified format.

_YYYY_MM_DD_To_Str

Formats a TDateTime value as an ISO 8601 datetime string.
It optionally includes milliseconds.
function _YYYY_MM_DD_To_Str(const TimeVal: Double; const ZZZ_Include: Boolean = False): String;

Parameters

  • TimeVal: Double; The input datetime value to format.
  • ZZZ_Include: Boolean; If `True`, includes milliseconds in the output.

Return Value

Returns a formatted ISO 8601 datetime string.

_Date_To_Week_Str

Calculates the ISO 8601 week and year for a given date.
function _Date_To_Week_Str(const TimeVal: Double): String;

Parameters

  • TimeVal: Double; The input date value to process.

Return Value

Returns a string in the format `WW/YYYY`, where `WW` is the week number and `YYYY` is the year.

_Hour_To_Str

Formats a TDateTime value as a time string in `HH:NN` format.
function _Hour_To_Str(const TimeVal: Double): String;

Parameters

  • TimeVal: Double; The input time value to format.

Return Value

Returns a string representing the time in `HH:NN` format.

Format_FixDT_To_Str

Formats a TDateTime value according to a specified mask.
If the mask is empty, a default format is applied based on regional settings.
function Format_FixDT_To_Str(_Mask: String; const Value: TDateTime): String;

Parameters

  • _Mask: String; The formatting mask to use.
    Supported options include:
    • `+S`: Includes seconds.
    • `+Z`: Includes milliseconds.
    Defaults to `DD/MM/YYYY HH:NN` or `MM/DD/YYYY HH:NN` based on regional settings.
  • Value: TDateTime; The input date and time value to format.

Return Value

Returns a formatted date and time string based on the mask.

_Hour_Num

Extracts the hour component from a TDateTime value.
function _Hour_Num(const TimeVal: Double): Word;

Parameters

  • TimeVal: Double; The input TDateTime value.

Return Value

Returns the `Word` value representing the hour component of the input time.

Calc_Next_Round_Hour

Calculates the next rounded hour based on a starting TDateTime value.
An optional minute offset can be added to the calculation.
function Calc_Next_Round_Hour(const From_Now: TDateTime; PlusMinutes: Byte = 0): TDateTime;

Parameters

  • From_Now: TDateTime; The starting point for the calculation.
  • PlusMinutes: Byte; Optional minute offset to add to the calculated hour.

Return Value

Returns the TDateTime value of the next rounded hour after applying the offset.
Returns `0` if the input is invalid.

_Money_To_Str

Formats a numeric value into a string for monetary representation.
Optional color coding can be applied for positive and negative values.
function _Money_To_Str(const Amount: Double; PnL_Colors: Boolean = False): String;

Parameters

  • Amount: Double; The monetary value to format.
  • PnL_Colors: Boolean; If `True`, applies green for positive values and red for negative values.

Return Value

Returns a formatted string representation of the monetary value.
Returns `'0.00'` for values near zero.

_Real_To_Str

Formats a floating-point number into a detailed string representation.
Optional color coding can be applied for positive and negative values.
function _Real_To_Str(CONST Amount: Double; CONST PnL_Colors: Boolean = False; CONST Format: String = ',20.8z2'): String;

Parameters

  • Amount: Double; The floating-point value to format.
  • PnL_Colors: Boolean; If `True`, applies green for positive values and red for negative values.
  • Format: String; Numeric format mask (default
    ',20.8z2'
    ).

Return Value

Returns a string formatted to include up to 8 decimal places with optional color coding.

_Int_To_Str

Formats an integer value into a string with grouping separators.
Optional color coding can be applied for positive and negative values.
function _Int_To_Str(const Amount: Double; PnL_Colors: Boolean = False): String;

Parameters

  • Amount: Double; The integer value to format.
  • PnL_Colors: Boolean; If `True`, applies green for positive values and red for negative values.

Return Value

Returns a string representation of the integer value with optional color coding.

B2S

Converts a boolean value into a string representation of `'True'` or `'False'`.
function B2S(Flag: Boolean): String;

Parameters

  • Flag: Boolean; The boolean value to convert.

Return Value

Returns `'True'` if the input is `True`, and `'False'` if the input is `False`.

_B2S

Converts a boolean value into a string representation of `'Yes'` or `'No'`.
function _B2S(Flag: Boolean): String;

Parameters

  • Flag: Boolean; The boolean value to convert.

Return Value

Returns `'Yes'` if the input is `True`, and `'No'` if the input is `False`.

_Date_To_Month_Str

Formats a TDateTime value into a string representing the month and year.
The month name is localized based on the specified language.
function _Date_To_Month_Str(const TimeVal: Double; Lang: ThTranslation_Language): String;

Parameters

  • TimeVal: Double; The input date value.
  • Lang: ThTranslation_Language; The language to use for the month name.

Return Value

Returns a string in the format `'Month Year'`, e.g., `'January 2025'`.

_Same_Str

Compares two strings to determine if they are identical.
An optional parameter ensures the comparison happens only if both strings are non-empty.
function _Same_Str(CONST St1, St2: String; IF_NOT_Empty: Boolean = False): Boolean;

Parameters

  • St1: String; The first string to compare.
  • St2: String; The second string to compare.
  • IF_NOT_Empty: Boolean; If `True`, the comparison is performed only if both strings are non-empty.

Return Value

Returns `True` if the strings are identical.
Returns `False` otherwise.

_Starting_With_Str

Checks if a source string starts with a specific substring.
function _Starting_With_Str(CONST FindString, SourceString: String): Boolean;

Parameters

  • FindString: String; The substring to check for at the start of the source string.
  • SourceString: String; The source string to evaluate.

Return Value

Returns `True` if the source string starts with the specified substring.
Returns `False` otherwise.

WPos_Backward

Searches for a substring within a source string, starting from a specific position and working backward.
It allows specifying a range for the search.
function WPos_Backward(CONST FindString, SourceString: String; FromPos, ToPos: Integer): Cardinal;

Parameters

  • FindString: String; The substring to search for.
  • SourceString: String; The source string to search within.
  • FromPos: Integer; The position to start the search from.
  • ToPos: Integer; The position to stop the search.

Return Value

Returns the position of the substring if found within the specified range.
Returns `0` if the substring is not found.

WPos

Searches for a substring within a source string, starting from a specified position.
An optional parameter allows defining the endpoint of the search.
function WPos(CONST FindString, SourceString: String; FromPos: Integer = 1; ToPos: Integer = 0): Cardinal;

Parameters

  • FindString: String; The substring to search for.
  • SourceString: String; The source string to search within.
  • FromPos: Integer; The position to start the search from (default is 1).
  • ToPos: Integer; The position to end the search (default is 0, meaning the end of the string).

Return Value

Returns the position of the substring if found within the specified range.
Returns `0` if the substring is not found.

_Cont_Str

Checks if a source string contains a specific substring.
function _Cont_Str(CONST FindString, SourceString: String): Boolean;

Parameters

  • FindString: String; The substring to search for.
  • SourceString: String; The source string to evaluate.

Return Value

Returns `True` if the source string contains the specified substring.
Returns `False` otherwise.

_Cont_Word

Checks if a source string contains a specific word. The search is case-sensitive.
function _Cont_Word(CONST FindString, SourceString: String): Boolean;

Parameters

  • FindString: String; The word to search for.
  • SourceString: String; The source string to evaluate.

Return Value

Returns `True` if the source string contains the specified word.
Returns `False` otherwise.

_Cont_ALL_Group_Items

Checks if all items in one list are present in another list.
Items in both lists are separated by CR-LF or #13. 
function _Cont_ALL_Group_Items(CONST Find_This_List, All_Items_List: String): Boolean;

Parameters

  • Find_This_List: String; A CR-LF list of items to check.
  • All_Items_List: String; A CR-LF list to check against.

Return Value

Returns `True` if all items in `Find_This_List` are found in `All_Items_List`.
Returns `False` otherwise.

_Cont_ANY_Group_Item

Checks if any item from one list is present in another list.
Items in both lists are separated by CR-LF or #13.
function _Cont_ANY_Group_Item(CONST Find_This_List, All_Items_List: String): Boolean;

Parameters

  • Find_This_List: String; A CR-LF list of items to check.
  • All_Items_List: String; A CR-LF list to check against.

Return Value

Returns `True` if any item in `Find_This_List` is found in `All_Items_List`.
Returns `False` otherwise.

Remove_Group_Item

Removes a specific item from a CR-LF list.
function Remove_Group_Item(CONST Remove_This_Item: String; VAR All_Items_List: String): Boolean;

Parameters

  • Remove_This_Item: String; The item to be removed.
  • All_Items_List: String; The list from which the item will be removed.

Return Value

Returns `True` if the item was successfully removed.
Returns `False` otherwise.

Parameter_Extract

Extracts the value of a named parameter from a string.
It is commonly used for extracting parameters from CSS or query strings.
function Parameter_Extract(CONST ParamName, SourceString: String; VAR Pvalue: String; ForCSS: Boolean = False): Boolean;

Parameters

  • ParamName: String; The name of the parameter to extract.
  • SourceString: String; The string containing the parameters.
  • Pvalue: String; The variable to store the extracted parameter value.
  • ForCSS: Boolean; If `True`, the function assumes CSS-style formatting.

Return Value

Returns `True` if the parameter was successfully extracted.
Returns `False` otherwise.

_Identify_Char_Lang

Determines the language of a single character.
function _Identify_Char_Lang(CONST _Char: WideChar): ThTranslation_Language;

Parameters

  • _Char: WideChar; The character to identify.

Return Value

Returns a `ThTranslation_Language` value representing the identified language.

_Validate_Lang

Checks if a character belongs to a specific language group.
function _Validate_Lang(CONST _Char: WideChar; CONST Language: ThTranslation_Language; CONST ExtraChars: String = ''): Boolean;

Parameters

  • _Char: WideChar; The character to validate.
  • Language: ThTranslation_Language; The language group to check against.
  • ExtraChars: String; Additional valid characters.

Return Value

Returns `True` if the character matches the specified language group or included in ExtraChars parameter.
Returns `False` otherwise.

_Does_Contain_Lang

Checks if a string contains characters from a specific language group.
function _Does_Contain_Lang(CONST Text: String; CONST Language: ThTranslation_Language; CONST ExtraChars: String = ''): Boolean;

Parameters

  • Text: String; The string to check.
  • Language: ThTranslation_Language; The language group to check against.
  • ExtraChars: String; Additional valid characters.

Return Value

Returns `True` if the string contains characters from the specified language group or included in ExtraChars parameter.
Returns `False` otherwise.

Verify_Acceptable_Input_Lang

Validates if a string contains only characters from specified language groups.
function Verify_Acceptable_Input_Lang(CONST InText: String; Acceptable_Languages: ThTranslation_Language_Group): Boolean;

Parameters

  • InText: String; The string to validate.
  • Acceptable_Languages: ThTranslation_Language_Group; The language groups to validate against.

Return Value

Returns `True` if the string contains only acceptable characters.
Returns `False` otherwise.

Get_Acceptable_Input_Lang_String

Retrieves the acceptable input languages as a string.
function Get_Acceptable_Input_Lang_String: String;

Return Value

Returns a string representing the acceptable input languages.

Copy_Upto_Char

Copies a substring from a source string up to a specified character.
function Copy_Upto_Char(CONST SourceString: String; FromPos: Cardinal; EndChar: Char): String;

Parameters

  • SourceString: String; The string to copy from.
  • FromPos: Cardinal; The position to start copying from.
  • EndChar: Char; The character to stop copying at.

Return Value

Returns the copied substring up to (but not including) the specified character.
If the character is not found, the function returns an empty string.

Search_And_Replace

Searches for a substring within a source string and replaces it with another substring.
function Search_And_Replace(CONST FindString, Replaceto: String; VAR SourceString: String): Boolean;

Parameters

  • FindString: String; The substring to search for.
  • Replaceto: String; The substring to replace the found text with.
  • SourceString: String; The string to perform the replacement on.

Return Value

Returns `True` if the replacement was successful.
Returns `False` if the substring was not found.

Search_And_Replace2

Performs a search-and-replace operation on a string and returns the updated string.
function Search_And_Replace2(CONST FindString, Replaceto, SourceString: String): String;

Parameters

  • FindString: String; The substring to search for.
  • Replaceto: String; The substring to replace the found text with.
  • SourceString: String; The string to perform the replacement on.

Return Value

Returns a new string with the specified replacements applied.

_Keep_The_Longest_String

Compares two strings and keeps the longer one.
procedure _Keep_The_Longest_String(CheckStr: String; VAR TargetStr: String);

Parameters

  • CheckStr: String; The string to compare with the target.
  • TargetStr: String; The target string, which will be replaced if CheckStr is longer.

Phone_Num_Mask

Applies a country-specific formatting mask to a phone number.
function Phone_Num_Mask(Text: String; Country: Word = 0): String;

Parameters

  • Text: String; The phone number to format.
  • Country: Word; The country code to apply the formatting for (default is 0).

Return Value

Returns a formatted phone number string based on the specified country code.
If no formatting is available for the specified country, the input string is returned as-is.

ReFormat_PlainText

Reflows plain text to fit within a specified number of characters per line.
function ReFormat_PlainText(CONST Source: String; Avg_Chars_At_Line: Word; Keep_Short_Lines_In_Place: Boolean): String;

Parameters

  • Source: String; The plain text to reformat.
  • Avg_Chars_At_Line: Word; The average number of characters per line.
  • Keep_Short_Lines_In_Place: Boolean; If `True`, short lines are preserved as-is.

Return Value

Returns the reformatted plain text with line breaks adjusted.

Clean_System_Chars_From_Text

Removes system characters from a string.
Optionally, line break characters can be preserved.
function Clean_System_Chars_From_Text(Source: String; Allow_CRLF: Boolean = False): String;

Parameters

  • Source: String; The input string to clean.
  • Allow_CRLF: Boolean; If `True`, preserves line break characters (CRLF). Default is `False`.

Return Value

Returns the input string with all system characters removed.

Trim_Below

Trims characters below a specified ASCII value from a string.
The trimming can be applied to the start, the end, or both ends of the string.
function Trim_Below(CONST Text: String; CONST BelowChar: Word = 33; CONST From_Start_End: Byte = 2): String;

Parameters

  • Text: String; The input string to trim.
  • BelowChar: Word; The ASCII value below which characters will be removed. Default is 33.
  • From_Start_End: Byte; Specifies where to trim:
    • `0`: Do not trim.
    • `1`: Trim only the start.
    • `2`: Trim only the end.
    • `3`: Trim both the start and the end.

Return Value

Returns the trimmed string.

Wide_Copy_String_To_Array

Copies a wide string into a wide character array.
procedure Wide_Copy_String_To_Array(VAR Dest: Array OF WideChar; CONST Source: String);

Parameters

  • Dest: Array OF WideChar; The destination array to copy the string into.
  • Source: String; The wide string to copy.

Wide_Copy_Array_To_String

Converts a wide character array into a wide string.
function Wide_Copy_Array_To_String(CONST Source: Array OF WideChar): String;

Parameters

  • Source: Array OF WideChar; The wide character array to convert.

Return Value

Returns the resulting wide string converted from the input array.

DOS_Reverse_Chars_Order

Reverses the byte order of characters within a specific range in a DOS-encoded byte string.
Only characters with ordinal values between From_Char and TO_Char are affected.
Function DOS_Reverse_Chars_Order(From_Char, TO_Char: Byte; Source: RawByteString): RawByteString;

Parameters

  • From_Char: Byte; the lower bound of the byte range to reverse.
  • TO_Char: Byte; the upper bound of the byte range to reverse.
  • Source: RawByteString; the input string to process, expected in DOS encoding.

Return Value

Returns a new RawByteString with characters in the specified range reversed in order.

DOS_Field_Spacer

Formats a DOS-style field to a fixed length by adding left or right padding with space characters.
Supports both left-to-right and right-to-left alignment depending on the RTL flag.
Function DOS_Field_Spacer(Source: RawByteString; Field_Length: Byte; RTL: Boolean): RawByteString;

Parameters

  • Source: RawByteString; the text to be padded, assumed to be in DOS encoding.
  • Field_Length: Byte; the desired final length of the padded field.
  • RTL: Boolean; if True, pads on the left (right-aligns the text); otherwise pads on the right.

Return Value

Returns a fixed-length RawByteString with added spaces for alignment.

Reverse_Chars_Order

Reverses the order of characters in a string within a specified range of character codes.
function Reverse_Chars_Order(From_Char, TO_Char: Word; Source: String): String;

Parameters

  • From_Char: Word; The starting character code of the range to reverse.
  • TO_Char: Word; The ending character code of the range to reverse.
  • Source: String; The input string to process.

Return Value

Returns the modified string with characters reversed within the specified range.

Convert_Inet_CharSet_To_Windows_CodePage

Maps an Internet character set name to a Windows code page identifier.
function Convert_Inet_CharSet_To_Windows_CodePage(CONST CharSet: RawByteString): Cardinal;

Parameters

  • CharSet: RawByteString; The name of the Internet character set to convert.

Return Value

Returns the corresponding Windows code page identifier.
Returns `0` if the character set is not recognized.

Convert_Ansi_To_Wide

Converts an ANSI-encoded string to a wide string using a specified code page.
function Convert_Ansi_To_Wide(CONST Source: RawByteString; CONST CodePage: Cardinal = CP_UTF8): String;

Parameters

  • Source: RawByteString; The input string to convert.
  • CodePage: Cardinal; The code page to use for conversion. Default is `CP_UTF8`.

Return Value

Returns the converted wide string.
If the conversion fails, an empty string is returned.

Convert_Wide_To_Ansi

Converts a wide string to an ANSI-encoded string using a specified code page.
function Convert_Wide_To_Ansi(CONST Source: String; CONST CodePage: Cardinal = CP_UTF8): RawByteString;

Parameters

  • Source: String; The input wide string to convert.
  • CodePage: Cardinal; The code page to use for conversion. Default is `CP_UTF8`.

Return Value

Returns the converted ANSI string.
If the conversion fails, an empty string is returned.

Convert_Inet_To_Wide

Converts an internet-encoded byte string into a wide Unicode string using the specified character set.
Optionally allows system encoding control via the Encoding_Sys flag.
Function Convert_Inet_To_Wide(Source, CharSet: RawByteString; CONST Encoding_Sys: AnsiChar = #0): String;

Parameters

  • Source: RawByteString; the byte string to be converted, typically received from an internet source.
  • CharSet: RawByteString; the name of the charset (e.g., 'utf-8', 'windows-1255') used to interpret the byte data.
  • Encoding_Sys: AnsiChar; optional flag for system-based encoding behaviors (default is #0, which disables it).

Return Value

Returns the converted string in Unicode (UTF-16) format, suitable for internal Delphi use.

Convert_Wide_To_Inet

Converts a wide Unicode string into an internet-compatible byte string using the specified charset.
Supports optional encoding control through Encoding_Sys.
Function Convert_Wide_To_Inet(Source: String; CONST CharSet: RawByteString; CONST Encoding_Sys: AnsiChar = #0): RawByteString;

Parameters

  • Source: String; the wide string to convert, typically in UTF-16 format.
  • CharSet: RawByteString; the desired output charset (e.g., 'utf-8', 'iso-8859-1').
  • Encoding_Sys: AnsiChar; optional system encoding control flag (default is #0).

Return Value

Returns the encoded byte string compatible with internet transfer or external systems.

Format_File_Name

Filters and formats a file name to ensure it is valid and safe for use in file systems.
function Format_File_Name(Source: String; IncAsterisk: Boolean = False): String;

Parameters

  • Source: String; The input string representing the file name to format.
  • IncAsterisk: Boolean; If `True`, includes asterisks in the formatted file name.

Return Value

Returns the formatted file name with invalid characters removed.

Format_Component_Name

Cleans and normalizes a component name string for safe or consistent usage.
Removes or replaces invalid characters and trims unwanted content.
Function Format_Component_Name(CONST Source: String; CONST LettersCase: ThFormat_Component_Name_Case = he_Lowercase): String;

Parameters

  • Source: String; the raw input text representing a component name.
  • LettersCase: ThFormat_Component_Name_Case; output letter case (default is
    he_Lowercase
    ).

Return Value

Returns a cleaned and valid component name string, ready for use in code or interfaces.

Format_Phone_Number_For_Dialer

Formats a phone number for use with a dialer, applying local or international formatting rules.
Can include the full international prefix when requested.
Function Format_Phone_Number_For_Dialer(LocalPrefix, PhoneNumber: String; FullInternational: Boolean): String;

Parameters

  • LocalPrefix: String; the local prefix or country code to use for formatting.
  • PhoneNumber: String; the raw phone number to format.
  • FullInternational: Boolean; if True, returns the number with full international prefix.

Return Value

Returns the formatted phone number string, ready for dialing use.

First_Letter_Uppercase

Converts the first letter of each word in a string to uppercase.
function First_Letter_Uppercase(Text: String): String;

Parameters

  • Text: String; The input string to process.

Return Value

Returns the string with the first letter of each word converted to uppercase.

Get_String_Index

Retrieves the index of a specific string in a CR-LF list of strings.
function Get_String_Index(Find_String, Strings_List: String): Integer;

Parameters

  • Find_String: String; The string to find in the list.
  • Strings_List: String; The CR-LF list of strings to search.

Return Value

Returns the index (1-based) of the string in the list.
Returns `0` if the string is not found.

Copy_Without_Counting_Tags

Extracts a substring while ignoring HTML or XML tags.
function Copy_Without_Counting_Tags(Source: String; _FromPos, _Length: Cardinal): String;

Parameters

  • Source: String; The input string to extract from.
  • _FromPos: Cardinal; The starting position of the extraction.
  • _Length: Cardinal; The number of characters to extract.

Return Value

Returns the extracted substring while excluding tag content.

Copy_Without_Attribute_Tags

Removes attribute tags from an input string.
function Copy_Without_Attribute_Tags(Source: String): String;

Parameters

  • Source: String; The input string to clean.

Return Value

Returns the cleaned string with attribute tags removed.

Remove_Tags

Removes specific tags and optionally their content from a string.
procedure Remove_Tags(VAR Text: String; CONST Tag_Name: String; CONST Remove_Content_Between_Tags: Boolean);

Parameters

  • Text: String; The input string to modify.
  • Tag_Name: String; The name of the tag to remove.
  • Remove_Content_Between_Tags: Boolean; If `True`, also removes the content between the tags.

Return Value

This procedure does not return a value.

Byte_To_Hex

Converts a byte value to its hexadecimal representation.
function Byte_To_Hex(CONST Input: Byte): RawByteString;

Parameters

  • Input: Byte; The byte value to convert.

Return Value

Returns the hexadecimal representation of the input byte.

Longword_To_Hex

Converts a cardinal value to its hexadecimal representation.
function Longword_To_Hex(CONST Input: Cardinal): String;

Parameters

  • Input: Cardinal; The cardinal value to convert.

Return Value

Returns the hexadecimal representation of the input cardinal value.

Double_To_Hex

Encodes a Double-precision floating-point value into a hexadecimal byte string.
The resulting string contains the raw memory representation of the floating-point value.
Function Double_To_Hex(CONST Input: Double): RawByteString;

Parameters

  • Input: Double; the floating-point number to be converted into hexadecimal representation.

Return Value

Returns a RawByteString containing the binary layout of the double value, encoded as a hex-like byte string.

Hex_To_Double

Decodes a RawByteString that contains a hexadecimal representation of a Double value.
Function Hex_To_Double(CONST Input: RawByteString): Double;

Parameters

  • Input: RawByteString; the hex-encoded or binary string to decode back into a Double value.

Return Value

Returns the reconstructed Double value extracted from the binary or hex input string.

IS_Password_Strong_Enought

Validates a password string and checks whether it is strong enough.
Validation level depends on the
Strong
flag.
Function IS_Password_Strong_Enought(CONST Value: String; Strong: Boolean = True): Boolean;

Parameters

  • Value: String; the password text to validate.
  • Strong: Boolean; when True, applies stricter validation rules.

Return Value

Returns True when the password passes validation.
Returns False otherwise.

Generate_Password

Creates a random password of a specified length.
function Generate_Password(_Length: Byte): String;

Parameters

  • _Length: Byte; The desired length of the password.

Return Value

Returns a randomly generated password containing alphanumeric characters.

Generate_Token_String

Generates a random token string of the specified length using safe byte characters.
The result is suitable for use as identifiers, session keys, or hashes.
Function Generate_Token_String(_Length: Word): RawByteString;

Parameters

  • _Length: Word; the number of characters to include in the generated token.

Return Value

Returns a RawByteString containing the generated random token of the requested length.

Copy_End_Of_String

Extracts a substring from the end of a string.
function Copy_End_Of_String(Source: String; LengthFromEnd: Integer): String;

Parameters

  • Source: String; The input string to extract from.
  • LengthFromEnd: Integer; The number of characters to extract from the end.

Return Value

Returns the substring from the end of the input string.

_Valid_IP_Addr_Str

Checks if a string represents a valid IPv4 or IPv6 address.
function _Valid_IP_Addr_Str(StrAddress: RawByteString): Boolean;

Parameters

  • StrAddress: RawByteString; The string to validate as an IP address.

Return Value

Returns `True` if the string is a valid IP address.
Returns `False` otherwise.

Push_Line

Appends a new line to a string if the new line is not empty.
procedure Push_Line(CONST New_Line: String; VAR Target: String);

Parameters

  • New_Line: String; The line to append.
  • Target: String; The string to which the line will be appended.

Push_String

Appends a new string to an existing target, using a separator only if the target is not empty.
Useful for building delimited strings dynamically without inserting unwanted leading separators.
Procedure Push_String(CONST New_Text, Separation: String; VAR Target: String);

Parameters

  • New_Text: String; the string to append to the target.
  • Separation: String; the separator to insert before New_Text, if Target is not empty.
  • Target: String; the destination string to which New_Text is appended.

Push_Line_Array

Appends a new line to an array of strings if the new line is not empty.
procedure Push_Line_Array(CONST New_Line: String; VAR Target: ThFlds_Name_Array);

Parameters

  • New_Line: String; The line to append.
  • Target: ThFlds_Name_Array; The array to which the line will be appended.

Copy_String_To_Clipboard

Copies a string to the system clipboard.
function Copy_String_To_Clipboard(CONST Text: String): Boolean;

Parameters

  • Text: String; The string to copy to the clipboard.

Return Value

Returns `True` if the string was successfully copied to the clipboard.
Returns `False` otherwise.

Log_Filename

Returns the path of the application's log file.
If the application is running inside the Delphi IDE (`bds.exe`), it returns a fixed log file path.
Otherwise, it appends `_Log.txt` to the application's executable name.
function Log_Filename: String;

Return Value

Returns the full path of the log file used by the application.
If running inside the Delphi IDE, the log file path is fixed to `C:\work\IDE_Log.txt`.
Otherwise, the log file is created in the same directory as the executable, with `_Log.txt` appended to the file name.

Write_Log_File

Appends a message line to the application's Unicode log file.
The log entry may include timestamps and is stored using UTF-16 encoding.
Function Write_Log_File(CONST MessageText: String): Boolean;

Parameters

  • MessageText: String; the log line to append, provided as a wide string.

Return Value

Returns True if the log line was successfully written.
Returns False on failure (e.g. file not accessible).

Translate

Retrieves a localized translation of a given text string.
function Translate(CONST Text: String): String;

Parameters

  • Text: String; The text to translate.

Return Value

Returns the translated version of the input text if a translation is available.

TC

Provides a shortcut for retrieving a translated caption in a specified language.
function TC(CONST Text: String; CONST Lang: ThTranslation_Language): String;

Parameters

  • Text: String; The text to translate.
  • Lang: ThTranslation_Language; The target language for translation.

Return Value

Returns the translated caption in the specified language.

_Same_Phone_Number

Compares two phone numbers for equality after filtering out non-numeric characters.
function _Same_Phone_Number(CONST Find_Digits_Filtered, Phone_Field: String): Boolean;

Parameters

  • Find_Digits_Filtered: String; The first phone number, filtered to include only numeric characters.
  • Phone_Field: String; The second phone number to compare.

Return Value

Returns `True` if the phone numbers are identical after filtering.
Returns `False` otherwise.

ThStringList

Custom string list class that supports check flags and associated integer data for each item.
Provides methods for searching, sorting, loading, and saving text lists with enhanced control.
Like Delphi class TStringList, but with better performance and more functions.

Count

Returns the number of items currently stored in the list.
Property ThStringList.Count: Integer;

Return Value

Returns the number of rows in the list.

Strings

Provides indexed access to the text of each item in the list.
This is the default property of the class.
Property ThStringList.Strings[Index: Integer]: String;

Parameters

  • Index: Integer; the zero-based position of the item.

Return Value

Gets or sets the string at the specified index.

Checked

Provides indexed access to the check flag of each item in the list.
Property ThStringList.Checked[Index: Integer]: Boolean;

Parameters

  • Index: Integer; the item index to check or uncheck.

Return Value

Gets or sets the Boolean check state of the specified item.

Data_Int

Provides indexed access to the integer data field of each item.
Property ThStringList.Data_Int[Index: Integer]: Int64;

Parameters

  • Index: Integer; the item index whose data is accessed.

Return Value

Gets or sets the 64-bit integer associated with the specified item.

Text

Gets or sets the full contents of the list as a single multi-line string.
Property ThStringList.Text: String;

Return Value

Returns or sets the list content as a single string with line breaks between items.

Checked_Items_Text

Gets or sets a single string containing only the checked items from the list.
Property ThStringList.Checked_Items_Text: String;

Return Value

Returns or sets a string composed of checked items only, separated by line breaks.

OnChange

Event triggered whenever the content of the list is changed programmatically.
Property ThStringList.OnChange: TNotifyEvent;

Return Value

Assigns or retrieves the event handler to be executed on changes.

Clear

Removes all items from the list, resetting it to an empty state.
Procedure ThStringList.Clear;

Empty

Checks whether the list contains any items.
Function ThStringList.Empty: Boolean;

Return Value

Returns True if the list is empty.
Returns False otherwise.

IndexOf

Searches for a string in the list and returns its index if found.
Function ThStringList.IndexOf(CONST S: String): Integer;

Parameters

  • S: String; the string to locate in the list.

Return Value

Returns the zero-based index of the string if found.
Returns -1 if not found.

IndexOfData

Searches for an item by its associated integer data value.
Function ThStringList.IndexOfData(CONST D: Int64): Integer;

Parameters

  • D: Int64; the data value to search for.

Return Value

Returns the index of the item with the given data value.
Returns -1 if no match is found.

IndexOfBoth

Searches for an item matching both a specific data value and string.
Function ThStringList.IndexOfBoth(CONST D: Int64; CONST S: String): Integer;

Parameters

  • D: Int64; the associated data value to search for.
  • S: String; the string to match.

Return Value

Returns the index of the matching item.
Returns -1 if not found.

Starting_With_Str

Finds the first item that begins with a specified string.
Function ThStringList.Starting_With_Str(CONST S: String): Integer;

Parameters

  • S: String; the prefix to match.

Return Value

Returns the index of the first matching item.
Returns -1 if no match is found.

SearchText

Searches for a string within a defined range of list items.
Function ThStringList.SearchText(CONST S: String; FromRow: Integer = 0; UntilRow: Integer = -1): Integer;

Parameters

  • S: String; the text to search for.
  • FromRow: Integer; the index to start searching from (default is 0).
  • UntilRow: Integer; the last index to search up to (default is -1 = end of list).

Return Value

Returns the index of the first match within the range.
Returns -1 if no match is found.

Insert

Inserts a new string at a specific index in the list.
Procedure ThStringList.Insert(CONST Index: Integer; CONST S: String);

Parameters

  • Index: Integer; the position at which to insert the item.
  • S: String; the string to insert.

Add

Appends a new item to the end of the list, with optional data and check flag.
Function ThStringList.Add(CONST S: String; CONST DataInt: Int64 = 0; CONST Flag: Boolean = False): Integer;

Parameters

  • S: String; the text to add.
  • DataInt: Int64; optional associated data (default is 0).
  • Flag: Boolean; optional check state (default is False).

Return Value

Returns the index of the newly added item.

Delete

Removes an item at the specified index from the list.
Procedure ThStringList.Delete(CONST Index: Integer);

Parameters

  • Index: Integer; the index of the item to remove.

Delete_Range

Deletes a range of items between two index positions, inclusive.
Procedure ThStringList.Delete_Range(FromIndex, ToIndex: Integer);

Parameters

  • FromIndex: Integer; starting index of the range.
  • ToIndex: Integer; ending index of the range.

Delete_Empty_Lines

Removes all empty string entries from the list.
Procedure ThStringList.Delete_Empty_Lines;

Search_And_Replace

Performs a search and replace operation on a specific item by index.
Function ThStringList.Search_And_Replace(CONST FindString, Replaceto: String; CONST Index: Integer): Boolean;

Parameters

  • FindString: String; the substring to search for.
  • Replaceto: String; the string to replace it with.
  • Index: Integer; the index of the item to process.

Return Value

Returns True if a replacement occurred.
Returns False if the string was not found.

Assign

Copies the content of another ThStringList instance into this one.
Procedure ThStringList.Assign(Source: ThStringList);

Parameters

  • Source: ThStringList; the source list to copy.

Sort

Sorts the list by text and/or data values using the specified directions.
Procedure ThStringList.Sort(CONST StringDirection, IntegerDirection: Byte);

Parameters

  • StringDirection: Byte; 0 = none, 1 = ascending, 2 = descending.
  • IntegerDirection: Byte; 0 = none, 1 = ascending, 2 = descending.

Load_From_HMemoryStream

Loads list content from a memory stream object.
Function ThStringList.Load_From_HMemoryStream(Source: TObject; Dec_UTF8_IF_No_Prefix: Boolean = False): Boolean;

Parameters

  • Source: TObject; a memory stream object containing text.
  • Dec_UTF8_IF_No_Prefix: Boolean; decode as UTF-8 when no encoding prefix exists (default is False).

Return Value

Returns True if the list was loaded successfully.
Returns False on failure.

Load_From_File

Loads the list from a text file on disk.
Function ThStringList.Load_From_File(FileName: String; Dec_UTF8_IF_No_Prefix: Boolean = False): Boolean;

Parameters

  • FileName: String; full path to the file to load.
  • Dec_UTF8_IF_No_Prefix: Boolean; decode as UTF-8 when no encoding prefix exists (default is False).

Return Value

Returns True if the file was loaded successfully.
Returns False on failure.

Load_From_Delphi_Stream

Loads the list from a Delphi TStream object.
Function ThStringList.Load_From_Delphi_Stream(Source: TStream; Count: Integer; Dec_UTF8_IF_No_Prefix: Boolean = False): Boolean;

Parameters

  • Source: TStream; the stream to load from.
  • Count: Integer; number of bytes to read from the stream.
  • Dec_UTF8_IF_No_Prefix: Boolean; decode as UTF-8 when no encoding prefix exists (default is False).

Return Value

Returns True if the stream was read successfully.
Returns False otherwise.

Load_List_From_String

Splits a delimited string into individual list items.
Procedure ThStringList.Load_List_From_String(Src: String; Separator: Char);

Parameters

  • Src: String; the string to split.
  • Separator: Char; the character to split the string on.

Merge_String_Lists

Merges a flat delimited string into the list, appending new items.
Function ThStringList.Merge_String_Lists(Source: String): Boolean;

Parameters

  • Source: String; the delimited string to merge.

Return Value

Returns True if items were merged successfully.

Trim_Every_Item_Below_33

Removes all control characters (below ASCII 33) from each item.
Procedure ThStringList.Trim_Every_Item_Below_33;

Any_Item_Checked

Checks whether any list item is marked as checked.
Function ThStringList.Any_Item_Checked: Boolean;

Return Value

Returns True if any item is checked.
Returns False otherwise.

Save_To_File

Saves the list contents to a file in UTF-8 or ANSI format.
Function ThStringList.Save_To_File(FileName: String; UTF8_Format: Boolean = True): Boolean;

Parameters

  • FileName: String; the full path to the output file.
  • UTF8_Format: Boolean; if True, saves as UTF-8. If False, saves as ANSI.

Return Value

Returns True if the file was saved successfully.
Returns False on failure.

Files_List

Scans files by path and mask, and loads matching file names into the list.

Function ThStringList.Files_List(SearchPath, SearchMask: String; CONST IncFileExt, IncPath, ScanSubFolders: Boolean;
                    CONST StopAfterFirstFile: Boolean = False; MinFileSizeInBytes: Int64 = 0; CONST MinFileDT_UTC: TDateTime = 0): Boolean;

Parameters

  • SearchPath: String; the base folder path to scan.
  • SearchMask: String; file mask (for example *.txt).
  • IncFileExt: Boolean; includes file extension in returned names.
  • IncPath: Boolean; includes relative/full path in each item.
  • ScanSubFolders: Boolean; scans subfolders recursively.
  • StopAfterFirstFile: Boolean; stops after first match when True.
  • MinFileSizeInBytes: Int64; minimum file size filter.
  • MinFileDT_UTC: TDateTime; minimum last-write UTC filter.

Return Value

Returns True if scan completed and at least one file matched.
Returns False otherwise.

Folders_List

Scans folders and loads matching folder names into the list.
Function ThStringList.Folders_List(SearchPath: String; How_Many_Levels: Word; CONST IncPath: Boolean; CONST StopAfterFirstFolder: Boolean = False): Boolean;

Parameters

  • SearchPath: String; the base folder path to scan.
  • How_Many_Levels: Word; recursion depth (0 = current level only).
  • IncPath: Boolean; includes relative/full path in each item.
  • StopAfterFirstFolder: Boolean; stops after first match when True.

Return Value

Returns True if scan completed and at least one folder matched.
Returns False otherwise.

SYE_Sound_String_Match unit

SM_Convert_To_Words

Converts the input text into a sound string match array, splitting by words and applying normalization for search or match operations.
This function supports both search strings and source texts.
function SM_Convert_To_Words(const Text: String; This_IS_Find_String: Boolean): TSound_String_Match_Array;

Parameters

  • Text: String; The input text to convert and normalize.
  • This_IS_Find_String: Boolean; Indicates if the input text is a search string (True) or a text block to match (False).

Return Value

Returns a TSound_String_Match_Array containing the normalized words for sound-based comparison.

SM_Test_By_Words

Tests if the find array of normalized words appears within the provided text block, using sound-based comparison logic.
function SM_Test_By_Words(Find: TSound_String_Match_Array; const FindText, InTextBlock: String): Boolean;

Parameters

  • Find: TSound_String_Match_Array; The precomputed array of words for sound matching.
  • FindText: String; The original search text.
  • InTextBlock: String; The text block in which to search for matches.

Return Value

Returns True if a sound-based match is found.
Returns False otherwise.

Single_Test_By_Words

Performs a sound-based word comparison to determine if the search text appears in the text block.
function Single_Test_By_Words(const FindText, InTextBlock: String): Boolean;

Parameters

  • FindText: String; The search text to test.
  • InTextBlock: String; The text block to test against.

Return Value

Returns True if a sound-based match is found.
Returns False otherwise.

SM_Convert_To_Sounds

Converts the input text into a sound string match array, normalizing each word to its sound representation.
Supports both search strings and source text blocks for sound-based comparisons.
function SM_Convert_To_Sounds(const Text: String; This_IS_Find_String: Boolean): TSound_String_Match_Array;

Parameters

  • Text: String; The input text to convert into sound representations.
  • This_IS_Find_String: Boolean; Indicates if the input text is a search string (True) or a text block (False).

Return Value

Returns a TSound_String_Match_Array of sound-normalized elements.

SM_Test_By_Sounds

Tests if the sound-normalized array of the search text appears within the sound-normalized representation of the text block.
function SM_Test_By_Sounds(Find: TSound_String_Match_Array; const FindText, InTextBlock: String): Boolean;

Parameters

  • Find: TSound_String_Match_Array; The precomputed sound-normalized array.
  • FindText: String; The search text to use for sound-based matching.
  • InTextBlock: String; The text block to search in.

Return Value

Returns True if a sound-based match is found.
Returns False otherwise.

Single_Test_By_Sounds

Performs a single sound-based comparison to determine if the search text matches content in the text block.
function Single_Test_By_Sounds(const FindText, InTextBlock: String): Boolean;

Parameters

  • FindText: String; The search text for sound comparison.
  • InTextBlock: String; The text block to test against.

Return Value

Returns True if a sound-based match is found.
Returns False otherwise.

SM_Convert_To_String

Converts a sound string match array into a single string representation for storage or comparison.
function SM_Convert_To_String(const SMA: TSound_String_Match_Array): String;

Parameters

  • SMA: TSound_String_Match_Array; The sound string match array to convert.

Return Value

Returns a string representation of the input sound match array.