Merge remote-tracking branch 'origin/master' into Distribution-Exponential

Author: jim-215-fisher

API-doc-FORD-file.md

@@ -28,7 +28,7 @@ extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORT
 print_creation_date: true
 creation_date: %Y-%m-%d %H:%M %z
 project_github: https://github.com/fortran-lang/stdlib
-project_download: https://github.com/fortran-lang/stdlib/archive/master.zip
+project_download: https://github.com/fortran-lang/stdlib/archive/HEAD.zip
 project_website: https://stdlib.fortran-lang.org
 favicon: doc/media/favicon.ico
 license: by-sa
@@ -57,7 +57,7 @@ The documentation for comment markup in source code, running [FORD] and the [FOR
 
 [FORD]: https://github.com/Fortran-FOSS-Programmers/ford#readme
 [FORD wiki]: https://github.com/Fortran-FOSS-Programmers/ford/wiki
-[FORD project file]: https://github.com/fortran-lang/stdlib/blob/master/API-doc-FORD-file.md
+[FORD project file]: https://github.com/fortran-lang/stdlib/blob/HEAD/API-doc-FORD-file.md
 
 Goals and Motivation
 ====================

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`
@@ -10,9 +13,17 @@ Features available from the latest git source
 - new module `stdlib_version`
   [#579](https://github.com/fortran-lang/stdlib/pull/579)
   - new procedure `get_stdlib_version`
+- update module `stdlib_io`
+  [597](https://github.com/fortran-lang/stdlib/pull/597)
+  - new procedure `getline`
 - new module `stdlib_io_npy`
   [#581](https://github.com/fortran-lang/stdlib/pull/581)
   - new procedures `save_npy`, `load_npy`
+- update module `stdlib_math`
+  - new procedures `is_close` and `all_close`
+    [#488](https://github.com/fortran-lang/stdlib/pull/488)
+  - new procedures `arg`, `argd` and `argpi`
+    [#498](https://github.com/fortran-lang/stdlib/pull/498)
 
 Changes to existing modules
 

CONTRIBUTING.md

@@ -9,7 +9,7 @@ requests.
 
 By contributing to *stdlib*, you certify that you own or are allowed to share the
 content of your contribution under the
-[stdlib license](https://github.com/fortran-lang/stdlib/blob/master/LICENSE).
+[stdlib license](https://github.com/fortran-lang/stdlib/blob/HEAD/LICENSE).
 
 * [Style](#style)
 * [Reporting a bug](#reporting-a-bug)
@@ -22,7 +22,7 @@ content of your contribution under the
 ## Style
 
 Please follow the
-[Fortran stdlib style guide](https://github.com/fortran-lang/stdlib/blob/master/STYLE_GUIDE.md)
+[Fortran stdlib style guide](https://github.com/fortran-lang/stdlib/blob/HEAD/STYLE_GUIDE.md)
 for any Fortran code that you contribute.
 This allows the community to focus on substance rather than style.
 
@@ -42,7 +42,7 @@ Before opening a bug report:
 1. Check if the issue has already been reported
    ([issues](https://github.com/fortran-lang/stdlib/issues)).
 2. Check if it is still an issue or it has been fixed?
-   Try to reproduce it with the latest version from the master branch.
+   Try to reproduce it with the latest version from the default branch.
 3. Isolate the problem and create a minimal test case.
 
 A good bug report should include all information needed to reproduce the bug.
@@ -74,7 +74,7 @@ It is quite possible we have not considered such solutions yet.
 ## Workflow
 
 The general workflow is documented in
-[this document](https://github.com/fortran-lang/stdlib/blob/master/WORKFLOW.md)
+[this document](https://github.com/fortran-lang/stdlib/blob/HEAD/WORKFLOW.md)
 
 The workflow guide is a living document.
 You are welcome to propose changes to the workflow by
@@ -93,7 +93,7 @@ You are welcome to propose changes to the workflow by
   [CHANGELOG](https://github.com/fortran-lang/stdlib/blob/master/CHANGELOG.md)
 * Be open to constructive criticism and requests for improving your code.
 * Again, please follow the
-  [Fortran stdlib style guide](https://github.com/fortran-lang/stdlib/blob/master/STYLE_GUIDE.md).
+  [Fortran stdlib style guide](https://github.com/fortran-lang/stdlib/blob/HEAD/STYLE_GUIDE.md).
 
 
 ## For new contributors

README.md

@@ -184,7 +184,7 @@ make -f Makefile.manual ADD_FYPPFLAGS=-DMAXRANK=4
 
 You can also specify the compiler and compiler-flags by setting the ``FC`` and ``FFLAGS`` environmental variables. Among other things, this facilitates use of compiler optimizations that are not specified in the Makefile.manual defaults.
 ```sh
-make -f Makefile.manual ADD_FYPPFLAGS=-DMAXRANK=4 FC=gfortran FFLAGS="-O3 -flto"
+make -f Makefile.manual ADD_FYPPFLAGS=-DMAXRANK=4 FC=gfortran FFLAGS="-O3"
 ```
 
 ### Build with [fortran-lang/fpm](https://github.com/fortran-lang/fpm)

STYLE_GUIDE.md

@@ -81,7 +81,7 @@ The following two sections are most relevant for contributing new code:
 
 To write the "spec" (specification) for a new proposal, please place it in the
 [FORD "pages"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Pages) directory at
-[`doc/specs/`](https://github.com/fortran-lang/stdlib/tree/master/doc/specs).
+[`doc/specs/`](https://github.com/fortran-lang/stdlib/tree/HEAD/doc/specs).
 To get help please see the ["Writing Pages"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Pages)
 and ["Writing Documentation"](https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Documentation) pages
 on the [FORD wiki](https://github.com/Fortran-FOSS-Programmers/ford/wiki).

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
+```

doc/specs/stdlib_io.md

@@ -223,3 +223,53 @@ program demo_savenpy
     call save_npy('example.npy', x)
 end program demo_savenpy
 ```
+
+## `getline`
+
+### Status
+
+Experimental
+
+### Description
+
+Read a whole line from a formatted unit into a string variable
+
+### Syntax
+
+`call [[stdlib_io(module):getline(interface)]] (unit, line[, iostat][, iomsg])`
+`call [[stdlib_io(module):getline(interface)]] (line[, iostat][, iomsg])`
+
+### Arguments
+
+`unit`: Formatted input unit.
+        This argument is `intent(in)`.
+        If `unit` is not specified standard input is used.
+
+`line`: Deferred length character or `string_type` variable.
+        This argument is `intent(out)`.
+
+`iostat`: Default integer, contains status of reading from unit, zero in case of success.
+          It is an optional argument, in case not present the program will halt for non-zero status.
+          This argument is `intent(out)`.
+
+`iomsg`: Deferred length character value, contains error message in case `iostat` is non-zero.
+         It is an optional argument, error message will be dropped if not present.
+         This argument is `intent(out)`.
+
+### Example
+
+```fortran
+program demo_getline
+    use, intrinsic :: iso_fortran_env, only : input_unit, output_unit
+    use stdlib_io, only: getline
+    implicit none
+    character(len=:), allocatable :: line
+    integer :: stat
+
+    call getline(input_unit, line, stat)
+    do while(stat == 0)
+      write(output_unit, '(a)') line
+      call getline(input_unit, line, stat)
+    end do
+end program demo_getline
+```