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])