API

ulist.constructor.arange(start: int, stop: Optional[int] = None, step: int = 1, dtype: str = 'int') ulist.core.UltraFastList

Return evenly spaced values within a given interval, which is similar to the Python built-in range function, but returns an ulist rather than a list.

Args:
start (int):

Start of interval. The interval includes this value. If stop is not given, then start=0 and stop=start.

stop (Optional[int], optional):

End of interval. The interval does not include this value. Defaults to None.

step (int, optional):

Spacing between values. Defaults to 1.

dtype (str, optional):

The type of the output ulist. ‘int’, ‘int32’, ‘int64’.

Returns:

UltraFastList: A ulist object.

>>> import ulist as ul
>>> arr1 = ul.arange(3)
>>> arr1
UltraFastList([0, 1, 2])
>>> arr2 = ul.arange(1, 4)
>>> arr2
UltraFastList([1, 2, 3])
>>> arr3 = ul.arange(1, 6, 2)
>>> arr3
UltraFastList([1, 3, 5])
ulist.constructor.choices(obj: Sequence, size: int, dtype: str) ulist.core.UltraFastList

Choose element from a sequence randomly and endlessly until the size is met.

Args:
obj (Sequence):

Sequence object such as list, tuple and range.

size (int):

size (int): Size of the new ulist.

dtype (str):

The type of the output ulist. ‘int’, ‘int32’, ‘int64’, ‘float’, ‘float32’, ‘float64’, ‘bool’ or ‘string’.

Raises:
ValueError:

Parameter dtype should be ‘int’, ‘int32’, ‘int64’, ‘float’, ‘float32’, ‘float64’, ‘bool’ or ‘string’!

Returns:

UltraFastList: A ulist object.

ulist.constructor.cycle(obj: Sequence, size: int, dtype: str) ulist.core.UltraFastList

Repeats a sequence endlessly until the size is met.

Args:
obj (Sequence):

Sequence object such as list, tuple and range.

size (int):

size (int): Size of the new ulist.

dtype (str):

The type of the output ulist. ‘int’, ‘int32’, ‘int64’, ‘float’, ‘float32’, ‘float64’, ‘bool’ or ‘string’.

Raises:
ValueError:

Parameter dtype should be ‘int’, ‘int32’, ‘int64’, ‘float’, ‘float32’, ‘float64’, ‘bool’ or ‘string’!

Returns:

UltraFastList: A ulist object.

>>> import ulist as ul
>>> arr1 = ul.cycle(range(3), 5, 'int')
>>> arr1
UltraFastList([0, 1, 2, 0, 1])
>>> arr2 = ul.cycle((0.0, 0.1), 4, 'float')
>>> arr2
UltraFastList([0.0, 0.1, 0.0, 0.1])
>>> arr3 = ul.cycle([True], 3, 'bool')
>>> arr3
UltraFastList([True, True, True])
>>> arr4 = ul.cycle(['foo'], 3, 'string')
>>> arr4
UltraFastList(['foo', 'foo', 'foo'])
ulist.constructor.from_seq(obj: Sequence, dtype: str) ulist.core.UltraFastList

Construct a ulist object from a sequence object.

Args:
obj (Sequence):

Sequence object such as list, tuple and range.

dtype (str):

The type of the output ulist. ‘int’, ‘int32’, ‘int64’, ‘float’, ‘float32’, ‘float64’, ‘bool’ or ‘string’.

Raises:
ValueError:

Parameter dtype should be ‘int’, ‘int32’, ‘int64’, ‘float’, ‘float32’, ‘float64’, ‘bool’ or ‘string’!

Returns:

UltraFastList: A ulist object.

>>> import ulist as ul
>>> arr1 = ul.from_seq([1.0, 2.0, 3.0], dtype='float')
>>> arr1
UltraFastList([1.0, 2.0, 3.0])
>>> arr2 = ul.from_seq(range(3), dtype='int')
>>> arr2
UltraFastList([0, 1, 2])
>>> arr3 = ul.from_seq((True, True, False), dtype='bool')
>>> arr3
UltraFastList([True, True, False])
>>> arr4 = ul.from_seq(('foo', 'bar', 'baz'), dtype='string')
>>> arr4
UltraFastList(['foo', 'bar', 'baz'])
ulist.constructor.random(size: int, dtype: str) ulist.core.UltraFastList

Return a new ulist of random number in [0.0, 1.0).

Args:
size (int):

size (int): Size of the new ulist.

dtype (str):

The type of the output ulist. ‘float’, ‘float32’ or ‘float64’.

ulist.constructor.repeat(elem: Union[int, float, bool, str], size: int) ulist.core.UltraFastList

Return a new ulist of given size, filled with elem.

Args:

elem (ELEM): Element to repeat. size (int): Size of the new ulist.

