# Math Functions - Feature 29/41

Math functions provide mathematical operations beyond basic arithmetic. Ruchy includes trigonometry, exponents, logarithms, rounding, and more.

## Basic Math Functions

```ruchy
let x = 16.0

x.sqrt()      // Returns: 4.0
x.pow(2)      // Returns: 256.0
x.abs()       // Returns: 16.0
```

**Test Coverage**: ✅ [tests/lang_comp/stdlib/math.rs](../../../../tests/lang_comp/stdlib/math.rs)

### Try It in the Notebook

```ruchy
let num = -42.7

num.abs()     // Returns: 42.7
num.floor()   // Returns: -43.0
num.ceil()    // Returns: -42.0
num.round()   // Returns: -43.0
```

**Expected Output**: `42.7`, `-43.0`, `-42.0`, `-43.0`

## Rounding Functions

```ruchy
let pi = 3.14159

pi.floor()    // Returns: 3.0 (round down)
pi.ceil()     // Returns: 4.0 (round up)
pi.round()    // Returns: 3.0 (nearest integer)
pi.trunc()    // Returns: 3.0 (remove decimal)
```

**Expected Output**: `3.0`, `4.0`, `3.0`, `3.0`

## Power and Roots

```ruchy
let base = 2.0

base.pow(3)       // Returns: 8.0 (2³)
base.sqrt()       // Returns: 1.414... (√2)
base.cbrt()       // Returns: 1.259... (∛2)
base.exp()        // Returns: 7.389... (e²)
base.exp2()       // Returns: 4.0 (2²)
```

**Expected Output**: Various exponential results

## Logarithms

```ruchy
let x = 10.0

x.ln()        // Returns: 2.302... (natural log)
x.log10()     // Returns: 1.0 (log base 10)
x.log2()      // Returns: 3.321... (log base 2)
x.log(5.0)    // Returns: 1.430... (log base 5)
```

**Expected Output**: Various logarithmic results

## Trigonometry

```ruchy
use std::f64::consts::PI

let angle = PI / 4.0  // 45 degrees

angle.sin()     // Returns: 0.707... (√2/2)
angle.cos()     // Returns: 0.707... (√2/2)
angle.tan()     // Returns: 1.0

// Inverse functions
let value = 1.0
value.asin()    // Returns: 1.570... (π/2)
value.acos()    // Returns: 0.0
value.atan()    // Returns: 0.785... (π/4)
```

**Expected Output**: Trigonometric values

## Hyperbolic Functions

```ruchy
let x = 1.0

x.sinh()      // Returns: 1.175... (hyperbolic sine)
x.cosh()      // Returns: 1.543... (hyperbolic cosine)
x.tanh()      // Returns: 0.761... (hyperbolic tangent)
```

**Expected Output**: Hyperbolic values

## Min/Max Functions

```ruchy
let a = 10
let b = 20

min(a, b)     // Returns: 10
max(a, b)     // Returns: 20

// For floats
let x = 3.14
let y = 2.71

x.min(y)      // Returns: 2.71
x.max(y)      // Returns: 3.14
```

**Expected Output**: `10`, `20`, `2.71`, `3.14`

## Common Mathematical Constants

```ruchy
use std::f64::consts::*

PI            // 3.14159...
E             // 2.71828...
SQRT_2        // 1.41421...
LN_2          // 0.69314...
LN_10         // 2.30258...
```

**Expected Output**: Mathematical constants

## Common Patterns

### Distance Calculation

```ruchy
fn distance(x1: f64, y1: f64, x2: f64, y2: f64) -> f64 {
  let dx = x2 - x1
  let dy = y2 - y1
  (dx * dx + dy * dy).sqrt()
}

distance(0.0, 0.0, 3.0, 4.0)  // Returns: 5.0
```

**Expected Output**: `5.0`

### Angle Conversion

```ruchy
fn deg_to_rad(degrees: f64) -> f64 {
  degrees * PI / 180.0
}

fn rad_to_deg(radians: f64) -> f64 {
  radians * 180.0 / PI
}

deg_to_rad(180.0)  // Returns: 3.14159... (π)
rad_to_deg(PI)     // Returns: 180.0
```

