Docs: Bitwise operators are referred to as logical operators

[Youssef1313]

Operators on this page, such as |, &, and ^, are referred to as logical OR, logical AND, logical XOR in the headings. In the text, it's said with the combination, e.g. "bitwise logical exclusive OR".

I haven't heard "bitwise logical" as a term together, and I think it should be just "bitwise", both in headings and text.

I opened as an issue instead of PR to discuss first, as I might be mistaken.

cc: @pkulikov

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 02b8f7c2-379e-7876-0d36-25b06a294baa
• Version Independent ID: 2410c828-0c66-9efe-ae87-9b07708aa731
• Content: Bitwise and shift operators - C# reference
• Content Source: docs/csharp/language-reference/operators/bitwise-and-shift-operators.md
• Product: dotnet-csharp
• Technology: csharp-language-reference
• GitHub Login: @pkulikov
• Microsoft Alias: wiwagn

[pkulikov]

@Youssef1313 The spec refers to those operators as "logical" (and uses "bitwise logical" wording):
https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/expressions#logical-operators

[Youssef1313]

@pkulikov So the spec was the source of this wording right?
Can the spec be inaccurate in this wording?

It's said everywhere as just bitwise operators.

[pkulikov]

@Youssef1313 I don't think it's inaccurate wording. It's explicit wording: "logical AND", not any other "AND". Though I guess "logical AND" and "AND" are treated as synonymous by many. I think that explicit wording is fine here, especially if it's supported by spec.

"Bitwise" here means that operation is performed on a bit level. "Logical AND" states which operation is performed.

[Youssef1313]

