 APL Font Required If the next two rowshave different symbols Њ„ј…Ѕ’‘њЇ–•— then click here

## ENCODE and DECODE

Encode (also called representation) and decode (also called base-value) are mixed functions. Their principal use is to convert numbers from one number base to another. Mixed number bases are permitted. Note that encode () is on the N key, while base-value (ѓ) is on the B key.

In APL, the representation of a number in a particular number base consists of a vector whose elements are the digit values in that base. For example, the decimal number 31 would be expressed in binary as a vector of five ones with any number of leading zeros: 0 0 0 1 1 1 1 1. The same number expressed as three hexadecimal (base 16) digits would be 0 1 15, while in base 10 it would be 0 3 1. Fifty-one inches would be expressed in yards, feet, inches as 1 1 3, an example of a mixed number base. The scalar quantities 31 and 51 in the above example should not be thought of as decimal numbers. Although they are represented at the terminal as a vector of decimal characters (digits), their internal form is not decimal, but rather depends on the characteristics of the computer, and so should be considered abstract quantities. In this discussion of encode and decode, Q will mean an abstract value or quantity and R will be its representation using a radix vector or number base B.

Encode is used to represent a number or an array of numbers in one or more number bases. The right argument is the array to be converted, the left argument defines the base (or bases) to be used for the representation. Consider first the representation of a scalar in a single uniform number base:

```
2 2 2 2 ‚ 2
0 0 1 0
2 2 2 2 ‚ 5
0 1 0 1
2 2 2 2 ‚ 13
1 1 0 1
16 16 16 ‚ 62
0 3 14
```
 The left argument is called the radix vector. If it is a scalar, it is not automatically extended as for scalar functions. The length of the radix vector determines the number of digits in the representation of the right argument. No error occurs if the length is insufficient to give a proper representation of the number. Exploring this situation will suggest other uses of encode, and may clarify the use of encode with mixed number bases.
```
4 4 4 4 ‚ 75   © The representation of 75 in base 4
1 0 2 3

4 4 4 ‚ 75     © At least four digits are needed for the full representation.
0 2 3

4 4 ‚ 75       © If fewer elements are in the left argument,
2 3

4 ‚ 75         © If the left argument is a scalar, encode is identical to residue.
3
4 ‚ 76
0

0 ‚ 75         © The expression O‚Q always yields Q as the result.
7 5

0 4 ‚ 7 5      © This usage returns quotient and remainder.
18 3
0 4 4 ‚ 75     © The first quotient (18) is again divided by 4,
© yielding a second quotient and remainder.
4 2 3

0 4 4 4 ‚ 7 5  © The process is repeated again. Since the last quotient
© is less than 4, the result is the same as 4 4 4 4 ‚ 75.
1 0 2 3

Now consider a mixed number base: convert 175 inches into yards, feet, inches.

0 12 ‚ 175     © 175 inches is 14 feet, 7 inches (quotient and remainder).
14 7
0 3 ‚ 14       © 14 feet is 4 yards, 2 feet,
4 2
0 3 12 ‚ 175   © so 175 inches is 4 yards, 2 feet, 7 inches.
4 2 7
```
 The basic concept underlying the encode function involves a vector left argument and a scalar right argument. The definition is extended to permit arrays of any rank for either argument. In the expression B‚Q, if the rank of the left argument is two or greater, then each vector along the first axis of B is applied independently to each element of Q in a manner directly analogous to the outer product. The resulting representation of each element of Q lies along the first dimension of the result. As with outer product, the shape of the result is the catenation of the shapes of B and Q.
```
4 4 4 4‚15 31 32 33 75     © The last column is 4 4 4 4‚75
0 0 0 0 1
0 1 2 2 0
3 3 0 0 2
3 3 0 1 3

10 10 10 10‚15 31 32 33 75
0 0 0 0 0
0 0 0 0 0
1 3 3 3 7
5 1 2 3 5

16 16 16 16‚15 31 32 33 75

0  0 0 0  0
0  0 0 0  0
0  1 2 2  4
15 15 0 1 11

Њ„ B„ 4 3Ѕ4 10 16    © B contains 3 radix vectors
4 10 16
4 10 16
4 10 16
4 10 16
B‚75      © The first column is 4 4 4 4‚75
1 0 0
0 0 0
2 7 4
3 5 11

B‚15 31 32 33 75    © The blue items are the elements of 4 4 4 4 ‚ 15
© The red items are the elements of 16 16 16 16 ‚ 75
0  0 0  0  1
0  0 0  0  0
0  0 0  0  0

0  1 2  2  0
0  0 0  0  0
0  0 0  0  0

3  3 0  0  2
1  3 3  3  7
0  1 2  2  4

3  3 0  1  3
5  1 2  3  5
i5 15 0  1 11

2 1 3іB‚15 31 32 33 75
0  0 0 0  1       © Dyadic transpose is used to reorder the
0  1 2 2  0       © result.
3  3 0 0  2       © The first plane is
3  3 0 1  3       © 4 4 4 4‚15 31 32 33 75

0  0 0 0  0       © This plane is
0  0 0 0  0       © 10 10 10 10‚15 31 32 33 75
1  3 3 3  7
5  1 2 3  5

0  0 0 0  0       © and this plane is
0  0 0 0  0       © 16 16 16 16‚15 31 32 33 75
0  1 2 2  4
15 15 0 1 11

```

