String Handling Subroutine (hApi unit)

Format_Float

The

Format_Float

function formats a floating-point number (AValue) into a string based on a specified FormatMask.
It supports two types of formatting: Delphi-native and a custom format unique to this implementation.

function Format_Float(const AValue: Double; const FormatMask: string): string;

Parameters

AValue: Double; The floating-point value to format.
FormatMask: 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).

Return Value

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

SaveInt

The

SaveInt

function 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

The

Save_Real_Filter

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

Return Value

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

Save_Date_Filter

The

Save_Date_Filter

function 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

The

Save_Time_Filter

function 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

The

Save_FixDT_Filter

function 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): Extended;

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

The

Save_Month_Filter

function 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

The

Save_Week_Filter

function 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

The

Web_Timezone_Offset_To_Delphi

function 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

The

Digits_Filter

function 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

The

Name_Filter

function 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

The

AlphaNum_Filter

function 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

The

Day_Of_Week

function 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

The

_Date_To_Str

function 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

The

_YYYY_MM_DD_To_Str

function 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

The

_Date_To_Week_Str

function 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

The

_Hour_To_Str

function 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

The

Format_FixDT_To_Str

function 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

The

_Hour_Num

function 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

The

Calc_Next_Round_Hour

function 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

The

_Money_To_Str

function 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

The

_Real_To_Str

function 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; PnL_Colors: Boolean = False): 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.

Return Value

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

_Int_To_Str

The

_Int_To_Str

function 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

The

B2S

function 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

The

_B2S

function 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

The

_Date_To_Month_Str

function 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

The

_Same_Str

function 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

The

_Starting_With_Str

function 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

The

WPos_Backward

function 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

The

WPos

function 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

The

_Cont_Str

function 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

The

_Cont_Word

function 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

The

_Cont_ALL_Group_Items

function 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

The

_Cont_ANY_Group_Item

function 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

The

Remove_Group_Item

function 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

The

Parameter_Extract

function 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

The

_Identify_Char_Lang

function 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

The

_Validate_Lang

function 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

The

_Does_Contain_Lang

function 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

The

Verify_Acceptable_Input_Lang

function 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

The

Get_Acceptable_Input_Lang_String

function 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

The

Copy_Upto_Char

function 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

The

Search_And_Replace

function 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

The

Search_And_Replace2

function 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

The

_Keep_The_Longest_String

procedure 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

The

Phone_Num_Mask

function 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

The

ReFormat_PlainText

function 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

The

Clean_System_Chars_From_Text

function 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

The

Trim_Below

function 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

The

Wide_Copy_String_To_Array

procedure 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

The

Wide_Copy_Array_To_String

function 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

The

Reverse_Chars_Order

function 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

The

Convert_Inet_CharSet_To_Windows_CodePage

function 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

The

Convert_Ansi_To_Wide

function 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

The

Convert_Wide_To_Ansi

function 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

The

Format_File_Name

function 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(Source: String): String;

Parameters

Source: String; the raw input text representing a component name.

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.

Wide_First_Letter_Uppercase

The

Wide_First_Letter_Uppercase

function converts the first letter of each word in a wide string to uppercase.

function Wide_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

The

Get_String_Index

function 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

The

Copy_Without_Counting_Tags

function 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

The

Copy_Without_Attribute_Tags

function 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

The

Remove_Tags

procedure 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

The

Byte_To_Hex

function 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

The

Longword_To_Hex

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

ThNumeric_To_Hex

Converts a ThNumeric value into its hexadecimal byte representation.
Used for serialization, hashing, or low-level storage of numeric values.

Function ThNumeric_To_Hex(CONST Input: ThNumeric): RawByteString;

Parameters

Input: ThNumeric; the numeric value to be encoded as a hex byte string.

Return Value

Returns a RawByteString that holds the binary contents of the ThNumeric structure.

Hex_To_ThNumeric

Decodes a RawByteString that contains a hexadecimal representation of a ThNumeric value.

Function Hex_To_ThNumeric(CONST Input: RawByteString): ThNumeric;

Parameters

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

Return Value

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

Generate_Password

The

Generate_Password

function 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

The

Copy_End_Of_String

function 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

The

_Valid_IP_Addr_Str

function 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

The

Push_Line

procedure 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

The

Push_Line_Array

procedure 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

The

Copy_String_To_Clipboard

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

_Same_Phone_Number

The

_Same_Phone_Number

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

Properties:

Count

Returns the number of items currently stored in the list.

Property 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 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 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 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 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 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 OnChange: TNotifyEvent;

Return Value

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

Public Procedures and Functions:

Clear

Removes all items from the list, resetting it to an empty state.

Procedure Clear;

Empty

Checks whether the list contains any items.

Function 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 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 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 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 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 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 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 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 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 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 Delete_Empty_Lines;

Search_And_Replace

Performs a search and replace operation on a specific item by index.

Function 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 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 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 Load_From_HMemoryStream(Source: TObject; Decode_UTF8_Anyway: Boolean = False): Boolean;

Parameters

Source: TObject; a memory stream object containing text.
Decode_UTF8_Anyway: Boolean; force UTF-8 decoding (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 Load_From_File(FileName: String; Decode_UTF8_Anyway: Boolean = False): Boolean;

Parameters

FileName: String; full path to the file to load.
Decode_UTF8_Anyway: Boolean; force UTF-8 decoding (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 Load_From_Delphi_Stream(Source: TStream; Count: Integer; Decode_UTF8_Anyway: Boolean = False): Boolean;

Parameters

Source: TStream; the stream to load from.
Count: Integer; number of bytes to read from the stream.
Decode_UTF8_Anyway: Boolean; force UTF-8 decoding (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 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 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 Trim_Every_Item_Below_33;

Any_Item_Checked

Checks whether any list item is marked as checked.

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

String Utilities (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.