lib/libm/complex/cproj.3

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "CPROJ" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" cproj
   4 .SH NAME
   5 cproj, cprojf, cprojl \- complex projection functions
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <complex.h>
   9 .br
  10 .sp
  11 double complex cproj(double complex\fP \fIz\fP\fB);
  12 .br
  13 float complex cprojf(float complex\fP \fIz\fP\fB);
  14 .br
  15 long double complex cprojl(long double complex\fP \fIz\fP\fB);
  16 .br
  17 \fP
  18 .SH DESCRIPTION
  19 .LP
  20 These functions compute a projection of \fIz\fP onto the Riemann
  21 sphere: \fIz\fP projects to \fIz\fP, except that all
  22 complex infinities (even those with one infinite part and one NaN
  23 part) project to positive infinity on the real axis. If \fIz\fP
  24 has an infinite part, then \fIcproj\fP( \fIz\fP) shall be equivalent
  25 to:
  26 .sp
  27 .RS
  28 .nf
  29
  30 \fBINFINITY + I * copysign(0.0, cimag(z))
  31 \fP
  32 .fi
  33 .RE
  34 .SH RETURN VALUE
  35 .LP
  36 These functions return the value of the projection onto the
  37 Riemann sphere.
  38 .SH ERRORS
  39 .LP
  40 No errors are defined.
  41 .LP
  42 \fIThe following sections are informative.\fP
  43 .SH EXAMPLES
  44 .LP
  45 None.
  46 .SH APPLICATION USAGE
  47 .LP
  48 None.
  49 .SH RATIONALE
  50 .LP
  51 Two topologies are commonly used in complex mathematics: the complex
  52 plane with its continuum of infinities, and the Riemann
  53 sphere with its single infinity. The complex plane is better suited
  54 for transcendental functions, the Riemann sphere for algebraic
  55 functions. The complex types with their multiplicity of infinities
  56 provide a useful (though imperfect) model for the complex plane.
  57 The \fIcproj\fP() function helps model the Riemann sphere by mapping
  58 all infinities to one, and should be used just before any
  59 operation, especially comparisons, that might give spurious results
  60 for any of the other infinities. Note that a complex value with
  61 one infinite part and one NaN part is regarded as an infinity, not
  62 a NaN, because if one part is infinite, the complex value is
  63 infinite independent of the value of the other part. For the same
  64 reason, \fIcabs\fP()
  65 returns an infinity if its argument has an infinite part and a NaN
  66 part.
  67 .SH FUTURE DIRECTIONS
  68 .LP
  69 None.
  70 .SH SEE ALSO
  71 .LP
  72 \fIcarg\fP(), \fIcimag\fP(), \fIconj\fP(), \fIcreal\fP(), the
  73 Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<complex.h>\fP
  74 .SH COPYRIGHT
  75 Portions of this text are reprinted and reproduced in electronic form
  76 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  77 -- Portable Operating System Interface (POSIX), The Open Group Base
  78 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
  79 Electrical and Electronics Engineers, Inc and The Open Group. In the
  80 event of any discrepancy between this version and the original IEEE and
  81 The Open Group Standard, the original IEEE and The Open Group Standard
  82 is the referee document. The original Standard can be obtained online at
  83 http://www.opengroup.org/unix/online.html .