API Reference¶

def as_arrayof_bytes(self, obj: List[Any]) -> OwningCffiNativeHandle:
    """Convert a list of "strings" to a char** like C array."""
    return as_arrayof_bytes(self._ffi, obj)

def as_c_double_array(
    self,
    data: np.ndarray,
    shallow: bool = False,  # noqa: FBT001, FBT002
) -> OwningCffiNativeHandle:
    """Convert a list or array of numeric values to a cffi pointer to a C array of double precision floats.

    Args:
        data (Union[List[float], np.ndarray]): list or array of numeric values
        shallow (bool, optional): If True the resulting C array points directly to the data in the input numpy array (if it is a numpy array),
            otherwise a new C array is created and the data is copied to it. Defaults to False.
            Note that if the input data is a list, it will be converted to a numpy array and the resulting C array will not be shallow.

    Returns:
        OwningCffiNativeHandle: A wrapper that owns the memory allocated for the resulting C array of double precision floats.
    """
    return as_c_double_array(self._ffi, data, shallow)

def as_character_vector(self, obj: List[Any]) -> OwningCffiNativeHandle:
    """Convert a list of "strings" to a character_vector* native struct."""
    return as_character_vector(self._ffi, obj)

def as_charptr(self, x: str, wrap: bool = False) -> CffiData:  # noqa: FBT001, FBT002
    """Convert an object to `bytes`, create as C array of char and copy values to it. Equivalent to `char arg[] = "world"` if x is the bytes b"world".

    Args:
        x (str): a string-like object; bytes or str, or string like object that can be encoded to bytes (six.string_like)
        wrap (bool, optional): return a "naked" cdata pointer object if False, or wrapped in a `OwningCffiNativeHandle` if True. Defaults to False.

    Returns:
        Union[OwningCffiNativeHandle,CffiData]: a (wrapper to a) cdata pointer object owning a new array of `char *`s of length `size`
    """
    return as_charptr(self._ffi, x, wrap)

def as_datetime(self, ptr: CffiData) -> datetime:
    """Convert if possible a cffi pointer to a C date_time_to_second struct, into a datetime.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData)

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        datetime: converted data
    """
    return dtts_as_datetime(ptr)

def as_native_time_series(self, data: TimeSeriesLike) -> OwningCffiNativeHandle:
    """Convert a pure python time series to a native representation via a C struct `multi_regular_time_series_data`.

    Args:
        data (TimeSeriesLike): xarray or pandas based time series

    Raises:
        TypeError: unexpected input type

    Returns:
        OwningCffiNativeHandle: wrapper to a C struct `multi_regular_time_series_data`
    """
    return as_native_time_series(self._ffi, data)

def as_native_tsgeom(self, tsgeom: TimeSeriesGeometry) -> TimeSeriesGeometryNative:
    """C-compatible representation of a time series geometry.

    Returns:
        TimeSeriesGeometryNative: wrapper around a cdata pointer to a new C struct `regular_time_series_geometry`
    """
    return tsgeom.as_native(self._ffi)

def as_np_array_double(
    self,
    ptr: CffiData,
    size: int,
    shallow: bool = False,  # noqa: FBT001, FBT002
) -> np.ndarray:
    """Convert if possible a cffi pointer to a C data array, into a numpy array of double precision floats `double[n]`.

    The returned numpy array may be directly pointing to the original data (faster performance), or a deep copy (memory safety - "normal" numpy array)

    Args:
        ptr (CffiData): cffi pointer (FFI.CData)
        size (int): array size
        shallow (bool): If True the resulting numpy array points directly to the native data array. Otherwise, return a numpy array with a deep copy of the data, managed by Python. Defaults to False.

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        np.ndarray: converted data
    """
    return as_np_array_double(self._ffi, ptr, size, shallow)

def as_numeric_np_array(
    self,
    ptr: CffiData,
    size: int,
    shallow: bool = False,  # noqa: FBT001, FBT002
) -> np.ndarray:
    """Convert if possible a cffi pointer to a C data array, into a numpy array.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData)
        size (int): array size
        shallow (bool): If true the array points directly to native data array. Defaults to False.

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        np.ndarray: converted data
    """
    return as_numeric_np_array(self._ffi, ptr, size, shallow)

def as_xarray_time_series(self, ptr: CffiData) -> Optional[xr.DataArray]:
    """Convert a native time series structure to an xarray representation."""
    return as_xarray_time_series(self._ffi, ptr)

def c_charptrptr_as_string_list(self, ptr: CffiData, size: int) -> List[str]:
    """Convert if possible a cffi pointer to a C data array char** , into a list of python strings.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData)
        size (int): number of character strings in the char** pointer

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        List[str]: converted data
    """
    return c_charptrptr_as_string_list(self._ffi, ptr, size)