Raises:

TypeError: Parameter elem should be int, float, bool or str type!

Returns:

UltraFastList: A ulist object.

>>> import ulist as ul
>>> arr1 = ul.repeat(0, 3)
>>> arr1
UltraFastList([0, 0, 0])
>>> arr2 = ul.repeat(1.0, 3)
>>> arr2
UltraFastList([1.0, 1.0, 1.0])
>>> arr3 = ul.repeat(True, 3)
>>> arr3
UltraFastList([True, True, True])
>>> arr4 = ul.repeat('foo', 3)
>>> arr4
UltraFastList(['foo', 'foo', 'foo'])
class ulist.control_flow.CaseObject(nums: UltraFastList, default: ELEM)

This is designed to implement case method for UtraFastList. To provide an interface similar to SQL’s case statement.

end() UltraFastList

Execute the case statement.

when(fn: Callable[[UltraFastList], UltraFastList], then: ELEM) CaseObject

Calculate the condition, and keep the condition and element to use.

Args:
fn (Callable[[UltraFastList], UltraFastList]):

Function to calculate the condition.

then (ELEM):

The element to use when the condition is satisfied.

Raises:
TypeError:

Calling parameter fn should return a ulist with dtype bool!

TypeError:

The type of parameter then should be the same as default!

Returns:

CaseObject

ulist.control_flow.select(conditions: List[UltraFastList], choices: LIST_PY, default: ELEM) UltraFastList

Return a ulist drawn from elements in choices, depending on`conditions`.

Args:
conditions (List[UltraFastList]):

The list of conditions which determine from which array in choices the output elements are taken. When multiple conditions are satisfied, the first one encountered in conditions is used.

choices (LIST_PY):

The list of ulist from which the output elements are taken. It has to be of the same length as conditions.

default (ELEM):

The element inserted in output when all conditions evaluate to False.

Raises:
TypeError:

The type of parameter default should be bool, float, int or str!

Returns:

UltraFastList: A ulist object.

>>> import ulist as ul
>>> arr = ul.arange(6)
>>> arr
UltraFastList([0, 1, 2, 3, 4, 5])
>>> conditions = [arr < 2, arr < 4]
>>> conditions
[
    UltraFastList([True, True, False, False, False, False]),
    UltraFastList([True, True, True, True, False, False])
]
>>> result = ul.select(conditions, choices=[0, 1], default=2)
>>> result
UltraFastList([0, 0, 1, 1, 2, 2])
class ulist.core.UltraFastList(values: Union[FloatList32, FloatList64, IntegerList32, IntegerList64, BooleanList, StringList])

Ultra fast list data structures written in Rust with Python bindings, which is abbreviated as ulist.

add(other: UltraFastList) UltraFastList

Return self + other.

add_scala(elem: Union[int, float]) UltraFastList

Return self + elem.

all() Optional[bool]

Whether all the elements of self are True.

all_equal(other: UltraFastList) Optional[bool]

Whether all elements in the same position of self and other are equal.

and_(other: UltraFastList) UltraFastList

Return self & other.

any() Optional[bool]

Whether any element of self is True.

append(elem: Union[int, None, float, bool, str]) None

Adds a new element at the end of the self.

apply(fn: Callable[[ulist.core.UltraFastList], ulist.core.UltraFastList]) ulist.core.UltraFastList

Return the result of fn(self).

Args:
fn (Callable[[UltraFastList], UltraFastList]):

Function to apply to self.

Returns:

UltraFastList: A ulist object.

>>> import ulist as ul
>>> arr = ul.arange(3)
>>> arr
UltraFastList([0, 1, 2])
>>> result = arr.apply(lambda x: x * 2)
>>> result
UltraFastList([0, 2, 4])
argmax() int

Returns the indices of the maximum values of self.

argmin() int

Returns the indices of the minimum values of self.

astype(dtype: str) UltraFastList

Copy of self, cast to a specified dtype.

Raises:
ValueError:

Parameter dtype should be ‘int’, ‘int32’, ‘int64’, ‘float’, ‘float32’, ‘float64’, ‘bool’ or ‘string’!

Returns:

UltraFastList: A ulist object.

case(default: ELEM) CaseObject

A method similar to SQL’s case statement.

Args:
default (ELEM):

The element inserted in output when all conditions evaluate to False.

Returns:

CaseObject

>>> import ulist as ul
>>> arr = ul.arange(6)
>>> arr
UltraFastList([0, 1, 2, 3, 4, 5])
>>> result = arr.case(default=2)        ...             .when(lambda x: x < 2, then=0)        ...             .when(lambda x: x < 4, then=1)        ...             .end()
>>> result
UltraFastList([0, 0, 1, 1, 2, 2])
contains(elem: str) ulist.core.UltraFastList

