0
# Data Type Functions
1

2
Data type utilities for type checking, conversion, and promotion. These functions help manage data types and ensure compatibility between operations on GPU arrays.
3

4
## Capabilities
5

6
### Type Checking and Casting
7

8
Functions to check type compatibility and determine safe casting between data types.
9

10
```python { .api }
11
def can_cast(from_, to, casting='safe'):
12
    """
13
    Returns True if cast between data types can occur according to casting rule.
14
    
15
    Parameters:
16
    - from_: dtype or cupy.ndarray, source data type or array
17
    - to: dtype, target data type
18
    - casting: {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, casting rule
19
    
20
    Returns:
21
    bool: True if cast is possible under specified rule
22
    """
23

24
def result_type(*arrays_and_dtypes):
25
    """
26
    Returns the type that results from applying NumPy type promotion rules.
27
    
28
    Parameters:
29
    - arrays_and_dtypes: sequence of arrays and dtypes
30
    
31
    Returns:
32
    numpy.dtype: resulting data type after promotion
33
    """
34

35
def common_type(*arrays):
36
    """
37
    Return a scalar type which is common to the input arrays.
38
    
39
    Parameters:
40
    - arrays: sequence of cupy.ndarray
41
    
42
    Returns:
43
    type: common scalar type for floating point arrays
44
    """
45

46
def min_scalar_type(a):
47
    """
48
    For scalar a, returns the data type with the smallest size and smallest 
49
    scalar kind which can hold its value.
50
    
51
    Parameters:
52
    - a: scalar, input scalar value
53
    
54
    Returns:
55
    numpy.dtype: smallest suitable data type
56
    """
57

58
def promote_types(type1, type2):
59
    """
60
    Returns the data type with the smallest size and smallest scalar kind 
61
    to which both type1 and type2 may be safely cast.
62
    
63
    Parameters:
64
    - type1: numpy.dtype, first data type
65
    - type2: numpy.dtype, second data type  
66
    
67
    Returns:
68
    numpy.dtype: promoted data type
69
    """
70
```
71

72
### Data Type Information
73

74
Functions to obtain information about data types including precision and ranges.
75

76
```python { .api }
77
def finfo(dtype):
78
    """
79
    Machine limits for floating point types.
80
    
81
    Parameters:
82
    - dtype: float, dtype, or instance, floating point data type
83
    
84
    Returns:
85
    numpy.finfo: object with floating point type information
86
    """
87

88
def iinfo(int_type):
89
    """
90
    Machine limits for integer types.
91
    
92
    Parameters:
93
    - int_type: integer type, dtype, or instance
94
    
95
    Returns:
96
    numpy.iinfo: object with integer type information
97
    """
98

99
def issubdtype(arg1, arg2):
100
    """
101
    Returns True if first argument is a typecode lower/equal in type hierarchy.
102
    
103
    Parameters:
104
    - arg1: numpy.dtype, data type to check
105
    - arg2: numpy.dtype, data type to compare against
106
    
107
    Returns:
108
    bool: True if arg1 is subtype of arg2
109
    """
110

111
def dtype(obj, align=False, copy=None):
112
    """
113
    Create a data type object.
114
    
115
    Parameters:
116
    - obj: object to convert to dtype
117
    - align: bool, add padding to match hardware alignment
118
    - copy: bool, make a copy of dtype object
119
    
120
    Returns:
121
    numpy.dtype: data type object
122
    """
123
```
124

125
### Legacy Type Functions
126

127
Legacy functions for backwards compatibility with older NumPy versions.
128

129
```python { .api }
130
def mintypecode(typechars, typeset='GDFgdf', default='d'):
131
    """
132
    Return the character for the minimum-size type which can represent 
133
    the data types in typechars.
134
    
135
    Parameters:
136
    - typechars: list of strings, type characters
137
    - typeset: str, set of type characters to choose from  
138
    - default: str, default type character
139
    
140
    Returns:
141
    str: type character for minimum type
142
    """
143

144
def typename(char):
145
    """
146
    Return a description for the given data type code.
147
    
148
    Parameters:
149
    - char: str, data type character code
150
    
151
    Returns:
152
    str: description of data type
153
    """
154
```
155

156
### Data Type Constants
157

158
Available data types and type categories inherited from NumPy.
159

160
```python { .api }
161
# Numeric type hierarchy
162
class generic: ...
163
class number(generic): ...
164
class integer(number): ...
165
class signedinteger(integer): ...
166
class unsignedinteger(integer): ...
167
class inexact(number): ...
168
class floating(inexact): ...
169
class complexfloating(inexact): ...
170

171
# Boolean type
172
class bool_(generic): ...
173

174
# Integer types
175
class int8(signedinteger): ...
176
class int16(signedinteger): ...
177
class int32(signedinteger): ...
178
class int64(signedinteger): ...
179

180
class uint8(unsignedinteger): ...
181
class uint16(unsignedinteger): ...
182
class uint32(unsignedinteger): ...
183
class uint64(unsignedinteger): ...
184

185
# Floating point types  
186
class float16(floating): ...
187
class float32(floating): ...
188
class float64(floating): ...
189

190
# Complex types
191
class complex64(complexfloating): ...
192
class complex128(complexfloating): ...
193

194
# Platform-dependent types
195
int_ = int64    # Platform integer
196
intp = int64    # Pointer-sized integer
197
float_ = float64  # Platform float
198
complex_ = complex128  # Platform complex
199
```
200

201
### Usage Examples
202

203
```python
204
import cupy as cp
205
import numpy as np
206

207
# Type checking and casting
208
arr_int = cp.array([1, 2, 3], dtype=cp.int32)
209
arr_float = cp.array([1.0, 2.0, 3.0], dtype=cp.float64)
210

211
# Check if casting is safe
212
can_cast_safe = cp.can_cast(arr_int.dtype, cp.float64, 'safe')  # True
213
can_cast_unsafe = cp.can_cast(arr_float.dtype, cp.int32, 'safe')  # False
214

215
# Find common result type
216
result_dtype = cp.result_type(arr_int, arr_float)  # float64
217

218
# Type promotion
219
promoted = cp.promote_types(cp.int32, cp.float32)  # float64
220

221
# Get type information
222
float_info = cp.finfo(cp.float32)
223
print(f"Float32 precision: {float_info.precision}")
224
print(f"Float32 range: {float_info.min} to {float_info.max}")
225

226
int_info = cp.iinfo(cp.int16)
227
print(f"Int16 range: {int_info.min} to {int_info.max}")
228

229
# Check type hierarchy
230
is_sub = cp.issubdtype(cp.int32, cp.integer)  # True
231
is_sub2 = cp.issubdtype(cp.float32, cp.integer)  # False
232

233
# Find minimum type for scalar
234
scalar_val = 100
235
min_type = cp.min_scalar_type(scalar_val)  # int8 (if 100 fits)
236

237
# Create dtype objects
238
dt1 = cp.dtype('f4')  # float32
239
dt2 = cp.dtype(cp.int64)  # int64
240
dt3 = cp.dtype([('x', cp.float32), ('y', cp.float32)])  # structured type
241

242
# Common type for arrays
243
common = cp.common_type(arr_int, arr_float)  # <class 'numpy.float64'>
244

245
# Legacy functions (mainly for compatibility)
246
type_char = cp.mintypecode(['i', 'f'], 'GDFgdf')  # 'd' for float64
247
type_desc = cp.typename('d')  # Description of float64
248
```