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.

Examples

// Delphi-native format (uses # and 0 placeholders)
Format_Float('#,##0.00', 1234.5678)    // returns '1,234.57'

// Custom format (8,.4z2 means 8 digits integer, thousands separators, 4 decimals, min 2 decimals)
Format_Float('8,.4z2', 1234.5)         // returns '    1,234.50'

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`.

Example

// Extracts digits and ignores non-numeric characters
SaveInt('12abc34')   // returns 1234

// Truncates fractional part if present
SaveInt('45.67')     // returns 45

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.

Example

// Ignores trailing non-numeric characters
StrtoInt_FreeTextBox('  42abc')    // returns 42

// Returns 0 for invalid input
StrtoInt_FreeTextBox('abc')        // returns 0

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`.

Example

// Filters and converts to a floating point value
Save_Real_Filter(' 1,234.56 ')   // returns 1234.56

// Removes invalid characters
Save_Real_Filter('abc 7.89 def')  // returns 7.89

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`.

Example

// Accepts multiple date formats
Save_Date_Filter('2025-03-12')    // returns non-zero date value

// Uses current year when year is missing
Save_Date_Filter('03/12')         // returns date for March 12 of current year

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.

Example

// Standard time parsing with optional flag
Save_Time_Filter('10:30', False)   // returns non-zero time value

// Invalid input yields 0
Save_Time_Filter('notatime', True) // returns 0

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.

Example

// Parses date+time strings
Save_FixDT_Filter('2025-03-12 10:30')  // returns non-zero datetime value

// Supports ISO-like 'T' separator
Save_FixDT_Filter('2025-03-12T10:30')  // returns non-zero datetime value

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.

Example

// Parses month name and year
Save_Month_Filter('Mar 2025')   // returns a non-zero date value for March 1, 2025

// Defaults to current year when year is missing
Save_Month_Filter('3')          // returns a non-zero date value for March 1 of current year

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.

Example

// ISO week number with year
Save_Week_Filter('12/2025')  // returns non-zero date value for week 12 of 2025

// Defaults to current year when year is missing
Save_Week_Filter('12')       // returns non-zero date value for week 12 of current year

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`.

Example

// Converts '+02:00' into a TDateTime offset (approx. 0.0833)
Web_Timezone_Offset_To_Delphi('+02:00')  // returns ~0.0833

// Handles compact formats too
Web_Timezone_Offset_To_Delphi('-0800')   // returns ~-0.3333

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`.

Example

Digits_Filter('Phone: 123-456')        // returns '123456'
Digits_Filter('A1-B2', '-')            // returns 'A1-B2' (hyphen allowed)

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.

Example

Name_Filter('John123 Doe!')   // returns 'John Doe'

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`.

Example

AlphaNum_Filter('A!@#1', '')    // returns 'A1'

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.

Example

// Sunday = 1, Monday = 2, etc.
Day_Of_Week(EncodeDate(2025, 3, 16))   // returns 1 (Sunday)

_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.

Example

_Date_To_Str(EncodeDate(2025, 3, 12))            // returns '03/12/2025' (or locale equivalent)
_Date_To_Str(EncodeDate(2025, 3, 12), True)      // returns '2025-03-12'

_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.

Example

_YYYY_MM_DD_To_Str(EncodeDate(2025, 3, 12))      // returns '2025-03-12T00:00:00'
_YYYY_MM_DD_To_Str(Now, True)                    // includes milliseconds when requested

_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.

Example

_Date_To_Week_Str(EncodeDate(2025, 3, 12))   // returns '11/2025' (ISO week format)

_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.

Example

_Hour_To_Str(EncodeTime(10, 30, 0, 0))   // returns '10:30'

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.

Example

// Default formatting
Format_FixDT_To_Str('', Now)          // returns current date/time in local format

// Includes seconds and milliseconds
Format_FixDT_To_Str('+SZ', Now)       // returns e.g. '03/12/2026 10:30:00.123'

