0
# Integer Mathematics
1

2
Specialized integer operations with overflow handling for 8-bit, 16-bit, and 32-bit signed and unsigned arithmetic.
3

4
## Capabilities
5

6
### Sign Extension
7

8
Functions for extending the sign of smaller integer types.
9

10
```typescript { .api }
11
/**
12
 * Sign extends 8-bit value to full integer
13
 * @param a - 8-bit value to sign extend
14
 * @returns Sign-extended value
15
 */
16
function signExtend8(a: number): number;
17

18
/**
19
 * Sign extends 16-bit value to full integer
20
 * @param a - 16-bit value to sign extend
21
 * @returns Sign-extended value
22
 */
23
function signExtend16(a: number): number;
24
```
25

26
### 8-bit Signed Integer Operations
27

28
Arithmetic and bitwise operations with 8-bit signed overflow behavior.
29

30
```typescript { .api }
31
/** 8-bit signed addition with overflow wrapping */
32
function addi8(a: number, b: number): number;
33

34
/** 8-bit signed subtraction with overflow wrapping */
35
function subi8(a: number, b: number): number;
36

37
/** 8-bit signed multiplication with overflow wrapping */
38
function muli8(a: number, b: number): number;
39

40
/** 8-bit signed division */
41
function divi8(a: number, b: number): number;
42

43
/** 8-bit signed bitwise AND */
44
function andi8(a: number, b: number): number;
45

46
/** 8-bit signed bitwise OR */
47
function ori8(a: number, b: number): number;
48

49
/** 8-bit signed bitwise XOR */
50
function xori8(a: number, b: number): number;
51

52
/** 8-bit signed bitwise NOT */
53
function noti8(a: number): number;
54

55
/** 8-bit signed left shift */
56
function lshifti8(a: number, b: number): number;
57

58
/** 8-bit signed right shift (arithmetic) */
59
function rshifti8(a: number, b: number): number;
60
```
61

62
### 16-bit Signed Integer Operations
63

64
Arithmetic and bitwise operations with 16-bit signed overflow behavior.
65

66
```typescript { .api }
67
/** 16-bit signed addition with overflow wrapping */
68
function addi16(a: number, b: number): number;
69

70
/** 16-bit signed subtraction with overflow wrapping */
71
function subi16(a: number, b: number): number;
72

73
/** 16-bit signed multiplication with overflow wrapping */
74
function muli16(a: number, b: number): number;
75

76
/** 16-bit signed division */
77
function divi16(a: number, b: number): number;
78

79
/** 16-bit signed bitwise AND */
80
function andi16(a: number, b: number): number;
81

82
/** 16-bit signed bitwise OR */
83
function ori16(a: number, b: number): number;
84

85
/** 16-bit signed bitwise XOR */
86
function xori16(a: number, b: number): number;
87

88
/** 16-bit signed bitwise NOT */
89
function noti16(a: number): number;
90

91
/** 16-bit signed left shift */
92
function lshifti16(a: number, b: number): number;
93

94
/** 16-bit signed right shift (arithmetic) */
95
function rshifti16(a: number, b: number): number;
96
```
97

98
### 32-bit Signed Integer Operations
99

100
Arithmetic and bitwise operations with 32-bit signed overflow behavior.
101

102
```typescript { .api }
103
/** 32-bit signed addition with overflow wrapping */
104
function addi32(a: number, b: number): number;
105

106
/** 32-bit signed subtraction with overflow wrapping */
107
function subi32(a: number, b: number): number;
108

109
/** 32-bit signed multiplication with overflow wrapping */
110
function muli32(a: number, b: number): number;
111

112
/** 32-bit signed division */
113
function divi32(a: number, b: number): number;
114

115
/** 32-bit signed bitwise AND */
116
function andi32(a: number, b: number): number;
117

118
/** 32-bit signed bitwise OR */
119
function ori32(a: number, b: number): number;
120

121
/** 32-bit signed bitwise XOR */
122
function xori32(a: number, b: number): number;
123

124
/** 32-bit signed bitwise NOT */
125
function noti32(a: number): number;
126

127
/** 32-bit signed left shift */
128
function lshifti32(a: number, b: number): number;
129

130
/** 32-bit signed right shift (arithmetic) */
131
function rshifti32(a: number, b: number): number;
132
```
133

134
### 8-bit Unsigned Integer Operations
135

136
Arithmetic and bitwise operations with 8-bit unsigned overflow behavior.
137

