.TH "Float.Array" 3o 2023-09-18 OCamldoc "OCaml library"
.SH NAME
Float.Array \- Float arrays with packed representation.
.SH Module
Module   Float.Array
.SH Documentation
.sp
Module
.BI "Array"
 : 
.B sig end

.sp
Float arrays with packed representation\&.

.sp

.sp
.sp
.I type t 
= 
.B floatarray

.sp
The type of float arrays with packed representation\&.

.sp
.B "Since"
4.08.0

.sp

.I val length 
: 
.B t -> int
.sp
Return the length (number of elements) of the given floatarray\&.

.sp

.I val get 
: 
.B t -> int -> float
.sp

.ft B
get a n
.ft R
returns the element number 
.ft B
n
.ft R
of floatarray 
.ft B
a
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
n
.ft R
is outside the range 0 to
.ft B
(length a \- 1)
.ft R
\&.

.sp

.I val set 
: 
.B t -> int -> float -> unit
.sp

.ft B
set a n x
.ft R
modifies floatarray 
.ft B
a
.ft R
in place, replacing element
number 
.ft B
n
.ft R
with 
.ft B
x
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
n
.ft R
is outside the range 0 to
.ft B
(length a \- 1)
.ft R
\&.

.sp

.I val make 
: 
.B int -> float -> t
.sp

.ft B
make n x
.ft R
returns a fresh floatarray of length 
.ft B
n
.ft R
, initialized with 
.ft B
x
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
n < 0
.ft R
or 
.ft B
n > Sys\&.max_floatarray_length
.ft R
\&.

.sp

.I val create 
: 
.B int -> t
.sp

.ft B
create n
.ft R
returns a fresh floatarray of length 
.ft B
n
.ft R
,
with uninitialized data\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
n < 0
.ft R
or 
.ft B
n > Sys\&.max_floatarray_length
.ft R
\&.

.sp

.I val init 
: 
.B int -> (int -> float) -> t
.sp

.ft B
init n f
.ft R
returns a fresh floatarray of length 
.ft B
n
.ft R
,
with element number 
.ft B
i
.ft R
initialized to the result of 
.ft B
f i
.ft R
\&.
In other terms, 
.ft B
init n f
.ft R
tabulates the results of 
.ft B
f
.ft R
applied to the integers 
.ft B
0
.ft R
to 
.ft B
n\-1
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
n < 0
.ft R
or 
.ft B
n > Sys\&.max_floatarray_length
.ft R
\&.

.sp

.I val append 
: 
.B t -> t -> t
.sp

.ft B
append v1 v2
.ft R
returns a fresh floatarray containing the
concatenation of the floatarrays 
.ft B
v1
.ft R
and 
.ft B
v2
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if
.ft B
length v1 + length v2 > Sys\&.max_floatarray_length
.ft R
\&.

.sp

.I val concat 
: 
.B t list -> t
.sp
Same as 
.ft B
Float\&.Array\&.append
.ft R
, but concatenates a list of floatarrays\&.

.sp

.I val sub 
: 
.B t -> int -> int -> t
.sp

.ft B
sub a pos len
.ft R
returns a fresh floatarray of length 
.ft B
len
.ft R
,
containing the elements number 
.ft B
pos
.ft R
to 
.ft B
pos + len \- 1
.ft R
of floatarray 
.ft B
a
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
pos
.ft R
and 
.ft B
len
.ft R
do not
designate a valid subarray of 
.ft B
a
.ft R
; that is, if
.ft B
pos < 0
.ft R
, or 
.ft B
len < 0
.ft R
, or 
.ft B
pos + len > length a
.ft R
\&.

.sp

.I val copy 
: 
.B t -> t
.sp

.ft B
copy a
.ft R
returns a copy of 
.ft B
a
.ft R
, that is, a fresh floatarray
containing the same elements as 
.ft B
a
.ft R
\&.

.sp

.I val fill 
: 
.B t -> int -> int -> float -> unit
.sp

.ft B
fill a pos len x
.ft R
modifies the floatarray 
.ft B
a
.ft R
in place,
storing 
.ft B
x
.ft R
in elements number 
.ft B
pos
.ft R
to 
.ft B
pos + len \- 1
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
pos
.ft R
and 
.ft B
len
.ft R
do not
designate a valid subarray of 
.ft B
a
.ft R
\&.

.sp

.I val blit 
: 
.B t -> int -> t -> int -> int -> unit
.sp

.ft B
blit src src_pos dst dst_pos len
.ft R
copies 
.ft B
len
.ft R
elements
from floatarray 
.ft B
src
.ft R
, starting at element number 
.ft B
src_pos
.ft R
,
to floatarray 
.ft B
dst
.ft R
, starting at element number 
.ft B
dst_pos
.ft R
\&.
It works correctly even if
.ft B
src
.ft R
and 
.ft B
dst
.ft R
are the same floatarray, and the source and
destination chunks overlap\&.

