overby.me
this repo has no description
1.\" Copyright (c) 2006 Apple Computer
2.\"
3.Dd December 11, 2006
4.Dt CABS 3
5.Os BSD 4
6.Sh NAME
7.Nm cabs
8.Nd complex norm (absolute value) function
9.br
10.Nm carg
11.Nd complex argument function
12.Sh SYNOPSIS
13.Fd #include <complex.h>
14.Ft double
15.Fn cabs "double complex z"
16.Ft long double
17.Fn cabsl "long double complex z"
18.Ft float
19.Fn cabsf "float complex z"
20.Ft double
21.Fn carg "double complex z"
22.Ft long double
23.Fn cargl "long double complex z"
24.Ft float
25.Fn cargf "float complex z"
26.Sh DESCRIPTION
27.Fn cabs "z"
28computes the norm (absolute value) of the complex floating-point number
29.Fa z .
30.Pp
31.Fn carg "z"
32computes the argument (also called phase angle) of the complex floating-point number
33.Fa z ,
34with a branch cut on the negative real axis. The result is in
35the range
36.Bq -\*(Pi , \*(Pi ,
37and has the same sign as the imaginary part of
38.Fa z .
39.Sh EXAMPLES
40The function foo defined in the example below applies a non-linear rotation to the
41complex plane, such that points near the origin are not much affected, and points
42far from the origin are rotated by about pi/2.
43.Pp
44This is accomplished by using cabs and carg to convert to polar coordinates, then
45computing the transformation in that coordinate system, and finally converting back
46to the usual rectangular coordinate system.
47.Bd -literal -offset indent
48#include <complex.h>
49#include <math.h>
50
51double complex foo(double complex z) {
52 // get the polar coordinates of z
53 double r = cabs(z);
54 double theta = carg(z);
55
56 // add a value dependent on r to theta
57 theta += atan(r);
58
59 // now change back to rectangular coordinates and
60 // return the new complex number
61 return r*cos(theta) + r*sin(theta)*I;
62}
63.Ed
64.Sh SPECIAL VALUES
65.Fn cabs "x + yi" ,
66.Fn cabs "y + xi" ,
67and
68.Fn cabs "x - yi"
69are equivalent. This is used to abbreviate the specification of special values.
70.Pp
71.Fn cabs "x � 0i"
72is equivalent to
73.Fn fabs "x" .
74.Pp
75.Fn cabs "�inf + yi"
76returns inf even if y is a NaN.
77.Pp
78.Fn cabs "x + NaN i"
79returns NaN, for finite x.
80.Pp
81.Fn cabs "NaN + NaN i"
82returns NaN.
83.Pp
84.Fn carg "-0 � 0i"
85returns �pi.
86.Pp
87.Fn carg "+0 � 0i"
88returns �0.
89.Pp
90.Fn carg "x � 0i"
91returns �pi for x < 0.
92.Pp
93.Fn carg "x � 0i"
94returns �0 for x > 0.
95.Pp
96.Fn carg "�0 + yi"
97returns -pi/2 for y < 0.
98.Pp
99.Fn carg "�0 + yi"
100returns +pi/2 for y > 0.
101.Pp
102.Fn carg "-inf � yi"
103returns �pi for finite y > 0.
104.Pp
105.Fn carg "+inf � yi"
106returns �0 for finite y > 0.
107.Pp
108.Fn carg "x � inf i"
109returns �pi/2 for finite x.
110.Pp
111.Fn carg "-inf � inf i"
112returns �3*pi/4.
113.Pp
114.Fn carg "+inf � inf i"
115returns �pi/4.
116.Pp
117.Fn carg "x + yi"
118returns NaN if either of x or y is NaN.
119.Sh NOTES
120.Fn cabs
121and
122.Fn carg
123are fully specified in terms of real functions:
124.Bd -literal -offset indent
125cabs(x + iy) = hypot(x,y)
126.br
127carg(x + iy) = atan2(y,x).
128.Ed
129.Sh SEE ALSO
130.Xr hypot 3 ,
131.Xr atan2 3 ,
132.Xr fabs 3 ,
133.Xr complex 3
134.Sh STANDARDS
135The
136.Fn cabs
137and
138.Fn carg
139functions conform to ISO/IEC 9899:1999(E).