"""
Float manipulation functions.

This module provides functions for working with floating-point numbers including
type conversion and parsing from strings.
"""
from __future__ import annotations

from . import StringValue
from ..frontend.base import Library, Expression, Field, Value
from ..frontend.core import Float, String
from relationalai.util.docutils import include_in_docs

__include_in_docs__ = True

# the front-end library object
library = Library("floats")

@include_in_docs
def float(value: Value) -> Expression:
    """
    Convert a value to a Float.

    Parameters
    ----------
    value: Value
        The value to convert to a `Float`.

    Returns
    -------
    Expression
        An `Expression` computing the `Float` conversion. Returns `Float`.

    Examples
    --------
    Convert various types to floats:

    >>> floats.float(42)
    >>> floats.float(Product.price)
    """
    return Float(value)

_parse_float = library.Relation("parse_float", [Field.input("value", String), Field("result", Float)])

@include_in_docs
def parse_float(value: StringValue) -> Expression:
    """
    Parse a string into a Float.

    Parameters
    ----------
    value: StringValue
        The string value to parse.

    Returns
    -------
    Expression
        An `Expression` computing the parsed `Float`. Returns `Float`.

    Examples
    --------
    Parse strings into floats:

    >>> floats.parse_float("3.14159")
    >>> floats.parse_float("2.3E40")
    >>> floats.parse_float(Measurement.value_str)
    """
    return _parse_float(value)
