Unit Helpers

Warning

The Torii API reference is a work in progress and we are actively working on improving it, however it may be deficient or missing in places.

torii.util.units.bits_for(value: SupportsIndex, require_sign_bit: bool = False) → int

Get the number of bits needed to represent the integer value n.

Parameters:

• value (SupportsIndex) – The value to find the number of bits to fit for.

• require_sign_bit (bool) – If value is signed, requiring us to add a sign bit. This is calculated automatically if value is less than 0.

Example

>>> bits_for(127)
7
>>> bits_for(127, True)
8
>>> bits_for(-128)
8
>>> bits_for(65355)
16

Returns:

The minimum number of bits needed to represent n

Return type:

int

torii.util.units.iec_size(size: int, dec: int = 2) → str

Converts the given number of bytes to an IEC suffixed string.

Parameters:

• size (int) – The raw byte count.

• dec (int) – The number of decimal digits to include if size is a non-whole unit.

Example

>>> iec_size(92873402)
'88.57MiB'
>>> iec_size(4294967296, 0)
'4GiB'

Returns:

size converted into the nearest IEC suffixed string possible.

Return type:

str

torii.util.units.log2_ceil(value: SupportsIndex) → int

Calculate the integer result of ⌈log₂(value)⌉

Parameters:

value (SupportsIndex) – The value to calculate the ⌈log₂(value)⌉ for.

Example

>>> log2_ceil(16)
4
>>> log2_ceil(35)
6

Returns:

The integer log₂ of smallest power of 2 that is equal to or greater than value

Return type:

int

Raises:

ValueError – when value is negative

torii.util.units.log2_exact(value: SupportsIndex) → int

Calculate the integer result of log₂(value) where value is an exact power of 2.

Parameters:

value (SupportsIndex) – The value to calculate the log₂(value) for.

Example

>>> log2_exact(8)
3
>>> log2_exact(19)
Traceback (most recent call last):
File "<python-input-19>", line 1, in <module>
        log2_exact(19)
        ~~~~~~~~~~^^^^
File "units.py", line 168, in log2_exact
ValueError: 19 is not a power of 2

Returns:

The integer log₂ of value

Return type:

int

Raises:

ValueError – when value is not a power of 2

torii.util.units.ms_to_sec(val: float) → float

Convert the given number of milliseconds into fractional seconds.

Parameters:

val (float) – The number of milliseconds to convert into seconds.

Example

>>> ms_to_sec(4000)
4.0
>>> ms_to_sec(500)
0.5

Returns:

The number of seconds.

Return type:

float

torii.util.units.ns_to_sec(val: float) → float

Convert the given number of nanoseconds into fractional seconds.

Parameters:

val (float) – The number of nanoseconds to convert into seconds.

Example

>>> ns_to_sec(3000000000)
3.0
>>> ns_to_sec(5000000)
0.005

Returns:

The number of seconds.

Return type:

float

torii.util.units.ps_to_sec(val: float) → float

Convert the given number of picoseconds into fractional seconds.

Parameters:

val (float) – The number of picoseconds to convert into seconds.

Example

>>> ps_to_sec(1000000000000)
1.0
>>> ps_to_sec(60000000)
6e-05

Returns:

The number of seconds.

Return type:

float

torii.util.units.sec_to_ms(val: float) → float

Convert the given number of seconds into milliseconds.

Parameters:

val (float) – The number of seconds to convert into milliseconds.

Example

>>> sec_to_ms(4)
4000.0
>>> sec_to_ms(0.5)
500.0

Returns:

The number of milliseconds.

Return type:

float

torii.util.units.sec_to_ns(val: float) → float

Convert the given number of seconds into nanoseconds.

Parameters:

val (float) – The number of seconds to convert into nanoseconds.

Example

>>> sec_to_ns(3)
3000000000.0
>>> sec_to_ns(0.005)
5000000.0

Returns:

The number of nanoseconds.

Return type:

float

torii.util.units.sec_to_ps(val: float) → float

Convert the given number of seconds into picoseconds.

Parameters:

val (float) – The number of seconds to convert to picoseconds.

Example

>>> sec_to_ps(1)
1000000000000.0
>>> sec_to_ps(0.00006)
60000000.0

Returns:

The number of picoseconds.

Return type:

float

torii.util.units.sec_to_us(val: float) → float

Convert the given number of seconds into microseconds.

Parameters:

val (float) – The number of seconds to convert into microseconds.

Example

>>> sec_to_us(1)
1000000.0
>>> sec_to_us(0.06)
60000.0

Returns:

The number of microseconds.

Return type:

float

torii.util.units.us_to_sec(val: float) → float

Convert the given number of microseconds into fractional seconds.

Parameters:

val (float) – The number of microseconds to convert into seconds.

Example

>>> us_to_sec(1000000)
1.0
>>> us_to_sec(60000)
0.06

Returns:

The number of seconds.

Return type:

float