Dimensions

def counter(self, start: Number, step: Number,
    end: Optional[Number] = None, include_end: bool = True) -> Generator[GenericDimension, None, None]:
    """Generate a finite or infinite sequence of `GenericDimension` objects.

    This function acts as a counter for measurements, yielding `GenericDimension`
    instances at specified intervals, defined by `start`, `step`, and `end`.
    The underlying numeric values are handled as raw values of the given unit.

    Args:
        start: The starting raw value for the sequence. Defaults to 0.
        step: The increment/decrement step for the sequence.
                            Must not be 0 for an infinite sequence. Defaults to 0.
        end: The raw value at which the sequence should stop (exclusive by default).
                                     If `None`, the sequence is infinite. Defaults to `None`.
        include_end: If `True` and `end` is provided, the `end` value will be
                            included in the sequence. Defaults to `True`.

    Yields:
        GenericDimension[Any]: A `GenericDimension` object representing the current measurement in the sequence.

    Raises:
        ValueError:
            If `step` is 0 for an infinite sequence, or if `step` has the wrong
                direction for the given `start` and `end` range.
        StopIteration:
            If the iteration limit (`MAX_ITERATIONS`) is reached during an infinite sequence.

    Examples:
        >>> list(Unit.Millisecond.counter(start=0, step=10, end=30))   
        [<Time: 0.0ms (0.0)>, <Time: 10.0ms (0.01)>, <Time: 20.0ms (0.02)>, <Time: 30.0ms (0.03)>]
    """
    _start: GenericDimension = self(start)
    _step: GenericDimension = self(step)
    _end: Optional[GenericDimension] = self(end) if end is not None else None

    _start_raw: Number = _start.raw_value
    _step_raw: Number = _step.raw_value
    _end_raw: Optional[Number] = _end.raw_value if _end is not None else None

    if _end_raw is not None and include_end:
        _end_raw += _step_raw
    for i, raw_value in enumerate(counter(_start_raw, _step_raw, _end_raw)):
        value: GenericDimension = self(0)
        value._value = raw_value
        yield value
        if i == MAX_ITERATIONS:
            raise ValueError("Reached generator limit %d" % MAX_ITERATIONS)

def iterator(self, items: Sequence[Number], /, *,
             sort: bool = False,
             reverse: bool = False) -> Generator["GenericDimension[Any]", None, None]:
    """Create a sorted sequence of `GenericDimension` objects from raw numeric values.

    Args:
        items: A sequence of raw numeric values (integers or floats).
        sort: If set to `True`, the elements will be sorted before yield.
        reverse: If set to `True`, the elements are sorted in descending order. Defaults to `False`.

    Yields:
        _GenericDimensionType: A `GenericDimension` object of the specific type implied by `u`, in sorted order.

    Examples:
        >>> list(Unit.Foot.iterator([5, 1, 2], sort=True))  # Inferred as Iterable[Distance]
        [<Distance: 1.0ft (12.0)>, <Distance: 2.0ft (24.0)>, <Distance: 5.0ft (60.0)>]
    """
    iter_ = iterator(items, sort=sort, reverse=reverse)
    for v in iter_:
        yield self(v)

