0
# Checking Functions
1

2
Validation functions that test whether inputs can be converted to specific numeric types without performing the actual conversion. These functions are optimized for speed and enable conditional processing, input validation, and type checking workflows.
3

4
## Capabilities
5

6
### Real Number Checking
7

8
Tests whether input can be converted to either an integer or float, providing the most general numeric validation.
9

10
```python { .api }
11
def check_real(
12
    x,
13
    *,
14
    consider=None,
15
    inf=NUMBER_ONLY,
16
    nan=NUMBER_ONLY,
17
    allow_underscores=False
18
) -> bool:
19
    """
20
    Check if input can be converted to int or float.
21

22
    Parameters:
23
    - x: Input to check (any type)
24
    - consider: Restrict checking to STRING_ONLY, NUMBER_ONLY, or None (both)
25
    - inf: How to handle infinity (NUMBER_ONLY, STRING_ONLY, ALLOWED, DISALLOWED)
26
    - nan: How to handle NaN (NUMBER_ONLY, STRING_ONLY, ALLOWED, DISALLOWED)
27
    - allow_underscores: Allow underscores in numeric strings (default: False)
28

29
    Returns:
30
    - bool: True if convertible to int or float, False otherwise
31
    """
32
```
33

34
#### Usage Examples
35

36
```python
37
from fastnumbers import check_real, STRING_ONLY, NUMBER_ONLY, ALLOWED, DISALLOWED
38

39
# Basic checking
40
check_real('123')      # True
41
check_real('123.45')   # True
42
check_real(42)         # True
43
check_real(3.14)       # True
44
check_real('invalid')  # False
45
check_real([1, 2, 3])  # False
46

47
# Type filtering
48
check_real('123', consider=STRING_ONLY)   # True
49
check_real(123, consider=STRING_ONLY)     # False
50
check_real('123', consider=NUMBER_ONLY)   # False
51
check_real(123, consider=NUMBER_ONLY)     # True
52

53
# Special value handling
54
check_real('inf')                      # False (NUMBER_ONLY default)
55
check_real('inf', inf=ALLOWED)         # True
56
check_real(float('inf'))               # True (numeric inf)
57
check_real('inf', inf=STRING_ONLY)     # True
58
check_real(float('inf'), inf=STRING_ONLY)  # False
59

60
# Unicode and formatting
61
check_real('\u2164')      # True (Roman numeral V)
62
check_real('1_000', allow_underscores=True)  # True
63
check_real('1_000')       # False (underscores not allowed by default)
64
```
65

66
### Float Checking
67

68
Tests whether input can be specifically converted to a float, with optional strict mode for more precise validation.
69

70
```python { .api }
71
def check_float(
72
    x,
73
    *,
74
    consider=None,
75
    inf=NUMBER_ONLY,
76
    nan=NUMBER_ONLY,
77
    strict=False,
78
    allow_underscores=False
79
) -> bool:
80
    """
81
    Check if input can be converted to float.
82

83
    Parameters:
84
    - x: Input to check (any type)
85
    - consider: Restrict checking to STRING_ONLY, NUMBER_ONLY, or None (both)
86
    - inf: How to handle infinity (NUMBER_ONLY, STRING_ONLY, ALLOWED, DISALLOWED)
87
    - nan: How to handle NaN (NUMBER_ONLY, STRING_ONLY, ALLOWED, DISALLOWED)
88
    - strict: Enable strict float checking (default: False)
89
    - allow_underscores: Allow underscores in numeric strings (default: False)
90

91
    Returns:
92
    - bool: True if convertible to float, False otherwise
93
    """
94
```
95

96
#### Usage Examples
97

98
```python
99
from fastnumbers import check_float
100

101
# Basic checking
102
check_float('123.45')    # True
103
check_float('123')       # True (int strings can become floats)
104
check_float(42)          # True (ints can become floats)
105
check_float('1e5')       # True (scientific notation)
106
check_float('invalid')   # False
107

108
# Strict mode
109
check_float('123', strict=False)    # True
110
check_float('123', strict=True)     # False (not a "true" float)
111
check_float('123.0', strict=True)   # True
112

113
# Special formatting
114
check_float('1.23e-4')     # True
115
check_float('.5')          # True
116
check_float('5.')          # True
117
check_float('  42.0  ')    # True (whitespace ignored)
118
```
119

120
### Integer Checking
121

122
Tests whether input can be converted to an integer, with support for different number bases.
123

