Math, Date/Time & utils   (hApi unit)

RoundNum

Rounds a numeric value to a specified number of digits.
function RoundNum(CONST Amount: ThNumeric; CONST Digits: Byte = 2): ThNumeric;

Parameters

  • Amount: ThNumeric; The value to round.
  • Digits: Byte; Number of fractional digits to keep (default is `2`).

Return Value

Returns the rounded numeric value.

_Same_Frac

Compares two numeric values and determines if they are equal within a specified number of decimal places.
function _Same_Frac(CONST Amount1, Amount2: ThNumeric; CONST Compare_Digits: Byte = 7): Boolean;

Parameters

  • Amount1: ThNumeric; The first numeric value to compare.
  • Amount2: ThNumeric; The second numeric value to compare.
  • Compare_Digits: Byte; The number of decimal places to consider in the comparison (default is 7).

Return Value

Returns `True` if the values are equal within the specified decimal precision.
Returns `False` otherwise.

_Same_Money

Compares two monetary values with a precision of two decimal places.
function _Same_Money(CONST Amount1, Amount2: ThNumeric): Boolean;

Parameters

  • Amount1: ThNumeric; The first monetary value to compare.
  • Amount2: ThNumeric; The second monetary value to compare.

Return Value

Returns `True` if the values are equal within two decimal places.
Returns `False` otherwise.

_Same_Month

Determines whether two TDateTime values fall within the same month and year.
This function requires decoding the date components, making it computationally intensive.
function _Same_Month(CONST DateTime1, DateTime2: TDateTime): Boolean;

Parameters

  • DateTime1: TDateTime; The first date to compare.
  • DateTime2: TDateTime; The second date to compare.

Return Value

Returns `True` if the dates share the same month and year.
Returns `False` otherwise.

_Same_Second

Determines if two TDateTime values fall within the same second.
This function decodes the time components, making it computationally intensive.
function _Same_Second(CONST DateTime1, DateTime2: TDateTime): Boolean;

Parameters

  • DateTime1: TDateTime; The first date-time value to compare.
  • DateTime2: TDateTime; The second date-time value to compare.

Return Value

Returns `True` if the time values share the same hour, minute, and second.
Returns `False` otherwise.

Bits_To_Byte

Constructs a byte value from eight individual bit values.
function Bits_To_Byte(CONST B7,B6,B5,B4,B3,B2,B1,B0: Byte): Byte;

Parameters

  • B7-B0: Byte; Each parameter represents a single bit, where `1` sets the corresponding bit in the result.

Return Value

Returns a `Byte` with the specified bits set accordingly.

IN_Range

Checks if a floating-point value falls within a specified range.
It allows for flexible range comparisons where the minimum and maximum values can be in any order.
function IN_Range(CONST Value, Minimum, Maximum: Double): Boolean;

Parameters

  • Value: Double; The value to check.
  • Minimum: Double; The lower bound of the range.
  • Maximum: Double; The upper bound of the range.

Return Value

Returns `True` if `Value` is between `Minimum` and `Maximum`, regardless of their order.
Returns `False` otherwise.

IN_Range2

Checks if an integer value falls strictly within a specified range.
It performs a fast and direct comparison without handling reversed bounds.
function IN_Range2(CONST Value, Minimum, Maximum: Integer): Boolean;

Parameters

  • Value: Integer; The value to check.
  • Minimum: Integer; The lower bound of the range.
  • Maximum: Integer; The upper bound of the range.

Return Value

Returns `True` if `Value` is strictly within `Minimum` and `Maximum`.
Returns `False` otherwise.

IN_Range64

Checks if a 64-bit integer falls within a specified range.
It performs a fast and strict comparison to verify if the value is within bounds.
function IN_Range64(CONST Value, Minimum, Maximum: Int64): Boolean;

Parameters

  • Value: Int64; The value to check.
  • Minimum: Int64; The lower bound of the range.
  • Maximum: Int64; The upper bound of the range.

Return Value

Returns `True` if `Value` is strictly within `Minimum` and `Maximum`.
Returns `False` otherwise.

IN_Rect

Determines whether a point `(X, Y)` falls within a given rectangle.
function IN_Rect(CONST X, Y: Integer; Rect: TRect): Boolean;

