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