Numeric Literal Suffixes documentation needs to be expanded

[vexx32]

Issue Details

Per PowerShell/PowerShell#7901 and PowerShell/PowerShell#7813

Also ref: PowerShell/PowerShell#7557

With these changes approved by PowerShell committee and partially merged to master already, we need to add documentation for the new numeric literals.

The linked PR descriptions have fairly extensive details, but see also a blog post I posted in order to better explain the details in places.

Of specific note:

• Smaller numeric types can and will fail to parse if specified with a multiplier that causes the value to exceed their range, e.g., 200sgb will fail parsing checks as the final value exceeds [short]::MaxValue
  • Yes, specifying huge values will still fail if you ask for a short result, just like casting to [short] will fail. E.g., 40000s will fail.
• The suffixes take on an additional function with hexadecimal literals, which causes them to be parsed with the usual sign bit as part of the value (e.g., although 0xFFFFFFFF -eq -1, 0xFFFFFFFFu -eq 4294967295)

Sidenote:

I am thus far unable to find any mention or reference to the preexisting L/l numeric suffix for Int64 literals that has been supported in PowerShell for some time now (indeed, there is no mention of when it was introduced, either).

It should perhaps be considered that this should be an additional about help topic -- perhaps about_Numbers or about_Numeric_Literals?

I'm more than willing to write this document myself; but I'd appreciate some guidance and opinion from others on the best way to document these. 😄

Version(s) of document impacted

• Impacts 6.next document
• Impacts 6 document
• Impacts 5.1 document
• Impacts 5.0 document
• Impacts 4.0 document
• Impacts 3.0 document

Reason(s) for not selecting all version of documents

• The documented feature was introduced in selected version of PowerShell
• This issue only shows up in selected version of the document

[iSazonov]

From original PR:

N.B.: I believe this will be a breaking change, as it means some command names (specifically, numerals suffixed with a y such as 100y) will now be interpreted as numerals instead of potential function or command names.

[vexx32]

Yeah, that should probably be emphasized, somewhat.

Full list of suffixes (thus far):

Suffix	Type
u	uint/ulong
ul	ulong
s	short
us	ushort
y	sbyte
uy	byte
d	decimal

So any numeric commands with those characters as a suffix would have to be called explicitly with the call operator (& 100uy, & 400ulgb) and will otherwise be interpreted as a numeral (with associated type)

EDIT: Also note that now that PowerShell/PowerShell/7993 has been merged, binary literals will need to be mentioned as well. 0b1011011 -> 91