Parameters

  • X: Integer; The X-coordinate of the point.
  • Y: Integer; The Y-coordinate of the point.
  • Rect: TRect; The rectangle to check against.

Return Value

Returns `True` if the point `(X, Y)` lies within `Rect`.
Returns `False` otherwise.

IN_DateTime_Range

Checks whether a given TDateTime value falls within a specified date-time range.
Both the `Minimum` and `Maximum` values must be greater than `0` for a valid range comparison.
function IN_DateTime_Range(CONST Value, Minimum{> 0}, Maximum{> 0}: Double): Boolean;

Parameters

  • Value: Double; The date-time value to check.
  • Minimum: Double; The lower bound of the date-time range. Must be greater than `0`.
  • Maximum: Double; The upper bound of the date-time range. Must be greater than `0`.

Return Value

Returns `True` if `Value` falls within the specified range.
Handles cases where either `Minimum` or `Maximum` is `0` to provide flexible range checking.
Returns `True` when both `Minimum` and `Maximum` are `0`.

IN_Hours_Range

Checks if a given TDateTime value falls within a specified range of hours.
All values must be incremented by 1 to indicate that they are filled-in flags.
function IN_Hours_Range(CONST Value, Minimum, Maximum: TDateTime): Boolean;

Parameters

  • Value: TDateTime; The time value to check.
  • Minimum: TDateTime; The lower bound of the hour range.
  • Maximum: TDateTime; The upper bound of the hour range.

Return Value

Returns `True` if `Value` is within the specified hour range.
Returns `False` otherwise.

Keep_Range (Int64)

Ensures that an Int64 value remains within a specified range.
If the value is below the minimum, it is set to the minimum.
If the value exceeds the maximum, it is set to the maximum.
procedure Keep_Range(VAR Value: Int64; CONST Minimum, Maximum: Int64);

Parameters

  • Value: Int64; The variable whose range is to be limited.
  • Minimum: Int64; The lower bound of the allowed range.
  • Maximum: Int64; The upper bound of the allowed range.

Return Value

This procedure does not return a value. It modifies `Value` in place.

Keep_Range (Integer)

Ensures that an integer value remains within a specified range.
If the value is below the minimum, it is set to the minimum.
If the value exceeds the maximum, it is set to the maximum.
procedure Keep_Range(VAR Value: Integer; CONST Minimum, Maximum: Integer);

Parameters

  • Value: Integer; The variable whose range is to be limited.
  • Minimum: Integer; The lower bound of the allowed range.
  • Maximum: Integer; The upper bound of the allowed range.

Return Value

This procedure does not return a value. It modifies `Value` in place.

Keep_Range (Double)

Ensures that a floating-point value remains within a specified range.
procedure Keep_Range(VAR Value: Double; CONST Minimum, Maximum: Double);

Parameters

  • Value: Double; The variable whose range is to be limited.
  • Minimum: Double; The lower bound of the allowed range.
  • Maximum: Double; The upper bound of the allowed range.

Return Value

This procedure does not return a value. It modifies `Value` in place.

Keep_Range
(Word)

Ensures that a `Word` value remains within a specified range.
procedure Keep_Range(VAR Value: Word; CONST Minimum, Maximum: Word);

Parameters

  • Value: Word; The variable whose range is to be limited.
  • Minimum: Word; The lower bound of the allowed range.
  • Maximum: Word; The upper bound of the allowed range.

Return Value

This procedure does not return a value. It modifies `Value` in place.

LowestValue

Finds the smallest value in an array of floating-point numbers.
function LowestValue(CONST Sources: Array OF Double): Double;

Parameters

  • Sources: Array of Double; The array of floating-point values.

Return Value

Returns the smallest value found in the array.
Returns `0` if the array is empty.

HighestValue

Finds the largest value in an array of floating-point numbers.
function HighestValue(CONST Sources: Array OF Double): Double;

Parameters

  • Sources: Array of Double; The array of floating-point values.

Return Value

Returns the largest value found in the array.
Returns `0` if the array is empty.

Safe_Div

Performs division while ensuring that division by zero does not occur.
function Safe_Div(CONST Numerator, Denominator: Double): Double;

Parameters

  • Numerator: Double; The dividend.
  • Denominator: Double; The divisor.

Return Value

Returns the quotient of `Numerator / Denominator`.
If `Denominator` is zero (or considered near zero within precision), the function returns `0`.

