Difference between revisions of "System Function DR"

From NARS2000
Jump to navigationJump to search
m (→‎Dyadic Function: expansion, correction)
Line 38: Line 38:
  
 
<apll>
 
<apll>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;6412 ⎕DR 'NARS2000'</apll> &mdash; Eight 16-bit characters (=128 bits) converts to <u>two 64-bit integers</u>:<apll><br />
+
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;6412 ⎕DR 'NARS2000'</apll> &mdash; Eight 16-bit characters (=128 bits) converts to <u>two 64-bit integers</u> (in both NARS2000 32-bit AND 64-bit exe's since <big>L=6412</big>):<apll><br />
 
23362775258562638 13511005043687474<br />
 
23362775258562638 13511005043687474<br />
 
</apll>
 
</apll>
Line 59: Line 59:
 
</apll>
 
</apll>
  
<p>However, this doesn't produce the expected result because this particular right argument is an <big>APA</big>, and <u>not</u> a simple Boolean vector of 1's.  That is, under certain circumstances, the reshape primitive creates an APA.  In this case, the APA is an array with an offset of <apll>1</apll>, a multiplier of <apll>0</apll> and a shape of <apll>2</apll> rows and <apll>64</apll> cols.  The usefulness of APS's in reducing data storage and processing times outweighs their sometimes added code complexity or additional insight, which may be required.</p>
+
<p>However, this doesn't produce the expected result because this particular right argument is an <big>APA</big>, and <u>not</u> a simple Boolean vector of 1's.  That is, under certain circumstances, the reshape primitive creates an APA.  In this case, the APA is an array with an offset of <apll>1</apll>, a multiplier of <apll>0</apll> and a shape of <apll>2</apll> rows and <apll>64</apll> cols.  The usefulness of APA's in reducing data storage and processing times outweighs their sometimes added code complexity or additional insight, which may be required.</p>
  
 
<p>On the other hand, this expression:</p>
 
<p>On the other hand, this expression:</p>
Line 97: Line 97:
 
76              ⍝ again dyadic ⎕DR results in a string, this time of length 76
 
76              ⍝ again dyadic ⎕DR results in a string, this time of length 76
 
</pre>
 
</pre>
Note in the above that iota-12 in System Function call '''0 ⎕DR ⍳12''' - was run using the '''64-bit NARS version''', hence the 64-bit offset and 64-bit multiplier.  Had it been run in '''32-bit NARS''', it would have returned 32-bit signatures.
+
<p>Note in the above that iota-12 in System Function call '''0 ⎕DR ⍳12''' - runs similarly using both '''64-bit AND 32-bit NARS versions''', hence the 64-bit offset and 64-bit multiplier.  This is because integer APAs are processed using 64-bit formats. Again, if ever there is any doubt or a need to precisely determine formats, use ⎕DR with its correct syntax, arguments.</p><br>
  
Many times in programming for debugging, data scrutiny or other purposes: It is very important to know <u>exactly how the data is represented by the program</u>. ⎕DR or Data Representation is a feature designed to allow close scrutiny of how data is stored in memory and operated on in NARS.
+
<p>Many times in programming - for debugging, data scrutiny or other purposes - it is very important to know <u>exactly how the data is represented by the program</u>. ⎕DR or Data Representation is a feature designed to allow close scrutiny of how data is stored in memory and operated on in NARS.</p><br>
  
 
<p>Some arrays have properties that may be displayed by this function:</p>
 
<p>Some arrays have properties that may be displayed by this function:</p>
Line 135: Line 135:
 
3FF199999999999A &nbsp; &nbsp;⍝ note the hexadecimal char representation of 1.1 is shown at left<br />
 
3FF199999999999A &nbsp; &nbsp;⍝ note the hexadecimal char representation of 1.1 is shown at left<br />
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;⍴1 ⎕DR 1.1<br />
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;⍴1 ⎕DR 1.1<br />
16 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;⍝ length of floating pt num 1.1 hex repr = 16 hex-chars = 64-bit-NARS<br />
+
16 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;⍝ length of floating pt num 1.1 hex repr = 16 hex-chars = both 64-bit and 32-bit NARS<br />
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1 ⎕DR '3fd',13⍴'5'<br />
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1 ⎕DR '3fd',13⍴'5'<br />
 
0.3333333333333333<br />
 
0.3333333333333333<br />
Line 191: Line 191:
 
</apll>
 
</apll>
 
<br/>
 
<br/>
 +
See also '''[[System_Variable_CT|System Variable ⎕CT]]''' and '''[[System_Variable_PP|System Variable ⎕PP]]'''.<br>
 
{{SFDM|DR}}
 
{{SFDM|DR}}

Revision as of 01:11, 22 August 2015

This function is available in both monadic and dyadic forms.

Monadic Function

Z←⎕DR R returns the data representation of R.
R is an arbitrary array.
Z is a numeric scalar which represents the datatype of R.


The datatypes are encoded with a unique index in the low-order two digits, and (where appropriate) the bits per element in the higher-order digits:

  •  110: Boolean, one bit per element
  • 1611: Character, 16 bits per element
  • 6412: Integer, 64 bits per element
  • 6413: Floating Point, 64 bits per element (double precision)
  •   14: Rational, 16 bytes plus two 4- or 8-byte pointers plus size of limbs per element
  •   15: Variable-precision Floating Point, 12 bytes plus one 4- or 8-byte pointer plus size of limbs per element
  •   19: Arithmetic Progression Array, 64 bits each for the offset and multiplier
  •   20: Heterogeneous, one 4- or 8-byte pointer per element
  •   21: Nested, one 4- or 8-byte pointer per element

For example,

      ⎕DR 1 0 1
110
      ⎕DR ⌈/⍬
6413
      ⎕DR 2 64⍴1
— Note this is really an APA, not Boolean
19
      ⎕DR 2 64⍴1 1
— This one is Boolean because Reshape produces APAs for integer singleton right arguments only
110


Dyadic Function

Z←L ⎕DR R converts R to the datatype indicated by L.
R is an arbitrary array.
L is an integer scalar or one-element vector datatype (see the table above), or a special value (see below).
Z is R where each of the values are converted to the datatype indicated by L.

Returned value Z may alternatively be: numeric scalar, vector of numbers, or a character string - depending on what the value of left argument L was.

If the conversion is from a narrower datatype to a wider datatype, there must be exactly enough columns in the right argument to match a multiple of the size of the wider datatype. For example, when converting from character (16-bit) to integer (64-bit), the last column of the right argument must be a multiple of 4 (= 64/16); otherwise, a LENGTH ERROR is signalled.

      6412 ⎕DR 'NARS2000' — Eight 16-bit characters (=128 bits) converts to two 64-bit integers (in both NARS2000 32-bit AND 64-bit exe's since L=6412):
23362775258562638 13511005043687474

If the conversion is from a wider datatype to a narrower datatype, the number of values in the result is a multiple of the ratio of the wider datatype to the narrower datatype. For example, when converting from integer (64-bit) to character (16-bit), the last column in the result is the product of last column of the right argument and 4 (= 64/16).

For example(inverse of the example just above),

      ⍴⎕←1611 ⎕DR 23362775258562638 13511005043687474
NARS2000
8

Keep in mind how Arithmetic Progression Arrays are created and represented; they can fool both the casual programmer as well as an experienced coder. For example, one might try the following to convert from Boolean to integer:

      6412 ⎕DR 2 64⍴1     ⍝ APA created
1 0 2 64

However, this doesn't produce the expected result because this particular right argument is an APA, and not a simple Boolean vector of 1's. That is, under certain circumstances, the reshape primitive creates an APA. In this case, the APA is an array with an offset of 1, a multiplier of 0 and a shape of 2 rows and 64 cols. The usefulness of APA's in reducing data storage and processing times outweighs their sometimes added code complexity or additional insight, which may be required.

On the other hand, this expression:

      6412 ⎕DR 2 64⍴1 1   ⍝ contrast to prior example - Boolean vec created here, NOT an APA
 ¯1
 ¯1

produces the expected result because the right argument is "right upon moment of vector 1 1 creation" - Boolean.

Special Values

There are several special values you may use as a left argument to ⎕DR:

  • The value 0 displays the datatype of the right argument as a text string so you don't need to remember the datatype numbers.

    For example,

          ⎕DR 'a'
    1611
          ⍴⎕DR 'a'   ⍝ the shape of a scalar is null
    
          ⍴⍴⎕DR 'a'
    0                ⍝ the shape of the shape of a scalar is always zero; monadic ⎕DR 'a' results in scalar number Z=1611
          0 ⎕DR 'a'
    Character (1611):  16 bits per element     ⍝ string result returned where left arg of ⎕DR was zero
          ⍴0 ⎕DR 'a'
    38              ⍝ the shape of the data returned is 38; dyadic 0 ⎕DR 'a' results in a character array, a string of length 38
    
    
          0 ⎕DR ⍳12
    Arithmetic Progression Array (19):  64 bit offset + 64 bit multiplier -- PV1       ⍝ 64-bit signatures re integer numeric progression
          ⍴0 ⎕DR ⍳12
    76              ⍝ again dyadic ⎕DR results in a string, this time of length 76
    

    Note in the above that iota-12 in System Function call 0 ⎕DR ⍳12 - runs similarly using both 64-bit AND 32-bit NARS versions, hence the 64-bit offset and 64-bit multiplier. This is because integer APAs are processed using 64-bit formats. Again, if ever there is any doubt or a need to precisely determine formats, use ⎕DR with its correct syntax, arguments.


    Many times in programming - for debugging, data scrutiny or other purposes - it is very important to know exactly how the data is represented by the program. ⎕DR or Data Representation is a feature designed to allow close scrutiny of how data is stored in memory and operated on in NARS.


    Some arrays have properties that may be displayed by this function:

    PV0 This array is a Permutation Vector, origin-0
    PV1 This array is a Permutation Vector, origin-1
    All2s This array consists of all 2s
    FPCnnn This array is a VFP and all entries are represented in Precision nnn
    FPC-Mixed This array is a VFP whose entries are represented in two or more different precisions
  • The value 1 converts between hex-character and floating point computer formats. This argument makes it very useful to view representations of floating point numbers - in order to better understand numeric precisions, program storage formats, debug multi-precision floating-point math routines(by NARS developers) or examine perceived floating point issues.

    For example,

          ⎕PP←99
          1 ⎕DR 1.1
    3FF199999999999A    ⍝ note the hexadecimal char representation of 1.1 is shown at left
          ⍴1 ⎕DR 1.1
    16                  ⍝ length of floating pt num 1.1 hex repr = 16 hex-chars = both 64-bit and 32-bit NARS
          1 ⎕DR '3fd',13⍴'5'
    0.3333333333333333
          1 ⎕DR ¯∞ ∞
    FFF0000000000000
    7FF0000000000000
          1 ⎕DR '7fe',13⍴'f'
    — The largest positive number
    1.7976931348623157E308
          1 ⎕DR '001',13⍴'0'
    — The smallest positive number
    2.2250738585072014E¯308
          1 ⎕DR '801',13⍴'0'
    — The largest negative number
    ¯2.2250738585072014E¯308
          1 ⎕DR 'ffe',13⍴'f'
    — The smallest negative number
    ¯1.7976931348623157E308

  • The value 2 converts between character and 64-bit integer. This argument makes it easy to see the representation of integers.

    For example,

          2 ⎕DR ¯1
    FFFFFFFFFFFFFFFF
          2 ⎕DR '7',15⍴'f'
    — The largest positive integer
    9223372036854775807
          2 ⎕DR '8',15⍴'0'
    — The smallest negative integer
    ¯9223372036854775808
          2 ⎕DR 9223372036854775807 ¯9223372036854775808
    7FFFFFFFFFFFFFFF
    8000000000000000

A Word of Caution

This system function allows you to create special numbers we don't support in that no other primitive generates these numbers and the behavior of all other primitives on these numbers is undefined. Examples of such special numbers include Quiet NaNs, Signaling NaNs, Negative Zero, and Denormals. If the system doesn't behave as you expect when using these special numbers, don't be surprised.

For example,

      ⎕CT←0 ⋄ ⎕PP←99
      6413 ⎕DR ¯64↑1
¯0
      QNaN←6413 ⎕DR ¯64↑13⍴1
— A Quiet NaN (Not a Number)
      1 ⎕DR QNaN
FFF8000000000000
      QNaN=QNaN
0
      1 ⎕DR '000fffffffffffff'
— The largest positive denormal
2.225073858507201E¯308
      1 ⎕DR '0000000000000001'
— The smallest positive denormal
5E¯324

See also System Variable ⎕CT and System Variable ⎕PP.

Note: ⎕DR is available as both a monadic and dyadic form system function, you cannot assign a value to it.

System Variables (A value may be assigned to these except for ⎕DM)
ALX CT DM DT ELX FC FEATURE FPC IC IO
LR LX PP PR PW RL SA WSID
Niladic System Functions (a value cannot be assigned to these)
A AV EM ET LC NNAMES NNUMS SI SYSID SYSVER
T TC TCBEL TCBS TCESC TCFF TCHT TCLF TCNL TCNUL
TS WA
Monadic or dyadic system functions (a value cannot be assigned to these)
AT CR DC DFT DL DR EA EC ERROR ES
EX FMT FX MF NAPPEND NC NCREATE NERASE NINFO NL
NLOCK NREAD NRENAME NREPLACE NRESIZE NSIZE NTIE NUNTIE STOP TF
TRACE UCS VR
Note that quad functions and variables (except for the ⎕A family of functions) are case insensitive


See Also
System Commands System Variables and Functions Operators


Keyboard
A+S
Alt ¨ ¯ < > × ÷
Sh ~ ! @ # $ % ^ & * ( ) _ +
Key ` 1 2 3 4 5 6 7 8 9 0 - =
A+S
Alt ? § π
Sh Q W E R T Y U I O P { } |
Key q w e r t y u i o p [ ] \
A+S
Alt
Sh A S D F G H J K L : "
Key a s d f g h j k l ; '
A+S
Alt
Sh Z X C V B N M < > ?
Key z x c v b n m , . /
NARS 2000 Lang
Tool
Bar
+ - × ÷ * ! ? |
< = >
~ § π .. ,
/ \ ¨ .
_ ¯
Second Row i j k i j k l g p r v x