ethereum.utils.numeric

Utility Functions For Numeric Operations.

.. contents:: Table of Contents :backlinks: none :local:

Introduction

Numeric operations specific utility functions used in this specification.

get_sign

Determines the sign of a number.

Parameters

value : The value whose sign is to be determined.

Returns

sign : int The sign of the number (-1 or 0 or 1). The return value is based on math signum function.

def get_sign(​value: int​) -> int:
20
    """
21
    Determines the sign of a number.
22
23
    Parameters
24
    ----------
25
    value :
26
        The value whose sign is to be determined.
27
28
    Returns
29
    -------
30
    sign : `int`
31
        The sign of the number (-1 or 0 or 1).
32
        The return value is based on math signum function.
33
34
    """
35
    if value < 0:
36
        return -1
37
    elif value == 0:
38
        return 0
39
    else:
40
        return 1

ceil32

Converts an unsigned integer to the next closest multiple of 32.

Parameters

value : The value whose ceil32 is to be calculated.

Returns

ceil32 : ethereum.base_types.U256 The same value if it's a perfect multiple of 32 else it returns the smallest multiple of 32 that is greater than value.

def ceil32(​value: Uint​) -> Uint:
44
    """
45
    Converts an unsigned integer to the next closest multiple of 32.
46
47
    Parameters
48
    ----------
49
    value :
50
        The value whose ceil32 is to be calculated.
51
52
    Returns
53
    -------
54
    ceil32 : `ethereum.base_types.U256`
55
        The same value if it's a perfect multiple of 32
56
        else it returns the smallest multiple of 32
57
        that is greater than `value`.
58
59
    """
60
    ceiling = Uint(32)
61
    remainder = value % ceiling
62
    if remainder == Uint(0):
63
        return value
64
    else:
65
        return value + ceiling - remainder

is_prime

Checks if number is a prime number.

Parameters

number : The number to check for primality.

Returns

is_number_prime : bool Boolean indicating if number is prime or not.

def is_prime(​number: SupportsInt​) -> bool:
69
    """
70
    Checks if `number` is a prime number.
71
72
    Parameters
73
    ----------
74
    number :
75
        The number to check for primality.
76
77
    Returns
78
    -------
79
    is_number_prime : `bool`
80
        Boolean indicating if `number` is prime or not.
81
82
    """
83
    number = int(number)
84
    if number <= 1:
85
        return False
86
87
    # number ** 0.5 is faster than math.sqrt(number)
88
    for x in range(2, int(number**0.5) + 1):
89
        # Return False if number is divisible by x
90
        if number % x == 0:
91
            return False
92
93
    return True

le_bytes_to_uint32_sequence

Convert little endian byte stream data to a little endian U32 sequence i.e., the first U32 number of the sequence is the least significant U32 number.

Parameters

data : The byte stream (little endian) which is to be converted to a U32 stream.

Returns

uint32_sequence : Tuple[U32, ...] Sequence of U32 numbers obtained from the little endian byte stream.

def le_bytes_to_uint32_sequence(​data: bytes​) -> Tuple[U32, ...]:
97
    """
98
    Convert little endian byte stream `data` to a little endian U32
99
    sequence i.e., the first U32 number of the sequence is the least
100
    significant U32 number.
101
102
    Parameters
103
    ----------
104
    data :
105
        The byte stream (little endian) which is to be converted to a U32
106
        stream.
107
108
    Returns
109
    -------
110
    uint32_sequence : `Tuple[U32, ...]`
111
        Sequence of U32 numbers obtained from the little endian byte
112
        stream.
113
114
    """
115
    sequence = []
116
    for i in range(0, len(data), 4):
117
        sequence.append(U32.from_le_bytes(data[i : i + 4]))
118
119
    return tuple(sequence)

le_uint32_sequence_to_bytes

Obtain little endian byte stream from a little endian U32 sequence i.e., the first U32 number of the sequence is the least significant U32 number.

Note - In this conversion, the most significant byte (byte at the end of the little endian stream) may have leading zeroes. This function doesn't take care of removing these leading zeroes as shown in below example.

le_uint32_sequence_to_bytes([U32(8)]) b'\x08\x00\x00\x00'

Parameters

sequence : The U32 stream (little endian) which is to be converted to a little endian byte stream.

Returns

result : bytes The byte stream obtained from the little endian U32 stream.

def le_uint32_sequence_to_bytes(​sequence: Sequence[U32]​) -> bytes:
123
    r"""
124
    Obtain little endian byte stream from a little endian U32 sequence
125
    i.e., the first U32 number of the sequence is the least significant
126
    U32 number.
127
128
    Note - In this conversion, the most significant byte (byte at the end of
129
    the little endian stream) may have leading zeroes. This function doesn't
130
    take care of removing these leading zeroes as shown in below example.
131
132
    >>> le_uint32_sequence_to_bytes([U32(8)])
133
    b'\x08\x00\x00\x00'
134
135
136
    Parameters
137
    ----------
138
    sequence :
139
        The U32 stream (little endian) which is to be converted to a
140
        little endian byte stream.
141
142
    Returns
143
    -------
144
    result : `bytes`
145
        The byte stream obtained from the little endian U32 stream.
146
147
    """
148
    result_bytes = b""
149
    for item in sequence:
150
        result_bytes += item.to_le_bytes4()
151
152
    return result_bytes

le_uint32_sequence_to_uint

Obtain Uint from a U32 sequence assuming that this sequence is little endian i.e., the first U32 number of the sequence is the least significant U32 number.

Parameters

sequence : The U32 stream (little endian) which is to be converted to a Uint.

Returns

value : Uint The Uint number obtained from the conversion of the little endian U32 stream.

def le_uint32_sequence_to_uint(​sequence: Sequence[U32]​) -> Uint:
156
    """
157
    Obtain Uint from a U32 sequence assuming that this sequence is little
158
    endian i.e., the first U32 number of the sequence is the least
159
    significant U32 number.
160
161
    Parameters
162
    ----------
163
    sequence :
164
        The U32 stream (little endian) which is to be converted to a Uint.
165
166
    Returns
167
    -------
168
    value : `Uint`
169
        The Uint number obtained from the conversion of the little endian
170
        U32 stream.
171
172
    """
173
    sequence_as_bytes = le_uint32_sequence_to_bytes(sequence)
174
    return Uint.from_le_bytes(sequence_as_bytes)

taylor_exponential

Approximates factor * e ** (numerator / denominator) using Taylor expansion.

Parameters

factor : The factor. numerator : The numerator of the exponential. denominator : The denominator of the exponential.

Returns

output : ethereum.base_types.Uint The approximation of factor * e ** (numerator / denominator).

def taylor_exponential(​factor: Uint, ​​numerator: Uint, ​​denominator: Uint​) -> Uint:
180
    """
181
    Approximates factor * e ** (numerator / denominator) using
182
    Taylor expansion.
183
184
    Parameters
185
    ----------
186
    factor :
187
        The factor.
188
    numerator :
189
        The numerator of the exponential.
190
    denominator :
191
        The denominator of the exponential.
192
193
    Returns
194
    -------
195
    output : `ethereum.base_types.Uint`
196
        The approximation of factor * e ** (numerator / denominator).
197
198
    """
199
    i = Uint(1)
200
    output = Uint(0)
201
    numerator_accumulated = factor * denominator
202
    while numerator_accumulated > Uint(0):
203
        output += numerator_accumulated
204
        numerator_accumulated = (numerator_accumulated * numerator) // (
205
            denominator * i
206
        )
207
        i += Uint(1)
208
    return output // denominator