138
```typescript { .api }
139
/** 8-bit unsigned addition with overflow wrapping */
140
function addu8(a: number, b: number): number;
141

142
/** 8-bit unsigned subtraction with underflow wrapping */
143
function subu8(a: number, b: number): number;
144

145
/** 8-bit unsigned multiplication with overflow wrapping */
146
function mulu8(a: number, b: number): number;
147

148
/** 8-bit unsigned division */
149
function divu8(a: number, b: number): number;
150

151
/** 8-bit unsigned bitwise AND */
152
function andu8(a: number, b: number): number;
153

154
/** 8-bit unsigned bitwise OR */
155
function oru8(a: number, b: number): number;
156

157
/** 8-bit unsigned bitwise XOR */
158
function xoru8(a: number, b: number): number;
159

160
/** 8-bit unsigned bitwise NOT */
161
function notu8(a: number): number;
162

163
/** 8-bit unsigned left shift */
164
function lshiftu8(a: number, b: number): number;
165

166
/** 8-bit unsigned right shift (logical) */
167
function rshiftu8(a: number, b: number): number;
168
```
169

170
### 16-bit Unsigned Integer Operations
171

172
Arithmetic and bitwise operations with 16-bit unsigned overflow behavior.
173

174
```typescript { .api }
175
/** 16-bit unsigned addition with overflow wrapping */
176
function addu16(a: number, b: number): number;
177

178
/** 16-bit unsigned subtraction with underflow wrapping */
179
function subu16(a: number, b: number): number;
180

181
/** 16-bit unsigned multiplication with overflow wrapping */
182
function mulu16(a: number, b: number): number;
183

184
/** 16-bit unsigned division */
185
function divu16(a: number, b: number): number;
186

187
/** 16-bit unsigned bitwise AND */
188
function andu16(a: number, b: number): number;
189

190
/** 16-bit unsigned bitwise OR */
191
function oru16(a: number, b: number): number;
192

193
/** 16-bit unsigned bitwise XOR */
194
function xoru16(a: number, b: number): number;
195

196
/** 16-bit unsigned bitwise NOT */
197
function notu16(a: number): number;
198

199
/** 16-bit unsigned left shift */
200
function lshiftu16(a: number, b: number): number;
201

202
/** 16-bit unsigned right shift (logical) */
203
function rshiftu16(a: number, b: number): number;
204
```
205

206
### 32-bit Unsigned Integer Operations
207

208
Arithmetic and bitwise operations with 32-bit unsigned overflow behavior.
209

210
```typescript { .api }
211
/** 32-bit unsigned addition with overflow wrapping */
212
function addu32(a: number, b: number): number;
213

214
/** 32-bit unsigned subtraction with underflow wrapping */
215
function subu32(a: number, b: number): number;
216

217
/** 32-bit unsigned multiplication with overflow wrapping */
218
function mulu32(a: number, b: number): number;
219

220
/** 32-bit unsigned division */
221
function divu32(a: number, b: number): number;
222

223
/** 32-bit unsigned bitwise AND */
224
function andu32(a: number, b: number): number;
225

226
/** 32-bit unsigned bitwise OR */
227
function oru32(a: number, b: number): number;
228

229
/** 32-bit unsigned bitwise XOR */
230
function xoru32(a: number, b: number): number;
231

232
/** 32-bit unsigned bitwise NOT */
233
function notu32(a: number): number;
234

235
/** 32-bit unsigned left shift */
236
function lshiftu32(a: number, b: number): number;
237

238
/** 32-bit unsigned right shift (logical) */
239
function rshiftu32(a: number, b: number): number;
240
```
241

242
**Usage Examples:**
243

244
```typescript
245
import { 
246
  addi8, muli16, signExtend8, 
247
  addu32, lshiftu16, andi32 
248
} from "@thi.ng/math/int";
249

250
// 8-bit signed arithmetic with overflow
251
const overflow = addi8(127, 1); // -128 (wraps around)
252
const signExtended = signExtend8(overflow); // Properly sign-extended
253

254
// 16-bit unsigned multiplication
255
const product = mulu16(300, 300); // Handles 16-bit overflow
256

257
// 32-bit operations for larger values
258
const sum = addu32(0xFFFFFFFF, 1); // 0 (32-bit unsigned overflow)
259
const shifted = lshiftu16(0x8000, 1); // 0 (shifts out high bit)
260

261
// Bitwise operations
262
const masked = andi32(0x12345678, 0xFF00FF00); // Mask specific bits
263
```