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
    if value < 0:
35
        return -1
36
    elif value == 0:
37
        return 0
38
    else:
39
        return 1

ceil32

Converts a 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:
43
    """
44
    Converts a unsigned integer to the next closest multiple of 32.
45
46
    Parameters
47
    ----------
48
    value :
49
        The value whose ceil32 is to be calculated.
50
51
    Returns
52
    -------
53
    ceil32 : `ethereum.base_types.U256`
54
        The same value if it's a perfect multiple of 32
55
        else it returns the smallest multiple of 32
56
        that is greater than `value`.
57
    """
58
    ceiling = Uint(32)
59
    remainder = value % ceiling
60
    if remainder == Uint(0):
61
        return value
62
    else:
63
        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: int​) -> bool:
67
    """
68
    Checks if `number` is a prime number.
69
70
    Parameters
71
    ----------
72
    number :
73
        The number to check for primality.
74
75
    Returns
76
    -------
77
    is_number_prime : `bool`
78
        Boolean indicating if `number` is prime or not.
79
    """
80
    if number <= 1:
81
        return False
82
83
    # number ** 0.5 is faster than math.sqrt(number)
84
    for x in range(2, int(number**0.5) + 1):
85
        # Return False if number is divisible by x
86
        if number % x == 0:
87
            return False
88
89
    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, ...]:
93
    """
94
    Convert little endian byte stream `data` to a little endian U32
95
    sequence i.e., the first U32 number of the sequence is the least
96
    significant U32 number.
97
98
    Parameters
99
    ----------
100
    data :
101
        The byte stream (little endian) which is to be converted to a U32
102
        stream.
103
104
    Returns
105
    -------
106
    uint32_sequence : `Tuple[U32, ...]`
107
        Sequence of U32 numbers obtained from the little endian byte
108
        stream.
109
    """
110
    sequence = []
111
    for i in range(0, len(data), 4):
112
        sequence.append(U32.from_le_bytes(data[i : i + 4]))
113
114
    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:
118
    r"""
119
    Obtain little endian byte stream from a little endian U32 sequence
120
    i.e., the first U32 number of the sequence is the least significant
121
    U32 number.
122
123
    Note - In this conversion, the most significant byte (byte at the end of
124
    the little endian stream) may have leading zeroes. This function doesn't
125
    take care of removing these leading zeroes as shown in below example.
126
127
    >>> le_uint32_sequence_to_bytes([U32(8)])
128
    b'\x08\x00\x00\x00'
129
130
131
    Parameters
132
    ----------
133
    sequence :
134
        The U32 stream (little endian) which is to be converted to a
135
        little endian byte stream.
136
137
    Returns
138
    -------
139
    result : `bytes`
140
        The byte stream obtained from the little endian U32 stream.
141
    """
142
    result_bytes = b""
143
    for item in sequence:
144
        result_bytes += item.to_le_bytes4()
145
146
    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:
150
    """
151
    Obtain Uint from a U32 sequence assuming that this sequence is little
152
    endian i.e., the first U32 number of the sequence is the least
153
    significant U32 number.
154
155
    Parameters
156
    ----------
157
    sequence :
158
        The U32 stream (little endian) which is to be converted to a Uint.
159
160
    Returns
161
    -------
162
    value : `Uint`
163
        The Uint number obtained from the conversion of the little endian
164
        U32 stream.
165
    """
166
    sequence_as_bytes = le_uint32_sequence_to_bytes(sequence)
167
    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:
173
    """
174
    Approximates factor * e ** (numerator / denominator) using
175
    Taylor expansion.
176
177
    Parameters
178
    ----------
179
    factor :
180
        The factor.
181
    numerator :
182
        The numerator of the exponential.
183
    denominator :
184
        The denominator of the exponential.
185
186
    Returns
187
    -------
188
    output : `ethereum.base_types.Uint`
189
        The approximation of factor * e ** (numerator / denominator).
190
191
    """
192
    i = 1
193
    output = 0
194
    numerator_accumulated = factor * denominator
195
    while numerator_accumulated > 0:
196
        output += numerator_accumulated
197
        numerator_accumulated = (numerator_accumulated * numerator) // (
198
            denominator * i
199
        )
200
        i += 1
201
    return output // denominator