Periods_Conflict

Checks if two time periods overlap.
function Periods_Conflict(PA_Start, PA_End, PB_Start, PB_End: Double): Boolean;

Parameters

  • PA_Start: Double; Start time of the first period.
  • PA_End: Double; End time of the first period.
  • PB_Start: Double; Start time of the second period.
  • PB_End: Double; End time of the second period.

Return Value

Returns `True` if the two periods overlap.
Returns `False` otherwise.

Percent

Calculates the percentage of a position within a given range.
function Percent(CONST CurrPos, TotalScope: Double): Byte;

Parameters

  • CurrPos: Double; The current position value.
  • TotalScope: Double; The total range to calculate the percentage from.

Return Value

Returns a percentage value from 0 to 100.

StrPercent

Converts a percentage calculation into a formatted string representation.
function StrPercent(CONST CurrPos, TotalScope: Double): RawByteString;

Parameters

  • CurrPos: Double; The current position value.
  • TotalScope: Double; The total range to calculate the percentage from.

Return Value

Returns a string representation of the percentage with a `%` suffix.

Yield_Percent

Calculates the percentage yield of a test price relative to a base price.
function Yield_Percent(CONST Test_Price, Base_Price: Double): Double;

Parameters

  • Test_Price: Double; The test price to evaluate.
  • Base_Price: Double; The base price used as a reference.

Return Value

Returns the percentage yield difference between the test price and base price.

Get_Day_Name_String

Returns the name of a day based on its numerical representation.
function Get_Day_Name_String(Day: Byte; Lang: ThTranslation_Language): String;

Parameters

  • Day: Byte; The day number (1 for Sunday, 7 for Saturday).
  • Lang: ThTranslation_Language; The language to use for the day name.

Return Value

Returns the localized name of the day.

Get_Month_String

Returns the name of a month based on its numerical representation.
function Get_Month_String(Month: Byte; Lang: ThTranslation_Language): String;

Parameters

  • Month: Byte; The month number (1 for January, 12 for December).
  • Lang: ThTranslation_Language; The language to use for the month name.

Return Value

Returns the localized name of the month.

Get_Full_Date_String

Formats a date value into a string representation, including optional day name, month name, and year number.
It supports different date formats based on locale settings.
function Get_Full_Date_String(Day: Double; _Day_Name, _Month_Name, _Year_Number: Boolean; Lang: ThTranslation_Language): String;

Parameters

  • Day: Double; The date value to format.
  • _Day_Name: Boolean; If `True`, includes the name of the day.
  • _Month_Name: Boolean; If `True`, includes the name of the month.
  • _Year_Number: Boolean; If `True`, includes the year.
  • Lang: ThTranslation_Language; The language in which the date should be formatted.

Return Value

Returns a formatted string representation of the date, following locale-specific ordering of day, month, and year.
Returns an empty string if the date value is invalid.

Format_Web_GMT_Time

Formats a UTC timestamp into a web-compatible GMT time string.
function Format_Web_GMT_Time(UTC_Value: TDateTime): RawByteString;

Parameters

  • UTC_Value: TDateTime; The UTC timestamp to format.

Return Value

Returns a formatted GMT time string compatible with web headers.

EnDate

Encodes a year, month, and day into a Delphi date integer.
This is a shortcut wrapper around date encoding logic.
function EnDate(Year, Month, Day: Word): Integer;

Parameters

  • Year: Word; The year component.
  • Month: Word; The month component.
  • Day: Word; The day component.

Return Value

Returns the encoded date as an integer (`TDateTime` date part).

Calc_Date_Offset

Calculates a date offset based on a given offset type and a reference date.
It supports various offset types such as `Today`, `StartOfaYear`, `EndOfaYear`, `StartOfaMonth`, and `EndOfaMonth`.
Additionally, it can process dynamic offsets using `+` or `-` followed by a numeric value.
function Calc_Date_Offset(OffSetType: String; MyDate: Double): Integer;