.sp
.B "Raises Invalid_argument"
if 
.ft B
src_pos
.ft R
and 
.ft B
len
.ft R
do not
designate a valid subarray of 
.ft B
src
.ft R
, or if 
.ft B
dst_pos
.ft R
and 
.ft B
len
.ft R
do not
designate a valid subarray of 
.ft B
dst
.ft R
\&.

.sp

.I val to_list 
: 
.B t -> float list
.sp

.ft B
to_list a
.ft R
returns the list of all the elements of 
.ft B
a
.ft R
\&.

.sp

.I val of_list 
: 
.B float list -> t
.sp

.ft B
of_list l
.ft R
returns a fresh floatarray containing the elements
of 
.ft B
l
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if the length of 
.ft B
l
.ft R
is greater than
.ft B
Sys\&.max_floatarray_length
.ft R
\&.

.sp

.PP
.SS Iterators

.PP

.I val iter 
: 
.B (float -> unit) -> t -> unit
.sp

.ft B
iter f a
.ft R
applies function 
.ft B
f
.ft R
in turn to all
the elements of 
.ft B
a
.ft R
\&.  It is equivalent to
.ft B
f a\&.(0); f a\&.(1); \&.\&.\&.; f a\&.(length a \- 1); ()
.ft R
\&.

.sp

.I val iteri 
: 
.B (int -> float -> unit) -> t -> unit
.sp
Same as 
.ft B
Float\&.Array\&.iter
.ft R
, but the
function is applied with the index of the element as first argument,
and the element itself as second argument\&.

.sp

.I val map 
: 
.B (float -> float) -> t -> t
.sp

.ft B
map f a
.ft R
applies function 
.ft B
f
.ft R
to all the elements of 
.ft B
a
.ft R
,
and builds a floatarray with the results returned by 
.ft B
f
.ft R
\&.

.sp

.I val mapi 
: 
.B (int -> float -> float) -> t -> t
.sp
Same as 
.ft B
Float\&.Array\&.map
.ft R
, but the
function is applied to the index of the element as first argument,
and the element itself as second argument\&.

.sp

.I val fold_left 
: 
.B ('a -> float -> 'a) -> 'a -> t -> 'a
.sp

.ft B
fold_left f x init
.ft R
computes
.ft B
f (\&.\&.\&. (f (f x init\&.(0)) init\&.(1)) \&.\&.\&.) init\&.(n\-1)
.ft R
,
where 
.ft B
n
.ft R
is the length of the floatarray 
.ft B
init
.ft R
\&.

.sp

.I val fold_right 
: 
.B (float -> 'a -> 'a) -> t -> 'a -> 'a
.sp

.ft B
fold_right f a init
.ft R
computes
.ft B
f a\&.(0) (f a\&.(1) ( \&.\&.\&. (f a\&.(n\-1) init) \&.\&.\&.))
.ft R
,
where 
.ft B
n
.ft R
is the length of the floatarray 
.ft B
a
.ft R
\&.

.sp

.PP
.SS Iterators on two arrays

.PP

.I val iter2 
: 
.B (float -> float -> unit) -> t -> t -> unit
.sp

.ft B
Array\&.iter2 f a b
.ft R
applies function 
.ft B
f
.ft R
to all the elements of 
.ft B
a
.ft R
and 
.ft B
b
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if the floatarrays are not the same size\&.

.sp

.I val map2 
: 
.B (float -> float -> float) -> t -> t -> t
.sp

.ft B
map2 f a b
.ft R
applies function 
.ft B
f
.ft R
to all the elements of 
.ft B
a
.ft R
and 
.ft B
b
.ft R
, and builds a floatarray with the results returned by 
.ft B
f
.ft R
:
.ft B
[| f a\&.(0) b\&.(0); \&.\&.\&.; f a\&.(length a \- 1) b\&.(length b \- 1)|]
.ft R
\&.

.sp
.B "Raises Invalid_argument"
if the floatarrays are not the same size\&.

.sp

.PP
.SS Array scanning

.PP

.I val for_all 
: 
.B (float -> bool) -> t -> bool
.sp

.ft B
for_all f [|a1; \&.\&.\&.; an|]
.ft R
checks if all elements of the floatarray
satisfy the predicate 
.ft B
f
.ft R
\&. That is, it returns
.ft B
(f a1) && (f a2) && \&.\&.\&. && (f an)
.ft R
\&.

.sp

.I val exists 
: 
.B (float -> bool) -> t -> bool
.sp

.ft B
exists f [|a1; \&.\&.\&.; an|]
.ft R
checks if at least one element of
the floatarray satisfies the predicate 
.ft B
f
.ft R
\&. That is, it returns
.ft B
(f a1) || (f a2) || \&.\&.\&. || (f an)
.ft R
\&.

