[Chapel Merge] Update the spec description of numeric types

[chapelhpcBot]

Branch: refs/heads/main
Revision: 0ce05cc83a1a3ac8cb9840414bc2a513aec0b0e2
Author: mppf
Link: Update the spec description of numeric types by mppf · Pull Request #24546 · chapel-lang/chapel · GitHub
Log Message:
Update the spec description of numeric types (#24546)

This PR adds information to the description of numeric types in the
types.rst spec chapter. It adds examples and links to later sections
since it forms a jumping-off point and it's fairly early in the spec, in
terms of chapters, for anyone reading it consecutively.

One of the main motivations of this PR is to describe in the spec the
behavior of casting between real and imag types.

I created this PR to address

Getting the imaginary part of an imaginary number

There is a slight discrepancy (in language and hence meaning) between Chapel and C with how they handle conversions between imaginary types and other types. The is related to how Chapel and C approach casting (or coercion). It might be a trap for C users and is worth noting. The way that Chapel does things is perfectly sound and robust and no change is even hinted at. This is just a note. A simpler form of this brief discussion might usefully appear in the documentation at the appropriate place…

Reviewed by @vasslitvinov - thanks!

• full comm=none testing

Compare: Comparing 740aa34437ad8517455d7c2c42c6b2e08297b216...3af8a8a6f714d90513e462a7433287dd2044284d · chapel-lang/chapel · GitHub

Diff:
M doc/rst/language/spec/conversions.rst
M doc/rst/language/spec/types.rst
https://github.com/chapel-lang/chapel/pull/24546.diff