ethereum.utils.numeric

  1"""
  2Utility Functions For Numeric Operations
  3^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  4
  5.. contents:: Table of Contents
  6    :backlinks: none
  7    :local:
  8
  9Introduction
 10------------
 11
 12Numeric operations specific utility functions used in this specification.
 13"""
 14from typing import Sequence, Tuple
 15
 16from ethereum.base_types import U32, Uint
 17
 18
 19def 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
 40
 41
 42def 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
 64
 65
 66def 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
 90
 91
 92def 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)
115
116
117def 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
147
148
149def 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)