Merge branch 'master' into develop_clip

Author: aman-godara

README.md

@@ -3,6 +3,18 @@
 [![Actions Status](https://github.com/fortran-lang/stdlib/workflows/CI/badge.svg)](https://github.com/fortran-lang/stdlib/actions)
 [![Actions Status](https://github.com/fortran-lang/stdlib/workflows/CI_windows/badge.svg)](https://github.com/fortran-lang/stdlib/actions)
 
+* [Goals and Motivation](#goals-and-motivation)
+* [Scope](#scope)
+* [Getting started](#getting-started)
+  - [Get the code](#get-the-code)
+  - [Requirements](#requirements)
+  - [Supported compilers](#supported-compilers)
+  - [Build with CMake](#build-with-cmake)
+  - [Build with make](#build-with-make)
+* [Using stdlib in your project](#using-stdlib-in-your-project)
+* [Documentation](#documentation)
+* [Contributing](#contributing)
+* [Links](#links)
 
 ## Goals and Motivation
 
@@ -138,7 +150,7 @@ To test your build, run the test suite after the build has finished with
 cmake --build build --target test
 ```
 
-Please report failing tests on our [issue tracker](https://github.com/fortran-lang/stdlib/issues/new/choose) including details on the compiler used, the operating system and platform architecture.
+Please report failing tests on our [issue tracker](https://github.com/fortran-lang/stdlib/issues/new/choose) including details of the compiler used, the operating system and platform architecture.
 
 To install the project to the declared prefix run
 

STYLE_GUIDE.md

@@ -47,7 +47,7 @@ focus on the semantics of the proposed changes rather than style and formatting.
 <!-- ATTENTION! This section includes intentional trailing whitespace to get decent formatting with GFM and Python Markdown. -->
 
 * Always specify `intent` for dummy arguments.
-* Don't use `dimension` attribute to declare arrays because it is less verbose.
+* Don't use `dimension` attribute to declare arrays because it is more verbose.
   Use this:  
   ```
   real, allocatable :: a(:), b(:,:)

WORKFLOW.md

@@ -59,3 +59,74 @@ PR and proposal was approved by "vast majority".
 
 You are welcome to propose changes to this workflow by opening an
 [issue](https://github.com/fortran-lang/stdlib/issues).
+
+
+## Build system
+
+This project supports two build systems right now, CMake and make.
+Eventually, stdlib will be using the Fortran package manager
+([fpm](https://github.com/fortran-lang/fpm)) as build system as well.
+The effort of supporting fpm is tracked in issue
+[#279](https://github.com/fortran-lang/stdlib/issues/279).
+
+
+### CMake build files
+
+The build files for CMake allow both in-tree, *i.e.* build artifacts share
+the same tree as the source files, and out-of-tree builds, *i.e.* build artifacts
+exist in a separate directory tree.
+Both build types are explicitly supported and tested, the latter strategy
+is recommended for local development.
+
+Sources for the main library target are added in ``src/CMakeLists.txt``
+relative to the library target, *i.e.* no absolute paths are required.
+
+To add tests, the macro ``ADDTEST`` should be used instead of the CMake function
+``add_test``, the macro hides creation of the executable target, linking against the 
+main library target and registering the test.
+The tests themselves are defined as standalone executables in the subdirectories
+in ``src/tests``, a new subdirectory with tests has to be registred in
+``src/tests/CMakeLists.txt``.
+
+The source tree should be considered read-only. References to ``PROJECT_SOURCE_DIR``
+and ``CMAKE_CURRENT_SOURCE_DIR`` should only be used for accessing source files,
+never to write build outputs, use ``PROJECT_BINARY_DIR`` and ``CMAKE_CURRENT_BINARY_DIR``
+to write build artifacts instead.
+To fully support in-tree builds, build artifacts must never have the same name as
+source files to avoid accidentally overwriting them, *e.g.* when preprocessing or
+configuring a file.
+
+The ``CMAKE_INSTALL_PREFIX`` should only be written to on install, never in the build
+process. To install generated files, create a build output in the build tree and
+install it with the ``install`` function.
+This project follows the GNU install conventions, this means that the variables
+``CMAKE_INSTALL_BINDIR``, ``CMAKE_INSTALL_LIBDIR``, and ``CMAKE_INSTALL_INCLUDEDIR``
+must be used instead of ``bin``, ``lib``, and ``include``, respectively.
+Library targets should be exported on install to allow correct inclusion of the
+project in other CMake projects.
+Prefer dashes as in ``project-config`` or ``project-targets`` over camel-case as in
+``projectConfig`` or ``projectTarget`` for file names as the former allows easier
+construction from the ``PROJECT_NAME`` variable by concatenation.
+
+The project is usable as CMake subproject. Explicit references to
+``CMAKE_SOURCE_DIR`` and ``CMAKE_BINARY_DIR`` must be avoided to not
+break subproject builds.
+An example project is available [here](https://github.com/fortran-lang/stdlib-cmake-example)
+to test the CMake subproject integration.
+
+
+### Make build files
+
+The build files for ``make`` are using the name ``Makefile.manual`` to
+not conflict with the in-tree build of CMake.
+This project uses recursive make to transverse the subdirectory structure
+from the top-level makefile, called ``Makefile.manual``, and the build
+happens in-tree, *i.e.* build artifacts are present along with the source code.
+
+New source files are added in ``src/Makefile.manual`` and include manual
+dependency definitions through the object files to allow parallel
+compilation.
+Tests are generated by the make include file ``src/tests/Makefile.manual.test.mk``
+and defined in the subdirectories of the ``src/tests`` as entries in ``PROGS_SRC``.
+New subdirectories have to be explicitly added to ``src/tests/Makefile.manual``
+or are ignored.

doc/specs/index.md

@@ -22,6 +22,7 @@ This is and index/directory of the specifications (specs) for each new module/fe
  - [stats](./stdlib_stats.html) - Descriptive Statistics
  - [stats_distribution_PRNG](./stdlib_stats_distribution_PRNG.html) - Probability Distributions random number generator
  - [string\_type](./stdlib_string_type.html) - Basic string support
+ - [strings](./stdlib_strings.html) - String handling and manipulation routines
 
 ## Missing specs
 

doc/specs/stdlib_ascii.md

@@ -169,3 +169,42 @@ program demo_reverse
     print'(a)', reverse("Hello, World!") ! returns "!dlroW ,olleH"
 end program demo_reverse
 ```
+
+
+### `to_string`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Create a character string representing the value of the provided variable.
+
+#### Syntax
+
+`res = [[stdlib_ascii(module):to_string(interface)]] (string)`
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`val`: shall be an intrinsic integer or logical type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type.
+
+#### Example
+
+```fortran
+program demo_string_value
+    use stdlib_ascii, only : to_string
+    implicit none
+    print'(a)', to_string(-3) ! returns "-3"
+    print'(a)', to_string(.true.) ! returns "T"
+    print'(a)', to_string(42) ! returns "42"
+end program demo_string_value
+```