Implement trueloc/falseloc

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 Features available from the latest git source
 
+- new module `stdlib_array`
+  [#603](https://github.com/fortran-lang/stdlib/pull/603)
+  - new procedures `trueloc`, `falseloc`
 - new module `stdlib_distribution_uniform`
   [#272](https://github.com/fortran-lang/stdlib/pull/272)
 - new module `stdlib_selection`

doc/specs/index.md

@@ -11,6 +11,7 @@ This is and index/directory of the specifications (specs) for each new module/fe
 
 ## Experimental Features & Modules
 
+ - [array](./stdlib_array.html) - Procedures for index manipulation and array handling
  - [ascii](./stdlib_ascii.html) - Procedures for handling ASCII characters
  - [bitsets](./stdlib_bitsets.html) - Bitset data types and procedures
  - [error](./stdlib_error.html) - Catching and handling errors

doc/specs/stdlib_array.md

@@ -0,0 +1,101 @@
+---
+title: array
+---
+
+# The `stdlib_array` module
+
+[TOC]
+
+## Introduction
+
+Module for index manipulation and array handling tasks.
+
+## Procedures and methods provided
+
+
+### `trueloc`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Turn a logical mask into an index array by selecting all true values.
+Provides similar functionality like the built-in `where` or the intrinsic procedures `merge` and `pack` when working with logical mask.
+The built-in / intrinsics are usually preferable to `trueloc`, unless the access to the index array is required.
+
+#### Syntax
+
+`loc = [[trueloc(function)]] (array[, lbound])`
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`array`: List of default logical arrays. This argument is `intent(in)`.
+
+`lbound`: Lower bound of the array to index. This argument is `optional` and `intent(in)`.
+
+#### Return value
+
+Returns an array of default integer size, with a maximum length of `size(array)` elements.
+
+#### Examples
+
+```fortran
+program demo_trueloc
+  use stdlib_array, only : trueloc
+  implicit none
+  real, allocatable :: array(:)
+  allocate(array(500))
+  call random_number(array)
+  array(trueloc(array > 0.5)) = 0.0
+end program demo_trueloc
+```
+
+
+### `falseloc`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Turn a logical mask into an index array by selecting all false values.
+Provides similar functionality like the built-in `where` or the intrinsic procedures `merge` and `pack` when working with logical mask.
+The built-in / intrinsics are usually preferable to `falseloc`, unless the access to the index array is required.
+
+#### Syntax
+
+`loc = [[falseloc(function)]] (array[, lbound])`
+
+#### Class
+
+Pure function.
+
+#### Arguments
+
+`array`: List of default logical arrays. This argument is `intent(in)`.
+
+`lbound`: Lower bound of the array to index. This argument is `optional` and `intent(in)`.
+
+#### Return value
+
+Returns an array of default integer size, with a maximum length of `size(array)` elements.
+
+#### Examples
+
+```fortran
+program demo_falseloc
+  use stdlib_array, only : falseloc
+  implicit none
+  real, allocatable :: array(:)
+  allocate(array(-200:200))
+  call random_number(array)
+  array(falseloc(array < 0.5), lbound(array)) = 0.0
+end program demo_falseloc
+```

src/CMakeLists.txt

@@ -71,6 +71,7 @@ list(
 fypp_f90("${fyppFlags}" "${fppFiles}" outFiles)
 
 set(SRC
+    stdlib_array.f90
     stdlib_error.f90
     stdlib_logger.f90
     stdlib_system.F90

src/Makefile.manual

@@ -46,6 +46,7 @@ SRCFYPP = \
         stdlib_version.fypp
 
 SRC = f18estop.f90 \
+      stdlib_array.f90 \
       stdlib_error.f90 \
       stdlib_specialfunctions.f90 \
       stdlib_specialfunctions_legendre.f90 \

src/stdlib_array.f90

@@ -0,0 +1,68 @@
+! SPDX-Identifier: MIT
+
+!> Module for index manipulation and general array handling
+!>
+!> The specification of this module is available [here](../page/specs/stdlib_array.html).
+module stdlib_array
+  implicit none
+  private
+
+  public :: trueloc, falseloc
+
+contains
+
+  !> Version: experimental
+  !>
+  !> Return the positions of the true elements in array.
+  !> [Specification](../page/specs/stdlib_array.html#trueloc)
+  pure function trueloc(array, lbound) result(loc)
+    !> Mask of logicals
+    logical, intent(in) :: array(:)
+    !> Lower bound of array to index
+    integer, intent(in), optional :: lbound
+    !> Locations of true elements
+    integer :: loc(count(array))
+
+    call logicalloc(loc, array, .true., lbound)
+  end function trueloc
+
+  !> Version: experimental
+  !>
+  !> Return the positions of the false elements in array.
+  !> [Specification](../page/specs/stdlib_array.html#falseloc)
+  pure function falseloc(array, lbound) result(loc)
+    !> Mask of logicals
+    logical, intent(in) :: array(:)
+    !> Lower bound of array to index
+    integer, intent(in), optional :: lbound
+    !> Locations of false elements
+    integer :: loc(count(.not.array))
+
+    call logicalloc(loc, array, .false., lbound)
+  end function falseloc
+
+  !> Return the positions of the truthy elements in array
+  pure subroutine logicalloc(loc, array, truth, lbound)
+    !> Locations of truthy elements
+    integer, intent(out) :: loc(:)
+    !> Mask of logicals
+    logical, intent(in) :: array(:)
+    !> Truthy value
+    logical, intent(in) :: truth
+    !> Lower bound of array to index
+    integer, intent(in), optional :: lbound
+    integer :: i, pos, offset
+
+    offset = 0
+    if (present(lbound)) offset = lbound - 1
+
+    i = 0
+    do pos = 1, size(array)
+      if (array(pos).eqv.truth) then
+        i = i + 1
+        loc(i) = pos + offset
+      end if
+    end do
+  end subroutine logicalloc
+
+end module stdlib_array

src/tests/CMakeLists.txt

@@ -15,6 +15,7 @@ list(
   "-I${PROJECT_SOURCE_DIR}/src"
 )
 
+add_subdirectory(array)
 add_subdirectory(ascii)
 add_subdirectory(bitsets)
 add_subdirectory(io)

src/tests/Makefile.manual

@@ -12,6 +12,7 @@ testdrive.F90:
 	$(FETCH) https://github.com/fortran-lang/test-drive/raw/v0.4.0/src/testdrive.F90 > $@
 
 all test clean::
+	$(MAKE) -f Makefile.manual --directory=array $@
 	$(MAKE) -f Makefile.manual --directory=ascii $@
 	$(MAKE) -f Makefile.manual --directory=bitsets $@
 	$(MAKE) -f Makefile.manual --directory=io $@

src/tests/array/CMakeLists.txt

@@ -0,0 +1 @@
+ADDTEST(logicalloc)

src/tests/array/Makefile.manual

@@ -0,0 +1,4 @@
+PROGS_SRC = test_logicalloc.f90
+
+
+include ../Makefile.manual.test.mk