0
# Math and Time Utilities
1

2
JavaScript-adapted mathematical functions and time/date utilities with proper type conversions and JavaScript Date integration. All math functions are implemented using JavaScript's Math object for optimal performance.
3

4
## Capabilities
5

6
### Mathematical Functions
7

8
Complete set of mathematical functions with Float and Double variants.
9

10
```kotlin { .api }
11
// Trigonometric functions
12
fun sin(x: Double): Double
13
fun sin(x: Float): Float
14
fun cos(x: Double): Double
15
fun cos(x: Float): Float  
16
fun tan(x: Double): Double
17
fun tan(x: Float): Float
18

19
// Inverse trigonometric functions
20
fun asin(x: Double): Double
21
fun asin(x: Float): Float
22
fun acos(x: Double): Double
23
fun acos(x: Float): Float
24
fun atan(x: Double): Double
25
fun atan(x: Float): Float
26
fun atan2(y: Double, x: Double): Double
27
fun atan2(y: Float, x: Float): Float
28

29
// Hyperbolic functions
30
fun sinh(x: Double): Double
31
fun sinh(x: Float): Float
32
fun cosh(x: Double): Double
33
fun cosh(x: Float): Float
34
fun tanh(x: Double): Double
35
fun tanh(x: Float): Float
36

37
// Exponential and logarithmic functions
38
fun exp(x: Double): Double
39
fun exp(x: Float): Float
40
fun expm1(x: Double): Double
41
fun expm1(x: Float): Float
42
fun log(x: Double): Double
43
fun log(x: Float): Float
44
fun log10(x: Double): Double
45
fun log10(x: Float): Float
46
fun log2(x: Double): Double
47
fun log2(x: Float): Float
48
fun ln(x: Double): Double
49
fun ln(x: Float): Float
50
fun ln1p(x: Double): Double
51
fun ln1p(x: Float): Float
52

53
// Power and root functions
54
fun pow(base: Double, exp: Double): Double
55
fun pow(base: Float, exp: Float): Float
56
fun sqrt(x: Double): Double
57
fun sqrt(x: Float): Float
58
fun hypot(x: Double, y: Double): Double
59
fun hypot(x: Float, y: Float): Float
60

61
// Rounding and absolute value
62
fun ceil(x: Double): Double
63
fun ceil(x: Float): Float
64
fun floor(x: Double): Double
65
fun floor(x: Float): Float
66
fun round(x: Double): Double
67
fun round(x: Float): Float
68
fun abs(x: Double): Double
69
fun abs(x: Float): Float
70
fun abs(x: Int): Int
71
fun abs(x: Long): Long
72

73
// Min/max functions
74
fun min(a: Double, b: Double): Double
75
fun min(a: Float, b: Float): Float
76
fun min(a: Int, b: Int): Int
77
fun min(a: Long, b: Long): Long
78
fun max(a: Double, b: Double): Double
79
fun max(a: Float, b: Float): Float
80
fun max(a: Int, b: Int): Int
81
fun max(a: Long, b: Long): Long
82

83
// Sign and truncation
84
fun sign(x: Double): Double
85
fun sign(x: Float): Float
86
fun truncate(x: Double): Double
87
fun truncate(x: Float): Float
88
```
89

90
### Time and Date Conversion
91

92
Seamless conversion between Kotlin time types and JavaScript Date objects.
93

94
```kotlin { .api }
95
/**
96
 * Convert Kotlin Instant to JavaScript Date
97
 */
98
fun Instant.toJSDate(): Date
99

100
/**
101
 * Convert JavaScript Date to Kotlin Instant  
102
 */
103
fun Date.toKotlinInstant(): Instant
104

105
/**
106
 * JavaScript Date object
107
 */
108
external class Date {
109
    constructor()
110
    constructor(milliseconds: Number)
111
    constructor(year: Int, month: Int, day: Int = 1, hours: Int = 0, minutes: Int = 0, seconds: Int = 0, ms: Int = 0)
112
    
113
    fun getTime(): Double
114
    fun getFullYear(): Int
115
    fun getMonth(): Int
116
    fun getDate(): Int
117
    fun getHours(): Int
118
    fun getMinutes(): Int
119
    fun getSeconds(): Int
120
    fun getMilliseconds(): Int
121
    
122
    fun setTime(time: Double)
123
    fun setFullYear(year: Int)
124
    fun setMonth(month: Int)
125
    fun setDate(date: Int)
126
    fun setHours(hours: Int)
127
    fun setMinutes(minutes: Int)
128
    fun setSeconds(seconds: Int)
129
    fun setMilliseconds(ms: Int)
130
    
131
    fun toISOString(): String
132
    fun toDateString(): String
133
    fun toTimeString(): String
134
    
135
    companion object {
136
        fun now(): Double
137
        fun parse(dateString: String): Double
138
    }
139
}
140
```
141

142
### Duration and Time Units
143

144
Duration units with JavaScript-specific scaling factors.
145

146
```kotlin { .api }
147
/**
148
 * Duration units adapted for JavaScript
149
 */
150
actual enum class DurationUnit(val scale: Double) {
151
    NANOSECONDS(1e-6),
152
    MICROSECONDS(1e-3), 
153
    MILLISECONDS(1.0),
154
    SECONDS(1e3),
155
    MINUTES(6e4),
156
    HOURS(3.6e6),
157
    DAYS(8.64e7);
158
    
159
    fun toMillis(value: Double): Double
160
    fun fromMillis(millis: Double): Double
161
}
162

163
/**
164
 * Convert duration value between units
165
 */
166
fun convertDurationUnit(value: Double, sourceUnit: DurationUnit, targetUnit: DurationUnit): Double
167
```
168

169
**Usage Examples:**
170

171
```kotlin
172
import kotlin.time.*
173
import kotlin.math.*
174

175
// Mathematical calculations
176
val angle = PI / 4
177
val sinValue = sin(angle) // 0.7071...
178
val cosValue = cos(angle) // 0.7071...
179

180
val logValue = ln(E) // 1.0
181
val powerValue = pow(2.0, 3.0) // 8.0
182
val sqrtValue = sqrt(16.0) // 4.0
183

184
// Rounding operations
185
val rounded = round(3.7) // 4.0
186
val floored = floor(3.7) // 3.0  
187
val ceiled = ceil(3.2) // 4.0
188

189
// Date conversions
190
val now = Clock.System.now()
191
val jsDate = now.toJSDate()
192
console.log("Current time: ${jsDate.toISOString()}")
193

194
val jsNow = Date()
195
val kotlinInstant = jsNow.toKotlinInstant()
196
console.log("Kotlin instant: $kotlinInstant")
197

198
// Duration unit conversions
199
val seconds = 5.0
200
val millis = DurationUnit.SECONDS.toMillis(seconds) // 5000.0
201
val minutes = DurationUnit.MILLISECONDS.fromMillis(millis) / 60000.0 // 0.0833...
202
```
203

204
## Types
205

206
```kotlin { .api }
207
// JavaScript Date
208
external class Date {
209
    constructor()
210
    constructor(milliseconds: Number)
211
    constructor(year: Int, month: Int, day: Int, hours: Int, minutes: Int, seconds: Int, ms: Int)
212
}
213

214
// Duration units
215
actual enum class DurationUnit {
216
    NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS
217
}
218

219
// Math constants (from kotlin.math)
220
const val PI: Double
221
const val E: Double
222
```