I see your point, and yes I think there is no problem with the combination of "bitwise logical OR" (although the wording isn't common), but it's explicit about that the operator applies logical OR on the bit level.

However, I still think the headings need an update. They just say "Logical OR operator" without any mention of "bitwise".
I believe anyone reads "Logical OR operator" will get it as || (which only applies to boolean, not integers).

[Youssef1313]

Also, it's very confusing if you opened both of these docs:

https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/bitwise-and-shift-operators#logical-or-operator-
https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/boolean-logical-operators#logical-or-operator-

(the same operator is explained twice but in different contexts)
I think it's more simple if | is explained on integers. Then, introduce some text saying something like: "The bitwise logical OR operator | can also be applied to operands of type bool, which will be treated as if they were integers of values 0 and 1".

[pkulikov]

It may even be incorrect to call | as bitwise logical OR operator. Generally, | is called "logical OR operator" (at least, in the spec), It performs bitwise operation on integer operands. In C#, bitwise operators are the ones that perform bitwise operations on integer operands. Those are logical OR, logical AND, logical XOR, and logical NOT.

So, "bitwise" refers not to operator, but to the operation it performs.

However, I still think the headings need an update. They just say "Logical OR operator" without any mention of "bitwise".
I believe anyone reads "Logical OR operator" will get it as || (which only applies to boolean, not integers).

The heading also includes | sign, so it's not to be mixed with ||. Also, the section is in the "Bitwise operators" article and the first sentence clears all the confusions.

I think it's more simple if | is explained on integers.

Not to me. I think it's more simple if | is explained on Booleans. I assume it's 50/50 division: some catch it on Booleans and "extrapolate" to integers; others - vice versa. Depends on the background people are from, I believe. That's why it's worth to explain both behaviors.

The bitwise logical OR operator | can also be applied to operands of type bool, which will be treated _as if_ they were integers of values 0 and 1

That would be confusing:

• Bitwise operators are applied to integer types.
• Why to refer to integers at all while talking about Boolean operands? That makes definition more complex. For example, I learned about bitwise operators long time after I had known Boolean operators. And when I think about 0 | 1, I treat 0 and 1 as if they were Booleans false and true.

Also, it's very confusing if you opened both of these docs:

What is confusing to you? Different operands - different behaviors. If one operator is to be explained based on another, then I would define Boolean logical OR and explain bitwise logical OR from it. For example, Wikipedia article does that: it explains bitwise AND based on logical AND.

the same operator is explained twice but in different contexts

That's fine. People are different, they come from different backgrounds, they develop in different contexts. I think it's completely fine to have two separate sections, each describing the operator behavior in its own context.

[pkulikov]

Operators on this page, such as |, &, and ^, are referred to as logical OR, logical AND, logical XOR in the headings

@Youssef1313 yes, after some thought I think it would be incorrect to put "bitwise" into the section headings. An individual operator is called "logical" (logical OR, logical AND, logical XOR). On integral operands, it performs bitwise logical operation. The set of those operators, though, can be referred as bitwise operators in a sense of "operators that perform bitwise operations"

[Youssef1313]

Hmm... Probably my confusion comes from what I was taught 😄

Strictly speaking, I learnt that:

• Logical operators apply to booleans only and results in a boolean value.
• Bitwise operators apply to integers or booleans (in that case they are treated as 0 or 1, as if they were integers). They do the logical operations on the bit level (bit by bit), and for sure they evaluate both sides to do that.

That's exactly the background I've in this area from college. Probably it's correct but things get different depending on the language (or specifically, the language specification)? Or that terminology I know is just incorrect?

In practice, all just boils to the same thing, just different "terminology".

[Youssef1313]

I looked at the VB reference

https://docs.microsoft.com/en-us/dotnet/visual-basic/programming-guide/language-features/operators-and-expressions/logical-and-bitwise-operators#binary-logical-operators

and based on my previous background from college, matches the terminology I know and is clearer IMO. But I haven't yet checked the VB spec.

[pkulikov]

Logical operators apply to booleans only and results in a boolean value.

Maybe, that's the case in some (a lot even?) languages, but it looks like that not in C#. C# calls |, &, and ^ as logical operators, regardless of the operand type. Then, depending on the operand type, there are integer logical operators and Boolean logical operators. Integer logical operators perform logical operations bit-by-bit and are part of bitwise operators (that set also includes ~).

As for the VB reference, note that it doesn't call operators "bitwise". These are operations that are bitwise.

[pkulikov]

Also, the very first paragraph from VB reference:

Logical operators compare Boolean expressions and return a Boolean result. The And, Or, AndAlso, OrElse, and Xor operators are binary because they take two operands, while the Not operator is unary because it takes a single operand. Some of these operators can also perform bitwise logical operations on integral values.

Note, there are no bitwise operators. The first sentence mentions "logical operators". The last sentence refers to them ("these operators") and basically claims that logical operators can be applied to integral values.

[Youssef1313]

As for the VB reference, note that it doesn't call operators "bitwise". These are operations that are bitwise.

The VB spec mentions "bitwise operators":

In other languages, Not, And, and Or may be overloaded both as logical operators and bitwise operators. Upon import from an external assembly, either form is accepted as a valid overload for these operators. However, for a type which defines both logical and bitwise operators, only the bitwise implementation will be considered.

(I actually couldn't get what's meant by this statement in the spec, but just quoting it as it mentions "bitwise operators".

---

Logical operators compare Boolean expressions and return a Boolean result. The And, Or, AndAlso, OrElse, and Xor operators are binary because they take two operands, while the Not operator is unary because it takes a single operand. Some of these operators can also perform bitwise logical operations on integral values.

Note, there are no bitwise operators. The first sentence mentions "logical operators". The last sentence refers to them ("these operators") and basically claims that logical operators can be applied to integral values.

When I first read this, I thought "these" refers to "binary operators". Not sure what the original author intended to refer to.

---

Maybe, that's the case in some (a lot even?) languages, but it looks like that not in C#.

I think the whole thing is just about "terminology", nothing more, and the problem seems to be from the spec not the article. The spec is basically not using the "common terminology" from other languages.

I checked the C standard (ISO/IEC 9899:TC2) Section 6.5 (Expressions) clearly mentions "bitwise operators". However, the C# spec seems to use the word "bitwise" only as operations.

Can the spec be more clear describing this area? specially that VB spec uses "bitwise operators". I don't know if this could be part of (https://github.com/dotnet-foundation/projects/issues/90)? Not sure about what changes are acceptable to the spec and what are not.

---

Finally, Thanks a lot @pkulikov for giving the time discussing this.

[BillWagner]

I think a bit of history will help us reach a resolution. The C# standard uses the terms "logical operator" and "conditional operator" to distinguish & from && (and | from || etc.) based on rules for overloading. Any type may overload the logical operators. But, the conditional operators cannot be overloaded. Instead, the compiler-generate code for any conditional operator calls the associated logical operator if and only if short circuiting deems it necessary.

The term "bitwise" sneaks in because integral types are the most common example, and in those cases the logical operators are bitwise operators. But, for any user defined type that overloads logical operators, the computation may not be a "bitwise" operation.

I'll propose that we continue to follow the standard text in this area, although I agree we may want to de-emphasize the use of "bitwise".

I'll also check with the other members of the standard committee on any updates planned here, but I doubt this change will be above the bar while we work to update the standard from V5. Getting to the current version is considerably more important.

[BillWagner]

Question for @pkulikov

Do you think we need to make any changes, or should we close this?

[Youssef1313]

Given that the doc matches the spec, I think close. If this diverged from the spec, it will probably be more confusing.

I can't think of any improvement that won't diverge from the spec, but will wait if @pkulikov has ideas.

[pkulikov]

@BillWagner @Youssef1313 I see only the minor possible improvement. In the following sentence

The & operator computes the bitwise logical AND of its operands

explicitly mention argument type: "its integral operands". What do you think? If agree, I'll submit PR.

[BillWagner]

@pkulikov

What do you think? If agree, I'll submit PR.

I like it.