Return whether the element of self contains elem.

copy() UltraFastList

Return a ulist copy of self.

count_na() int

Count of missing values.

counter() Union[Dict[Optional[int], int], Dict[Optional[bool], int], Dict[Optional[str], int]]

Return a dictionary where the elements of self are stored as dictionary keys and their counts are stored as dictionary values.

div(other: UltraFastList, zero_div: bool = False) UltraFastList

Return self / other.

div_scala(elem: float, zero_div: bool = False) UltraFastList

Return self / elem.

ends_with(elem: str) ulist.core.UltraFastList

Return whether the element of self ends with elem.

equal(other: UltraFastList) UltraFastList

Return self == other.

equal_scala(elem: Union[int, float, bool, str]) UltraFastList

Return self == elem.

filter(condition: UltraFastList) UltraFastList

According to the condition, return a ulist with elements of self correspondingly.

get(index: int) Union[int, None, float, bool, str]

Return self[index].

get_by_indexes(indexes: IndexList) ulist.core.UltraFastList

Return self[indexes].

greater_than(other: UltraFastList) UltraFastList

Return self > other.

greater_than_or_equal(other: UltraFastList) UltraFastList

Return self >= other.

greater_than_or_equal_scala(elem: Union[int, float]) UltraFastList

Return self >= elem.

greater_than_scala(elem: Union[int, float]) UltraFastList

Return self > elem.

has_na() bool

Return NA in self.

has_zero() bool

Return zero in self.

less_than(other: UltraFastList) UltraFastList

Return self < other.

less_than_or_equal(other: UltraFastList) UltraFastList

Return self <= other.

less_than_or_equal_scala(elem: Union[int, float]) UltraFastList

Return self <= elem.

less_than_scala(elem: Union[int, float]) UltraFastList

Return self < elem.

max() Union[int, float]

Return the maximum of self.

mean() float

Return the mean of self.

min() Union[int, float]

Return the minimum of self.

mul(other: UltraFastList) UltraFastList

Return self * other.

mul_scala(elem: Union[int, float]) UltraFastList

Return self * elem.

not_() UltraFastList

Return ~self.

not_equal(other: UltraFastList) UltraFastList

Return self != other.

not_equal_scala(elem: Union[int, float]) UltraFastList

Return self != elem.

or_(other: UltraFastList) UltraFastList

Return self | other.

pop() None

Removes the last element of self.

pow_scala(elem: Union[int, float]) UltraFastList

Return self ** elem.

replace(old: Union[int, None, float, bool, str], new: Union[int, None, float, bool, str]) None

Replace the old elements of self with the new one.

set(index: int, elem: Union[int, None, float, bool, str]) None

Set self[index] to elem.

size() int

Number of elements of self.

sort(ascending: bool) None

Sort self.

Args:
ascending (bool):

Ascending or descending.

Returns:

UltraFastList: The sorted ulist.

starts_with(elem: str) ulist.core.UltraFastList

Return whether the element of self starts with elem.

str_len() UltraFastList

Return each element’s string length of self.

sub(other: UltraFastList) UltraFastList

Return self - other.

sub_scala(elem: Union[int, float]) UltraFastList

Return self - elem.

sum() Union[int, float]

Return the sum of self.

to_index() IndexList

Convert self from BooleanList to IndexList by filtering the indexes where the element of self is True.

Returns:

IndexList

>>> import ulist as ul
>>> arr = ul.from_seq([True, False, True, True], dtype='bool')
>>> arr.to_index()
IndexList([0, 2, 3])
to_list() Union[List[Optional[float]], List[Optional[int]], List[Optional[bool]], List[Optional[str]]]

Return a list with the elements of self.

union_all(other: UltraFastList) UltraFastList

Concatenate self and other together as a new ulist.

unique() UltraFastList

Returns the sorted unique elements of self.

var(ddof: int = 0) float

Returns the variance of self.

Args:
ddof (int, optional):

Delta Degrees of Freedom - the divisor used in the calculation is N - ddof, where N represents the number of elements. Defaults to 0.

Raises:

TypeError: Only support dtype int, float and bool.

Returns:

float: variance

where(fn: Callable[[ulist.core.UltraFastList], ulist.core.UltraFastList]) ulist.core.UltraFastList

Calculate the condition by fn(self), and return a ulist with elements of self correspondingly.

Args:
fn (Callable[[UltraFastList], UltraFastList]):

Function to process self and return a BooleanList.

Returns:

UltraFastList: A ulist object.

>>> import ulist as ul
>>> arr = ul.arange(6)
>>> arr
UltraFastList([0, 1, 2, 3, 4, 5])
>>> result = arr.where(lambda x: x > 2)
>>> result
UltraFastList([3, 4, 5])