124
```python { .api }
125
def check_int(
126
    x,
127
    *,
128
    consider=None,
129
    base=0,
130
    allow_underscores=False
131
) -> bool:
132
    """
133
    Check if input can be converted to int.
134

135
    Parameters:
136
    - x: Input to check (any type)
137
    - consider: Restrict checking to STRING_ONLY, NUMBER_ONLY, or None (both)
138
    - base: Number base for checking (0 for auto-detect, 2-36, default: 0)
139
    - allow_underscores: Allow underscores in numeric strings (default: False)
140

141
    Returns:
142
    - bool: True if convertible to int, False otherwise
143
    """
144
```
145

146
#### Usage Examples
147

148
```python
149
from fastnumbers import check_int
150

151
# Basic checking
152
check_int('123')       # True
153
check_int(456)         # True
154
check_int('123.45')    # False (has decimal part)
155
check_int(78.0)        # True (whole number float)
156
check_int(78.5)        # False (fractional part)
157

158
# Base checking
159
check_int('ff', base=16)      # True (hex)
160
check_int('1010', base=2)     # True (binary)
161
check_int('123', base=8)      # True (octal)
162
check_int('gg', base=16)      # False (invalid hex)
163

164
# Auto-detection (base=0)
165
check_int('0xff')      # True (hex prefix)
166
check_int('0b1010')    # True (binary prefix)
167
check_int('0o123')     # True (octal prefix)
168

169
# Type filtering
170
check_int('123', consider=STRING_ONLY)   # True
171
check_int(123, consider=STRING_ONLY)     # False
172
```
173

174
### Integer-like Checking
175

176
Tests whether input represents an integer-like value (whole numbers), even if stored as float or string.
177

178
```python { .api }
179
def check_intlike(
180
    x,
181
    *,
182
    consider=None,
183
    allow_underscores=False
184
) -> bool:
185
    """
186
    Check if input represents an integer-like value.
187

188
    Parameters:
189
    - x: Input to check (any type)
190
    - consider: Restrict checking to STRING_ONLY, NUMBER_ONLY, or None (both)
191
    - allow_underscores: Allow underscores in numeric strings (default: False)
192

193
    Returns:
194
    - bool: True if represents whole number, False otherwise
195
    """
196
```
197

198
#### Usage Examples
199

200
```python
201
from fastnumbers import check_intlike
202

203
# Basic checking
204
check_intlike('123')      # True
205
check_intlike('123.0')    # True (whole number)
206
check_intlike('123.45')   # False (has fractional part)
207
check_intlike(456)        # True
208
check_intlike(456.0)      # True (whole number float)
209
check_intlike(456.7)      # False (has fractional part)
210

211
# Edge cases
212
check_intlike('0')        # True
213
check_intlike('-123')     # True
214
check_intlike('+456')     # True
215
check_intlike('1e2')      # True (100.0)
216
check_intlike('1e-1')     # False (0.1)
217

218
# Formatting
219
check_intlike('  123  ')  # True (whitespace ignored)
220
check_intlike('1_000', allow_underscores=True)  # True
221
```
222

223
## Consider Parameter Options
224

225
The `consider` parameter allows filtering by input type:
226

227
- **`None`** (default): Check both string and numeric inputs
228
- **`STRING_ONLY`**: Only validate string inputs, return False for numbers
229
- **`NUMBER_ONLY`**: Only validate numeric inputs, return False for strings
230

231
```python
232
from fastnumbers import check_real, STRING_ONLY, NUMBER_ONLY
233

234
# Mixed checking (default)
235
check_real('123')    # True
236
check_real(123)      # True
237

238
# String-only checking
239
check_real('123', consider=STRING_ONLY)    # True
240
check_real(123, consider=STRING_ONLY)      # False
241

242
# Number-only checking  
243
check_real('123', consider=NUMBER_ONLY)    # False
244
check_real(123, consider=NUMBER_ONLY)      # True
245
```
246

247
## Special Value Handling
248

249
The `inf` and `nan` parameters control how infinity and NaN values are treated:
250

251
- **`NUMBER_ONLY`** (default): Allow numeric inf/nan, reject string inf/nan
252
- **`STRING_ONLY`**: Allow string inf/nan, reject numeric inf/nan  
253
- **`ALLOWED`**: Allow both string and numeric inf/nan
254
- **`DISALLOWED`**: Reject all inf/nan values
255