.sp

.I val mem 
: 
.B float -> t -> bool
.sp

.ft B
mem a set
.ft R
is true if and only if there is an element of 
.ft B
set
.ft R
that is
structurally equal to 
.ft B
a
.ft R
, i\&.e\&. there is an 
.ft B
x
.ft R
in 
.ft B
set
.ft R
such
that 
.ft B
compare a x = 0
.ft R
\&.

.sp

.I val mem_ieee 
: 
.B float -> t -> bool
.sp
Same as 
.ft B
Float\&.Array\&.mem
.ft R
, but uses IEEE equality instead of structural equality\&.

.sp

.PP
.SS Sorting

.PP

.I val sort 
: 
.B (float -> float -> int) -> t -> unit
.sp
Sort a floatarray in increasing order according to a comparison
function\&.  The comparison function must return 0 if its arguments
compare as equal, a positive integer if the first is greater,
and a negative integer if the first is smaller (see below for a
complete specification)\&.  For example, 
.ft B
compare
.ft R
is
a suitable comparison function\&.  After calling 
.ft B
sort
.ft R
, the
array is sorted in place in increasing order\&.
.ft B
sort
.ft R
is guaranteed to run in constant heap space
and (at most) logarithmic stack space\&.
.sp
The current implementation uses Heap Sort\&.  It runs in constant
stack space\&.
.sp
Specification of the comparison function:
Let 
.ft B
a
.ft R
be the floatarray and 
.ft B
cmp
.ft R
the comparison function\&. The following
must be true for all 
.ft B
x
.ft R
, 
.ft B
y
.ft R
, 
.ft B
z
.ft R
in 
.ft B
a
.ft R
:
.sp
\-     
.ft B
cmp x y
.ft R
> 0 if and only if 
.ft B
cmp y x
.ft R
< 0
.sp
\-     if 
.ft B
cmp x y
.ft R
>= 0 and 
.ft B
cmp y z
.ft R
>= 0 then 
.ft B
cmp x z
.ft R
>= 0

When 
.ft B
sort
.ft R
returns, 
.ft B
a
.ft R
contains the same elements as before,
reordered in such a way that for all i and j valid indices of 
.ft B
a
.ft R
:
.sp
\-     
.ft B
cmp a\&.(i) a\&.(j)
.ft R
>= 0 if and only if i >= j


.sp

.I val stable_sort 
: 
.B (float -> float -> int) -> t -> unit
.sp
Same as 
.ft B
Float\&.Array\&.sort
.ft R
, but the sorting algorithm is stable (i\&.e\&.
elements that compare equal are kept in their original order) and
not guaranteed to run in constant heap space\&.
.sp
The current implementation uses Merge Sort\&. It uses a temporary
floatarray of length 
.ft B
n/2
.ft R
, where 
.ft B
n
.ft R
is the length of the floatarray\&.
It is usually faster than the current implementation of 
.ft B
Float\&.Array\&.sort
.ft R
\&.

.sp

.I val fast_sort 
: 
.B (float -> float -> int) -> t -> unit
.sp
Same as 
.ft B
Float\&.Array\&.sort
.ft R
or 
.ft B
Float\&.Array\&.stable_sort
.ft R
, whichever is faster
on typical input\&.

.sp

.PP
.SS Float arrays and Sequences

.PP

.I val to_seq 
: 
.B t -> float Seq.t
.sp
Iterate on the floatarray, in increasing order\&. Modifications of the
floatarray during iteration will be reflected in the sequence\&.

.sp

.I val to_seqi 
: 
.B t -> (int * float) Seq.t
.sp
Iterate on the floatarray, in increasing order, yielding indices along
elements\&. Modifications of the floatarray during iteration will be
reflected in the sequence\&.

.sp

.I val of_seq 
: 
.B float Seq.t -> t
.sp
Create an array from the generator\&.

.sp

.I val map_to_array 
: 
.B (float -> 'a) -> t -> 'a array
.sp

.ft B
map_to_array f a
.ft R
applies function 
.ft B
f
.ft R
to all the elements of 
.ft B
a
.ft R
,
and builds an array with the results returned by 
.ft B
f
.ft R
:
.ft B
[| f a\&.(0); f a\&.(1); \&.\&.\&.; f a\&.(length a \- 1) |]
.ft R
\&.

.sp

.I val map_from_array 
: 
.B ('a -> float) -> 'a array -> t
.sp

.ft B
map_from_array f a
.ft R
applies function 
.ft B
f
.ft R
to all the elements of 
.ft B
a
.ft R
,
and builds a floatarray with the results returned by 
.ft B
f
.ft R
\&.

.sp