Namespaces
Variants
Views
Actions

Difference between revisions of "c/numeric/complex"

From cppreference.com
< c‎ | numeric
(more categorization)
m (fmt.)
 
(43 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
{{title|Complex number arithmetic}}
 
{{title|Complex number arithmetic}}
 
{{c/numeric/complex/navbar}}
 
{{c/numeric/complex/navbar}}
 +
{{rrev|since=c11|
 +
If the macro constant {{tt|__STDC_NO_COMPLEX__}} is defined by the implementation, the complex types, the header {{tt|<complex.h>}} and all of the names listed here are not provided.}}
  
The header {{tt|<complex.h>}} defines macros and declares functions that support complex number arithmetic. Complex values are values of type {{tt|double complex}}, {{tt|float complex}}, {{tt|long double complex}},
+
The C programming language, as of C99, supports complex number math with the three built-in types {{c|double _Complex}}, {{c|float _Complex}}, and {{c|long double _Complex}} (see {{ltt|c/keyword/_Complex}}). When the header {{tt|<complex.h>}} is included, the three complex number types are also accessible as {{c|double complex}}, {{c|float complex}}, {{c|long double complex}}.
  
If the macro constant {{tt|__STDC_IEC_559_COMPLEX__}}{{mark c99}} is defined by the compiler, in addition to the complex types, the imaginary types are also supported: {{tt|double imaginary}}, {{tt|float imaginary}}, and {{tt|long double imaginary}}. When a value of imaginary type is converted to a value of complex type, the resulting complex type has its real component set to zero. When a value of complex type is converted to a value of imaginary type, the real component is discarded.
+
In addition to the complex types, the three imaginary types may be supported: {{c|double _Imaginary}}, {{c|float _Imaginary}}, and {{c|long double _Imaginary}} (see {{ltt|c/keyword/_Imaginary}}). When the header {{tt|<complex.h>}} is included, the three imaginary types are also accessible as {{c|double imaginary}}, {{c|float imaginary}}, and {{c|long double imaginary}}.
  
Standard arithmetic operators {{c|+, -, *, /}} can be used with real, complex, and imaginary types in any combination.
+
Standard arithmetic operators {{c|+}}, {{c|-}}, {{c|*}}, {{c|/}} can be used with real, complex, and imaginary types in any combination. <!--TODO: link to the arithmetic operators, don't forget cx limited range and the details from G.5.1 and G.5.2. in their description -->
  
If the macro constant {{tt|__STDC_NO_COMPLEX__}}{{mark c11}} is defined by the compiler, the header {{tt|<complex.h>}} and all of the names listed here are not provided.
+
{{rrev multi|since1=c99|rev1=
 +
A compiler that defines {{tt|__STDC_IEC_559_COMPLEX__}} is recommended, but not required to support imaginary numbers. POSIX recommends checking if the macro {{lc|_Imaginary_I}} is defined to identify imaginary number support.
 +
|since2=c11|rev2=
 +
Imaginary numbers are supported if {{tt|__STDC_IEC_559_COMPLEX__}} {{rev inl|since=c23|or  {{tt|__STDC_IEC_60559_COMPLEX__}}}} is defined.
 +
}}
  
If {{c|#pragma STDC CX_LIMITED_RANGE on}} is used, complex multiplication, division, and absolute value may use simplified mathematical formulas, despite the possibility of intermediate overflow.
+
{{dsc begin}}
 +
{{dsc header|complex.h}}
 +
{{dsc h2|Types}}
 +
{{dsc inc|c/numeric/complex/dsc imaginary}}
 +
{{dsc inc|c/numeric/complex/dsc complex}}
  
{{dcl list begin}}
+
{{dsc h2|The imaginary constant}}
{{dcl list header | complex.h}}
+
{{dsc inc|c/numeric/complex/dsc Imaginary_I}}
{{dcl list h2 | Types}}
+
{{dsc inc|c/numeric/complex/dsc Complex_I}}
{{dcl list template | c/numeric/complex/dcl list complex}}
+
{{dsc inc|c/numeric/complex/dsc I}}
{{dcl list template | c/numeric/complex/dcl list Complex_I}}
+
  
{{dcl list h2 | The imaginary constant}}
+
{{dsc h2|Manipulation}}
{{dcl list template | c/numeric/complex/dcl list imaginary}}
+
{{dsc inc|c/numeric/complex/dsc CMPLX}}
{{dcl list template | c/numeric/complex/dcl list Imaginary_I}}
+
{{dsc inc|c/numeric/complex/dsc creal}}
{{dcl list template | c/numeric/complex/dcl list I}}
+
{{dsc inc|c/numeric/complex/dsc cimag}}
 +
{{dsc inc|c/numeric/complex/dsc cabs}}
 +
{{dsc inc|c/numeric/complex/dsc carg}}
 +
{{dsc inc|c/numeric/complex/dsc conj}}
 +
{{dsc inc|c/numeric/complex/dsc cproj}}
  
{{dcl list h2 | Manipulation}}
+
{{dsc h2|Exponential functions}}
{{dcl list template | c/numeric/complex/dcl list CMPLX}}
+
{{dsc inc|c/numeric/complex/dsc cexp}}
{{dcl list template | c/numeric/complex/dcl list cimag}}
+
{{dsc inc|c/numeric/complex/dsc clog}}
{{dcl list template | c/numeric/complex/dcl list creal}}
+
{{dcl list template | c/numeric/complex/dcl list carg}}
+
{{dcl list template | c/numeric/complex/dcl list conj}}
+
{{dcl list template | c/numeric/complex/dcl list cproj}}
+
{{dcl list template | c/numeric/complex/dcl list cabs}}
+
  
{{dcl list h2 | Exponential functinos}}
+
{{dsc h2|Power functions}}
{{dcl list template | c/numeric/complex/dcl list cexp}}
+
{{dsc inc|c/numeric/complex/dsc cpow}}
{{dcl list template | c/numeric/complex/dcl list clog}}
+
{{dsc inc|c/numeric/complex/dsc csqrt}}
  
{{dcl list h2 | Power functions}}
+
{{dsc h2|Trigonometric functions}}
{{dcl list template | c/numeric/complex/dcl list cpow}}
+
{{dsc inc|c/numeric/complex/dsc csin}}
{{dcl list template | c/numeric/complex/dcl list csqrt}}
+
{{dsc inc|c/numeric/complex/dsc ccos}}
 +
{{dsc inc|c/numeric/complex/dsc ctan}}
 +
{{dsc inc|c/numeric/complex/dsc casin}}
 +
{{dsc inc|c/numeric/complex/dsc cacos}}
 +
{{dsc inc|c/numeric/complex/dsc catan}}
  
{{dcl list h2 | Trigonometric functions}}
+
{{dsc h2|Hyperbolic functions}}
{{dcl list template | c/numeric/complex/dcl list cacos}}
+
{{dsc inc|c/numeric/complex/dsc csinh}}
{{dcl list template | c/numeric/complex/dcl list casin}}
+
{{dsc inc|c/numeric/complex/dsc ccosh}}
{{dcl list template | c/numeric/complex/dcl list catan}}
+
{{dsc inc|c/numeric/complex/dsc ctanh}}
{{dcl list template | c/numeric/complex/dcl list ccos}}
+
{{dsc inc|c/numeric/complex/dsc casinh}}
{{dcl list template | c/numeric/complex/dcl list csin}}
+
{{dsc inc|c/numeric/complex/dsc cacosh}}
{{dcl list template | c/numeric/complex/dcl list ctan}}
+
{{dsc inc|c/numeric/complex/dsc catanh}}
 +
{{dsc end}}
  
{{dcl list h2 | Hyperbolic functions}}
+
===Notes===
{{dcl list template | c/numeric/complex/dcl list cacosh}}
+
The following function names are {{rev inl|since=c23|potentially}} reserved for future addition to {{tt|complex.h}} and are not available for use in the programs that include that header: {{lc|cerf}}, {{lc|cerfc}}, {{lc|cexp2}}, {{lc|cexpm1}}, {{lc|clog10}}, {{lc|clog1p}}, {{lc|clog2}}, {{lc|clgamma}}, {{lc|ctgamma}}{{rev inl|since=c23|, {{lc|csinpi}}, {{lc|ccospi}}, {{lc|ctanpi}}, {{lc|casinpi}}, {{lc|cacospi}}, {{lc|catanpi}}, {{lc|ccompoundn}}, {{lc|cpown}}, {{lc|cpowr}}, {{lc|crootn}}, {{lc|crsqrt}}, {{lc|cexp10m1}}, {{lc|cexp10}}, {{lc|cexp2m1}}, {{lc|clog10p1}}, {{lc|clog2p1}}, {{lc|clogp1}}}}, along with their -{{tt|f}} and -{{tt|l}} suffixed variants.
{{dcl list template | c/numeric/complex/dcl list casinh}}
+
 
{{dcl list template | c/numeric/complex/dcl list catanh}}
+
Although the C standard names the inverse hyperbolics with "complex arc hyperbolic sine" etc., the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct names are "complex inverse hyperbolic sine" etc. Some authors use "complex area hyperbolic sine" etc.
{{dcl list template | c/numeric/complex/dcl list ccosh}}
+
 
{{dcl list template | c/numeric/complex/dcl list csinh}}
+
A complex or imaginary number is infinite if one of its parts is infinite, even if the other part is NaN.
{{dcl list template | c/numeric/complex/dcl list ctanh}}
+
 
{{dcl list end}}
+
A complex or imaginary number is finite if both parts are neither infinities nor NaNs.
 +
 
 +
A complex or imaginary number is a zero if both parts are positive or negative zeroes.
 +
 
 +
While MSVC does provide a [https://learn.microsoft.com/en-us/cpp/c-runtime-library/complex-math-support {{tt|<complex.h>}}] header, it does not implement complex numbers as native types, but as {{c|struct}}s, which are incompatible with standard C complex types and do not support the {{c|+}}, {{c|-}}, {{c|*}}, {{c|/}} operators.
 +
 
 +
===Example===
 +
{{example
 +
|code=
 +
#include <complex.h>
 +
#include <stdio.h>
 +
#include <tgmath.h>
 +
 
 +
int main(void)
 +
{
 +
    double complex z1 = I * I;    // imaginary unit squared
 +
    printf("I * I = %.1f%+.1fi\n", creal(z1), cimag(z1));
 +
 
 +
    double complex z2 = pow(I, 2); // imaginary unit squared
 +
    printf("pow(I, 2) = %.1f%+.1fi\n", creal(z2), cimag(z2));
 +
 
 +
    double PI = acos(-1);
 +
    double complex z3 = exp(I * PI); // Euler's formula
 +
    printf("exp(I*PI) = %.1f%+.1fi\n", creal(z3), cimag(z3));
 +
 
 +
    double complex z4 = 1 + 2 * I, z5 = 1 - 2 * I; // conjugates
 +
    printf("(1+2i)*(1-2i) = %.1f%+.1fi\n", creal(z4 * z5), cimag(z4 * z5));
 +
}
 +
|output=
 +
I * I = -1.0+0.0i
 +
pow(I, 2) = -1.0+0.0i
 +
exp(I*PI) = -1.0+0.0i
 +
(1+2i)*(1-2i) = 5.0+0.0i
 +
}}
 +
 
 +
===References===
 +
{{ref std c23}}
 +
{{ref std|section=6.10.8.3/1/2|title={{tt|__STDC_NO_COMPLEX__}}|p=TBD}}
 +
{{ref std|section=6.10.8.3/1/2|title={{tt|__STDC_IEC_559_COMPLEX__}}|p=TBD}}
 +
{{ref std|section=7.3|title=Complex arithmetic {{tt|<complex.h>}}|p=TBD}}
 +
{{ref std|section=7.25|title=Type-generic math {{tt|<tgmath.h>}}|p=TBD}}
 +
{{ref std|section=7.31.1|title=Complex arithmetic {{tt|<complex.h>}}|p=TBD}}
 +
{{ref std|section=Annex G (normative)|title=IEC 60559-compatible complex arithmetic|p=TBD}}
 +
{{ref std end}}
 +
{{ref std c17}}
 +
{{ref std|section=6.10.8.3/1/2|title={{tt|__STDC_NO_COMPLEX__}}|p=128}}
 +
{{ref std|section=6.10.8.3/1/2|title={{tt|__STDC_IEC_559_COMPLEX__}}|p=128}}
 +
{{ref std|section=7.3|title=Complex arithmetic {{tt|<complex.h>}}|p=136-144}}
 +
{{ref std|section=7.25|title=Type-generic math {{tt|<tgmath.h>}}|p=272-273}}
 +
{{ref std|section=7.31.1|title=Complex arithmetic {{tt|<complex.h>}}|p=391}}
 +
{{ref std|section=Annex G (normative)|title=IEC 60559-compatible complex arithmetic|p=469-479}}
 +
{{ref std end}}
 +
{{ref std c11}}
 +
{{ref std|section=6.10.8.3/1/2|title={{tt|__STDC_NO_COMPLEX__}}|p=177}}
 +
{{ref std|section=6.10.8.3/1/2|title={{tt|__STDC_IEC_559_COMPLEX__}}|p=177}}
 +
{{ref std|section=7.3|title=Complex arithmetic {{tt|<complex.h>}}|p=188-199}}
 +
{{ref std|section=7.25|title=Type-generic math {{tt|<tgmath.h>}}|p=373-375}}
 +
{{ref std|section=7.31.1|title=Complex arithmetic {{tt|<complex.h>}}|p=455}}
 +
{{ref std|section=Annex G (normative)|title=IEC 60559-compatible complex arithmetic|p=532-545}}
 +
{{ref std end}}
 +
{{ref std c99}}
 +
{{ref std|section=6.10.8/2|title={{tt|__STDC_IEC_559_COMPLEX__}}|p=161}}
 +
{{ref std|section=7.3|title=Complex arithmetic {{tt|<complex.h>}}|p=170-180}}
 +
{{ref std|section=7.22|title=Type-generic math {{tt|<tgmath.h>}}|p=335-337}}
 +
{{ref std|section=7.26.1|title=Complex arithmetic {{tt|<complex.h>}}|p=401}}
 +
{{ref std|section=Annex G (informative)|title=IEC 60559-compatible complex arithmetic|p=467-480}}
 +
{{ref std end}}
 +
 
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc see cpp|cpp/numeric/complex|Complex number arithmetic|nomono=true}}
 +
{{dsc end}}
 +
 
 +
{{langlinks|ar|cs|de|es|fr|it|ja|ko|pl|pt|ru|tr|zh}}

Latest revision as of 12:35, 1 February 2024

 
 
 
Complex number arithmetic
Types and the imaginary constant
(C99)
(C99)    
(C11)
(C99)
Manipulation
(C99)
(C99)
(C99)
(C99)
(C99)
(C99)
Power and exponential functions
(C99)
(C99)
(C99)
(C99)
Trigonometric functions
(C99)
(C99)
(C99)
(C99)
(C99)
(C99)
Hyperbolic functions
(C99)
(C99)
(C99)
(C99)
(C99)
(C99)
 

If the macro constant __STDC_NO_COMPLEX__ is defined by the implementation, the complex types, the header <complex.h> and all of the names listed here are not provided.

(since C11)

The C programming language, as of C99, supports complex number math with the three built-in types double _Complex, float _Complex, and long double _Complex (see _Complex). When the header <complex.h> is included, the three complex number types are also accessible as double complex, float complex, long double complex.

In addition to the complex types, the three imaginary types may be supported: double _Imaginary, float _Imaginary, and long double _Imaginary (see _Imaginary). When the header <complex.h> is included, the three imaginary types are also accessible as double imaginary, float imaginary, and long double imaginary.

Standard arithmetic operators +, -, *, / can be used with real, complex, and imaginary types in any combination.

A compiler that defines __STDC_IEC_559_COMPLEX__ is recommended, but not required to support imaginary numbers. POSIX recommends checking if the macro _Imaginary_I is defined to identify imaginary number support.

(since C99)
(until C11)

Imaginary numbers are supported if __STDC_IEC_559_COMPLEX__ or __STDC_IEC_60559_COMPLEX__(since C23) is defined.

(since C11)
Defined in header <complex.h>

Contents

Types
imaginary type macro
(keyword macro) [edit]
complex type macro
(keyword macro) [edit]
The imaginary constant
the imaginary unit constant i
(macro constant) [edit]
the complex unit constant i
(macro constant) [edit]
(C99)
the complex or imaginary unit constant i
(macro constant) [edit]
Manipulation
(C11)(C11)(C11)
constructs a complex number from real and imaginary parts
(function macro) [edit]
(C99)(C99)(C99)
computes the real part of a complex number
(function) [edit]
(C99)(C99)(C99)
computes the imaginary part a complex number
(function) [edit]
(C99)(C99)(C99)
computes the magnitude of a complex number
(function) [edit]
(C99)(C99)(C99)
computes the phase angle of a complex number
(function) [edit]
(C99)(C99)(C99)
computes the complex conjugate
(function) [edit]
(C99)(C99)(C99)
computes the projection on Riemann sphere
(function) [edit]
Exponential functions
(C99)(C99)(C99)
computes the complex base-e exponential
(function) [edit]
(C99)(C99)(C99)
computes the complex natural logarithm
(function) [edit]
Power functions
(C99)(C99)(C99)
computes the complex power function
(function) [edit]
(C99)(C99)(C99)
computes the complex square root
(function) [edit]
Trigonometric functions
(C99)(C99)(C99)
computes the complex sine
(function) [edit]
(C99)(C99)(C99)
computes the complex cosine
(function) [edit]
(C99)(C99)(C99)
computes the complex tangent
(function) [edit]
(C99)(C99)(C99)
computes the complex arc sine
(function) [edit]
(C99)(C99)(C99)
computes the complex arc cosine
(function) [edit]
(C99)(C99)(C99)
computes the complex arc tangent
(function) [edit]
Hyperbolic functions
(C99)(C99)(C99)
computes the complex hyperbolic sine
(function) [edit]
(C99)(C99)(C99)
computes the complex hyperbolic cosine
(function) [edit]
(C99)(C99)(C99)
computes the complex hyperbolic tangent
(function) [edit]
(C99)(C99)(C99)
computes the complex arc hyperbolic sine
(function) [edit]
(C99)(C99)(C99)
computes the complex arc hyperbolic cosine
(function) [edit]
(C99)(C99)(C99)
computes the complex arc hyperbolic tangent
(function) [edit]

[edit] Notes

The following function names are potentially(since C23) reserved for future addition to complex.h and are not available for use in the programs that include that header: cerf, cerfc, cexp2, cexpm1, clog10, clog1p, clog2, clgamma, ctgamma, csinpi, ccospi, ctanpi, casinpi, cacospi, catanpi, ccompoundn, cpown, cpowr, crootn, crsqrt, cexp10m1, cexp10, cexp2m1, clog10p1, clog2p1, clogp1(since C23), along with their -f and -l suffixed variants.

Although the C standard names the inverse hyperbolics with "complex arc hyperbolic sine" etc., the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct names are "complex inverse hyperbolic sine" etc. Some authors use "complex area hyperbolic sine" etc.

A complex or imaginary number is infinite if one of its parts is infinite, even if the other part is NaN.

A complex or imaginary number is finite if both parts are neither infinities nor NaNs.

A complex or imaginary number is a zero if both parts are positive or negative zeroes.

While MSVC does provide a <complex.h> header, it does not implement complex numbers as native types, but as structs, which are incompatible with standard C complex types and do not support the +, -, *, / operators.

[edit] Example

#include <complex.h>
#include <stdio.h>
#include <tgmath.h>
 
int main(void)
{
    double complex z1 = I * I;     // imaginary unit squared
    printf("I * I = %.1f%+.1fi\n", creal(z1), cimag(z1));
 
    double complex z2 = pow(I, 2); // imaginary unit squared
    printf("pow(I, 2) = %.1f%+.1fi\n", creal(z2), cimag(z2));
 
    double PI = acos(-1);
    double complex z3 = exp(I * PI); // Euler's formula
    printf("exp(I*PI) = %.1f%+.1fi\n", creal(z3), cimag(z3));
 
    double complex z4 = 1 + 2 * I, z5 = 1 - 2 * I; // conjugates
    printf("(1+2i)*(1-2i) = %.1f%+.1fi\n", creal(z4 * z5), cimag(z4 * z5));
}

Output:

I * I = -1.0+0.0i
pow(I, 2) = -1.0+0.0i
exp(I*PI) = -1.0+0.0i
(1+2i)*(1-2i) = 5.0+0.0i

[edit] References

  • C23 standard (ISO/IEC 9899:2024):
  • 6.10.8.3/1/2 __STDC_NO_COMPLEX__ (p: TBD)
  • 6.10.8.3/1/2 __STDC_IEC_559_COMPLEX__ (p: TBD)
  • 7.3 Complex arithmetic <complex.h> (p: TBD)
  • 7.25 Type-generic math <tgmath.h> (p: TBD)
  • 7.31.1 Complex arithmetic <complex.h> (p: TBD)
  • Annex G (normative) IEC 60559-compatible complex arithmetic (p: TBD)
  • C17 standard (ISO/IEC 9899:2018):
  • 6.10.8.3/1/2 __STDC_NO_COMPLEX__ (p: 128)
  • 6.10.8.3/1/2 __STDC_IEC_559_COMPLEX__ (p: 128)
  • 7.3 Complex arithmetic <complex.h> (p: 136-144)
  • 7.25 Type-generic math <tgmath.h> (p: 272-273)
  • 7.31.1 Complex arithmetic <complex.h> (p: 391)
  • Annex G (normative) IEC 60559-compatible complex arithmetic (p: 469-479)
  • C11 standard (ISO/IEC 9899:2011):
  • 6.10.8.3/1/2 __STDC_NO_COMPLEX__ (p: 177)
  • 6.10.8.3/1/2 __STDC_IEC_559_COMPLEX__ (p: 177)
  • 7.3 Complex arithmetic <complex.h> (p: 188-199)
  • 7.25 Type-generic math <tgmath.h> (p: 373-375)
  • 7.31.1 Complex arithmetic <complex.h> (p: 455)
  • Annex G (normative) IEC 60559-compatible complex arithmetic (p: 532-545)
  • C99 standard (ISO/IEC 9899:1999):
  • 6.10.8/2 __STDC_IEC_559_COMPLEX__ (p: 161)
  • 7.3 Complex arithmetic <complex.h> (p: 170-180)
  • 7.22 Type-generic math <tgmath.h> (p: 335-337)
  • 7.26.1 Complex arithmetic <complex.h> (p: 401)
  • Annex G (informative) IEC 60559-compatible complex arithmetic (p: 467-480)

[edit] See also

C++ documentation for Complex number arithmetic