diff --git a/doc/specs/stdlib_error.md b/doc/specs/stdlib_error.md index 5629a32e9..b719f3570 100644 --- a/doc/specs/stdlib_error.md +++ b/doc/specs/stdlib_error.md @@ -2,26 +2,33 @@ title: error --- -# Catching and handling errors +# The `stdlib_error` module [TOC] -## `check` - Checks the value of a logical condition +## Introduction -### Status +Catching and handling errors. + +## Procedures and methods provided + + +### `check` - Checks the value of a logical condition + +#### Status Experimental -### Description +#### Description Checks the value of a logical condition. -### Syntax +#### Syntax `call [[check(subroutine)]](condition, msg, code, warn)` -### Arguments +#### Arguments `condition`: Shall be a scalar of type `logical`. @@ -31,7 +38,7 @@ Checks the value of a logical condition. `warn` (optional): Shall be a scalar of type `logical`. The default `warn` is `.true.`. -### Return value +#### Return value If `condition` is `.false`., and: @@ -43,7 +50,7 @@ If `condition` is `.false`., and: * `warn` is provided and `warn` is `.true.`, this subroutine doesn't stop the program and prints the message. -### Examples +#### Examples ```fortran program demo_check1 @@ -82,31 +89,31 @@ program demo_check3 end program demo_check3 ``` -## `error_stop` - aborts the program +### `error_stop` - aborts the program -### Status +#### Status Experimental -### Description +#### Description Aborts the program with a message and a nonzero exit code. -### Syntax +#### Syntax `call [[stdlib_error(module):error_stop(interface)]](msg, code)` -### Arguments +#### Arguments `msg`: Shall be a character expression containing the message to be printed to `stderr`. `code` (optional): Shall be a scalar of type `integer` to be returned as exit code. -### Output +#### Output Aborts the program with printing the message `msg` to `stderr` and a nonzero exit code. The nonzero exit code is equal to `code` if provided, and 1 otherwise. -### Examples +#### Examples Without error code: diff --git a/doc/specs/stdlib_string_type.md b/doc/specs/stdlib_string_type.md index 4c6d84194..17cdce920 100644 --- a/doc/specs/stdlib_string_type.md +++ b/doc/specs/stdlib_string_type.md @@ -38,6 +38,10 @@ used in a pure way. ### Constructor for empty string +#### Status + +Experimental + #### Description The module defines a constructor to create an empty string type. @@ -48,10 +52,6 @@ Creates a string instance representing an empty string. `res = [[stdlib_string_type(module):string_type(interface)]] ()` -#### Status - -Experimental - #### Class Elemental function. @@ -80,6 +80,10 @@ end program demo ### Constructor from character scalar +#### Status + +Experimental + #### Description The module defines a constructor to create a string type from a character scalar. @@ -92,10 +96,6 @@ character variable is passed. `res = [[stdlib_string_type(module):string_type(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -126,6 +126,10 @@ end program demo ### Constructor from integer scalar +#### Status + +Experimental + #### Description The module defines a constructor to create a string type from an integer scalar. @@ -134,10 +138,6 @@ The module defines a constructor to create a string type from an integer scalar. `res = [[stdlib_string_type(module):string_type(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -168,6 +168,10 @@ end program demo ### Constructor from logical scalar +#### Status + +Experimental + #### Description The module defines a constructor to create a string type from a logical scalar. @@ -176,10 +180,6 @@ The module defines a constructor to create a string type from a logical scalar. `res = [[stdlib_string_type(module):string_type(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -210,6 +210,10 @@ end program demo ### Assignment of character scalar +#### Status + +Experimental + #### Description The module defines an assignment operations, `=`, to create a string type @@ -221,10 +225,6 @@ Creates a string instance representing the right-hand-side character scalar valu `lhs = rhs` -#### Status - -Experimental - #### Class Elemental subroutine, `assignment(=)`. @@ -246,6 +246,10 @@ end program demo ### Len function +#### Status + +Experimental + #### Description Returns the length of the string. @@ -254,10 +258,6 @@ Returns the length of the string. `res = [[stdlib_string_type(module):len(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -293,6 +293,10 @@ end program demo ### Len\_trim function +#### Status + +Experimental + #### Description Returns the length of the character sequence without trailing spaces @@ -302,10 +306,6 @@ represented by the string. `res = [[stdlib_string_type(module):len_trim(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -341,6 +341,10 @@ end program demo ### Trim function +#### Status + +Experimental + #### Description Returns the character sequence hold by the string without trailing spaces @@ -350,10 +354,6 @@ represented by a `string_type`. `res = [[stdlib_string_type(module):trim(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -384,6 +384,10 @@ end program demo ### Adjustl function +#### Status + +Experimental + #### Description Left-adjust the character sequence represented by the string. @@ -393,10 +397,6 @@ The length of the character sequence remains unchanged. `res = [[stdlib_string_type(module):adjustl(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -427,6 +427,10 @@ end program demo ### Adjustr function +#### Status + +Experimental + #### Description Right-adjust the character sequence represented by the string. @@ -436,10 +440,6 @@ The length of the character sequence remains unchanged. `res = [[stdlib_string_type(module):adjustr(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -470,6 +470,10 @@ end program demo ### Repeat function +#### Status + +Experimental + #### Description Repeats the character sequence hold by the string by the number of @@ -479,10 +483,6 @@ specified copies. `res = [[stdlib_string_type(module):repeat(interface)]] (string, ncopies)` -#### Status - -Experimental - #### Class Elemental function. @@ -514,6 +514,10 @@ end program demo ### Char function +#### Status + +Experimental + #### Description Return the character sequence represented by the string. @@ -522,10 +526,6 @@ Return the character sequence represented by the string. `res = [[stdlib_string_type(module):char(interface)]] (string)` -#### Status - -Experimental - #### Class Pure function. @@ -557,6 +557,10 @@ end program demo ### Char function (position variant) +#### Status + +Experimental + #### Description Return the character at a certain position in the string. @@ -565,10 +569,6 @@ Return the character at a certain position in the string. `res = [[stdlib_string_type(module):char(interface)]] (string, pos)` -#### Status - -Experimental - #### Class Elemental function. @@ -604,6 +604,10 @@ end program demo ### Char function (range variant) +#### Status + +Experimental + #### Description Return a substring from the character sequence of the string. @@ -612,10 +616,6 @@ Return a substring from the character sequence of the string. `res = [[stdlib_string_type(module):char(interface)]] (string, start, last)` -#### Status - -Experimental - #### Class Pure function. @@ -649,6 +649,10 @@ end program demo ### Ichar function +#### Status + +Experimental + #### Description Character-to-integer conversion function. @@ -660,10 +664,6 @@ character sequence in the system's native character set. `res = [[stdlib_string_type(module):ichar(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -694,6 +694,10 @@ end program demo ### Iachar function +#### Status + +Experimental + #### Description Code in ASCII collating sequence. @@ -705,10 +709,6 @@ the character sequences represent by the string. `res = [[stdlib_string_type(module):iachar(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -739,6 +739,10 @@ end program demo ### Index function +#### Status + +Experimental + #### Description Position of a *substring* within a *string*. @@ -751,10 +755,6 @@ present in *string*, zero is returned. `res = [[stdlib_string_type(module):index(interface)]] (string, substring[, back])` -#### Status - -Experimental - #### Class Elemental function. @@ -794,6 +794,10 @@ end program demo ### Scan function +#### Status + +Experimental + #### Description Scans a *string* for the presence any of the characters in a *set* of characters. @@ -806,10 +810,6 @@ the rightmost position is returned. If no character of *set* is found in `res = [[stdlib_string_type(module):scan(interface)]] (string, set[, back])` -#### Status - -Experimental - #### Class Elemental function. @@ -849,6 +849,10 @@ end program demo ### Verify function +#### Status + +Experimental + #### Description Verifies that all the characters in *string* belong to the set of characters in *set*. @@ -861,10 +865,6 @@ in *set*, the result is zero. `res = [[stdlib_string_type(module):verify(interface)]] (string, set[, back])` -#### Status - -Experimental - #### Class Elemental function. @@ -910,6 +910,10 @@ end program demo ### Lgt function (lexical greater than) +#### Status + +Experimental + #### Description Lexically compare the order of two character sequences being greater than. @@ -922,10 +926,6 @@ This defines three procedures overloading the intrinsic `lgt` procedure. `res = [[stdlib_string_type(module):lgt(interface)]] (lhs, rhs)` -#### Status - -Experimental - #### Class Elemental function. @@ -964,6 +964,10 @@ end program demo ### Llt function (lexical less than) +#### Status + +Experimental + #### Description Lexically compare the order of two character sequences being less than. @@ -976,10 +980,6 @@ This defines three procedures overloading the intrinsic `llt` procedure. `res = [[stdlib_string_type(module):llt(interface)]] (lhs, rhs)` -#### Status - -Experimental - #### Class Elemental function. @@ -1018,6 +1018,10 @@ end program demo ### Lge function (lexical greater than or equal) +#### Status + +Experimental + #### Description Lexically compare the order of two character sequences being greater than @@ -1031,10 +1035,6 @@ This defines three procedures overloading the intrinsic `lge` procedure. `res = [[stdlib_string_type(module):lge(interface)]] (lhs, rhs)` -#### Status - -Experimental - #### Class Elemental function. @@ -1073,6 +1073,10 @@ end program demo ### Lle function (lexical less than or equal) +#### Status + +Experimental + #### Description Lexically compare the order of two character sequences being less than @@ -1086,10 +1090,6 @@ This defines three procedures overloading the intrinsic `lle` procedure. `res = [[stdlib_string_type(module):lle(interface)]] (lhs, rhs)` -#### Status - -Experimental - #### Class Elemental function. @@ -1128,19 +1128,19 @@ end program demo ### To\_lower function +#### Status + +Experimental + #### Description -Returns a new string_type instance which holds the lowercase version of the +Returns a new string_type instance which holds the lowercase version of the character sequence hold by the input string. #### Syntax `lowercase_string = [[stdlib_string_type(module): to_lower(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -1174,19 +1174,19 @@ end program demo ### To\_upper function +#### Status + +Experimental + #### Description -Returns a new string_type instance which holds the uppercase version of the +Returns a new string_type instance which holds the uppercase version of the character sequence hold by the input string. #### Syntax `uppercase_string = [[stdlib_string_type(module): to_upper(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -1220,24 +1220,24 @@ end program demo ### To\_title function +#### Status + +Experimental + #### Description -Returns a new string_type instance which holds the titlecase version -of the character sequence hold by the input string. -Title case: First character of every word in the sentence is converted to -uppercase and the rest of the characters are converted to lowercase. -A word is a contiguous sequence of character(s) which consists of alphabetical -character(s) and numeral(s) only and doesn't exclude any alphabetical character +Returns a new string_type instance which holds the titlecase version +of the character sequence hold by the input string. +Title case: First character of every word in the sentence is converted to +uppercase and the rest of the characters are converted to lowercase. +A word is a contiguous sequence of character(s) which consists of alphabetical +character(s) and numeral(s) only and doesn't exclude any alphabetical character or numeral present next to either of its 2 ends. #### Syntax `titlecase_string = [[stdlib_string_type(module): to_title(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -1270,22 +1270,22 @@ end program demo_to_title ### To\_sentence function +#### Status + +Experimental + #### Description -Returns a new string_type instance which holds the sentencecase -version of the character sequence hold by the input string. -Sentencecase version: The first alphabetical character of the input character sequence -is transformed to uppercase unless it follows a numeral and the rest of the +Returns a new string_type instance which holds the sentencecase +version of the character sequence hold by the input string. +Sentencecase version: The first alphabetical character of the input character sequence +is transformed to uppercase unless it follows a numeral and the rest of the characters in the sequence are transformed to lowercase. #### Syntax `sentencecase_string = [[stdlib_string_type(module): to_sentence(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -1318,19 +1318,19 @@ end program demo_to_sentence ### Reverse function +#### Status + +Experimental + #### Description -Returns a new string_type instance which holds the reversed version of the +Returns a new string_type instance which holds the reversed version of the character sequence hold by the input string. #### Syntax `reverse_string = [[stdlib_string_type(module): reverse(interface)]] (string)` -#### Status - -Experimental - #### Class Elemental function. @@ -1350,7 +1350,7 @@ program demo use stdlib_string_type implicit none type(string_type) :: string, reverse_string - + string = "Reverse This String" ! string <-- "Reverse This String" @@ -1364,6 +1364,10 @@ end program demo ### Comparison operator greater +#### Status + +Experimental + #### Description Compare the order of two character sequences being greater. @@ -1379,10 +1383,6 @@ and `operator(.gt.)`. `res = lhs .gt. rhs` -#### Status - -Experimental - #### Class Elemental function, `operator(>)` and `operator(.gt.)`. @@ -1421,6 +1421,10 @@ end program demo ### Comparison operator less +#### Status + +Experimental + #### Description Compare the order of two character sequences being less. @@ -1436,10 +1440,6 @@ and `operator(.lt.)`. `res = lhs .lt. rhs` -#### Status - -Experimental - #### Class Elemental function, `operator(<)` and `operator(.lt.)`. @@ -1478,6 +1478,10 @@ end program demo ### Comparison operator greater or equal +#### Status + +Experimental + #### Description Compare the order of two character sequences being greater or equal. @@ -1493,10 +1497,6 @@ and `operator(.ge.)`. `res = lhs .ge. rhs` -#### Status - -Experimental - #### Class Elemental function, `operator(>=)` and `operator(.ge.)`. @@ -1535,6 +1535,10 @@ end program demo ### Comparison operator less or equal +#### Status + +Experimental + #### Description Compare the order of two character sequences being less or equal. @@ -1550,10 +1554,6 @@ and `operator(.le.)`. `res = lhs .le. rhs` -#### Status - -Experimental - #### Class Elemental function, `operator(<=)` and `operator(.le.)`. @@ -1592,6 +1592,10 @@ end program demo ### Comparison operator equal +#### Status + +Experimental + #### Description Compare two character sequences for equality. @@ -1607,10 +1611,6 @@ and `operator(.eq.)`. `res = lhs .eq. rhs` -#### Status - -Experimental - #### Class Elemental function, `operator(==)` and `operator(.eq.)`. @@ -1649,6 +1649,10 @@ end program demo ### Comparison operator not equal +#### Status + +Experimental + #### Description Compare two character sequences for inequality. @@ -1664,10 +1668,6 @@ and `operator(.ne.)`. `res = lhs .ne. rhs` -#### Status - -Experimental - #### Class Elemental function, `operator(/=)` and `operator(.ne.)`. @@ -1706,6 +1706,10 @@ end program demo ### Concatenation operator +#### Status + +Experimental + #### Description Concatenate two character sequences. @@ -1718,10 +1722,6 @@ This defines three procedures overloading the intrinsic `operator(//)`. `res = lhs // rhs` -#### Status - -Experimental - #### Class Elemental function, `operator(//)`. @@ -1753,6 +1753,10 @@ end program demo ### Unformatted write +#### Status + +Experimental + #### Description Write the character sequence hold by the string to a connected unformatted unit. @@ -1763,10 +1767,6 @@ holding the length of the following character record. `write(unit, iostat=iostat, iomsg=iomsg) string` -#### Status - -Experimental - #### Class Unformatted user defined derived type output. @@ -1803,6 +1803,10 @@ end program demo ### Formatted write +#### Status + +Experimental + #### Description Write the character sequence hold by the string to a connected formatted unit. @@ -1814,10 +1818,6 @@ output. Requesting namelist output will raise an error. `write(unit, fmt, iostat=iostat, iomsg=iomsg) string` -#### Status - -Experimental - #### Class Formatted user defined derived type output. @@ -1862,6 +1862,10 @@ end program demo ### Unformatted read +#### Status + +Experimental + #### Description Read a character sequence from a connected unformatted unit into the string. @@ -1874,10 +1878,6 @@ On failure the state the read variable is undefined and implementation dependent `read(unit, iostat=iostat, iomsg=iomsg) string` -#### Status - -Experimental - #### Class Unformatted derived type input. @@ -1915,6 +1915,10 @@ end program demo ### Formatted read +#### Status + +Experimental + #### Description Read a character sequence from a connected formatted unit into the string. @@ -1929,10 +1933,6 @@ Requesting `dt` formatted input or namelist output will raise an error. `read(unit, fmt, iostat=iostat, iomsg=iomsg) string` -#### Status - -Experimental - #### Class Formatted derived type input. @@ -1977,20 +1977,20 @@ end program demo ### move +#### Status + +Experimental + #### Description -Moves the allocation from `from` to `to`, consequently deallocating `from` in this process. -If `from` is not allocated before execution, `to` gets deallocated by the process. +Moves the allocation from `from` to `to`, consequently deallocating `from` in this process. +If `from` is not allocated before execution, `to` gets deallocated by the process. An unallocated `string_type` instance is equivalent to an empty string. #### Syntax `call [[stdlib_string_type(module):move(interface)]] (from, to)` -#### Status - -Experimental - #### Class Pure Subroutine.