ranges_doc.yaml

- DocumentID: decimal
  Title: >+
    Decimal Ranges
  CategoryID: mkarray
  Summary: >-
    Create arrays of decimal integers
  Description: |-
    This document describes how to create arrays of decimals using mkarray (`a` et
    al).

    {{ include "gen/includes/mkarray-range-description.inc.md" }}
  Usage: |-
    {{ include "gen/includes/mkarray-range-usage.inc.md" }}
  Examples: |-
    ```
    » a [1..3]
    1
    2
    3
    ```

    ```
    » a [3..1]
    3
    2
    1
    ```

    ```
    » a [01..03]
    01
    02
    03
    ```
  Flags:
  Detail: |-
    ### Floating Point Numbers

    If you do need a range of fixed floating point numbers generated then you can
    do so by merging two decimal integer ranges together. For example

    ```
    » a [0..5].[0..9]
    0.0
    0.1
    0.2
    0.3
    0.4
    0.5
    0.6
    0.7
    0.8
    0.9
    1.0
    1.1
    1.2
    1.3
    ...
    4.8
    4.9
    5.0
    5.1
    5.2
    5.3
    5.4
    5.5
    5.6
    5.7
    5.8
    5.9
    ```

    ### Everything Is A String

    Please note that all arrays are created as strings. Even when using typed
    arrays such as JSON (`ja`).

    ```
    » ja [0..5]
    [
        "0",
        "1",
        "2",
        "3",
        "4",
        "5"
    ] 
    ```
  Synonyms:
  Related:
    - non-decimal
    - character
    - a
    - ja
    - ta
    - range
    - count
    - index
    - element

- DocumentID: non-decimal
  Title: >+
    Non-Decimal Ranges
  CategoryID: mkarray
  Summary: >-
    Create arrays of integers from non-decimal number bases
  Description: |-
    When making arrays you can specify ranges of an alternative number base by
    using an `x` or `.` in the end range:

    ```
    a [00..ffx16]
    a [00..ff.16]
    ```

    All number bases from 2 (binary) to 36 (0-9 plus a-z) are supported.
    Please note that the start and end range are written in the target base
    while the base identifier is written in decimal: `[hex..hex.dec]`

    Also note that the additional zeros denotes padding (ie the results will
    start at `00`, `01`, etc rather than `0`, `1`...)

    {{ include "gen/includes/mkarray-range-description.inc.md" }}
  Usage: |-
    {{ include "gen/includes/mkarray-range-usage.inc.md" }}
  Examples: |-
    ```
    » a [08..10x16]
    08
    09
    0a
    0b
    0c
    0d
    0e
    0f
    10
    ```

    ```
    » a [10..08x16]
    10
    f
    e
    d
    c
    b
    a
    9
    8
    ```
  Flags:
  Detail: |-
    ### Floating Point Numbers

    If you do need a range of fixed floating point numbers generated then you can
    do so by merging two decimal integer ranges together. For example

    ```
    » a [05..10x8].[0..7]
    05.0
    05.1
    05.2
    05.3
    05.4
    05.5
    05.6
    05.7
    06.0
    06.1
    06.2
    ...
    07.5
    07.6
    07.7
    10.0
    10.1
    10.2
    10.3
    10.4
    10.5
    10.6
    10.7
    ```

    ### Everything Is A String

    Please note that all arrays are created as strings. Even when using typed
    arrays such as JSON (`ja`).

    ```
    » ja [0..5]
    [
        "0",
        "1",
        "2",
        "3",
        "4",
        "5"
    ] 
    ```
  Synonyms:
  Related:
    - decimal
    - character
    - a
    - ja
    - ta
    - range
    - count
    - index
    - element

- DocumentID: character
  Title: >+
    Character arrays
  CategoryID: mkarray
  Summary: >-
    Making character arrays (a to z)
  Description: |-
    You can create arrays from a range of letters (a to z):

    ```
    » a [a..z]
    » a [z..a]
    » a [A..Z]
    » a [Z..A]
    ```

    ...or any characters within that range.

    {{ include "gen/includes/mkarray-range-description.inc.md" }}
  Usage: |-
    {{ include "gen/includes/mkarray-range-usage.inc.md" }}
  Examples: |-
    ```
    » a [a..c]
    a
    b
    c
    ```

    ```
    » a [c..a]
    c
    b
    a
    ```
  Flags:
  Detail:
  Synonyms:
  Related:
    - decimal
    - non-decimal
    - a
    - ja
    - ta
    - range
    - count
    - index
    - element