256
```python
257
from fastnumbers import check_float, ALLOWED, DISALLOWED, STRING_ONLY
258

259
# Default behavior (NUMBER_ONLY)
260
check_float(float('inf'))    # True
261
check_float('inf')           # False
262

263
# Allow all inf/nan
264
check_float('inf', inf=ALLOWED)        # True
265
check_float(float('inf'), inf=ALLOWED) # True
266

267
# Disallow all inf/nan
268
check_float(float('inf'), inf=DISALLOWED)  # False
269
check_float('inf', inf=DISALLOWED)         # False
270

271
# String inf/nan only
272
check_float('inf', inf=STRING_ONLY)        # True
273
check_float(float('inf'), inf=STRING_ONLY) # False
274
```
275

276
## Deprecated Functions
277

278
The following functions are maintained for backward compatibility but are deprecated in favor of the newer `check_*` equivalents:
279

280
### isreal (Deprecated)
281

282
```python { .api }
283
def isreal(
284
    x,
285
    *,
286
    str_only=False,
287
    num_only=False,
288
    allow_inf=False,
289
    allow_nan=False,
290
    allow_underscores=True
291
) -> bool:
292
    """
293
    DEPRECATED: Use check_real() instead.
294
    
295
    Check if input can be converted to int or float.
296
    
297
    Parameters:
298
    - x: Input to check (any type)
299
    - str_only: Only check string inputs (default: False)
300
    - num_only: Only check numeric inputs (default: False)
301
    - allow_inf: Allow infinity values (default: False)
302
    - allow_nan: Allow NaN values (default: False)
303
    - allow_underscores: Allow underscores in numeric strings (default: True)
304
    
305
    Returns:
306
    - bool: True if convertible to int or float, False otherwise
307
    """
308
```
309

310
### isfloat (Deprecated)
311

312
```python { .api }
313
def isfloat(
314
    x,
315
    *,
316
    str_only=False,
317
    num_only=False,
318
    allow_inf=False,
319
    allow_nan=False,
320
    allow_underscores=True
321
) -> bool:
322
    """
323
    DEPRECATED: Use check_float() instead.
324
    
325
    Check if input can be converted to float.
326
    
327
    Parameters:
328
    - x: Input to check (any type)
329
    - str_only: Only check string inputs (default: False)
330
    - num_only: Only check numeric inputs (default: False)
331
    - allow_inf: Allow infinity values (default: False)
332
    - allow_nan: Allow NaN values (default: False)
333
    - allow_underscores: Allow underscores in numeric strings (default: True)
334
    
335
    Returns:
336
    - bool: True if convertible to float, False otherwise
337
    """
338
```
339

340
### isint (Deprecated)
341

342
```python { .api }
343
def isint(
344
    x,
345
    *,
346
    str_only=False,
347
    num_only=False,
348
    base=0,
349
    allow_underscores=True
350
) -> bool:
351
    """
352
    DEPRECATED: Use check_int() instead.
353
    
354
    Check if input can be converted to int.
355
    
356
    Parameters:
357
    - x: Input to check (any type)
358
    - str_only: Only check string inputs (default: False)
359
    - num_only: Only check numeric inputs (default: False)
360
    - base: Number base for checking (0 for auto-detect, 2-36, default: 0)
361
    - allow_underscores: Allow underscores in numeric strings (default: True)
362
    
363
    Returns:
364
    - bool: True if convertible to int, False otherwise
365
    """
366
```
367

368
### isintlike (Deprecated)
369

370
```python { .api }
371
def isintlike(
372
    x,
373
    *,
374
    str_only=False,
375
    num_only=False,
376
    allow_underscores=True
377
) -> bool:
378
    """
379
    DEPRECATED: Use check_intlike() instead.
380
    
381
    Check if input represents an integer-like value.
382
    
383
    Parameters:
384
    - x: Input to check (any type)
385
    - str_only: Only check string inputs (default: False)
386
    - num_only: Only check numeric inputs (default: False)
387
    - allow_underscores: Allow underscores in numeric strings (default: True)
388
    
389
    Returns:
390
    - bool: True if represents whole number, False otherwise
391
    """
392
```
393

394
## Performance Characteristics
395

396
These checking functions are highly optimized and significantly faster than attempting conversion and catching exceptions. They use the same underlying C++ implementation as conversion functions but skip the actual conversion step, making them ideal for:
397

398
- Input validation in loops
399
- Conditional processing pipelines  
400
- Type checking in data processing
401
- Filtering mixed-type data structures