def c_string_as_py_string(self, ptr: CffiData) -> str:
    """Convert if possible a cffi pointer to an ANSI C string <char*> to a python string.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData)

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        str: converted string
    """
    return c_string_as_py_string(self._ffi, ptr)

def character_vector_as_string_list(self, ptr: CffiData) -> List[str]:
    """Convert if possible a cffi pointer to a C character_vector , into a list of python strings.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData)

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        List[str]: converted data
    """
    return self.c_charptrptr_as_string_list(ptr.values, ptr.size)

def create_values_struct(
    self,
    data: Union[List[float], np.ndarray],
) -> OwningCffiNativeHandle:
    """Convert a list or array of numeric values to a cffi pointer to a `values_vector` struct."""
    return create_values_struct(self._ffi, data)

def datetime_to_dtts(self, dt: datetime) -> OwningCffiNativeHandle:
    """Convert a python datetime to a cffi pointer to a C struct `date_time_to_second`."""
    return datetime_to_dtts(self._ffi, dt)

def dict_to_named_values(self, data: Dict[str, float]) -> OwningCffiNativeHandle:
    """Convert a dictionary to a cffi pointer to a `named_values_vector` struct.

    Args:
        data (Dict[str,float]): mapping from keys to numeric values

    Returns:
        OwningCffiNativeHandle: A wrapper that owns the memory allocated for the resulting `named_values_vector` pointed to
    """
    return dict_to_named_values(self._ffi, data)

def dict_to_string_map(self, data: Dict[str, str]) -> OwningCffiNativeHandle:
    """Convert a dictionary to a cffi pointer to a `string_string_map` struct."""
    return dict_to_string_map(self._ffi, data)

def get_native_tsgeom(self, pd_series: pd.Series) -> OwningCffiNativeHandle:
    """Get a native representation of the geometry of a time series. A simple heuristic is used to find the time step."""
    return get_native_tsgeom(self._ffi, pd_series)

def named_values_to_dict(self, ptr: CffiData) -> Dict[str, float]:
    """Convert if possible a cffi pointer to a `named_values_vector` struct, into a dictionary.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData) to a `named_values_vector` struct

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        Dict[str,float]: converted data
    """
    return named_values_to_dict(self._ffi, ptr)

def new_charptr_array(
    self,
    size: int,
    wrap: bool = False,  # noqa: FBT001, FBT002
) -> Union[OwningCffiNativeHandle, CffiData]:
    """Creates a new C array of pointers to char (strings) `char*[n]`.

    Args:
        size (int): array size
        wrap (bool, optional): return a "naked" cdata pointer object if False, or wrapped in a `OwningCffiNativeHandle` if True. Defaults to False.

    Returns:
        Union[OwningCffiNativeHandle,CffiData]: a (wrapper to a) cdata pointer object owning a new array of pointers to char (strings) of length `size`
    """
    return new_charptr_array(self._ffi, size, wrap)

def new_ctype_array(
    self,
    ctype: str,
    size: int,
    wrap: bool = False,  # noqa: FBT001, FBT002
) -> Union[OwningCffiNativeHandle, CffiData]:
    """Creates a new C array of the specified type and size.

    Args:
        ctype (str): C type of the array elements, e.g. "int", "double", "char*"
        size (int): array size
        wrap (bool, optional): return a "naked" cdata pointer object if False, or wrapped in a `OwningCffiNativeHandle` if True. Defaults to False.

    Returns:
        Union[OwningCffiNativeHandle,CffiData]: a (wrapper to a) cdata pointer object owning a new array of the specified type and length `size`
    """
    return new_ctype_array(self._ffi, ctype, size, wrap)

def new_date_time_to_second(self) -> OwningCffiNativeHandle:
    """Create a new cffi pointer to a C struct `date_time_to_second`."""
    return new_date_time_to_second(self._ffi)

def new_double_array(
    self,
    size: int,
    wrap: bool = False,  # noqa: FBT001, FBT002
) -> Union[OwningCffiNativeHandle, CffiData]:
    """Creates a new C array of double precision floats `double[n]`.

    Args:
        size (int): array size
        wrap (bool, optional): return a "naked" cdata pointer object if False, or wrapped in a `OwningCffiNativeHandle` if True. Defaults to False.

    Returns:
        Union[OwningCffiNativeHandle,CffiData]: a (wrapper to a) cdata pointer object owning a new array of double precision floats of length `size`
    """
    return new_double_array(self._ffi, size, wrap)

