Rename function seq to arange.

Update related docs.

Author: zoziha

doc/specs/stdlib_math.md

@@ -275,7 +275,7 @@ program demo_logspace_rstart_cbase
 
 end program demo_logspace_rstart_cbase
 ```
-## `seq` - Creates an vector of `integer/real` type with evenly spaced values within a given interval.
+## `arange` - Create a vector of the `integer/real` type with evenly spaced values within a given interval.
 
 ### Status
 
@@ -287,49 +287,56 @@ Pure function.
 
 ### Description
 
-Creates an vector of `integer/real` type with evenly spaced values within a given interval.
+Create a vector of the `integer/real` type with evenly spaced values within a given interval.
 
 ### Syntax
 
-`result = [[stdlib_math(module):seq(interface)]](start [, end, by])`
+`result = [[stdlib_math(module):arange(interface)]](start [, end, by])`
 
 ### Arguments
 
 `start`: Shall be an `integer/real` scalar.
-This is an `intent(in)` argument.
+This is an `intent(in)` argument.  
+The default `start` value is `1`.
 
 `end`: Shall be an `integer/real` scalar.
-This is an `intent(in)` and `optional` argument.
-
-`by`: Shall be an `integer/real` scalar and large than `0`.
 This is an `intent(in)` and `optional` argument.  
+The default `end` value is the inputted `start` value.
+
+`by`: Shall be an `integer/real` scalar and large than `0`. 
+This is an `intent(in)` and `optional` argument.   
+The default `by` value is `1`.
 
-Warning:  
-If `by = 0`, the `by` argument will be corrected to `1/1.0` by the internal process of the `seq` function.   
-If `by < 0`, the `by` argument will be corrected to `abs(by)` by the internal process of the `seq` function. 
+#### Warning
+If `by = 0`, the `by` argument will be corrected to `1/1.0` by the internal process of the `arange` function.   
+If `by < 0`, the `by` argument will be corrected to `abs(by)` by the internal process of the `arange` function. 
 
 ### Return value
 
-Vector of evenly spaced values.
+Return a vector of evenly spaced values.
 
-For floating point arguments, the length of the result is `floor((end - start)/by) + 1`.
+For `real` type arguments, the length of the result vector is `floor((end - start)/by) + 1`.
 
 ### Example
 
 ```fortran
-program demo_math_seq
-    use stdlib_math, only: seq
+program demo_math_arange
+    use stdlib_math, only: arange
+
+    print *, arange(3)                 !! [1,2,3]
+    print *, arange(-1)                !! [1,0,-1]
+    print *, arange(0,2)               !! [0,1,2]
+    print *, arange(1,-1)              !! [1,0,-1]
+    print *, arange(0, 2, 2)           !! [0,2]
+
+    print *, arange(3.0)               !! [1.0,2.0,3.0]
+    print *, arange(0.0,5.0)           !! [0.0,1.0,2.0,3.0,4.0,5.0]
+    print *, arange(0.0,5.0,2.0)       !! [0.0,2.0,4.0]
 
-    print *, seq(3)                 !! [1,2,3]
-    print *, seq(3.0)               !! [1.0,2.0,3.0]
-    print *, seq(-1)                !! [1,0,-1]
-    print *, seq(0,2)               !! [0,1,2]
-    print *, seq(1,-1)              !! [1,0,-1]
-    print *, seq(0, 2, 2)           !! [0,2]
-    print *, (1.0,1.0)*seq(3)       !! [(1.0,1.0),(2.0,2.0),[3.0,3.0]]
+    print *, (1.0,1.0)*arange(3)       !! [(1.0,1.0),(2.0,2.0),[3.0,3.0]]
 
-    print *, seq(0.0,2.0,-2.0)      !! [0.0,2.0]. Not recommended: `by` argument is negative!
-    print *, seq(0.0,2.0,0.0)       !! [0.0,1.0]. Not recommended: `by` argument is zero!
+    print *, arange(0.0,2.0,-2.0)      !! [0.0,2.0].     Not recommended: `by` argument is negative!
+    print *, arange(0.0,2.0,0.0)       !! [0.0,1.0,2.0]. Not recommended: `by` argument is zero!
 