_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.

Example

_Hour_Num(EncodeTime(10, 30, 0, 0))   // returns 10

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.

Example

// Round up to the next hour
Calc_Next_Round_Hour(Now)       // returns the next hour (e.g., if now is 10:30, returns 11:00)

// Add 15 minutes after rounding
Calc_Next_Round_Hour(Now, 15)   // returns next hour plus 15 minutes

_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.

Example

_Money_To_Str(1234.56)         // returns '1,234.56'
_Money_To_Str(-12.34, True)    // returns red-formatted '-12.34' (if color coding is supported)

_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.

Example

_Real_To_Str(1234.5678)         // returns similar to '1,234.56780000'
_Real_To_Str(-1.23, True)        // returns '-1.23000000' (negative = red color, positive = green color)

_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.

Example

_Int_To_Str(1234)      // returns '1,234'
_Int_To_Str(-5, True)  // returns '-5' (negative = red color, positive = green color)

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`.

Example

B2S(True)   // returns 'True'
B2S(False)  // returns '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`.

Example

_B2S(True)   // returns 'Yes'
_B2S(False)  // returns 'No'

_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'`.

Example

_Date_To_Month_Str(EncodeDate(2025, 3, 12), he_English)   // returns 'March 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.

Example

_Same_Str('abc', 'abc')     // returns True
_Same_Str('abc', 'def')     // returns False

_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.

Example

_Starting_With_Str('ab', 'abc')   // returns True
_Starting_With_Str('bc', 'abc')   // returns False

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.

Example

WPos_Backward('a', 'abcabc', 6, 1)  // returns 4 (last 'a')

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.

Example

WPos('bc', 'abc')   // returns 2

// With range
WPos('b', 'abc', 2, 3)   // returns 2

_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.

Example

_Cont_Str('bc', 'abc')     // returns True
_Cont_Str('x', 'abc')      // returns False

_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.

Example

_Cont_Word('foo', 'foo bar')    // returns True
_Cont_Word('foo', 'foobar')     // returns False (word boundary required)

_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.

Example