- DocumentID: special
  Title: >+
    Special Ranges
  CategoryID: mkarray
  Summary: >-
    Create arrays from ranges of dictionary terms (eg weekdays, months, seasons, etc)
  Description: |-
    Unlike bash, Murex also supports some special ranges:

    ```  
    » a [mon..sun]
    » a [monday..sunday]
    » a [jan..dec]
    » a [january..december]
    » a [spring..winter]
    ```

    {{ include "gen/includes/mkarray-range-description.inc.md" }}
  Usage: |-
    {{ include "gen/includes/mkarray-range-usage.inc.md" }}
  Examples: |-
    ```
    » a [summer..winter]
    summer
    autumn
    winter
    ```
  Flags:
  Detail: |-
    ### Case Sensitivity

    Special ranges are case aware. If the ranges are uppercase then the return will
    be uppercase. If the ranges are title case (capital first letter) then the
    return will be in title case.

    #### lower case

    ```
    » a [monday..wednesday]
    monday
    tuesday
    wednesday
    ```

    #### Title Case

    ```
    » a [Monday..Wednesday]
    Monday
    Tuesday
    Wednesday
    ```

    #### UPPER CASE

    ```
    » a [MONDAY..WEDNESDAY]
    MONDAY
    TUESDAY
    WEDNESDAY
    ```

    ### Looping vs Negative Ranges

    Where the special ranges differ from a regular range is they cannot
    cannot down. eg `a: [3..1]` would output

    ```
    » a [3..1]
    3
    2
    1
    ```

    however a negative range in special ranges will cycle through to the end
    of the range and then loop back from the start:

    ```
    » a [Thursday..Wednesday]
    Thursday
    Friday
    Saturday
    Sunday
    Monday
    Tuesday
    Wednesday
    ```

    This decision was made because generally with ranges of this type, you
    would more often prefer to cycle through values rather than iterate
    backwards through the list.

    If you did want to reverse then pipe the output into another tool:

    ```
    » a [Monday..Friday] -> mtac
    Friday
    Thursday
    Wednesday
    Tuesday
    Monday
    ```

    There are other UNIX tools which aren't data type aware but would work in
    this specific scenario:

    * `tac` (Linux),

    * `tail -r` (BSD / OS X)

    * `perl -e "print reverse <>"` (Multi-platform but requires Perl installed)

    ### Supported Dictionary Terms

    Below is the source for the supported dictionary terms:

    ```go
    {{ include "builtins/core/mkarray/consts.go" }}
    ```
  Synonyms:
  Related:
    - date
    - a
    - ja
    - ta
    - datetime
    - mtac
    - range
    - count
    - index
    - element

- DocumentID: date
  Title: >+
    Calendar Date Ranges
  CategoryID: mkarray
  Summary: >-
    Create arrays of dates
  Description: |-
    Unlike bash, Murex also supports date ranges:

    ```  
    » a [25-dec-2020..05-jan-2021]
    » a [..25-dec-2020]
    » a [25-dec-2020..]
    ```

    {{ include "gen/includes/mkarray-range-description.inc.md" }}
  Usage: |-
    {{ include "gen/includes/mkarray-range-usage.inc.md" }}
  Examples: |-
    ```
    » a [25-Dec-2020..01-Jan-2021]
    25-Dec-2020
    26-Dec-2020
    27-Dec-2020
    28-Dec-2020
    29-Dec-2020
    30-Dec-2020
    31-Dec-2020
    01-Jan-2021
    ```

    ```
    » a [31-Dec..25-Dec]
    31-Dec
    30-Dec
    29-Dec
    28-Dec
    27-Dec
    26-Dec
    25-Dec
    ```
  Flags:
  Detail: |-
    ### Current Date

    If the start value is missing (eg `[..01-Jan-2020]`) then mkarray (`a` et al)
    will start the range from the current date and count up or down to the end.

    If the end value is missing (eg `[01-Jan-2020..]`) then mkarray will start at
    the start value, as usual, and count up or down to the current date.

    For example, if today was 25th December 2020:

    ```
    » a [23-December-2020..]
    23-December-2020
    24-December-2020
    25-December-2020
    ```

    ```
    » a [..23-December-2020]
    25-December-2020
    24-December-2020
    23-December-2020
    ```

    This can lead so some fun like countdowns:

    ```
    » out "${a: [..01-January-2021] -> len -> =-1} days until the new year!"
    7 days until the new year!
    ```

    ### Case Sensitivity

    Date ranges are case aware. If the ranges are uppercase then the return will be
    uppercase. If the ranges are title case (capital first letter) then the return
    will be in title case.

    #### lower case

    ```
    » a [01-jan..03-jan]
    01-jan
    02-jan
    03-jan
    ```

    #### Title Case

    ```
    » a [01-Jan..03-Jan]
    01-Jan
    02-Jan
    03-Jan
    ```

    #### UPPER CASE

    ```
    » a [01-JAN..03-JAN]
    01-JAN
    02-JAN
    03-JAN
    ```

    ### Supported Date Formatting

    Below is the source for the supported formatting options for date ranges:

    ```go
    {{ include "builtins/core/mkarray/date.go" }}
    ```

    If you do need any other formatting options not supported there, you can use
    `datetime` to convert the output of `a`. eg:

    ```
    » a [01-Jan-2020..03-Jan-2020] -> foreach { -> datetime --in "{go}02-Jan-2006" --out "{py}%A, %d %B"; echo }
    Wednesday, 01 January
    Thursday, 02 January
    Friday, 03 January
    ```
  Synonyms:
  Related:
    - special
    - a
    - ja
    - ta
    - datetime
    - mtac
    - range
    - count
    - index
    - element