From e6b4aea6e4ad522e0193c6ba968b537d012b261e Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 24 Jul 2024 16:39:37 -0700 Subject: [PATCH 1/3] update system.numerics.complex --- docfx.json | 1 + xml/System.Numerics/Complex.xml | 210 +++++++++----------------------- 2 files changed, 60 insertions(+), 151 deletions(-) diff --git a/docfx.json b/docfx.json index e2c052892f2..f646aa04317 100644 --- a/docfx.json +++ b/docfx.json @@ -46,6 +46,7 @@ "ms.author": "dotnetcontent", "ms.date": "05/16/2023", "searchScope": [".NET"], + "show_latex": true, "uhfHeaderId": "MSDocsHeader-DotNet", "apiPlatform": "dotnet", "ms.topic": "managed-reference", diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml index 4f04d42d834..496c2724238 100644 --- a/xml/System.Numerics/Complex.xml +++ b/xml/System.Numerics/Complex.xml @@ -226,8 +226,6 @@ ## Remarks The `real` or `imaginary` arguments may lose precision if they are data types that require an explicit cast to . - - ## Examples The following example instantiates two complex numbers, and then uses them in addition, subtraction, multiplication, and division operations. @@ -283,18 +281,14 @@ property. The absolute value of a complex number a + bi is calculated as follows: + The absolute value of a complex number is equivalent to its property. The absolute value of a complex number `a + bi` is calculated as follows: - If b = 0, the result is a. - - If a > b, the result is a * (1 + b2/a2). - - If b > a, the result is b * (1 + a2/b2). If the calculation of the absolute value results in an overflow, the method returns either or . If either the or property is and the other property is neither nor , the method returns . - - ## Examples The following example calculates the absolute value of a complex number and demonstrates that it is equivalent to the value of the property. @@ -356,8 +350,6 @@ (-) * (`value` + *( - `value` * `value`))) - - ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -436,9 +428,8 @@ @@ -483,9 +474,7 @@ The addition of a real number (which can be regarded as the complex number a + 0 @@ -543,10 +532,7 @@ The addition of a complex number (a + bi) and a real number (which can be regard @@ -603,8 +589,6 @@ The addition of a complex number (a + bi) and a real number (which can be regard - * ( * value + ( - value * value)) - - ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -668,8 +652,6 @@ The addition of a complex number (a + bi) and a real number (which can be regard ( / new Complex(2.0, 0.0)) * (( - * value) - ( + ImaginaryOne * value)) - - ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -727,9 +709,7 @@ The addition of a complex number (a + bi) and a real number (which can be regard method for complex numbers corresponds to the method for real numbers. - The method uses the following formula to calculate the cosine of the complex number a + bi: + The method uses the following formula to calculate the cosine of the complex number `a + bi`: ((a) * (b), -((a) * (b))) - - ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -853,7 +831,7 @@ The addition of a complex number (a + bi) and a real number (which can be regard ## Remarks The method for complex numbers corresponds to the method for real numbers. - The method uses the following formula to calculate the hyperbolic cosine of the complex number a + bi: + The method uses the following formula to calculate the hyperbolic cosine of the complex number `a + bi`: ((a) * (b), (a) * (b)) @@ -1100,7 +1078,7 @@ The addition of a complex number (a + bi) and a real number (which can be regard ## Remarks - The division of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form: + The division of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: (ac / (c2 + d2)) + (ad / (c2 + d2)i @@ -1150,7 +1128,7 @@ The addition of a complex number (a + bi) and a real number (which can be regard ## Remarks - The division of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form: + The division of a complex number (`a + bi`) and a real number (which can be regarded as the complex number `c + 0i`) takes the following form: (ac / c2) + (bc / c2)i @@ -1211,7 +1189,7 @@ The addition of a complex number (a + bi) and a real number (which can be regard 2 + d2)) + ((bc - ad) / (c2 + d2)i @@ -1440,8 +1418,6 @@ The addition of a complex number (a + bi) and a real number (which can be regard The method for complex numbers corresponds to the method for real numbers. is the inverse of . - - ## Examples The following example illustrates the method. It shows that, with some allowance for the lack of precision of the data type, passing the value returned by the method to the method returns the original value. @@ -1502,12 +1478,10 @@ The addition of a complex number (a + bi) and a real number (which can be regard ## Remarks The method instantiates a complex number based on its polar coordinates. - Because there are multiple representations of a point on a complex plane, the return value of the method is normalized. The magnitude is normalized to a positive number, and the phase is normalized to a value in the range of - to . As a result, the values of the and properties of the resulting complex number may not equal the original values of the `magnitude` and `phase` parameters. + Because there are multiple representations of a point on a complex plane, the return value of the method is normalized. The magnitude is normalized to a positive number, and the phase is normalized to a value in the range of - to . As a result, the values of the and properties of the resulting complex number might not equal the original values of the `magnitude` and `phase` parameters. To convert a value from degrees to radians for the `phase` parameter, multiply it by /180. - - ## Examples The following example uses the method to instantiate a complex number based on its polar coordinates and then displays the value of its and properties. @@ -1607,12 +1581,10 @@ The addition of a complex number (a + bi) and a real number (which can be regard property returns the value of b. - - + Given a complex number `a + bi`, the property returns the value of `b`. ## Examples - The following example instantiates an array of objects and displays the real and imaginary components of each in the form a + bi. + The following example instantiates an array of objects and displays the real and imaginary components of each in the form `a + bi`. :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Imaginary/real1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Numerics/Complex/Imaginary/real1.fs" id="Snippet1"::: @@ -1791,7 +1763,7 @@ This function returns `false` for a complex number `a + bi` where `b` is zero. ## Remarks -This method correctly handles floating-point values and so `2.0` will return `true` while `2.2` will return `false`. +This method correctly handles floating-point values and so `2.0` returns `true` while `2.2` returns `false`. A return value of `false` does not imply that will return `true`. A number with a fractional portion, for example, `3.3`, is not even or odd. @@ -2057,7 +2029,7 @@ This method correctly handles floating-point values and so `2.0` and `3.0` will ## Remarks -A return value of `false` does not imply that will return `true`. A complex number, `a + bi` for non-zero `b`, is not positive or negative +A return value of `false` does not imply that will return `true`. A complex number, `a + bi` for non-zero `b`, is not positive or negative. ]]> @@ -2227,7 +2199,7 @@ A return value of `false` does not imply that will return `true`. A complex number, `a + bi` for non-zero `b`, is not positive or negative +A return value of `false` does not imply that will return `true`. A complex number, `a + bi` for non-zero `b`, is not positive or negative. ]]> @@ -2412,8 +2384,6 @@ This function returns `true` for a complex number `a + bi` where `b` is zero. ## Remarks The method for complex numbers corresponds to the method for real numbers. - - ## Examples The following example illustrates the method. It shows that, with some allowance for the lack of precision of the data type, passing the value returned by the method to the method returns the original value. @@ -2571,7 +2541,7 @@ This function returns `true` for a complex number `a + bi` where `b` is zero. ## Remarks The property is equivalent to the absolute value of a complex number. It specifies the distance from the origin (the intersection of the x-axis and the y-axis in the Cartesian coordinate system) to the two-dimensional point represented by a complex number. The absolute value is calculated as follows: - | a + bi | = (a * a + b * b) + $| a + bi | = Math.Sqrt(a \times a + b \times b)$ If the calculation of the absolute value results in an overflow, this property returns either or . @@ -2579,8 +2549,6 @@ This function returns `true` for a complex number `a + bi` where `b` is zero. You can instantiate a complex number based on its polar coordinates instead of its Cartesian coordinates by calling the method. - - ## Examples The following example calculates the absolute value of a complex number and demonstrates that it is equivalent to the value of the property. @@ -2703,7 +2671,6 @@ If the multiplication results in an overflow in either the real or imaginary com The method is implemented for languages that do not support custom operators. Its behavior is identical to multiplication using the multiplication operator. - ## Examples The following example multiples a complex number by each element in an array of complex numbers. @@ -2757,9 +2724,7 @@ The following example multiples a complex number by each element in an array of ## Remarks - The multiplication of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form: - - ac + adi + The multiplication of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: `ac + adi` ]]> @@ -2806,9 +2771,7 @@ The following example multiples a complex number by each element in an array of ## Remarks -The multiplication of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form: - -ac + bci +The multiplication of a complex number (`a + bi`) and a real number (which can be regarded as the complex number `c + 0i`) takes the following form: `ac + bci` ]]> @@ -2866,9 +2829,9 @@ ac + bci @@ -2961,8 +2924,6 @@ ac + bci The method is implemented for languages that do not support custom operators. Its behavior is identical to negation using the unary negation operator, . - - ## Examples The following example obtains the additive inverse of each element in an array of complex numbers. @@ -3099,9 +3060,9 @@ The following example illustrates addition with complex numbers: ## Remarks -The addition of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form: +The addition of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: -(a + c) + di +`(a + c) + di` Languages that do not support custom operators can call the equivalent method instead. @@ -3151,9 +3112,7 @@ Languages that do not support custom operators can call the equivalent method instead. @@ -3213,9 +3172,9 @@ Languages that do not support custom operators can call the equivalent method instead. @@ -3326,7 +3285,7 @@ The operators that receive one dou ## Remarks -The division of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form: +The division of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: (ac / (c2 + d2)) + (ad / (c2 + d2)i @@ -3378,7 +3337,7 @@ Languages that do not support custom operators and operator overloading can call ## Remarks -The division of a complex number (a + bi) and a real number (which can be regarded as the complex number c + 0i) takes the following form: +The division of a complex number (`a + bi`) and a real number (which can be regarded as the complex number `c + 0i`) takes the following form: (ac / c2) + (bc / c2)i @@ -3440,7 +3399,7 @@ Languages that do not support custom operators and operator overloading can call ## Remarks -The division of a complex number, a + bi, and a second complex number, c + di, takes the following form: +The division of a complex number, `a + bi`, and a second complex number, `c + di`, takes the following form: ((ac + bd) / (c2 + d2)) + ((bc - ad) / (c2 + d2)i @@ -3581,8 +3540,6 @@ Languages that do not support custom operators and operator overloading can call The conversion of a value to the real part of a complex number can result in a loss of precision because a , which is the type of the complex number's property, has fewer significant digits than a . - - ## Examples The following example illustrates the explicit conversion of values to values. @@ -3678,8 +3635,6 @@ Languages that do not support custom operators and operator overloading can call If the conversion is unsuccessful because the value is out of the range of the type, the operation does not throw an . Instead, if `value` is less than , the result is a complex number that has a property value equal to . If `value` is greater than , the result is a complex number that has a property value equal to . - - ## Examples The following example illustrates the explicit conversion of values to values. @@ -4643,13 +4598,10 @@ The operators that receive one dou ## Remarks -The multiplication of a real number (which can be regarded as the complex number a + 0i) and a complex number (c + di) takes the following form: - -ac + adi +The multiplication of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: `ac + adi` Languages that do not support custom operators can call the equivalent method instead. - ]]> @@ -4696,9 +4648,7 @@ Languages that do not support custom operators can call the equivalent method instead. @@ -4758,9 +4708,7 @@ Languages that do not support custom operators can call the equivalent method instead. @@ -4834,9 +4782,7 @@ The operators that receive one dou ## Remarks -The subtraction of a complex number (c + di) from a real number (which can be regarded as the complex number a + 0i) takes the following form: - -(a - c) - di +The subtraction of a complex number (`c + di`) from a real number (which can be regarded as the complex number `a + 0i`) takes the following form: `(a - c) - di` Languages that do not support custom operators can call the method instead. @@ -4886,9 +4832,7 @@ Languages that do not support custom operators can call the method instead. @@ -4948,9 +4892,7 @@ Languages that do not support custom operators can call the method instead. @@ -5297,7 +5239,7 @@ Languages that do not support custom operators can call the (b, a). + For a complex number `a + bi`, the phase is computed as (b, a). You can identify a complex number by its Cartesian coordinates on the complex plane or by its polar coordinates. The phase (argument) of a complex number is the angle to the real axis of a line drawn from the point of origin (the intersection of the x-axis and the y-axis) to the point represented by the complex number. The magnitude (represented by the property) is the distance from the point of origin to the point that is represented by the complex number. @@ -5305,8 +5247,6 @@ Languages that do not support custom operators can call the . - - ## Examples The following example uses the method to instantiate a complex number based on its polar coordinates, and then displays the value of its and properties. @@ -5379,8 +5319,6 @@ Languages that do not support custom operators can call the method for primitive numeric types. - - ## Examples The following example illustrates exponentiation using a complex number and an exponent whose value ranges from -1 to 10. @@ -5483,12 +5421,10 @@ Languages that do not support custom operators can call the property returns the value of a. - - + Given a complex number `a + bi`, the property returns the value of `a`. ## Examples - The following example instantiates an array of objects and displays the real and imaginary components of each in the form a + bi. + The following example instantiates an array of objects and displays the real and imaginary components of each in the form `a + bi`. :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Imaginary/real1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Numerics/Complex/Imaginary/real1.fs" id="Snippet1"::: @@ -5543,12 +5479,10 @@ Languages that do not support custom operators can call the when the two numbers are multiplied. If a complex number is represented by a +bi, its reciprocal is represented by the expression a/(a2+b2) + -b/(a2 + b2). + The reciprocal, or multiplicative inverse, of a number `x` is a number `y` where `x * y` yields 1. The reciprocal of a complex number is the complex number that produces when the two numbers are multiplied. If a complex number is represented by `a + bi`, its reciprocal is represented by the expression a/(a2+b2) + -b/(a2 + b2). If value is , the method returns . Otherwise, it returns the result of the expression /`value`. - - ## Examples The following example uses the method to calculate the reciprocal values of several complex numbers. It also demonstrates that the result of multiplying a complex number by its reciprocal is . @@ -5606,12 +5540,10 @@ Languages that do not support custom operators can call the method for complex numbers corresponds to the method for real numbers. - The method uses the following formula to calculate the sine of the complex number a + bi: + The method uses the following formula to calculate the sine of the complex number `a + bi`: ((a) * (b), (a) * (b)) - - ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -5671,7 +5603,7 @@ Languages that do not support custom operators can call the method for complex numbers corresponds to the method for real numbers. - The method uses the following formula to calculate the hyperbolic sine of the complex number a + bi: + The method uses the following formula to calculate the hyperbolic sine of the complex number `a + bi`: ((a) * (b), (a) * (b)) @@ -5803,9 +5735,7 @@ The following example subtracts each complex number in an array from a complex n ## Remarks -The subtraction of a complex number (c + di) from a real number (which can be regarded as the complex number a + 0i) takes the following form: - -(a - c) - di +The subtraction of a complex number (`c + di`) from a real number (which can be regarded as the complex number `a + 0i`) takes the following form: `(a - c) - di` Languages that support custom operators can use the equivalent operator too. @@ -5855,9 +5785,7 @@ Languages that support custom operators can use the equivalent operator too. @@ -5919,9 +5847,9 @@ Languages that support custom operators can use the equivalent operator too. @@ -6689,8 +6617,6 @@ Languages that support custom operators can use the (`value`) / (`value`) - - ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -6816,9 +6742,7 @@ Languages that support custom operators can use the `, where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the general format specifier ("G") and the conventions of the current system culture. - - + The default string representation of a complex number displays the number using its Cartesian coordinates in the form `` (or `(a, b)` in .NET 7 and earlier versions), where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the general format specifier ("G") and the conventions of the current system culture. ## Examples The following example displays the string representation of several complex numbers. The output uses the formatting conventions of the English - United States ("en-US") culture, which, in this case, is the current system culture. @@ -6889,20 +6813,16 @@ Languages that support custom operators can use the `, where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the general format specifier ("G") and the conventions of the culture defined by `provider`. + The string representation of the complex number returned by this method displays the number using its Cartesian coordinates in the form `` (or `(a, b)` in .NET 7 and earlier versions), where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the general format specifier ("G") and the conventions of the culture defined by `provider`. The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of the real and imaginary numbers in the returned string. If `provider` is `null`, the returned string is formatted using the object of the current culture. The `provider` parameter can be one of the following: - A object that represents the culture that supplies formatting information - - The object that supplies formatting information. - - A custom object that implements the interface. Its method returns the object that supplies formatting information. - - ## Examples The following example displays the string representation of several complex numbers. The result uses the formatting conventions of the English - United States ("en-US") and French - France ("fr-FR") cultures. @@ -6976,18 +6896,15 @@ Languages that support custom operators can use the `, where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the format string specified by `format`. The `format` parameter can be any valid standard numeric format specifier, or any combination of custom numeric format specifiers. If `format` is equal to or is `null`, the real and imaginary parts of the complex number are formatted with the general format specifier ("G"). If `format` is any other value, the method throws a . - - The .NET Framework provides extensive formatting support, which is described in greater detail in the following topics: + The string representation of the complex number returned by this method displays the number using its Cartesian coordinates in the form `` (or `(a, b)` in .NET 7 and earlier versions), where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the format string specified by `format`. The `format` parameter can be any valid standard numeric format specifier, or any combination of custom numeric format specifiers. If `format` is equal to or is `null`, the real and imaginary parts of the complex number are formatted with the general format specifier ("G"). If `format` is any other value, the method throws a . -- For more information about numeric format strings, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). +.NET provides extensive formatting support, which is described in greater detail in the following articles: -- For more information about formatting in the .NET Framework, see [Formatting Types](/dotnet/standard/base-types/formatting-types). +- For more information about numeric format strings, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). +- For more information about formatting in .NET, see [Formatting Types](/dotnet/standard/base-types/formatting-types). The format of the returned string is determined by the object for the current culture. Depending on the `format` parameter, this object controls symbols such as the negative sign, the group separator, and the decimal point symbol in the output string. To provide formatting information for cultures other than the current culture, call the overload. - - ## Examples The following example initializes a complex number and displays it using several standard format strings. @@ -7066,25 +6983,20 @@ Languages that support custom operators can use the `, where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the format string specified by `format`. The `format` parameter can be any valid standard numeric format specifier, or any combination of custom numeric format specifiers. If `format` is equal to or is `null`, the real and imaginary parts of the complex number are formatted with the general format specifier ("G"). If `format` is any other value, the method throws a . - - The .NET Framework provides extensive formatting support, which is described in greater detail in the following topics: + The string representation of the complex number returned by this method displays the number using its Cartesian coordinates in the form `` (or `(a, b)` in .NET 7 and earlier versions), where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the format string specified by `format`. The `format` parameter can be any valid standard numeric format specifier, or any combination of custom numeric format specifiers. If `format` is equal to or is `null`, the real and imaginary parts of the complex number are formatted with the general format specifier ("G"). If `format` is any other value, the method throws a . -- For more information about numeric format strings, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). +.NET provides extensive formatting support, which is described in greater detail in the following articles: -- For more information about formatting in the .NET Framework, see [Formatting Types](/dotnet/standard/base-types/formatting-types). +- For more information about numeric format strings, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). +- For more information about formatting in .NET, see [Formatting Types](/dotnet/standard/base-types/formatting-types). The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of the real and imaginary numbers in the returned string. Depending on the `format` parameter, this object controls symbols such as the negative sign, the group separator, and the decimal point symbol in the output string. If `provider` is `null`, the returned string is formatted using the object of the current culture. The `provider` parameter can be one of the following: -- A object that represents the culture that supplies formatting information - -- The object that supplies formatting information. - -- A custom object that implements the interface. Its method returns the object that supplies formatting information. - - +- A object that represents the culture that supplies formatting information +- The object that supplies formatting information. +- A custom object that implements the interface. Its method returns the object that supplies formatting information. ## Examples The following example creates an array of complex numbers, and displays each using several standard format strings as well as objects that represent the English - United States ("en-US") and French - France ("fr-FR") cultures. @@ -7216,9 +7128,7 @@ Languages that support custom operators can use the - on the same type. - TryFormat should return `false` only if there is not enough space in the destination buffer. Any other failures should throw an exception. +An implementation of this interface should produce the same string of characters as an implementation of on the same type. `TryFormat` should return `false` only if there's not enough space in the destination buffer. Any other failures should throw an exception. ]]> @@ -7466,8 +7376,6 @@ An implementation of this interface should produce the same string of characters ## Remarks The property is most frequently used to compare a value to zero. - - ## Examples The following example instantiates a value by using the property. It then compares this value to another value that is instantiated by calling the constructor with a real part equal to zero and an imaginary part equal to zero. As the output from the example shows, the two values are equal. From bfea927b2e0c53e6e1746749603da83dc6b822da Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 25 Jul 2024 16:08:10 -0700 Subject: [PATCH 2/3] use latex formulas --- xml/System.Numerics/Complex.xml | 139 ++++++++++++++++++-------------- 1 file changed, 77 insertions(+), 62 deletions(-) diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml index 496c2724238..5a8f10d2e58 100644 --- a/xml/System.Numerics/Complex.xml +++ b/xml/System.Numerics/Complex.xml @@ -283,9 +283,9 @@ ## Remarks The absolute value of a complex number is equivalent to its property. The absolute value of a complex number `a + bi` is calculated as follows: -- If b = 0, the result is a. -- If a > b, the result is a * (1 + b2/a2). -- If b > a, the result is b * (1 + a2/b2). +- If `b = 0`, the result is `a`. +- If `a > b`, the result is $a \times \sqrt{1 + \frac{b^2}{a^2}$. +- If `b > a`, the result is $b \times \sqrt{1 + \frac{a^2}{b^2}$. If the calculation of the absolute value results in an overflow, the method returns either or . If either the or property is and the other property is neither nor , the method returns . @@ -348,7 +348,7 @@ The method uses the following formula: - (-) * (`value` + *( - `value` * `value`))) + `(-ImaginaryOne) * Log(value + ImaginaryOne * Sqrt(One - value * value))` ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -374,7 +374,7 @@ If the method call results in an overflow in either the real or imaginary component, the value of the component is either or . - Languages that do not support custom operators can use the method to perform addition with complex numbers. + Languages that don't support custom operators can use the method to perform addition with complex numbers. The methods that receive one double are more efficient than the methods that receive two complex numbers. @@ -473,7 +473,6 @@ The addition of a real number (which can be regarded as the complex number `a + The sum of and . @@ -587,7 +586,7 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega The method uses the following formula: - - * ( * value + ( - value * value)) +`-ImaginaryOne * Log(ImaginaryOne * value + Sqrt(One - value * value))` ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -650,7 +649,7 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega The method uses the following formula: - ( / new Complex(2.0, 0.0)) * (( - * value) - ( + ImaginaryOne * value)) +`(ImaginaryOne / new Complex(2.0, 0.0)) * (Log(One - ImaginaryOne * value) - Log(One + ImaginaryOne * value))` ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -768,9 +767,10 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega ## Remarks The method for complex numbers corresponds to the method for real numbers. - The method uses the following formula to calculate the cosine of the complex number `a + bi`: + The method calculates the cosine of the complex number `a + bi` as `x + yi`, where: - ((a) * (b), -((a) * (b))) +- `x` is $\cos a \times \cosh b$ +- `y` is $-(\sin a \times \sinh b)$ ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -831,9 +831,10 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega ## Remarks The method for complex numbers corresponds to the method for real numbers. - The method uses the following formula to calculate the hyperbolic cosine of the complex number `a + bi`: + The method calculates the hyperbolic cosine of the complex number `a + bi` as `x + yi`, where: - ((a) * (b), (a) * (b)) +- `x` is $\cosh a \times \cos b$ +- `y` is $\sinh a \times \sin b$ ]]> @@ -1022,7 +1023,7 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega If the calculation of the quotient results in an overflow in either the real or imaginary component, the value of that component is either or . - The method can be used by languages that do not support custom operators. Its behavior is identical to division using the division operator. + The method can be used by Languages that don't support custom operators. Its behavior is identical to division using the division operator. The methods that receive one double are more efficient than the methods that receive two complex numbers. @@ -1080,7 +1081,7 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega The division of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: - (ac / (c2 + d2)) + (ad / (c2 + d2)i +$\frac{ac}{c^2 + d^2} + (\frac{ad}{c^2 + d^2})i$ ]]> @@ -1130,7 +1131,7 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega The division of a complex number (`a + bi`) and a real number (which can be regarded as the complex number `c + 0i`) takes the following form: - (ac / c2) + (bc / c2)i +$\frac{ac}{c^2} + (\frac{bc}{c^2})i$ ]]> @@ -1191,7 +1192,7 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega ## Remarks The division of a complex number, `a + bi`, by a second complex number, `c + di`, takes the following form: - ((ac + bd) / (c2 + d2)) + ((bc - ad) / (c2 + d2)i +$\frac{ac + bd}{c^2 + d^2} + (\frac{bc - ad}{c^2 + d^2})i$ ]]> @@ -2541,7 +2542,7 @@ This function returns `true` for a complex number `a + bi` where `b` is zero. ## Remarks The property is equivalent to the absolute value of a complex number. It specifies the distance from the origin (the intersection of the x-axis and the y-axis in the Cartesian coordinate system) to the two-dimensional point represented by a complex number. The absolute value is calculated as follows: - $| a + bi | = Math.Sqrt(a \times a + b \times b)$ + $| a + bi | = \sqrt{a \times a + b \times b}$ If the calculation of the absolute value results in an overflow, this property returns either or . @@ -2669,7 +2670,7 @@ The methods allow performing multipli If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either or . -The method is implemented for languages that do not support custom operators. Its behavior is identical to multiplication using the multiplication operator. +The method is implemented for Languages that don't support custom operators. Its behavior is identical to multiplication using the multiplication operator. ## Examples @@ -2831,7 +2832,7 @@ The multiplication of a complex number (`a + bi`) and a real number (which can b ## Remarks The multiplication of a complex number, `a + bi`, and a second complex number, `c + di`, takes the following form: - `(ac - bd) + (ad + bc)i` +$(ac - bd) + (ad + bc)i$ ]]> @@ -2922,7 +2923,7 @@ The multiplication of a complex number (`a + bi`) and a real number (which can b ## Remarks The additive inverse of a complex number is a complex number that produces a value of when it is added to the original complex number. This method returns a complex number in which the real and imaginary components of the original complex number are multiplied by -1. - The method is implemented for languages that do not support custom operators. Its behavior is identical to negation using the unary negation operator, . + The method is implemented for Languages that don't support custom operators. Its behavior is identical to negation using the unary negation operator, . ## Examples The following example obtains the additive inverse of each element in an array of complex numbers. @@ -3003,7 +3004,7 @@ The operator allows performing add If the addition results in an overflow in either the real or imaginary component, the value of that component is either or . -Languages that do not support custom operators can call the equivalent group of methods instead. +Languages that don't support custom operators can call the equivalent group of methods instead. The operators that receive one double are more efficient than the operators that receive two Complex numbers. @@ -3062,9 +3063,9 @@ The following example illustrates addition with complex numbers: The addition of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: -`(a + c) + di` +$(a + c) + di$ -Languages that do not support custom operators can call the equivalent method instead. +Languages that don't support custom operators can call the equivalent method instead. ]]> @@ -3112,9 +3113,9 @@ Languages that do not support custom operators can call the equivalent method instead. +Languages that don't support custom operators can call the equivalent method instead. ]]> @@ -3174,9 +3175,9 @@ Languages that do not support custom operators can call the equivalent method instead. +Languages that don't support custom operators can call the equivalent method instead. ]]> @@ -3236,7 +3237,7 @@ The operator allows performing div If the division results in an overflow in either the real or imaginary component, the value of that component is either or . -Languages that do not support custom operators and operator overloading can call the equivalent group of method instead. +Languages that don't support custom operators and operator overloading can call the equivalent group of method instead. The operators that receive one double are more efficient than the operators that receive two Complex numbers. @@ -3287,9 +3288,9 @@ The operators that receive one dou The division of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: -(ac / (c2 + d2)) + (ad / (c2 + d2)i +$\frac{ac}{c^2 + d^2} + (\frac{ad}{c^2 + d^2})i$ -Languages that do not support custom operators and operator overloading can call the equivalent method instead. +Languages that don't support custom operators and operator overloading can call the equivalent method instead. ]]> @@ -3339,9 +3340,9 @@ Languages that do not support custom operators and operator overloading can call The division of a complex number (`a + bi`) and a real number (which can be regarded as the complex number `c + 0i`) takes the following form: -(ac / c2) + (bc / c2)i +$\frac{ac}{c^2} + (\frac{bc}{c^2})i$ -Languages that do not support custom operators and operator overloading can call the equivalent method instead. +Languages that don't support custom operators and operator overloading can call the equivalent method instead. ]]> @@ -3401,9 +3402,9 @@ Languages that do not support custom operators and operator overloading can call The division of a complex number, `a + bi`, and a second complex number, `c + di`, takes the following form: -((ac + bd) / (c2 + d2)) + ((bc - ad) / (c2 + d2)i +$\frac{ac + cd}{c^2 + d^2} + (\frac{bc - ad}{c^2 + d^2})i$ -Languages that do not support custom operators and operator overloading can call the equivalent method instead. +Languages that don't support custom operators and operator overloading can call the equivalent method instead. ]]> @@ -3467,7 +3468,7 @@ Languages that do not support custom operators and operator overloading can call :::code language="fsharp" source="~/snippets/fsharp/System.Numerics/Complex/Equals/eqoperator1.fs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.equals/vb/eqoperator1.vb" id="Snippet9"::: - Languages that do not support custom operators can call the method instead. + Languages that don't support custom operators can call the method instead. Two complex numbers are equal if their real parts are equal and their imaginary parts are equal. The method is equivalent to the following expression: @@ -4524,7 +4525,7 @@ This API is not CLS-compliant. :::code language="fsharp" source="~/snippets/fsharp/System.Numerics/Complex/op_Inequality/inequality1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.inequality/vb/inequality1.vb" id="Snippet1"::: - Languages that do not support custom operators can test for inequality by calling the method and reversing its value. + Languages that don't support custom operators can test for inequality by calling the method and reversing its value. Note that, because of differences in precision, two complex numbers that are apparently equivalent can be considered unequal. One possible workaround is to implement a comparison method that returns `true` only if the difference between the two real and imaginary parts of the complex numbers exceeds a certain threshold (such as .01% of the value of the real or imaginary component of one of the complex numbers). For more information, see the method. @@ -4549,7 +4550,7 @@ The operator allows performing mul If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either or . -Languages that do not support custom operators can call the equivalent group of methods instead. +Languages that don't support custom operators can call the equivalent group of methods instead. The operators that receive one double are more efficient than the operators that receive two Complex numbers. @@ -4600,7 +4601,7 @@ The operators that receive one dou The multiplication of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: `ac + adi` -Languages that do not support custom operators can call the equivalent method instead. +Languages that don't support custom operators can call the equivalent method instead. ]]> @@ -4650,7 +4651,7 @@ Languages that do not support custom operators can call the equivalent method instead. +Languages that don't support custom operators can call the equivalent method instead. ]]> @@ -4708,9 +4709,9 @@ Languages that do not support custom operators can call the equivalent method instead. +Languages that don't support custom operators can call the equivalent method instead. ]]> @@ -4733,7 +4734,7 @@ The operator allows performing If the subtraction results in an overflow in either the real or imaginary component, the value of that component is either or . -Languages that do not support custom operators can call the equivalent group of methods instead. +Languages that don't support custom operators can call the equivalent group of methods instead. The operators that receive one double are more efficient than the operators that receive two Complex numbers. @@ -4782,9 +4783,11 @@ The operators that receive one dou ## Remarks -The subtraction of a complex number (`c + di`) from a real number (which can be regarded as the complex number `a + 0i`) takes the following form: `(a - c) - di` +The subtraction of a complex number (`c + di`) from a real number (which can be regarded as the complex number `a + 0i`) takes the following form: + +$(a - c) - di$ -Languages that do not support custom operators can call the method instead. +Languages that don't support custom operators can call the method instead. ]]> @@ -4832,9 +4835,11 @@ Languages that do not support custom operators can call the method instead. +$(a - c) + bi$ + +Languages that don't support custom operators can call the method instead. ]]> @@ -4892,9 +4897,11 @@ Languages that do not support custom operators can call the method instead. +$(a - c) + (b - d)i$ + +Languages that don't support custom operators can call the method instead. ]]> @@ -4955,7 +4962,7 @@ Languages that do not support custom operators can call the when it is added to the original complex number. Languages that do not support custom operators can call the method instead. + The resulting complex number produces a value of when it is added to the original complex number. Languages that don't support custom operators can call the method instead. The equivalent method for this operator is ]]> @@ -5239,13 +5246,13 @@ Languages that do not support custom operators can call the (b, a). + For a complex number `a + bi`, the phase is computed as `Atan(b, a)`. You can identify a complex number by its Cartesian coordinates on the complex plane or by its polar coordinates. The phase (argument) of a complex number is the angle to the real axis of a line drawn from the point of origin (the intersection of the x-axis and the y-axis) to the point represented by the complex number. The magnitude (represented by the property) is the distance from the point of origin to the point that is represented by the complex number. You can instantiate a complex number based on its polar coordinates instead of its Cartesian coordinates by calling the method. - To convert the phase from radians to degrees, multiply it by 180/. + To convert the phase from radians to degrees, multiply it by $\frac{180}{\pi}$. ## Examples The following example uses the method to instantiate a complex number based on its polar coordinates, and then displays the value of its and properties. @@ -5479,7 +5486,9 @@ Languages that do not support custom operators can call the when the two numbers are multiplied. If a complex number is represented by `a + bi`, its reciprocal is represented by the expression a/(a2+b2) + -b/(a2 + b2). + The reciprocal, or multiplicative inverse, of a number `x` is a number `y` where `x * y` yields 1. The reciprocal of a complex number is the complex number that produces when the two numbers are multiplied. If a complex number is represented by `a + bi`, its reciprocal is represented by the following expression: + +$\frac{a}{a^2 + b^2} + -\frac{b}{a^2 + b^2}$ If value is , the method returns . Otherwise, it returns the result of the expression /`value`. @@ -5540,9 +5549,10 @@ Languages that do not support custom operators can call the method for complex numbers corresponds to the method for real numbers. - The method uses the following formula to calculate the sine of the complex number `a + bi`: + The method calculates the sine of the complex number `a + bi` as `x + yi`, where: - ((a) * (b), (a) * (b)) +- `x` is $\sin a \times \cosh b$ +- `y` is $\cos a \times \sinh b$ ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -5603,9 +5613,10 @@ Languages that do not support custom operators can call the method for complex numbers corresponds to the method for real numbers. - The method uses the following formula to calculate the hyperbolic sine of the complex number `a + bi`: + The method calculates the hyperbolic sine of the complex number `a + bi` as `x + yi`, where: - ((a) * (b), (a) * (b)) +- `x` is $\sinh a \times \cos b$ +- `y` is $\cosh a \times \sin b$ ]]> @@ -5658,7 +5669,7 @@ Languages that do not support custom operators can call the ((`value`.), `value`./2.0) +`Complex.FromPolarCoordinates(Math.Sqrt(value.Magnitude), value.Phase/2.0)` The method for complex numbers corresponds to the method for real numbers. @@ -5735,7 +5746,9 @@ The following example subtracts each complex number in an array from a complex n ## Remarks -The subtraction of a complex number (`c + di`) from a real number (which can be regarded as the complex number `a + 0i`) takes the following form: `(a - c) - di` +The subtraction of a complex number (`c + di`) from a real number (which can be regarded as the complex number `a + 0i`) takes the following form: + +$(a - c) - di$ Languages that support custom operators can use the equivalent operator too. @@ -5785,7 +5798,9 @@ Languages that support custom operators can use the equivalent operator too. @@ -5849,7 +5864,7 @@ Languages that support custom operators can use the equivalent operator too. @@ -6615,7 +6630,7 @@ Languages that support custom operators can use the method uses the following formula to calculate the tangent of the complex number `value`: - (`value`) / (`value`) +`Sin(value)/Cos(value)` ## Examples The following example illustrates the method. It shows that passing the value returned by the method to the method returns the original value. @@ -6678,7 +6693,7 @@ Languages that support custom operators can use the method uses the following formula to calculate the hyperbolic tangent of the complex number `value`: - (`value`) / (`value`) +`Sinh(value)/Cosh(value)` ]]> From 05f0de35542b0811654ccb913f80079d891cd24b Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 25 Jul 2024 22:17:14 -0700 Subject: [PATCH 3/3] review changes --- xml/System.Numerics/Complex.xml | 42 +++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml index 5a8f10d2e58..a2a6221d41b 100644 --- a/xml/System.Numerics/Complex.xml +++ b/xml/System.Numerics/Complex.xml @@ -284,8 +284,8 @@ The absolute value of a complex number is equivalent to its property. The absolute value of a complex number `a + bi` is calculated as follows: - If `b = 0`, the result is `a`. -- If `a > b`, the result is $a \times \sqrt{1 + \frac{b^2}{a^2}$. -- If `b > a`, the result is $b \times \sqrt{1 + \frac{a^2}{b^2}$. +- If `a > b`, the result is $a \times \sqrt{1 + \frac{b^2}{a^2}}$. +- If `b > a`, the result is $b \times \sqrt{1 + \frac{a^2}{b^2}}$. If the calculation of the absolute value results in an overflow, the method returns either or . If either the or property is and the other property is neither nor , the method returns . @@ -429,7 +429,9 @@ @@ -473,7 +475,9 @@ The addition of a real number (which can be regarded as the complex number `a + The sum of and . @@ -531,7 +535,9 @@ The addition of a complex number (`a + bi`) and a real number (which can be rega @@ -1481,7 +1487,7 @@ $\frac{ac + bd}{c^2 + d^2} + (\frac{bc - ad}{c^2 + d^2})i$ Because there are multiple representations of a point on a complex plane, the return value of the method is normalized. The magnitude is normalized to a positive number, and the phase is normalized to a value in the range of - to . As a result, the values of the and properties of the resulting complex number might not equal the original values of the `magnitude` and `phase` parameters. - To convert a value from degrees to radians for the `phase` parameter, multiply it by /180. + To convert a value from degrees to radians for the `phase` parameter, multiply it by $\frac{\pi}{180}$. ## Examples The following example uses the method to instantiate a complex number based on its polar coordinates and then displays the value of its and properties. @@ -2725,7 +2731,9 @@ The following example multiples a complex number by each element in an array of ## Remarks - The multiplication of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: `ac + adi` + The multiplication of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: + +$ac + adi$ ]]> @@ -2772,7 +2780,9 @@ The following example multiples a complex number by each element in an array of ## Remarks -The multiplication of a complex number (`a + bi`) and a real number (which can be regarded as the complex number `c + 0i`) takes the following form: `ac + bci` +The multiplication of a complex number (`a + bi`) and a real number (which can be regarded as the complex number `c + 0i`) takes the following form: + +$ac + bci$ ]]> @@ -3113,7 +3123,9 @@ Languages that don't support custom operators can call the equivalent method instead. @@ -4599,7 +4611,9 @@ The operators that receive one dou ## Remarks -The multiplication of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: `ac + adi` +The multiplication of a real number (which can be regarded as the complex number `a + 0i`) and a complex number (`c + di`) takes the following form: + +$ac + adi$ Languages that don't support custom operators can call the equivalent method instead. @@ -4649,7 +4663,9 @@ Languages that don't support custom operators can call the equivalent method instead. @@ -4709,7 +4725,9 @@ Languages that don't support custom operators can call the equivalent method instead.