_Cont_ALL_Group_Items('a'#13#10'b', 'a'#13#10'b'#13#10'c')  // returns True
_Cont_ALL_Group_Items('a'#13#10'd', 'a'#13#10'b')          // returns False

_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.

Example

_Cont_ANY_Group_Item('x'#13#10'y', 'a'#13#10'y'#13#10'z')  // returns True
_Cont_ANY_Group_Item('x', 'a'#13#10'b')                   // returns False

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.

Example

var s: String;
Remove_Group_Item('b', 'a'#13#10'b'#13#10'c');   // returns True and list becomes 'a#13#10c'

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.

Example

var v: String;
Parameter_Extract('id', 'id=123&name=abc', v);  // returns True and v = '123'

_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.

Example

_Identify_Char_Lang('א')   // returns the 'he_Hebrew' language constant
_Identify_Char_Lang('A')   // returns the 'he_English' language constant

_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.

Example

_Validate_Lang('א', he_Hebrew)      // returns True
_Validate_Lang('A', he_Hebrew)      // returns False

_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.

Example

_Does_Contain_Lang('שלום', he_Hebrew)   // returns True
_Does_Contain_Lang('Hello', he_Hebrew)  // returns False

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.

Example

Verify_Acceptable_Input_Lang('abc', [he_Latin])   // returns True
Verify_Acceptable_Input_Lang('אבג', [he_Latin])   // returns False

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.

Example

Get_Acceptable_Input_Lang_String()   // returns language list as string

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.

Example

Copy_Upto_Char('abc;def', 1, ';')   // returns 'abc'

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.

Example

var s: String;
s := 'hello';
Search_And_Replace('l', 'L', s);   // returns True, s becomes 'heLLo'

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.

Example

Search_And_Replace2('l', 'L', 'hello')   // returns 'heLLo'

_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.

Example

var t: String;
t := 'short';
_Keep_The_Longest_String('longer', t);   // t becomes '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.

Example

Phone_Num_Mask('1234567890', 1)   // returns '(123) 456-7890' (example format)

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.

Example

ReFormat_PlainText('This is a long line that should wrap.', 10, True)

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.

Example

Clean_System_Chars_From_Text('Line1'#13#10'Line2', True)   // preserves CRLF
Clean_System_Chars_From_Text('Line1'#13#10'Line2', False)  // removes CRLF

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.

Example

Trim_Below('  abc  ', 33, 3)   // returns 'abc'
Trim_Below(#10'abc'#10, 33, 1) // trims left only

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.

Example

var arr: array[0..9] of WideChar;
Wide_Copy_String_To_Array(arr, 'Hello');

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.

Example

var arr: array[0..4] of WideChar = ('H','e','l','l','o');
Wide_Copy_Array_To_String(arr)   // returns 'Hello'

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.

Example

DOS_Reverse_Chars_Order(65, 90, 'ABC')   // returns 'CBA'

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.

Example

DOS_Field_Spacer('hi', 5, False)   // returns 'hi   '
DOS_Field_Spacer('hi', 5, True)    // returns '   hi'

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.

Example

Reverse_Chars_Order(97, 122, 'abcxyz')   // returns 'zyxcba'

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.

Example

Convert_Inet_CharSet_To_Windows_CodePage('utf-8')       // returns 65001
Convert_Inet_CharSet_To_Windows_CodePage('unknown')     // returns 0

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.

Example

Convert_Ansi_To_Wide('hello', CP_UTF8)   // returns 'hello'

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.

Example

Convert_Wide_To_Ansi('hello', CP_UTF8)   // returns 'hello'

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.

Example

Convert_Inet_To_Wide('hello', 'utf-8')   // returns 'hello'

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.

Example

Convert_Wide_To_Inet('hello', 'utf-8')   // returns 'hello' (UTF-8 bytes)

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.

Example

Format_File_Name('my*file?.txt')   // returns 'myfile.txt'

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.

Example

Format_Component_Name('My Component!')   // returns 'my_component' (example)

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.

Example

Format_Phone_Number_For_Dialer('+1', '1234567890', True)  // returns '+1 123 456 7890' (example)

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.

Example

First_Letter_Uppercase('hello world')   // returns 'Hello World'

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.

Example

Get_String_Index('b', 'a'#13#10'b'#13#10'c')   // returns 2

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.

Example

Copy_Without_Counting_Tags('hello', 1, 5)   // returns 'hello'

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.

Example

Copy_Without_Attribute_Tags('link')   // returns 'link'

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.

Example

var s: String;
Remove_Tags(s, 'b', True);  // removes  tags and any text between them in s

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.

Example

Byte_To_Hex($AF)   // returns 'AF'

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.

Example

Longword_To_Hex($1234)   // returns '1234'

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.

Example

Double_To_Hex(1.0)   // returns a hex string representing the double value

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.

Example

Hex_To_Double(Double_To_Hex(1.0))   // returns 1.0

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.

Example

IS_Password_Strong_Enought('P@ssw0rd', True)   // returns True (strong)
IS_Password_Strong_Enought('123', True)        // returns False (too weak)

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.

Example

Generate_Password(8)   // returns an 8-character random password

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.

Example

Generate_Token_String(16)   // returns a 16-byte token string

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.

Example

Copy_End_Of_String('HelloWorld', 5)   // returns 'World'

_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.

Example

_Valid_IP_Addr_Str('192.168.1.1')   // returns True
_Valid_IP_Addr_Str('999.999.999.999') // returns False

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.

Example

var s: String;
s := 'first';
Push_Line('second', s);   // s becomes 'first'#13#10'second'

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.

Example

var s: String;
s := 'apple';
Push_String('banana', ',', s);   // s becomes 'apple,banana'

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.

Example

var arr: ThFlds_Name_Array;
Push_Line_Array('line1', arr);   // appends 'line1' to the array

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.

Example

Copy_String_To_Clipboard('Hello world')  // returns True if clipboard write succeeds

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.

Example

Log_Filename()   // returns something like 'C:\MyApp\MyApp_Log.txt'

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).

Example

Write_Log_File('Test message')   // returns True when write succeeds

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.

Example

Translate('Hello')   // returns localized 'Hello' based on installed translations

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.

Example

TC('Hello', he_English)   // returns translated string for English

_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.

Example

_Same_Phone_Number('1234567', '(123) 456-7')   // returns True
_Same_Phone_Number('123', '321')               // returns False

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('One');
    L.Add('Two');
    // Count is 2
    ShowMessage(IntToStr(L.Count));
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('First');
    L.Strings[0] := 'Updated';
    // L.Strings[0] now contains 'Updated'
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('Option');
    L.Checked[0] := True; // mark first item as checked
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('Item', 42);
    // Data_Int[0] is 42
    ShowMessage(IntToStr(L.Data_Int[0]));
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Text := 'Line1'#13#10'Line2';
    // L.Count is 2 (this is a SET example)
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('A', 0, True);
    L.Add('B', 0, False);
    // Checked_Items_Text contains only checked items (here: 'A')
  finally
    L.Free;
  end;
end;

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.

Example

procedure TForm1.ListChanged(Sender: TObject);
begin
  ShowMessage('List changed');
end;

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.OnChange := ListChanged;
    L.Add('Test'); // triggers OnChange
  finally
    L.Free;
  end;
end;

Clear

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

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('One');
    L.Clear; // removes all items
  finally
    L.Free;
  end;
end;

Empty

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

Return Value

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

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    ShowMessage(BoolToStr(L.Empty, True)); // True
    L.Add('x');
    ShowMessage(BoolToStr(L.Empty, True)); // False
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Idx: Integer;
begin
  L := ThStringList.Create;
  try
    L.Add('Alpha');
    Idx := L.IndexOf('Alpha'); // returns 0
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Idx: Integer;
begin
  L := ThStringList.Create;
  try
    L.Add('A', 100);
    Idx := L.IndexOfData(100); // returns 0
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Idx: Integer;
begin
  L := ThStringList.Create;
  try
    L.Add('Item', 123);
    Idx := L.IndexOfBoth(123, 'Item'); // returns 0
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Idx: Integer;
begin
  L := ThStringList.Create;
  try
    L.Add('Start');
    L.Add('Stop');
    Idx := L.Starting_With_Str('St'); // returns 0
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Idx: Integer;
begin
  L := ThStringList.Create;
  try
    L.Add('One');
    L.Add('Two');
    Idx := L.SearchText('Two', 0, -1); // returns 1
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('A');
    L.Insert(0, 'B'); // list is now ['B', 'A']
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Idx: Integer;
begin
  L := ThStringList.Create;
  try
    Idx := L.Add('Hello', 123, True);
    // Idx is 0
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('A');
    L.Add('B');
    L.Delete(0); // removes 'A'
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('A');
    L.Add('B');
    L.Add('C');
    L.Delete_Range(0, 1); // removes 'A' and 'B'
  finally
    L.Free;
  end;
end;

Delete_Empty_Lines

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

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('');
    L.Add('Data');
    L.Delete_Empty_Lines; // removes empty items
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Replaced: Boolean;
begin
  L := ThStringList.Create;
  try
    L.Add('Hello World');
    Replaced := L.Search_And_Replace('World', 'Friend', 0); // returns True
  finally
    L.Free;
  end;
end;

Assign

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

Parameters

  • Source: ThStringList; the source list to copy.

Example

var
  L1, L2: ThStringList;
begin
  L1 := ThStringList.Create;
  L2 := ThStringList.Create;
  try
    L1.Add('A');
    L2.Assign(L1);
    // L2 now has 'A'
  finally
    L1.Free;
    L2.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('B', 2);
    L.Add('A', 1);
    L.Sort(1, 1); // sorts by string ascending, then data ascending
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Stream: TMemoryStream;
begin
  L := ThStringList.Create;
  Stream := TMemoryStream.Create;
  try
    Stream.LoadFromFile('C:\temp\list.txt');
    Stream.Position := 0;
    L.Load_From_HMemoryStream(Stream, True);
  finally
    Stream.Free;
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    if L.Load_From_File('C:\temp\list.txt') then
      ShowMessage('Loaded ' + IntToStr(L.Count) + ' items');
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
  Stream: TFileStream;
begin
  L := ThStringList.Create;
  Stream := TFileStream.Create('C:\temp\list.txt', fmOpenRead);
  try
    L.Load_From_Delphi_Stream(Stream, Stream.Size, True);
  finally
    Stream.Free;
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Load_List_From_String('One,Two,Three', ',');
    // L.Count is 3
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    if L.Merge_String_Lists('A;B;C') then
      ShowMessage('Merged ' + IntToStr(L.Count) + ' items');
  finally
    L.Free;
  end;
end;

Trim_Every_Item_Below_33

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

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('Hello'#9'World');
    L.Trim_Every_Item_Below_33;
    // After trimming, the item no longer contains the tab character
    ShowMessage(L[0]);
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('Item 1');
    L.Add('Item 2');
    L.Checked[1] := True; // mark second item as checked

    if L.Any_Item_Checked then
      ShowMessage('At least one item is checked');
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    L.Add('First');
    L.Add('Second');

    if L.Save_To_File('C:\Temp\list.txt', True) then
      ShowMessage('Saved list to file');
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    if L.Files_List('C:\Temp', '*.txt', True, True, False) then
      ShowMessage('Found ' + IntToStr(L.Count) + ' text files');
  finally
    L.Free;
  end;
end;

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.

Example

var
  L: ThStringList;
begin
  L := ThStringList.Create;
  try
    if L.Folders_List('C:\Temp', 1, True) then
      ShowMessage('Found ' + IntToStr(L.Count) + ' folders');
  finally
    L.Free;
  end;
end;

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.

Example

var
  FindWords: TSound_String_Match_Array;
begin
  FindWords := SM_Convert_To_Words('lazy dog', True);
  if SM_Test_By_Words(FindWords, 'lazy dog', 'The quick brown fox jumps over the lazy dog') then
    ShowMessage('Word match found');
end;

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.

Example

begin
  if Single_Test_By_Words('lazy dog', 'The quick brown fox jumps over the lazy dog') then
    ShowMessage('Word match found');
end;

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.

Example

var
  Sounds: TSound_String_Match_Array;
begin
  Sounds := SM_Convert_To_Sounds('hello world', True);
  // 'Sounds' now contains sound-normalized elements
  ShowMessage('Converted ' + IntToStr(Length(Sounds)) + ' sound elements');
end;

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.

Example

var
  Sounds: TSound_String_Match_Array;
begin
  Sounds := SM_Convert_To_Sounds('hello world', True);
  if SM_Test_By_Sounds(Sounds, 'hello world', 'Hello World!') then
    ShowMessage('Sound match found');
end;

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.

Example

begin
  if Single_Test_By_Sounds('hello world', 'Hello World!') then
    ShowMessage('Single sound match found');
end;

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.

Example

var
  SMA: TSound_String_Match_Array;
  S: String;
begin
  SMA := SM_Convert_To_Words('example text', True);
  S := SM_Convert_To_String(SMA);
  ShowMessage('Converted sound match array: ' + S);
end;




© 2026 All rights reserved to SYE software industries LTD.     This website is under development, There may be errors and missing content.