ethereum.utils.hexadecimal

  1"""
  2Utility Functions For Hexadecimal Strings
  3^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  4
  5.. contents:: Table of Contents
  6    :backlinks: none
  7    :local:
  8
  9Introduction
 10------------
 11
 12Hexadecimal strings specific utility functions used in this specification.
 13"""
 14from ethereum.base_types import (
 15    U64,
 16    U256,
 17    Bytes,
 18    Bytes8,
 19    Bytes20,
 20    Bytes32,
 21    Bytes256,
 22    Uint,
 23)
 24from ethereum.crypto.hash import Hash32
 25
 26
 27def has_hex_prefix(hex_string: str) -> bool:
 28    """
 29    Check if a hex string starts with hex prefix (0x).
 30
 31    Parameters
 32    ----------
 33    hex_string :
 34        The hexadecimal string to be checked for presence of prefix.
 35
 36    Returns
 37    -------
 38    has_prefix : `bool`
 39        Boolean indicating whether the hex string has 0x prefix.
 40    """
 41    return hex_string.startswith("0x")
 42
 43
 44def remove_hex_prefix(hex_string: str) -> str:
 45    """
 46    Remove 0x prefix from a hex string if present. This function returns the
 47    passed hex string if it isn't prefixed with 0x.
 48
 49    Parameters
 50    ----------
 51    hex_string :
 52        The hexadecimal string whose prefix is to be removed.
 53
 54    Returns
 55    -------
 56    modified_hex_string : `str`
 57        The hexadecimal string with the 0x prefix removed if present.
 58    """
 59    if has_hex_prefix(hex_string):
 60        return hex_string[len("0x") :]
 61
 62    return hex_string
 63
 64
 65def hex_to_bytes(hex_string: str) -> Bytes:
 66    """
 67    Convert hex string to bytes.
 68
 69    Parameters
 70    ----------
 71    hex_string :
 72        The hexadecimal string to be converted to bytes.
 73
 74    Returns
 75    -------
 76    byte_stream : `bytes`
 77        Byte stream corresponding to the given hexadecimal string.
 78    """
 79    return bytes.fromhex(remove_hex_prefix(hex_string))
 80
 81
 82def hex_to_bytes8(hex_string: str) -> Bytes8:
 83    """
 84    Convert hex string to 8 bytes.
 85
 86    Parameters
 87    ----------
 88    hex_string :
 89        The hexadecimal string to be converted to 8 bytes.
 90
 91    Returns
 92    -------
 93    8_byte_stream : `Bytes8`
 94        8-byte stream corresponding to the given hexadecimal string.
 95    """
 96    return Bytes8(bytes.fromhex(remove_hex_prefix(hex_string).rjust(16, "0")))
 97
 98
 99def hex_to_bytes20(hex_string: str) -> Bytes20:
100    """
101    Convert hex string to 20 bytes.
102
103    Parameters
104    ----------
105    hex_string :
106        The hexadecimal string to be converted to 20 bytes.
107
108    Returns
109    -------
110    20_byte_stream : `Bytes20`
111        20-byte stream corresponding to the given hexadecimal string.
112    """
113    return Bytes20(bytes.fromhex(remove_hex_prefix(hex_string).rjust(20, "0")))
114
115
116def hex_to_bytes32(hex_string: str) -> Bytes32:
117    """
118    Convert hex string to 32 bytes.
119
120    Parameters
121    ----------
122    hex_string :
123        The hexadecimal string to be converted to 32 bytes.
124
125    Returns
126    -------
127    32_byte_stream : `Bytes32`
128        32-byte stream corresponding to the given hexadecimal string.
129    """
130    return Bytes32(bytes.fromhex(remove_hex_prefix(hex_string).rjust(64, "0")))
131
132
133def hex_to_bytes256(hex_string: str) -> Bytes256:
134    """
135    Convert hex string to 256 bytes.
136
137    Parameters
138    ----------
139    hex_string :
140        The hexadecimal string to be converted to 256 bytes.
141
142    Returns
143    -------
144    256_byte_stream : `Bytes256`
145        256-byte stream corresponding to the given hexadecimal string.
146    """
147    return Bytes256(
148        bytes.fromhex(remove_hex_prefix(hex_string).rjust(512, "0"))
149    )
150
151
152def hex_to_hash(hex_string: str) -> Hash32:
153    """
154    Convert hex string to hash32 (32 bytes).
155
156    Parameters
157    ----------
158    hex_string :
159        The hexadecimal string to be converted to hash32.
160
161    Returns
162    -------
163    hash : `Hash32`
164        32-byte stream obtained from the given hexadecimal string.
165    """
166    return Hash32(bytes.fromhex(remove_hex_prefix(hex_string)))
167
168
169def hex_to_uint(hex_string: str) -> Uint:
170    """
171    Convert hex string to Uint.
172
173    Parameters
174    ----------
175    hex_string :
176        The hexadecimal string to be converted to Uint.
177
178    Returns
179    -------
180    converted : `Uint`
181        The unsigned integer obtained from the given hexadecimal string.
182    """
183    return Uint(int(remove_hex_prefix(hex_string), 16))
184
185
186def hex_to_u64(hex_string: str) -> U64:
187    """
188    Convert hex string to U64.
189
190    Parameters
191    ----------
192    hex_string :
193        The hexadecimal string to be converted to U256.
194
195    Returns
196    -------
197    converted : `U64`
198        The U64 integer obtained from the given hexadecimal string.
199    """
200    return U64(int(remove_hex_prefix(hex_string), 16))
201
202
203def hex_to_u256(hex_string: str) -> U256:
204    """
205    Convert hex string to U256.
206
207    Parameters
208    ----------
209    hex_string :
210        The hexadecimal string to be converted to U256.
211
212    Returns
213    -------
214    converted : `U256`
215        The U256 integer obtained from the given hexadecimal string.
216    """
217    return U256(int(remove_hex_prefix(hex_string), 16))