@staticmethod
def parse(input_: Union[str, Number],
          preferred: Optional[Union[Unit, str]] = None) -> Optional[Union[GenericDimension[Any], Any, Unit]]:
    """Parse a value with optional unit specification into a unit measurement.

    Args:
        input_: Value to parse - can be a number or string with optional unit.
        preferred: Preferred unit to use for numeric inputs, either as Unit enum or string alias.

    Returns:
        Parsed unit measurement if successful, raises exception on failure.

    Raises:
        TypeError: If input type is not supported.
        UnitAliasError: If unit alias cannot be parsed.

    Examples:
        >>> # Parse numeric value with preferred unit
        >>> Unit.parse(100, Unit.Meter)
        <Distance: 100.0m (3937.0079)>

        >>> # Parse string with embedded unit
        >>> Unit.parse('2yd')
        <Distance: 2.0yd (72.0)>

        >>> # Parse with PreferredUnit string
        >>> Unit.parse(50, 'grain')
        <Weight: 50.0gr (50.0)>
    """

    def create_as_preferred(value_):
        if isinstance(preferred, Unit):
            return preferred(float(value_))
        if isinstance(preferred, str):
            if units_ := Unit._parse_unit(preferred):
                return units_(float(value_))
        raise UnitAliasError(f"Unsupported {preferred=} unit alias")

    if isinstance(input_, (float, int)):
        return create_as_preferred(input_)

    if not isinstance(input_, str):
        raise TypeError(f"type, [str, float, int] expected for 'input_', got {type(input_)}")

    input_string = input_.replace(" ", "")
    if match := re.match(r'^-?(?:\d+\.\d*|\.\d+|\d+\.?)$', input_string):
        value = match.group()
        return create_as_preferred(value)

    if match := re.match(r'(^-?(?:\d+\.\d*|\.\d+|\d+\.?))(.*$)', input_string):
        value, alias = match.groups()
        if units := Unit._parse_unit(alias):
            return units(float(value))
        raise UnitAliasError(f"Unsupported unit {alias=}")

    raise UnitAliasError(f"Can't parse unit {input_=}")

@classmethod
def new_from_raw(cls, raw_value: float, to_units: Unit) -> Self:
    """Create a new instance from a raw value in base units.

    Args:
        raw_value: Value in the dimension's raw unit (e.g., inches for Distance).
        to_units: Target unit type for the new instance.

    Returns:
        New instance with the raw value converted to the specified units.
    """
    value_in_units = raw_value / cls._get_conversion_factor(to_units)
    return cls(value_in_units, to_units)

@classmethod
def from_raw(cls, raw_value: float, unit: Unit) -> Number:
    """Convert a raw value to the specified units.

    Args:
        raw_value: Value in the dimension's raw unit.
        unit: Target unit type for conversion.

    Returns:
        Numeric value converted to the specified units.

    Note:
        Static conversion method that doesn't create a unit instance.
    """
    cls._validate_unit_type(unit)
    return raw_value / cls._get_conversion_factor(unit)

@classmethod
def to_raw(cls, value: Number, units: Unit) -> Number:
    """Convert a value in specified units to the raw unit.

    Args:
        value: Numeric value to convert.
        units: Unit type of the input value.

    Returns:
        Value converted to the dimension's raw unit.

    Note:
        Used internally for storing values in consistent raw units.
    """
    cls._validate_unit_type(units)
    return value * cls._get_conversion_factor(units)

def convert(self, units: Unit) -> Self:
    """Convert this measurement to different units within the same dimension.

    Args:
        units: Target unit type for conversion.

    Returns:
        New instance of the same dimension type with value in target units.

    Raises:
        UnitConversionError: If target units are incompatible with this dimension.

    Examples:
        >>> distance = Distance.Meter(100)
        >>> print(f"100m = {distance.convert(Distance.Yard)}")
        100m = 109.4yd
    """
    return self.__class__.new_from_raw(self._value, units)

def get_in(self, units: Unit) -> Number:
    """Get the numeric value of this measurement in specified units.

    Args:
        units: Target unit type for the value.

    Returns:
        Numeric value in the specified units (float or int).

    Raises:
        UnitConversionError: If target units are incompatible with this dimension.

    Examples:
        >>> distance = Distance.Meter(100)
        >>> print(f"100m = {distance.get_in(Distance.Yard):.5f} yards")
        100m = 109.36133 yards
    """
    return self.__class__.from_raw(self._value, units)

@override
@classmethod
def to_raw(cls, value: Number, units: Unit) -> Number:
    """Normalize angle to (-π, π]."""
    radians = super().to_raw(value, units)
    # Normalize to [-π, π)
    r = (radians + pi) % (2.0 * pi) - pi
    return r if r > -pi else pi  # move -π to +π

@override
@classmethod
def new_from_raw(cls, raw_value: float, to_units: Unit) -> Temperature:
    """Create Temperature from raw Fahrenheit value into target units.

    Unlike other dimensions, Temperature uses affine conversions; this method
        relies on `from_raw` instead of dividing by a scale factor.
    """
    # Temperature conversion uses affine transforms; do not divide by a factor.
    value_in_units = cls.from_raw(raw_value, to_units)
    return cls(value_in_units, to_units)