# Promotion Rules
> Return the array [data type][@stdlib/array/dtypes] with the smallest size and closest "kind" to which array [data types][@stdlib/array/dtypes] can be **safely** cast.
## Usage
```javascript
var promotionRules = require( '@stdlib/array/promotion-rules' );
```
#### promotionRules( \[dtype1, dtype2] )
If provided [data types][@stdlib/array/dtypes], returns the array [data type][@stdlib/array/dtypes] with the smallest size and closest "kind" to which array [data types][@stdlib/array/dtypes] can be **safely** cast.
```javascript
var out = promotionRules( 'float32', 'uint32' );
// returns 'float64'
```
If not provided [data types][@stdlib/array/dtypes], the function returns a promotion table.
```javascript
var out = promotionRules();
// returns {...}
var f32 = out[ 'float32' ];
// returns {...}
var rule = f32[ 'uint32' ];
// returns 'float64'
```
If provided an unrecognized or unsupported `dtype`, the function returns `null`.
```javascript
var out = promotionRules( 'foo', 'generic' );
// returns null
```
## Notes
- If a [data type][@stdlib/array/dtypes] to which [data types][@stdlib/array/dtypes] can be safely cast does **not** exist (or is not supported), the function returns `-1`.
## Examples
```javascript
var dtypes = require( '@stdlib/array/dtypes' );
var promotionRules = require( '@stdlib/array/promotion-rules' );
var DTYPES;
var dt1;
var dt2;
var dt;
var i;
var j;
// Get the list of supported array data types:
DTYPES = dtypes();
// Print the promotion rule for each pair of array data types...
for ( i = 0; i < DTYPES.length; i++ ) {
dt1 = DTYPES[ i ];
for ( j = 0; j < DTYPES.length; j++ ) {
dt2 = DTYPES[ j ];
dt = promotionRules( dt1, dt2 );
console.log( '(%s, %s) => %s', dt1, dt2, dt );
}
}
```
[@stdlib/array/dtypes]: https://www.npmjs.com/package/@stdlib/array/tree/main/dtypes