Parameters

  • OffSetType: String; The type of offset to apply. Recognized values include:
    • `Today` - Returns the truncated current date with an optional offset.
    • `StartOfaYear` - Returns the start of the year of `MyDate`.
    • `EndOfaYear` - Returns the end of the year of `MyDate`.
    • `StartOfaMonth` - Returns the first day of the month of `MyDate`.
    • `EndOfaMonth` - Returns the last day of the month of `MyDate`.
    • `StartOfaWeek` - Returns the first day of the week of `MyDate`.
    • `EndOfaWeek` - Returns the last day of the week of `MyDate`.
    If the string contains `+` or `-` followed by a number, that value is added/subtracted from the calculated date.
  • MyDate: Double; The reference date to apply the offset on.

Return Value

Returns an integer representing the truncated date after applying the offset.
Returns `Trunc(MyDate)` if no recognized offset type is provided.

NOW_UTC

Returns the current UTC date and time.
function NOW_UTC: TDateTime;

Return Value

Returns the current UTC timestamp as a `TDateTime` value.

Calculate_Zodiac_Sign_Index

Determines the zodiac sign index based on a given date.
The result is an integer from `0` to `11`, representing zodiac signs from Capricorn to Sagittarius.
function Calculate_Zodiac_Sign_Index(_Date: TDateTime): Byte;

Parameters

  • _Date: TDateTime; The date for which the zodiac sign index is calculated.

Return Value

Returns a `Byte` value representing the zodiac sign index from `0` (Capricorn) to `11` (Sagittarius).

Calculate_Zodiac_Sign

Returns the English name of the zodiac sign based on a given date.
function Calculate_Zodiac_Sign(_Date: TDateTime): RawByteString;

Parameters

  • _Date: TDateTime; The date for which the zodiac sign is determined.

Return Value

Returns the English name of the zodiac sign, such as `"Capricorn"`, `"Aquarius"`, etc.

Calc_Circle_Point

Calculates the coordinates of a point on a circle given its center, radius, and degree angle.
function Calc_Circle_Point(XCenter, YCenter, Radius, Degree: Integer): TPoint;

Parameters

  • XCenter: Integer; The X-coordinate of the circle's center.
  • YCenter: Integer; The Y-coordinate of the circle's center.
  • Radius: Integer; The radius of the circle.
  • Degree: Integer; The angle in degrees (0 to 360) at which the point is calculated.

Return Value

Returns a `TPoint` representing the calculated coordinates on the circle's perimeter.

Check_Number_By_Luhn_Algo

Validates a numeric string using the Luhn algorithm.
It is commonly used for validating credit card numbers.
function Check_Number_By_Luhn_Algo(Text: RawByteString): Boolean;

Parameters

  • Text: RawByteString; The numeric string to be validated.

Return Value

Returns `True` if the number passes the Luhn validation check.
Returns `False` if the input is invalid or does not pass the check.

Center_Point

Calculates the center point of a given rectangle.
function Center_Point(Rect: TRect): TPoint;

Parameters

  • Rect: TRect; The rectangle from which to calculate the center point.

Return Value

Returns a `TPoint` representing the center of the rectangle.
If the calculated X or Y coordinate is negative, it is adjusted to `0`.

IS_Weekend

Checks whether a given date falls on a weekend.
function IS_Weekend(_Date: Double; TwoDaysFormat: Boolean = True): Boolean;

Parameters

  • _Date: Double; The date to check.
  • TwoDaysFormat: Boolean; If `True`, considers Friday and Saturday as the weekend.

Return Value

Returns `True` if the date is a weekend day according to the configured weekend settings.

Hours_Between

Calculates the number of hours between two date-time values.
function Hours_Between(_FromDateTime, _UntilDateTime: TDateTime): Double;

Parameters

  • _FromDateTime: TDateTime; The starting date-time value.
  • _UntilDateTime: TDateTime; The ending date-time value.

Return Value

Returns the absolute difference in hours between the two date-time values.

Days_Between

Calculates the number of days between two dates, with an option for a 360-day calendar year calculation.
function Days_Between(_FromDate, _UntilDate: TDateTime; CONST Base_360: Boolean): Integer;

Parameters

  • _FromDate: TDateTime; The starting date.
  • _UntilDate: TDateTime; The ending date.
  • Base_360: Boolean; If `True`, uses a 360-day year calculation.

Return Value

Returns the number of days between the two dates.

Month_Span

Calculates the number of months between two dates based on a 360-day year assumption.
function Month_Span(CONST _FromDateTime, _UntilDateTime: TDateTime): Double;

