"""
Module for normalizing and adjusting periodic positional data.

This module provides array manipulation utilities to shift periodic
variables (such as angles) to a zero baseline while respecting
modulo arithmetic and handling floating-point inaccuracies.
"""

import numpy as np
from numpy import typing as npt

__all__ = ["_set_position_zero"]

def _set_position_zero(angle: npt.NDArray[np.float64],
					   period: float = 2*np.pi,
					   isclose: bool = True,
) -> npt.NDArray[np.float64]:
	"""
	Shift an array of periodic values so that its first element is zero.

	This function shifts an array of angles by subtracting its first
	element (`angle[0]`) from all elements. It then wraps the results
	within the specified `period` using a modulo operation.

	Parameters
	----------
	angle : npt.NDArray[np.float64]
		An array of angles or periodic variables. The first element
		(`angle[0]`) is used as the reference point to shift the rest of
		the array.
	period : float, optional
		The period of the cyclic variable. The default is `2 * np.pi`.
	isclose : bool, optional
		If True, accounts for the minor inaccuracies that occur in
		floating-point calculations by strictly snapping values
		that are computationally close to `0` or `period` to exactly `0`.
		The default is True.

	Returns
	-------
	npt.NDArray[np.float64]
		A new array of the same shape where the values are shifted and
		normalized within the given period.
	"""
	zero_angle = np.mod(angle + period - angle[0], period)
	if isclose:
		zero_angle[np.isclose(zero_angle, period)] = 0
		zero_angle[np.isclose(zero_angle, 0)] = 0

	return zero_angle