Unclear documentation for System.Numerics.Complex Increment and Decrement operators

[M-Badger]

Type of issue

Missing information

Description

The meaning of Increment and Decrement in the context of complex numbers is not clear. There is no standard interpretation of these operations such as exists for scalar types.

Testing reveals that the implemented behaviour is to increase or decrease the Real part of the complex number. This information should be added explicitly to the documentation to avoid confusion.

For example, it would equally valid to increment or decrement the `Imaginary' part (or both parts) or to create a new instance using the 'FromPolarCoordinates' method and increasing or decreasing the 'Magnitude' by 1.

using System.Numerics;

public class Example
{
    public static void Main()
    {
        Complex a = new(1, 2);
        Console.WriteLine("Original value : {0}", a);

        --a;
        Console.WriteLine("Decrement,     : {0}", a);

        ++a;
        Console.WriteLine("Increment,     : {0}", a);
    }
}

// The example displays the following output:
//       Original value, a : (1, 2)
//       Decrement,      a : (0, 2)
//       Increment,      a : (1, 2)

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.numerics.complex.op_increment?view=net-9.0

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Numerics/Complex.xml

Document Version Independent Id

972c853b-d3c7-56e6-a473-c4edfb80a625

Platform Id

39853e0f-4766-3121-6602-6a2cdb8c10bb

Article author

@dotnet-bot

[tannergooding]

Increment is largely classified, in general, as being x += 1 (and this is the part of the docs for the operator in the language, the general Framework Design Guidelines around not being "cute" and doing custom things with operators, and is even covered in the general ECMA-335 documentation that covers op_Increment and the typical behavior.

I'd be fine with a remarks section being added that explicitly calls out that this is equivalent to x += 1, but otherwise this is one of those behaviors that should be intuitive and self explanatory in the space of the ecosystem.

[M-Badger]

I agree that x += 1 is well defined in the ecosystem for a single value scalar; my difficulty is that a complex number is a 2 value scalar.
In this case we have to assume that x = x + 1 is equivalent to (a + bi) = (a + bi) + (1 + 0i), whereas it could be one of a number of other things, such as (a + bi) = (a + bi) + (1 + 1i) or Magnitude + 1.

My suggestion is simply to add sufficient information to avoid doubt, such as (as I think you suggest) adding "equivalent to (a + bi) = (a + bi) + (1 + 0i)" or other equivalent text as appropriate - i.e. the "1" in x += 1 is in fact "(1 + 0i)".

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-numerics