Update crate with new APIs added for upstream 3.8 release

- max ragged API, docs and example

- API for cov, var & stdev fns that accept bias enum

- bitwise complement

- Bump up Crate version to 3.8.0

- Update GitHub Action CI to use version 3.8.0 Linux installer

- Update README to reflect package manager packages newly being shipped
  starting 3.8.0 release of ArrayFire upstream

Author: 9prady9

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
         name: Build and Test Wrapper
         runs-on: ubuntu-18.04
         env:
-            AF_VER: 3.7.2
+            AF_VER: 3.8.0
         steps:
             - name: Checkout Repository
               uses: actions/checkout@master

Cargo.toml

@@ -2,7 +2,7 @@
 edition       = "2018"
 name          = "arrayfire"
 description   = "ArrayFire is a high performance software library for parallel computing with an easy-to-use API. Its array based function set makes parallel programming simple. ArrayFire's multiple backends (CUDA, OpenCL and native CPU) make it platform independent and highly portable. A few lines of code in ArrayFire can replace dozens of lines of parallel computing code, saving you valuable time and lowering development costs. This crate provides Rust bindings for ArrayFire library."
-version       = "3.7.2"
+version       = "3.8.0"
 documentation = "http://arrayfire.github.io/arrayfire-rust/arrayfire/index.html"
 homepage      = "https://github.com/arrayfire/arrayfire"
 repository    = "https://github.com/arrayfire/arrayfire-rust"

README.md

@@ -22,7 +22,9 @@ Linux, Windows and OSX. Rust 1.31 or newer is required.
 
 To use the rust bindings for ArrayFire from crates.io, the following requirements are to be met first.
 
-1. [Download and install ArrayFire binaries][10] based on your operating system.
+1. [Download and install ArrayFire binaries][10] based on your operating system. Depending on the
+   method of your installation for Linux, steps (2) & (3) may not be required. If that is the case,
+   proceed to step (4) directly.
 2. Set the evironment variable `AF_PATH` to point to ArrayFire installation root folder.
 3. Make sure to add the path to lib files to your path environment variables.
     - On Linux: do `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$AF_PATH/lib64`
@@ -44,7 +46,7 @@ one of the following two ways.
 - [Download and install binaries][10]
 - [Build and install from source][1]
 
-To build arrayfire submodule available in the rust wrapper, you have to do the following.
+To build arrayfire submodule available in the rust wrapper repository, you have to do the following.
 
 ```bash
 git submodule update --init --recursive

src/algorithm/mod.rs

@@ -133,6 +133,13 @@ extern "C" {
         dim: c_int,
         nan_val: c_double,
     ) -> c_int;
+    fn af_max_ragged(
+        val_out: *mut af_array,
+        idx_out: *mut af_array,
+        input: af_array,
+        ragged_len: af_array,
+        dim: c_int,
+    ) -> c_int;
 }
 
 macro_rules! dim_reduce_func_def {
@@ -1440,6 +1447,66 @@ dim_reduce_by_key_nan_func_def!(
     ValueType::ProductOutType
 );
 
+/// Max reduction along given axis as per ragged lengths provided
+///
+/// # Parameters
+///
+/// - `input` contains the input values to be reduced
+/// - `ragged_len` array containing number of elements to use when reducing along `dim`
+/// - `dim` is the dimension along which the max operation occurs
+///
+/// # Return Values
+///
+/// Tuple of Arrays:
+/// - First element: An Array containing the maximum ragged values in `input` along `dim`
+///                  according to `ragged_len`
+/// - Second Element: An Array containing the locations of the maximum ragged values in
+///                   `input` along `dim` according to `ragged_len`
+///
+/// # Examples
+/// ```rust
+/// use arrayfire::{Array, dim4, print, randu, max_ragged};
+/// let vals: [f32; 6] = [1.0f32, 2.0, 3.0, 4.0, 5.0, 6.0];
+/// let rlens: [u32; 2] = [9, 2];
+/// let varr = Array::new(&vals, dim4![3, 2]);
+/// let rarr = Array::new(&rlens, dim4![1, 2]);
+/// print(&varr);
+/// // 1 4
+/// // 2 5
+/// // 3 6
+/// print(&rarr); // numbers of elements to participate in reduction along given axis
+/// // 9 2
+/// let (out, idx) = max_ragged(&varr, &rarr, 0);
+/// print(&out);
+/// // 3 5
+/// print(&idx);
+/// // 2 1 //Since 3 is max element for given length 9 along first column
+///        //Since 5 is max element for given length 2 along second column
+/// ```
+pub fn max_ragged<T>(
+    input: &Array<T>,
+    ragged_len: &Array<u32>,
+    dim: i32,
+) -> (Array<T::InType>, Array<u32>)
+where
+    T: HasAfEnum,
+    T::InType: HasAfEnum,
+{
+    unsafe {
+        let mut out_vals: af_array = std::ptr::null_mut();
+        let mut out_idxs: af_array = std::ptr::null_mut();
+        let err_val = af_max_ragged(
+            &mut out_vals as *mut af_array,
+            &mut out_idxs as *mut af_array,
+            input.get(),
+            ragged_len.get(),
+            dim,
+        );
+        HANDLE_ERROR(AfError::from(err_val));
+        (out_vals.into(), out_idxs.into())
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::super::core::c32;

src/core/arith.rs

@@ -3,7 +3,7 @@ use super::data::{constant, tile, ConstGenerator};
 use super::defines::AfError;
 use super::dim4::Dim4;
 use super::error::HANDLE_ERROR;
-use super::util::{af_array, HasAfEnum, ImplicitPromote};
+use super::util::{af_array, HasAfEnum, ImplicitPromote, IntegralType};
 use num::Zero;
 
 use libc::c_int;
@@ -97,6 +97,7 @@ extern "C" {
     fn af_iszero(out: *mut af_array, arr: af_array) -> c_int;
     fn af_isinf(out: *mut af_array, arr: af_array) -> c_int;
     fn af_isnan(out: *mut af_array, arr: af_array) -> c_int;
+    fn af_bitnot(out: *mut af_array, arr: af_array) -> c_int;
 }
 
 /// Enables use of `!` on objects of type [Array](./struct.Array.html)
@@ -975,3 +976,16 @@ where
         sub(&cnst, &self, true)
     }
 }
+
+/// Perform bitwise complement on all values of Array
+pub fn bitnot<T: HasAfEnum>(input: &Array<T>) -> Array<T>
+where
+    T: HasAfEnum + IntegralType,
+{
+    unsafe {
+        let mut temp: af_array = std::ptr::null_mut();
+        let err_val = af_bitnot(&mut temp as *mut af_array, input.get());
+        HANDLE_ERROR(AfError::from(err_val));
+        temp.into()
+    }
+}

src/core/util.rs

@@ -835,3 +835,15 @@ impl IndexableType for u32 {}
 impl IndexableType for i16 {}
 impl IndexableType for u16 {}
 impl IndexableType for u8 {}
+
+/// Trait qualifier for given type indicating computability of covariance
+pub trait IntegralType {}
+
+impl IntegralType for i64 {}
+impl IntegralType for u64 {}
+impl IntegralType for i32 {}
+impl IntegralType for u32 {}
+impl IntegralType for i16 {}
+impl IntegralType for u16 {}
+impl IntegralType for u8 {}
+impl IntegralType for bool {}