System.Int64 improper 32-bit heading and some general commentary/suggestions for Int32 and Int64 about docs HOT 6 OPEN

Possible alternatives to decimal:

• base-10 (seems best IMO)
• radix-10

from docs.

Also, both the Int32 and Int64 articles mention the unsigned variants. Would it be worthwhile to add a footnote or parenthetical callout or something to briefly mention that UInt32 and UInt64 are not CLS-compliant?

from docs.

Another thought:

Binary, octal, and hex literals can get confusing when using the signed types, as it is considered an overflow to set the MSB explicitly without an unchecked expression and a cast. To me, that's a language bug, but I don't imagine that's something likely to be changed, due to breakage potential.

In any case, mentioning this restriction when talking about Int(32|64) literals in bases != 10 seems a lot better than just saying that it's a (31|63)-bit number with a sign bit. That doesn't help much when someone is writing a [Flags] enum, for example, and runs into the apparently common small but inconvenient stumbling block of something like this being illegal:

[Flags]
public enum Broken
{
  None = 0b_00000000_00000000_00000000_00000000,
  Bit0 = 0b_00000000_00000000_00000000_00000001,
  // ... And so on up to...
  Bit31 = 0b_10000000_00000000_00000000_00000000 // <--- Compile error claiming it's an Int64
}
// Also happens for octal or hex literals with MSB == 1, as well as shifted literals that would set the MSB to 1 (like `Bit31 = 1 << 31`)

That can be resolved by:

• Using the negative base-10 representation (Not pretty and unintuitive)
• Using a unary - prefix on the non-base-10 literals (unintuitive and error-prone if you don't do the two's complement correctly).
• Using a bitwise ~ operator on the negated value, like ~0b_01111111_11111111_11111111_11111111 (also very non-ideal)
• Wrapping the literal like so: unchecked((int)0b_10000000_00000000_00000000_00000000) (Not pretty - messes up alignment but at least keeps binary representation)
• Changing the enum to an unsigned or larger type (breaking change plus not CLS-compliant if unsigned)

All of those evaluate to the same constant at compile-time, yet only those explicitly written in the code such that the literal sets the MSB to 1 cause the unintuitive wider type inference (well...and the shift, which is inconsistent), and use of unchecked totally shouldn't be necessary to do that without error. But, if it is, this behavior and available workarounds seem like a good idea to document.

from docs.

@tannergooding could you PTAL?

from docs.

System.Int64 has a reference to 32-bit that

Please feel free to open a PR fixing it.

I think it would be best to avoid using the word decimal in those articles, in particular, when talking about base-10 numbers, as it could potentially be confused with the decimal type, discussed in the same section of the documentation.

decimal is a common term that will exist as the natural wording across a wide range of docs. It would be far more effort than it's worth to try and ensure every doc doesn't use it and likely overall more confusing to avoid it. This is particularly prevalent when the terminology is almost always clarrified by the surrounding context, such as decimal digits and examples.

Would it be worthwhile to add a footnote or parenthetical callout or something to briefly mention that UInt32 and UInt64 are not CLS-compliant?

IMO, no. CLS Compliance exists very broadly and is exposed to users when they go read the docs for a type or member that is marked with it.

More so, it is largely a legacy concept that isn't fully supported anymore. A number of modern features have never been considered for CLS Compliance and would likely have been considered non-compliant given the original spirit of the feature. This includes things like ref structs (and therefore Span<T>), default interface members, static virtuals in interfaces, and most other new runtime functionality. There are also places where the language doesn't "properly" raise that something should be marked CLSCompliant(false), such as any of the places where it emits a modreq for a virtual member.

To me, that's a language bug, but I don't imagine that's something likely to be changed, due to breakage potential.

This is how most languages work, the representation doesn't matter only the resulting magnitude which is always interpreted as unsigned. You then only get a negative value by using the negation operator on a literal, thus 0b_10000000_00000000_00000000_00000000 is 0x8000_0000 which is 2147483648 and thus is outside the range of int. Negative 1 is then represented as -0b1 or -0x1 or -1, not as 0xFFFF_FFFF.

Some languages, like C, allow all kinds of implicit conversion without warning and so it "appears" to work, but in practice its just silently allowing overflow to happen (which is also strictly undefined behavior according to the language spec).

from docs.

Thanks for the responses and background.

As far as the decimal term goes, I specifically meant for these documents, within that section - not as a global change - due to the proximity of the concepts. The decimal type document comes before the integer documents in that section, too.

from docs.