Decode (or base-value) is used to determine the value of the representation of a quantity in some number base. If R is a vector representation (perhaps produced by the encode function described above) of some quantity Q in a number base defined by the radix vector B (i.e., R„B‚Q), then the expression BѓR yields Q:
```
2 2 2 2 ѓ 0 0 1 0
2

2 2 2 2 ѓ 0 1 0 1
5

16 16 16 ѓ 0 3 14
62
```
 As with other APL functions, scalars or one element vectors will be extended to match the length of the other argument; otherwise, the lengths of vector arguments must match.
```
2 2 2 2 ѓ 1 1 1 1
15

2 ѓ 1 1 1 1
15

2 2 2 2 ѓ 1
15

2 2 2 ѓ 1 1 1 1
LENGTH ERROR
2 2 2 ѓ 1 1 1 1
^

As with the encode function, mixed number bases can be used:

0 3 12 ѓ 4 2 7         © Convert 4 yards, 2 feet, 7 inches to inches.
175

0 24 60 60 ѓ 2 3 5 27  © Convert 2 days, 3 hours, 5 minutes,
© and 27 seconds to seconds
183927

0 24 60 60 ѓ 2 3 5 27 ч 60   © or to minutes.
3065.45
```
 The first element of the radix vector (left argument) is not used; it is required only to make the lengths match and so can be any value. This fact, and the use of encode with mixed number bases, may be clarified if we explore the mechanism used to evaluate encode. From B, the radix vector in the statement Q„BѓR, we compute a weighting vector, W, as the first step of the evaluation. Using a specific example: 0 3 12 ѓ 4 2 7 (converting yards, feet and inches to inches), compute a weighting vector from B as follows: inches per yard: 3Ч12 or 36 inches per foot: 12 inches per inch: 1 The weighting vector is 36 12 1. In APL, the process for evaluation of the weighting vector can be written:
```
W„NЅ0              © Give W the proper shape
W„Ч/1‡B         © Product of all but the first element  of B
W„Ч/2‡B         © Product of all but the first 2 elements  of B  etc.
.
.
W[N-1]„Ч/(N-1)‡B   © Next to last element of W is last  element of B
W[N]„1             © Last element of W is always I

```
 Note that the first element of B was not used. To complete the evaluation of encode, take the sum of W times R:
```
Q„+/WЧR

This result is BѓR. For our specific example:

36 12 1 Ч 4 2 7
144 24 7

144 + 24 + 7
175
0 3 12 ѓ 4 2 7
175
```
 Consider a uniform number base. If the radix vector is 2 2 2 2 2 2, then the weighting vector is 32 16 8 4 2 1, and
```
2 2 2 2 2 2 ѓ 0 1 0 1 1 1
23

is equivalent to the usual rule for converting binary numbers:

+/32 16 8 4 2 1 Ч 0 1 0 1 1 1
23
```
 The basic action of decode is to convert two vectors (radix vector and a representation) into a single quantity. The definition is extended to arrays of any rank for either argument. In the expression BѓR, each vector along the last axis of B is considered a radix vector, while each vector along the first axis of R is a representation of some quantity. It follows that the last dimension of B must match the first dimension of R. Each radix vector in B is applied independently to every representation in R. The result is an array of values from all possible combinations of the radix vectors in B with. the representations in R. The shape of the result is (Ї1‡ЅB),1‡ЅR. These rules are analagous to the rules for inner product. The following examples illustrate the use of decode with arrays; compare them with examples of encode given earlier.
```
R1„4 4 4 4 ‚ 15 31 32 33 75
R1
0 0 0 0 1
0 1 2 2 0
3 3 0 0 2
3 3 0 1 3

4 4 4 4 ѓ Rl
15 31 32 33 75

4 ѓ R1
15 31 32 33 75

B
4  4  4  4
10 10 10 10
16 16 16 16

R2„(іB) ‚ 75
R2
1 0  0
0 0  0
2 7  4
3 5 11

BѓR2
75  33 27    © Note that 75 appears on the diagonal of the result
1023  75 51
4131 117 75

R3„(іB) ‚ 15 31 32 33 75

R3
0  0 0 0  1
0  0 0 0  0
0  0 0 0  0

0  1 2 2  0
0  0 0 0  0
0  0 0 0  0

3  3 0 0  2
1  3 3 3  7
0  1 2 2  4

3  3 0 1  3
5  1 2 3  5
15 15 0 1 11

BѓR3
15  31  32  33   75
9  13  14  15   33
15  19   8   9   27

33 133 200 201 1023
15  31  32  33   75
15  25  20  21   51

51 307 512 513 4131
21  49  50  51  117
15  31  32  33   75
```
 In some instances, encode and decode are inverse functions, but not always. For example:
```
B„10 10 10 10   © For these arguments, ‚ and ѓ are inverse of each other
B ‚ 1215
1 2 1 5
B ѓ B ‚ 1215
1215
```
 But if B (in the expression B‚Q) does not have enough elements to yield the full representation of Q:
```

B2„10 10
B2 ‚ 1215
1 5
B2 ѓ B2 ‚ 1215
15
```
 The elements of a representation produced by encode are always less than the corresponding elements (except for 0) of the radix vector (B). But this property need not apply to the right argument of decode:
```
B„10 10 10 10
B ѓ 1 3 17 22
1492
B ‚ B ѓ 1 3 17 22
1 4 9 2
```
 Encode and decode are not restricted to integer arguments:
```
0 3.5 2.5 ‚ 10.5
1 0.5 0.5
2.5 ѓ 1 .5 .5
8

```

## Examples Using Encode and Decode

APL uses a vector of digit values to represent a quantity in an arbitrary number base. This convention is convenient and efficient for numeric manipulation of such data, but it is cometimes desirable to use a character representation with letters for digits greater than nine, particularly for display purposes. Suppose we wish to convert numbers to hexadecimal (base 16) using 0 through 9 and A through F as the digits. The following function shows how this might be done. The left argument specifies the desired number of digits.
```
’ r„n ConvertToHex arg;ЊIO
   ЊIO„0
   r„'0123456789ABCDEF'[і (nЅ16) ‚ arg]
’

2 ConvertToHex 31
1F

4 ConvertToHex 15 31 32 33 75
000F
001F
0020
0021
004B
```
The next example is a function that will convert the result of ConvertToHex back to numeric quantities.
```

’ r„ConvertFromHex arg;ЊIO
   ЊIO„0
   r„16 ѓ і '0123456789ABCDEF' ј arg
’

ConvertFromHex '1F'
31

ConvertFromHex 3 3 Ѕ '00F01F02F'
15 31 47

ConvertFromHex 5 ConvertToHex 2 2 5 Ѕј20
1  2  3  4  5
6  7  8  9 10

11 12 13 14 15
16 17 18 19 20

```
 Suppose we wish to create a scalar date stamp containing packed decimal digits representing month, year and day using the system variable ЊTS. ЊTS is a vector containing year, month, day, hours, minutes, seconds, milliseconds:
```
ЊTS
1998 3 6 16 2 9 430
100 100 100 ѓ 100 | 1 І 3 † ЊTS
30698
```
 Packing data in this way may occasionally be useful in other applications. Here are functions for decimal packing and unpacking. The left argument specifies the number of digits to be used for each element of the unpacked vector:
```
’ r„n PACK arg
   r„(10*n) ѓ arg
’

’ r„n UNPACK arg
   © if n is not a scalar, assume it is a vector of the proper length
   …(0¬ЅЅn)/Џunpack

   © if n is a scalar, it must be extended, use log to find number of digits
   r„—10µarg

   © divide the number of digits by n to find the number of fields in arg
   r„—rчn

  © reshape n to match the number of fields in arg
  n„rЅn

  Џunpack: r„(10*n) ‚ arg
’

3 PACK 4 7 9 12
4007009012
2 3 4 PACK 9 22 666
90220666
2 3 4 UNPACK 90220666
9 22 666

```
 Note that a mixed number base was used in the above examples (different powers of ten). Other uses of mixed number bases have already been suggested (hours, minutes, seconds; yards, feet, inches, etc.). Decode, with a mixed base, can also be used to assign or select (index) several random elements from a matrix or higher order array at once.
```
ЊIO„0
0  1  2  3  4  5  6  7  8
10 11 12 13 14 15 16 17 18
20 21 22 23 24 25 26 27 28
30 31 32 33 34 35 36 37 38
40 41 42 43 44 45 46 47 48
50 51 52 53 54 55 56 57 58
```
 Suppose we wish to add 100 to the elements of M whose coordinates are specified by the matrix S:
```
S
3 7
5 2
4 8
0 3

B„ЅM
(,M)[BѓіS]
37 52 48 3
M„,M
M[BѓіS]„100+M[BѓіS]
M„BЅM
M
0  1   2 103  4  5  6   7   8
10 11  12  13 14 15 16  17  18
20 21  22  23 24 25 26  27  28
30 31  32  33 34 35 36 137  38
40 41  42  43 44 45 46  47 148
50 51 152  53 54 55 56  57  58
```
 The following application is possible because non-integer arguments can be used and because the digits of a representation in base B need not be less than B. Consider a simple polynomial in X: Y=X4+3X3-12X2+2 One way to evaluate this polynomial in APL is:
```
Њio„1
C„1 3 Ї12 0 2   © vector of coefficients
X„4
+/CЧX*І0,ј4
258
```
 Since the coefficient vector can be thought of as a representation of Y in base X, we can use decode to evaluate the polynomial at X:
```
XѓC
258
```
 If we wish to evaluate the polynomial for several values of X, make X a matrix with one column:
```
X„8 1 Ѕ .5 Ч ј8
(5/X)ѓC
Ї0.5625 Ї6 Ї9.8125 Ї6 12.9375 56 133.6875 258
```