def new_doubleptr_array(
    self,
    size: int,
    wrap: bool = False,  # noqa: FBT001, FBT002
) -> Union[OwningCffiNativeHandle, CffiData]:
    """Creates a new C array of pointers to double precision floats `double*[n]`.

    Args:
        size (int): array size
        wrap (bool, optional): return a "naked" cdata pointer object if False, or wrapped in a `OwningCffiNativeHandle` if True. Defaults to False.

    Returns:
        Union[OwningCffiNativeHandle,CffiData]: a (wrapper to a) cdata pointer object owning a new array of pointers to double precision floats of length `size`
    """
    return new_doubleptr_array(self._ffi, size, wrap)

def new_int_array(
    self,
    size: int,
    wrap: bool = False,  # noqa: FBT001, FBT002
) -> Union[OwningCffiNativeHandle, CffiData]:
    """Creates a new C array of integers `int[n]`.

    Args:
        size (int): array size
        wrap (bool, optional): return a "naked" cdata pointer object if False, or wrapped in a `OwningCffiNativeHandle` if True. Defaults to False.

    Returns:
        Union[OwningCffiNativeHandle,CffiData]: a (wrapper to a) cdata pointer object owning a new array of integers of length `size`
    """
    return new_int_array(self._ffi, size, wrap)

def new_int_scalar_ptr(self, value: int = 0) -> "CffiData":
    """Creates a new C array of integers.

    Args:
        value (int, optional): _description_. Defaults to 0.

    Returns:
        CffiData: a cdata pointer object owning a new pointer to a single integer valued as specified.
    """
    return new_int_scalar_ptr(self._ffi, value)

def new_native_struct(self, type_of_struct: str) -> OwningCffiNativeHandle:
    """Create a new native C struct of the specified type."""
    return OwningCffiNativeHandle(self._ffi.new(type_of_struct), type_of_struct)

def new_native_tsgeom(self) -> TimeSeriesGeometryNative:
    """Create a new native time series geometry struct."""
    return TimeSeriesGeometryNative(self._ffi)

def string_map_to_dict(self, ptr: CffiData) -> Dict[str, str]:
    """Convert if possible a cffi pointer to a `string_string_map` struct, into a dictionary.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData) to a `string_string_map` struct

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        Dict[str,str]: converted data
    """
    return string_map_to_dict(self._ffi, ptr)

def two_d_as_np_array_double(
    self,
    ptr: CffiData,
    nrow: int,
    ncol: int,
) -> np.ndarray:
    """Convert if possible a cffi pointer to a C data array, into a numpy array of double precision floats.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData)
        nrow (int): number of rows
        ncol (int): number of columns

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        np.ndarray: converted data
    """
    return two_d_as_np_array_double(self._ffi, ptr, nrow, ncol)

def two_d_np_array_double_to_native(
    self,
    data: np.ndarray,
) -> OwningCffiNativeHandle:
    """Convert if possible a cffi pointer to a C data array, into a numpy array of double precision floats.

    Args:
        data (np.ndarray): data

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        OwningCffiNativeHandle: wrapper to a C array of pointers to double precision floats of length `nrow`
    """
    return two_d_np_array_double_to_native(self._ffi, data)

def values_to_nparray(self, ptr: CffiData) -> np.ndarray:
    """Convert if possible a cffi pointer to a `values_vector` struct, into a python array.

    Args:
        ptr (CffiData): cffi pointer (FFI.CData) to a `values_vector` struct

    Raises:
        RuntimeError: conversion is not supported

    Returns:
        Dict[str,float]: converted data
    """
    return values_to_nparray(self._ffi, ptr)

def as_native(self, ffi: FFI) -> "TimeSeriesGeometryNative":
    """C-compatible representation of a time series geometry.

    Args:
        ffi (FFI): FFI instance wrapping the native compilation module owning the native memory

    Returns:
        TimeSeriesGeometryNative: wrapper around a cdata pointer to a new C struct `regular_time_series_geometry`
    """
    return TimeSeriesGeometryNative(
        ffi,
        self.start,
        self.time_step_seconds,
        self.length,
        self.time_step_code,
    )

@staticmethod
def from_native(ts_geom: "TimeSeriesGeometryNative") -> "TimeSeriesGeometry":
    """Create a simplified time series geometry from a native representation."""
    return TimeSeriesGeometry(
        ts_geom.start,
        ts_geom.time_step_seconds,
        ts_geom.length,
        ts_geom.time_step_code,
    )

def time_index(self) -> Union[List, pd.DatetimeIndex]:
    """Get the time index corresponding to this time series geometry."""
    return _ts_geom_to_time_index(self)