0
# LibC Math Functions
1

2
C standard library math functions providing low-level mathematical operations for compatibility with C and enhanced precision control.
3

4
## Capabilities
5

6
### Sign and Magnitude Operations
7

8
Functions for manipulating the sign and magnitude components of floating-point numbers.
9

10
```typescript { .api }
11
/**
12
 * Returns a value with the magnitude of x and the sign of y
13
 * @param x - Source magnitude 
14
 * @param y - Source sign
15
 * @returns Value with magnitude of x and sign of y
16
 */
17
function copysign(x: number, y: number): number;
18
```
19

20
### Exponential Functions
21

22
Power functions using base 2 operations.
23

24
```typescript { .api }
25
/**
26
 * Returns 2^x
27
 * @param x - Exponent value  
28
 * @returns 2 raised to the power of x
29
 */
30
function exp2(x: number): number;
31
```
32

33
### Difference and Multiplication
34

35
Functions for positive differences and fused multiply-add operations.
36

37
```typescript { .api }
38
/**
39
 * Returns the positive difference between x and y, i.e. x - y if x > y, otherwise zero
40
 * @param x - First value
41
 * @param y - Second value  
42
 * @returns Positive difference or zero
43
 */
44
function fdim(x: number, y: number): number;
45

46
/**
47
 * Fused multiply-add operation: returns x * y + z
48
 * @param x - First multiplicand
49
 * @param y - Second multiplicand
50
 * @param z - Additive term
51
 * @returns Result of x * y + z
52
 */
53
function fma(x: number, y: number, z: number): number;
54
```
55

56
### Modulo Operations  
57

58
C-style modulo operations with different behavior from JavaScript's default % operator.
59

60
```typescript { .api }
61
/**
62
 * C-style modulo operation. Returns x - y * trunc(x / y)
63
 * Result will always have the sign of x
64
 * @param x - Dividend
65
 * @param y - Divisor
66
 * @returns C-style modulo result
67
 */
68
function fmod(x: number, y: number): number;
69

70
/**
71
 * IEEE remainder function. Returns x - y * round(x / y)
72
 * @param x - Dividend  
73
 * @param y - Divisor
74
 * @returns IEEE remainder
75
 */
76
function remainder(x: number, y: number): number;
77
```
78

79
### Binary Decomposition
80

81
Functions for breaking down and reconstructing floating-point numbers using binary significand and exponent.
82

83
```typescript { .api }
84
/**
85
 * Breaks number x into binary significand and exponent
86
 * Returns [significand, exponent] where x = significand * 2^exponent
87
 * Significand has absolute value in [0.5, 1.0) interval
88
 * @param x - Input number  
89
 * @returns Tuple of [significand, exponent]
90
 */
91
function frexp(x: number): [number, number];
92

93
/**
94
 * Inverse of frexp. Returns x * 2^exp  
95
 * @param x - Significand value
96
 * @param exp - Exponent value
97
 * @returns Reconstructed floating-point number
98
 */
99
function ldexp(x: number, exp: number): number;
100
```
101

102
### Integer Division
103

104
Extended division operations returning both quotient and remainder.
105

106
```typescript { .api }
107
/**
108
 * Computes both quotient and remainder of integer division x / y
109
 * @param x - Numerator (converted to integer)
110
 * @param y - Denominator (converted to integer)  
111
 * @returns Tuple of [quotient, remainder]
112
 */
113
function ldiv(x: number, y: number): [number, number];
114
```
115

116
## Usage Examples
117

118
```typescript
119
import { copysign, exp2, fdim, fma, fmod, remainder } from "@thi.ng/math/libc";
120
import { frexp, ldexp, ldiv } from "@thi.ng/math/libc";
121

122
// Sign manipulation
123
copysign(5, -2); // -5 (magnitude of 5, sign of -2)
124
copysign(-3, 4); // 3 (magnitude of 3, sign of 4)
125

126
// Power of 2 operations  
127
exp2(3); // 8 (2^3)
128
exp2(0.5); // 1.414... (2^0.5 = sqrt(2))
129

130
// Positive difference
131
fdim(5, 2); // 3 (5 - 2)
132
fdim(2, 5); // 0 (cannot be negative)
133

134
// Fused multiply-add
135
fma(2, 3, 4); // 10 (2 * 3 + 4)
136

137
// C-style vs IEEE modulo
138
fmod(-7, 3); // -1 (sign of dividend)
139
remainder(-7, 3); // 2 (IEEE remainder)
140

141
// Binary decomposition and reconstruction
142
const [sig, exp] = frexp(12); // [0.75, 4] since 12 = 0.75 * 2^4
143
ldexp(0.75, 4); // 12 (reconstructed)
144

145
// Integer division with remainder
146
ldiv(17, 5); // [3, 2] since 17 = 3 * 5 + 2
147
```