asciimat Converts an array of text into ASCII/UTF8 codes, and reciprocally

## Syntax

                unicodes = asciimat(text)
                text = asciimat(unicodes)

## Arguments

text
  single text, or vector, matrix or hypermatrix of texts. Text elements may have various lengths, and may include UTF-8 extended characters.

  `asciimat(…)` always concatenates the columns of `text` along rows, as input or output argument.

unicodes
  single integer ASCII code, or vector, matrix or hypermatrix of ASCII or unicode 1-byte numbers.

## Description

`asciimat(…)` converts an array of `text` into an array of related 1-byte ascii or UTF-8 `unicodes`, and reciprocally.

`asciimat(…)` is an Octave/Matlab compatibility function, aiming to provide in the m2sci Matlab-to-Scilab code converter an equivalence for the addition and subtraction between some character strings or with numbers. Thus,

    >> ['ab' 'c' ; 'd' 'ef'] + 4
    ans =
       101   102   103
       104   105   106

    >> ['ab';'cd'] + ['ef';'gh']
    ans =
       198   200
       202   204

    >> ['ab';'cd'] - ['ef';'gh']
    ans =
      -4  -4
      -4  -4

can be performed by the Matlab-to-Scilab converter with

    asciimat(['ab' 'c' ; 'd' 'ef']) + 4
    asciimat(['ab';'cd']) + asciimat(['ef';'gh'])
    asciimat(['ab';'cd']) - asciimat(['ef';'gh'])

`asciimat(…)` should not be used out of the M2Sci converter.

### unicodes = asciimat(text)

For a scalar or row `text`, `asciimat(text)` is equal to `ascii(text)`. All strings are glued together before building the row vector of codes of their characters.

For any `text` array of any sizes, made only of empty strings "", `asciimat(text)` returns []. Indeed, `asciimat(…)` considers "" as a void vector of (indexed) characters as in Octave/Matlab, not as a Scilab text object.

For a 2D matrix `text`, `asciimat(text)` builds a unique column of text by gluing `text` columns along rows.

Then, for each row/string of the column, the row vector of ASCII or UTF-8 codes of all its characters is computed.

Finally, all resulting row vectors of codes are vertically concatenated to build the `unicodes` matrix. Too short vectors of codes are beforehand padded with the ascii(" ")==32 code.

For an hypermatrix of `text`, the processing is basically the same, as if all `text` rows over all dimensions > 2 were beforehand stacked into a 2D matrix. The resulting 2D `unicodes` matrix is finally reshaped into an hypermatrix..

The sizes of `unicodes` and `text` arrays differ only by their number of columns.

### text = asciimat(unicodes)

For a scalar or a row `unicodes`, `asciimat(unicodes)` is equal to `ascii(unicodes)`. It returns the character string whose characters have the given codes.

Zeros stand for the code of the empty character "", as the true ascii(0) character is currently not supported in Scilab 6.

For a column, matrix or hypermatrix `unicodes`, each `unicodes` row is processed separately and builds a single Scilab character string.

All trailing ascii(32) spaces of built character strings are trimmed.

Finally, `text` has the size of `unicodes`, except that `size(text,2)==1`.

## Examples

    asciimat([])
    asciimat("")
    asciimat(0)

    r = asciimat("A")
    asciimat(r)

    // With an input ROW:
    r = asciimat(["A" "BC"])
    asciimat(r)

    r = asciimat(["A" "" "BC"])      // "" in rows are ignored
    asciimat(r)

    --> asciimat([])
     ans  =
        []
    --> asciimat("")
     ans  =
        []
    --> asciimat(0)
     ans  =
      ""

    --> r = asciimat("A")
     r  =
       65.
    --> asciimat(r)
     ans  =
      "A"

    --> // With an input ROW:
    --> r = asciimat(["A" "BC"])
     r  =
       65.   66.   67.

    --> asciimat(r)
     ans  =
      "ABC"

    --> r = asciimat(["A" "" "BC"])      // "" in rows are ignored
     r  =
       65.   66.   67.

    --> asciimat(r)
     ans  =
      "ABC"

With an input column:

    asciimat(["" ; ""])
    asciimat((97:110)')'
    strsplit("a":"n")'

    r = asciimat(["ABC" ; "" ; "D"]) // Padding short rows with 32
    asciimat(r)
    r = asciimat(["AB" ; "αβ"])      // 1-byte UTF-8 coding is used
    asciimat(r)                      // Trailing ascii(32) spaces are trimmed

    --> asciimat(["" ; ""])
     ans  =
        []

    --> asciimat((97:110)')'
     ans  =
      "a"  "b"  "c"  "d"  "e"  "f"  "g"  "h"  "i"  "j"  "k"  "l"  "m"  "n"

    --> strsplit("a":"n")'
     ans  =
      "a"  "b"  "c"  "d"  "e"  "f"  "g"  "h"  "i"  "j"  "k"  "l"  "m"  "n"

    --> r = asciimat(["ABC" ; "" ; "D"]) // Padding short rows with 32
     r  =
       65.   66.   67.
       32.   32.   32.
       68.   32.   32.

    --> asciimat(r)
     ans  =
      "ABC"
      ""
      "D"

    --> r = asciimat(["AB" ; "αβ"])      // 1-byte UTF-8 coding is used
     r  =
       65.    66.    32.    32.
       206.   177.   206.   178.

    --> asciimat(r)                      // Trailing ascii(32) spaces are trimmed
     ans  =
      "AB"
      "αβ"

With a 2D input matrix:

    r = asciimat([" AB", " ", "CD " ; "α", "βγ", " "])
    asciimat(r)

    --> r = asciimat([" AB", " ", "CD " ; "α", "βγ", " "])
     r  =
       32.    65.    66.    32.    67.    68.    32.
       206.   177.   206.   178.   206.   179.   32.

    --> asciimat(r)
     ans  =
      " AB CD"
      "αβγ"

With a 3D input hypermatrix:

    x = ["a €" "bδ " ; "" "" ;  "" "" ];
    x2 = [" α" "βδc" ; "" "" ; "ε4" ""];
    h = cat(3, x, x2)
    r = asciimat(h)
    asciimat(r)

    --> h = cat(3, x, x2)
     h  =
    (:,:,1)
      "a €"  "bδ "
      ""     ""
      ""     ""
    (:,:,2)
      " α"  "βδc"
      ""    ""
      "ε4"  ""

    --> r = asciimat(h)
     r  =
    (:,:,1)
       97.   32.   226.   130.   172.   98.   206.   180.   32.
       32.   32.   32.    32.    32.    32.   32.    32.    32.
       32.   32.   32.    32.    32.    32.   32.    32.    32.
    (:,:,2)
       32.    206.   177.   206.   178.   206.   180.   99.   32.
       32.    32.    32.    32.    32.    32.    32.    32.   32.
       206.   181.   52.    32.    32.    32.    32.    32.   32.

    --> asciimat(r)
     ans  =
    (:,:,1)
      "a €bδ"
      ""
      ""
    (:,:,2)
      " αβδc"
      ""
      "ε4"

## See also

- ascii
- char

## History

6.1.1

- Text components with various lengths or/and including UTF-8 characters are accepted. Padding with the ascii(" ")==32 code implemented.
- asciimat(unicodes) trims all trailing spaces.
- For any unicodes hypermatrix, r = asciimat(unicodes) no longer squeezes size(r,2).