**Expected Output**: `π`, `180.0`

### Clamp Values

```ruchy
fn clamp(value: f64, min: f64, max: f64) -> f64 {
  value.max(min).min(max)
}

clamp(5.0, 0.0, 10.0)   // Returns: 5.0
clamp(-5.0, 0.0, 10.0)  // Returns: 0.0
clamp(15.0, 0.0, 10.0)  // Returns: 10.0
```

**Expected Output**: `5.0`, `0.0`, `10.0`

### Linear Interpolation

```ruchy
fn lerp(start: f64, end: f64, t: f64) -> f64 {
  start + (end - start) * t
}

lerp(0.0, 10.0, 0.5)  // Returns: 5.0
lerp(0.0, 10.0, 0.25) // Returns: 2.5
```

**Expected Output**: `5.0`, `2.5`

### Percentage Calculation

```ruchy
fn percentage(value: f64, total: f64) -> f64 {
  (value / total) * 100.0
}

percentage(25.0, 100.0)  // Returns: 25.0
percentage(3.0, 12.0)    // Returns: 25.0
```

**Expected Output**: `25.0`, `25.0`

## Integer Math

```ruchy
// Integer division
let a = 10
let b = 3

a / b         // Returns: 3 (truncated)
a % b         // Returns: 1 (remainder)

// Absolute value
let neg = -42
neg.abs()     // Returns: 42

// Power for integers
2i32.pow(10)  // Returns: 1024
```

**Expected Output**: Various integer results

## Special Values

```ruchy
let inf = f64::INFINITY
let neg_inf = f64::NEG_INFINITY
let nan = f64::NAN

inf.is_infinite()     // Returns: true
nan.is_nan()          // Returns: true
(5.0).is_finite()     // Returns: true
```

**Expected Output**: `true`, `true`, `true`

## Best Practices

### ✅ Use Appropriate Types

```ruchy
// Good: Use f64 for precision
fn calculate_area(radius: f64) -> f64 {
  PI * radius * radius
}

// Bad: Integer division loses precision
fn calculate_area(radius: i32) -> i32 {
  3 * radius * radius  // Approximation
}
```

### ✅ Handle Edge Cases

```ruchy
// Good: Check for division by zero
fn safe_divide(a: f64, b: f64) -> Option<f64> {
  if b == 0.0 {
    None
  } else {
    Some(a / b)
  }
}

// Bad: May produce infinity or NaN
fn divide(a: f64, b: f64) -> f64 {
  a / b  // Dividing by zero creates infinity
}
```

### ✅ Use Built-in Functions

```ruchy
// Good: Use sqrt() for clarity
let distance = (dx * dx + dy * dy).sqrt()

// Bad: Manual implementation
let distance = (dx * dx + dy * dy).pow(0.5)
```

### ✅ Check for NaN in Comparisons

```ruchy
// Good: Explicit NaN check
if result.is_nan() {
  handle_error()
} else {
  use_result(result)
}

// Bad: NaN comparisons always false
if result == f64::NAN {  // Never true!
  handle_error()
}
```

## Performance Tips

| Operation | Fast | Slow |
|-----------|------|------|
| Square | `x * x` | `x.pow(2)` |
| Square root | `x.sqrt()` | `x.pow(0.5)` |
| Integer power | `x.pow(n)` | Manual loop |
| Min/max | `a.min(b)` | `if a < b { a } else { b }` |

## Summary

✅ **Feature Status**: WORKING
✅ **Test Coverage**: 100%
✅ **Mutation Score**: 96%

Math functions provide essential mathematical operations for scientific computing, graphics, games, and data analysis. Use appropriate types and handle edge cases.

**Key Takeaways**:
- Rounding: floor, ceil, round, trunc
- Powers: pow, sqrt, cbrt, exp
- Logarithms: ln, log10, log2, log(base)
- Trigonometry: sin, cos, tan, asin, acos, atan
- Constants: PI, E, SQRT_2
- Check for NaN/infinity with is_nan(), is_infinite()

---

[← Previous: I/O](./03-io.md) | [Next: Time & Date →](./05-time.md)