Parameters

  • _FromDateTime: TDateTime; The starting date.
  • _UntilDateTime: TDateTime; The ending date.

Return Value

Returns the calculated month span as a floating-point value, using a 360-day year convention.

Next_Monthly_Day

Determines the next occurrence of a specific day within a month, considering grace days for flexibility.
function Next_Monthly_Day(_FromDate: TDateTime; DayoftheMonth, GraceDays: Byte): Integer;

Parameters

  • _FromDate: TDateTime; The reference date.
  • DayoftheMonth: Byte; The desired day of the month.
  • GraceDays: Byte; The number of additional days to allow if the target date is unavailable.

Return Value

Returns the next available date as an integer (truncated `TDateTime`).

Gen_Unique_TimeSign

Generates a unique timestamp by combining the current time with an incrementing counter.
function Gen_Unique_TimeSign(CurrentDT: Double): Double;

Parameters

  • CurrentDT: Double; The current date-time value.

Return Value

Returns a unique timestamp as a double, ensuring distinct values even for calls within the same second.

Reset_String_Array

Clears all elements in a string array by setting them to empty strings.
procedure Reset_String_Array(VAR Dest: Array OF String);

Parameters

  • Dest: Array of String; The string array to reset.

Reset_Double_Array

Clears all elements in a double array by setting them to `0`.
procedure Reset_Double_Array(VAR Dest: Array OF Double);

Parameters

  • Dest: Array of Double; The double array to reset.

Reset_ThNumeric_Array

Resets all elements in a ThNumeric array to a specified value.
procedure Reset_ThNumeric_Array(VAR Dest: Array OF ThNumeric; Value: ThNumeric = 0);

Parameters

  • Dest: Array of ThNumeric; The array to reset.
  • Value: ThNumeric; The value to assign to all elements (default is `0`).

Reset_Integer_Array

Resets all elements in an integer array to a specified value (default is `0`).
procedure Reset_Integer_Array(VAR Dest: Array OF Integer; Value: Integer = 0);

Parameters

  • Dest: Array of Integer; The integer array to reset.
  • Value: Integer; The value to assign to all elements (default is `0`).

Reset_Int64_Array

Resets all elements in an Int64 array to a specified value.
procedure Reset_Int64_Array(VAR Dest: Array OF Int64; Value: Int64 = 0);

Parameters

  • Dest: Array of Int64; The Int64 array to reset.
  • Value: Int64; The value to assign to all elements (default is `0`).

Reset_Bool_Array

Clears all elements in a boolean array by setting them to `False`.
procedure Reset_Bool_Array(VAR Dest: Array OF Boolean);

Parameters

  • Dest: Array of Boolean; The boolean array to reset.

Reset_Byte_Array

Clears all elements in a byte array by setting them to `0`.
procedure Reset_Byte_Array(VAR Dest: Array OF Byte);

Parameters

  • Dest: Array of Byte; The byte array to reset.

Unix_To_DateTime

Converts a Unix timestamp (seconds since January 1, 1970) to a Delphi TDateTime value.
function Unix_To_DateTime(CONST AValue: Int64): TDateTime;

Parameters

  • AValue: Int64; The Unix timestamp to convert.

Return Value

Returns a `TDateTime` value representing the corresponding date and time.
If `AValue` is less than `1`, the function returns `0`.

DateTime_To_Unix

Converts a Delphi TDateTime value into a Unix timestamp (seconds since January 1, 1970).
function DateTime_To_Unix(CONST AValue: TDateTime): Int64;

Parameters

  • AValue: TDateTime; The date-time value to convert.

Return Value

Returns an `Int64` representing the Unix timestamp of the input `AValue`.
If `AValue` is earlier than January 1, 1970, the function returns `0`.

DateTime_To_Unix_Milli

Converts a Delphi TDateTime value to a Unix timestamp in milliseconds.
Optionally adjusts for local time zone by subtracting the system bias.
Function DateTime_To_Unix_Milli(CONST AValue: TDateTime; CONST IncDate: Boolean = True): Int64;

Parameters

  • AValue: TDateTime; the input date and time to convert.
  • IncDate: Boolean; if True, subtracts the local time zone bias to return UTC time.

Return Value

Returns the number of milliseconds since 1970-01-01 00:00:00 UTC.