-end program demo_math_seq
+end program demo_math_arange
 ```

src/CMakeLists.txt

@@ -32,7 +32,7 @@ set(fppFiles
     stdlib_math.fypp
     stdlib_math_linspace.fypp
     stdlib_math_logspace.fypp
-    stdlib_math_seq.fypp
+    stdlib_math_arange.fypp
     stdlib_string_type.fypp
 )
 

src/Makefile.manual

@@ -7,7 +7,7 @@ SRCFYPP =\
         stdlib_linalg.fypp \
         stdlib_linalg_diag.fypp \
         stdlib_linalg_outer_product.fypp \
-        stdlib_math_seq.fypp \
+        stdlib_math_arange.fypp \
         stdlib_optval.fypp \
         stdlib_quadrature.fypp \
         stdlib_quadrature_trapz.fypp \
@@ -155,7 +155,7 @@ stdlib_math_linspace.o: \
 	stdlib_math.o
 stdlib_math_logspace.o: \
 	stdlib_math_linspace.o
-stdlib_math_seq.o: \
+stdlib_math_arange.o: \
     stdlib_math.o \
     stdlib_kinds.o
 stdlib_linalg_outer_product.o: stdlib_linalg.o

src/stdlib_math.fypp

@@ -10,7 +10,7 @@ module stdlib_math
     public :: clip, linspace, logspace
     public :: EULERS_NUMBER_SP, EULERS_NUMBER_DP, EULERS_NUMBER_QP
     public :: DEFAULT_LINSPACE_LENGTH, DEFAULT_LOGSPACE_BASE, DEFAULT_LOGSPACE_LENGTH
-    public :: seq
+    public :: arange
 
     integer, parameter :: DEFAULT_LINSPACE_LENGTH = 100
     integer, parameter :: DEFAULT_LOGSPACE_LENGTH = 50
@@ -264,18 +264,21 @@ module stdlib_math
 
     !> Version: experimental
     !>
-    !> `seq` creates an vector of `integer/real` type 
+    !> `arange` creates a vector of the `integer/real` type 
     !>  with evenly spaced values within a given interval.
-    interface seq
+    !> ([Specification](../page/specs/stdlib_math.html#
+    !>arange-create-a-vector-of-the-integerreal-type-
+    !>with-evenly-spaced-values-within-a-given-interval))
+    interface arange
         #:set RI_KINDS_TYPES = REAL_KINDS_TYPES + INT_KINDS_TYPES
         #:for k1, t1 in RI_KINDS_TYPES
-        pure module function seq_${t1[0]}$_${k1}$(start, end, by) result(result)
+        pure module function arange_${t1[0]}$_${k1}$(start, end, by) result(result)
             ${t1}$, intent(in) :: start
             ${t1}$, intent(in), optional :: end, by
             ${t1}$, allocatable :: result(:)
-        end function seq_${t1[0]}$_${k1}$
+        end function arange_${t1[0]}$_${k1}$
         #:endfor
-    end interface seq
+    end interface arange
 
 contains
 

src/stdlib_math_seq.fypp renamed to src/stdlib_math_arange.fypp

@@ -1,14 +1,14 @@
 #:include "common.fypp"
-submodule(stdlib_math) stdlib_math_seq
+submodule(stdlib_math) stdlib_math_arange
 
     implicit none
 
 contains
 
     #:for k1, t1 in REAL_KINDS_TYPES
-    !> `seq` creates an vector of `${t1}$` type 
+    !> `arange` creates a vector of the `${t1}$` type 
     !>  with evenly spaced values within a given interval.
-    pure module function seq_${t1[0]}$_${k1}$(start, end, by) result(result)
+    pure module function arange_${t1[0]}$_${k1}$(start, end, by) result(result)
 
         ${t1}$, intent(in) :: start
         ${t1}$, intent(in), optional :: end, by
@@ -23,18 +23,16 @@ contains
                  1.0_${k1}$, present(by)), end_ - start_)
 
         allocate(result(floor((end_ - start_)/by_) + 1))
-            #!TODO: ??
-            #! floor or ceiling, floor is better.
 
         result = [(start_ + (i - 1)*by_, i=1, size(result), 1)]
 
-    end function seq_${t1[0]}$_${k1}$
+    end function arange_${t1[0]}$_${k1}$
     #:endfor
 
     #:for k1, t1 in INT_KINDS_TYPES
-    !> `seq` creates an vector of `${t1}$` type 
+    !> `arange` creates a vector of the `${t1}$` type 
     !>  with evenly spaced values within a given interval.
-    pure module function seq_${t1[0]}$_${k1}$(start, end, by) result(result)
+    pure module function arange_${t1[0]}$_${k1}$(start, end, by) result(result)
 
         ${t1}$, intent(in) :: start
         ${t1}$, intent(in), optional :: end, by
@@ -52,7 +50,7 @@ contains
 
         result = [(i, i=start_, end_, by_)]
 
-    end function seq_${t1[0]}$_${k1}$
+    end function arange_${t1[0]}$_${k1}$
     #:endfor
 
-end submodule stdlib_math_seq
+end submodule stdlib_math_arange

src/tests/math/CMakeLists.txt

@@ -1,4 +1,4 @@
 ADDTEST(stdlib_math)
 ADDTEST(linspace)
 ADDTEST(logspace)
-ADDTEST(math_seq)
+ADDTEST(math_arange)

src/tests/math/Makefile.manual

@@ -1,5 +1,5 @@
 PROGS_SRC = test_stdlib_math.f90 test_linspace.f90 test_logspace.f90 \
-    test_math_seq.f90
+    test_math_arange.f90
 
 
 include ../Makefile.manual.test.mk

src/tests/math/test_math_arange.f90

@@ -0,0 +1,53 @@
+!> SPDX-Identifier: MIT
+module test_math_arange
+
+    use stdlib_error, only: check
+    use stdlib_math, only: arange
+    implicit none
+
+    logical, private :: warn = .false.
+
+contains
+
+    subroutine test_math_arange_real
+        !> Normal
+        call check(all(arange(3.0) == [1.0, 2.0, 3.0]),        msg="all(arange(3.0) == [1.0,2.0,3.0]) failed.",           warn=warn)
+        call check(all(arange(-1.0) == [1.0, 0.0, -1.0]),      msg="all(arange(-1.0) == [1.0,0.0,-1.0]) failed.",         warn=warn)
+        call check(all(arange(0.0, 2.0) == [0.0, 1.0, 2.0]),   msg="all(arange(0.0,2.0) == [0.0,1.0,2.0]) failed.",       warn=warn)
+        call check(all(arange(1.0, -1.0) == [1.0, 0.0, -1.0]), msg="all(arange(1.0,-1.0) == [1.0,0.0,-1.0]) failed.",     warn=warn)
+        call check(all(arange(1.0, 1.0) == [1.0]),             msg="all(arange(1.0,1.0) == [1.0]) failed.",               warn=warn)
+        call check(all(arange(0.0, 2.0, 2.0) == [0.0, 2.0]),   msg="all(arange(0.0,2.0,2.0) == [0.0,2.0]) failed.",       warn=warn)
+        call check(all(arange(1.0, -1.0, 2.0) == [1.0, -1.0]), msg="all(arange(1.0,-1.0,2.0) == [1.0,-1.0]) failed.",     warn=warn)
+        !> Not recommended
+        call check(all(arange(0.0, 2.0, -2.0) == [0.0, 2.0]),  msg="all(arange(0.0,2.0,-2.0) == [0.0,2.0]) failed.",      warn=warn)
+        call check(all(arange(1.0, -1.0, -2.0) == [1.0, -1.0]),msg="all(arange(1.0,-1.0,-2.0) == [1.0,-1.0]) failed.",    warn=warn)
+        call check(all(arange(0.0, 2.0, 0.0) == [0.0,1.0,2.0]),msg="all(arange(0.0, 2.0, 0.0) == [0.0,1.0,2.0]) failed.", warn=warn)
+    end subroutine test_math_arange_real
+
+    subroutine test_math_arange_integer
+        !> Normal
+        call check(all(arange(3) == [1, 2, 3]),        msg="all(arange(3) == [1,2,3]) failed.",       warn=warn)
+        call check(all(arange(-1) == [1, 0, -1]),      msg="all(arange(-1) == [1,0,-1]) failed.",     warn=warn)
+        call check(all(arange(0, 2) == [0, 1, 2]),     msg="all(arange(0,2) == [0,1,2]) failed.",     warn=warn)
+        call check(all(arange(1, -1) == [1, 0, -1]),   msg="all(arange(1,-1) == [1,0,-1]) failed.",   warn=warn)
+        call check(all(arange(1, 1) == [1]),           msg="all(arange(1,1) == [1]) failed.",         warn=warn)
+        call check(all(arange(0, 2, 2) == [0, 2]),     msg="all(arange(0,2,2) == [0,2]) failed.",     warn=warn)
+        call check(all(arange(1, -1, 2) == [1, -1]),   msg="all(arange(1,-1,2) == [1,-1]) failed.",   warn=warn)
+        !> Not recommended
+        call check(all(arange(0, 2, -2) == [0, 2]),    msg="all(arange(0,2,-2) == [0,2]) failed.",    warn=warn)
+        call check(all(arange(1, -1, -2) == [1, -1]),  msg="all(arange(1,-1,-2) == [1,-1]) failed.",  warn=warn)
+        call check(all(arange(0, 2, 0) == [0,1,2]),    msg="all(arange(0, 2, 0) == [0,1,2]) failed.", warn=warn)
+    end subroutine test_math_arange_integer
+
+end module test_math_arange
+
+program tester
+
+    use test_math_arange
+
+    call test_math_arange_real
+    call test_math_arange_integer
+    
+    print *, "All tests in `test_math_arange` passed."
+
+end program tester