Skip to content

format_functions

shortfx.fxNumeric.format_functions

Format Functions Module.

Provides number formatting utilities, float comparison, and percentage calculations.

Example

from shortfx.fxNumeric.format_functions import format_as_percentage format_as_percentage(0.1234) '12.34%'

Functions

compare_floats_with_tolerance(a: float, b: float, rel_tol: float = 1e-09, abs_tol: float = 1e-05) -> bool

Compares two floating-point numbers to determine if they are "close" to each other.

Uses relative and absolute tolerances. This function is ideal for comparing floats in systems where the inherent precision of floating-point calculations can lead to small differences that should not be considered significant.

Parameters:

Name Type Description Default
a float

The first floating-point number to compare.

 required
b float

The second floating-point number to compare.

 required
rel_tol float

The relative tolerance. Default is 1e-9.

 1e-09
abs_tol float

The absolute tolerance. Default is 1e-5.

 1e-05

Returns:

Name Type Description
bool bool

True if 'a' and 'b' are considered close according to the tolerances.
Example

compare_floats_with_tolerance(0.1 + 0.2, 0.3) True compare_floats_with_tolerance(1000000.0, 1000000.0000001, rel_tol=1e-9) True

Cost: O(1), tolerance comparison using math.isclose.

Source code in shortfx/fxNumeric/format_functions.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def compare_floats_with_tolerance(a: float, b: float, rel_tol: float = 1e-9, abs_tol: float = 1e-5) -> bool:
    """Compares two floating-point numbers to determine if they are "close" to each other.

    Uses relative and absolute tolerances. This function is ideal for comparing
    floats in systems where the inherent precision of floating-point calculations
    can lead to small differences that should not be considered significant.

    Args:
        a (float): The first floating-point number to compare.
        b (float): The second floating-point number to compare.
        rel_tol (float): The relative tolerance. Default is 1e-9.
        abs_tol (float): The absolute tolerance. Default is 1e-5.

    Returns:
        bool: True if 'a' and 'b' are considered close according to the tolerances.

    Example:
        >>> compare_floats_with_tolerance(0.1 + 0.2, 0.3)
        True
        >>> compare_floats_with_tolerance(1000000.0, 1000000.0000001, rel_tol=1e-9)
        True

    **Cost:** O(1), tolerance comparison using math.isclose.
    """
    return math.isclose(a, b, rel_tol=rel_tol, abs_tol=abs_tol)

format_as_percentage(number: float, decimals: int = 2) -> str

Formats a floating-point number as a percentage string.

Parameters:

Name Type Description Default
number float

The number to format (e.g., 0.1234).

 required
decimals int

The number of decimal places to display in the percentage. Default is 2.

 2

Returns:

Name Type Description
str str

The formatted percentage string (e.g., "12.34%").
Example

format_as_percentage(0.1234) '12.34%' format_as_percentage(0.5, 0) '50%' format_as_percentage(0.005, 1) '0.5%'

Cost: O(1), string formatting.

Source code in shortfx/fxNumeric/format_functions.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def format_as_percentage(number: float, decimals: int = 2) -> str:
    """Formats a floating-point number as a percentage string.

    Args:
        number (float): The number to format (e.g., 0.1234).
        decimals (int): The number of decimal places to display in the percentage. Default is 2.

    Returns:
        str: The formatted percentage string (e.g., "12.34%").

    Example:
        >>> format_as_percentage(0.1234)
        '12.34%'
        >>> format_as_percentage(0.5, 0)
        '50%'
        >>> format_as_percentage(0.005, 1)
        '0.5%'

    **Cost:** O(1), string formatting.
    """
    return f"{number:.{decimals}%}"

format_as_scientific_notation(number: float, decimals: int = 2) -> str

Formats a floating-point number in scientific notation.

Parameters:

Name Type Description Default
number float

The number to format.

 required
decimals int

The number of decimal places for the mantissa. Default is 2.

 2

Returns:

Name Type Description
str str

The number string in scientific notation (e.g., "1.23e+06").
Example

