.\" Copyright (c) 2012 Apple Inc.
.\" All rights reserved.
.Dd December 15, 2012
.Dt __COSPI 3
.Os
.Sh NAME
.Nm __cospi
.Nd cosine-pi function
.Sh SYNOPSIS
.Fd #include <math.h>
.Ft float
.Fn __cospif "float x"
.Ft double
.Fn __cospi "double x"
.Sh DESCRIPTION
The
.Fn __cospi
function returns the cosine of pi times
.Fa x
(measured in radians).  This can be computed more accurately than
.Fn cos "M_PI * x" ,
because it can implicitly use as many bits of pi as are necessary to deliver a
well-rounded result, instead of the 53-bits to which M_PI is limited.  For
large
.Fa x
it may also be more efficient, as the argument reduction involved
is significantly simpler.
.Pp
This function may be especially useful for working with degrees; whereas
.Fn cos "M_PI * x / 180.0"
cannot produce exact results for angles that naively "should" be exact,
like 90 degrees,
.Fn __cospi "x / 180.0"
can be computed exactly.
.Sh SPECIAL VALUES
.Fn __cospi "-x"
is the same as
.Fn __cospi "x"
for any finite 
.Fa x .
.br
.Fn __cospi "n"
returns +1 for any even integer
.Fa n .
.br
.Fn __cospi "n"
returns -1 for any odd integer
.Fa n .
.br
.Fn __cospi "n + 0.5"
returns +0 for any integer
.Fa n .
.br
.Fn __cospi "±infinity"
raises the invalid floating-point exception and returns
.Fa NaN .
.Sh VECTOR OPERATIONS
If you need to apply the
.Fn __cospi
function to SIMD vectors or arrays, using the following functions provided
by the Accelerate.framework may be useful:
.Pp
.Fd #include <Accelerate/Accelerate.h>
.Pp
.Ft vFloat
.Fn vcospif "vFloat x" ;
.br
.Ft void
.Fn vvcospif "float *y" "const float *x" "const int *n" ;
.br
.Ft void
.Fn vvcospi "double *y" "const double *x" "const int *n" ;
.Sh SEE ALSO
.Xr __sinpi 3 ,
.Xr __tanpi 3 ,
.Xr __sincospi 3 ,
.Xr math 3