format_as_scientific_notation(1230000) '1.23e+06' format_as_scientific_notation(0.0000000000456, 1) '4.6e-11' format_as_scientific_notation(1.0, 0) '1e+00'

Cost: O(1), scientific notation formatting.

Source code in shortfx/fxNumeric/format_functions.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def format_as_scientific_notation(number: float, decimals: int = 2) -> str:
    """Formats a floating-point number in scientific notation.

    Args:
        number (float): The number to format.
        decimals (int): The number of decimal places for the mantissa. Default is 2.

    Returns:
        str: The number string in scientific notation (e.g., "1.23e+06").

    Example:
        >>> format_as_scientific_notation(1230000)
        '1.23e+06'
        >>> format_as_scientific_notation(0.0000000000456, 1)
        '4.6e-11'
        >>> format_as_scientific_notation(1.0, 0)
        '1e+00'

    **Cost:** O(1), scientific notation formatting.
    """
    return f"{number:.{decimals}e}"

format_with_leading_zeros(number: int, width: int) -> str

Formats an integer as a string, padding with leading zeros to a specific width.

Parameters:

Name Type Description Default
number int

The integer to format.

 required
width int

The desired total width of the resulting string.

 required

Returns:

Name Type Description
str str

The number string with leading zeros.
Example

format_with_leading_zeros(5, 3) '005' format_with_leading_zeros(123, 5) '00123'

Cost: O(1), string formatting.

Source code in shortfx/fxNumeric/format_functions.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def format_with_leading_zeros(number: int, width: int) -> str:
    """Formats an integer as a string, padding with leading zeros to a specific width.

    Args:
        number (int): The integer to format.
        width (int): The desired total width of the resulting string.

    Returns:
        str: The number string with leading zeros.

    Example:
        >>> format_with_leading_zeros(5, 3)
        '005'
        >>> format_with_leading_zeros(123, 5)
        '00123'

    **Cost:** O(1), string formatting.
    """
    return format(number, f'0{width}')

percent_change(old_value: float, new_value: float) -> float

Calculates the percentage change between two values.

Parameters:

Name Type Description Default
old_value float

The original value (must not be zero).

 required
new_value float

The new value.

 required

Returns:

Type Description
float

The percentage change as a float (e.g. 50.0 for a 50% increase).

Raises:

Type Description
ValueError

If old_value is zero.
Example

percent_change(100, 150) 50.0 percent_change(200, 150) -25.0

Complexity: O(1)

Source code in shortfx/fxNumeric/format_functions.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def percent_change(old_value: float, new_value: float) -> float:
    """Calculates the percentage change between two values.

    Args:
        old_value: The original value (must not be zero).
        new_value: The new value.

    Returns:
        The percentage change as a float (e.g. 50.0 for a 50% increase).

    Raises:
        ValueError: If old_value is zero.

    Example:
        >>> percent_change(100, 150)
        50.0
        >>> percent_change(200, 150)
        -25.0

    Complexity: O(1)
    """
    if old_value == 0:
        raise ValueError("old_value cannot be zero.")

    return ((new_value - old_value) / old_value) * 100

percent_of(part: float, whole: float) -> float

Calculates what percentage part is of whole.

Parameters:

Name Type Description Default
part float

The partial value.

 required
whole float

The total value (must not be zero).

 required

Returns:

Type Description
float

The percentage as a float.

Raises:

Type Description
ValueError

If whole is zero.
Example

percent_of(25, 200) 12.5 percent_of(3, 4) 75.0

Complexity: O(1)

Source code in shortfx/fxNumeric/format_functions.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def percent_of(part: float, whole: float) -> float:
    """Calculates what percentage ``part`` is of ``whole``.

    Args:
        part: The partial value.
        whole: The total value (must not be zero).

    Returns:
        The percentage as a float.

    Raises:
        ValueError: If whole is zero.

    Example:
        >>> percent_of(25, 200)
        12.5
        >>> percent_of(3, 4)
        75.0

    Complexity: O(1)
    """
    if whole == 0:
        raise ValueError("whole cannot be zero.")

    return (part / whole) * 100