AppleIIAsm-Collection/source/d3_arrays/T.DEMO.ARRAYS.ASM
nathanriggs 9b12b6fd9b HOUSEKEEPING
- getting ready for major changes for 0.6.0.
- be sure to download the 0.5.0 release to ensure proper functionality, as these rountines will not work together in the SRC or BIN folder during the transition
- Beginning to significantly alter documentation
2019-12-17 17:19:24 -05:00

462 lines
16 KiB
NASM

*
*``````````````````````````````*
* DEMO.ARRAYS *
* *
* A DECIDEDLY NON-EXHAUSTIVE *
* DEMO OF ARRAY FUNCTIONALITY *
* IN THE APPLEIIASM LIBRARY. *
* *
* AUTHOR: NATHAN RIGGS *
* CONTACT: NATHAN.RIGGS@ *
* OUTLOOK.COM *
* *
* DATE: 14-JUL-2019 *
* ASSEMBLER: MERLIN 8 PRO *
* OS: DOS 3.3 *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** ASSEMBLER DIRECTIVES
*
CYC AVE
EXP OFF
TR ON
DSK DEMO.ARRAYS
OBJ $BFE0
ORG $6000
*
*``````````````````````````````*
* TOP INCLUDES (HOOKS,MACROS) *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
PUT MIN.HEAD.REQUIRED
USE MIN.MAC.REQUIRED
USE MIN.MAC.ARRAYS
PUT MIN.HOOKS.ARRAYS
*
*``````````````````````````````*
* PROGRAM MAIN BODY *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
]VAR1 EQU $300
]COUNT1 EQU $320
]ARRAY1 EQU $4000
]ARRAY2 EQU $5000
]HOME EQU $FC58
*
JSR ]HOME
_PRN "1D AND 2D 8BIT/16BIT ARRAYS",8D
_PRN "===========================",8D8D
_PRN "THIS MACRO LIBRARY AND VARIOUS",8D
_PRN "SUBROUTINES ARE USED FOR THE CREATION,",8D
_PRN "ACCESS AND MANAGEMENT OF ARRAYS THAT",8D
_PRN "CAN BE EITHER ONE OR TWO DIMENSIONS",8D
_PRN "AND CAN HAVE EITHER 255 ELEMENTS PER",8D
_PRN "DIMENSION IN THE CASE OF 8BIT ARRAYS OR",8D
_PRN "UP TO 65,530 ELEMENTS IN THE CASE OF",8D
_PRN "16BIT ARRAYS--AT LEAST, THEORETICALLY.",8D
_PRN "SINCE THAT WOULD TAKE UP THE ENTIRETY",8D
_PRN "OF RAM ON MOST APPLE ][ COMPUTERS,",8D
_PRN "HAVING THAT MANY ELEMENTS IS NOT LIKELY.",8D8D
_WAIT
JSR ]HOME
_PRN "AT LEAST IN THIS LIBRARY, ARRAYS",8D
_PRN "ARE FAIRLY SIMPLE DATA STRUCTURES.",8D
_PRN "EVERY ARRAY HAS A HEADER THAT SPECIFIES",8D
_PRN "THE NUMBER OF ELEMENTS PER DIMENSION",8D
_PRN "AS WELL AS THE LENGTH OF EACH ELEMENT.",8D
_PRN "THESE ARE SET WITH THE DIM MACROS AND",8D
_PRN "SUBROUTINES:",8D8D
_PRN "DIM81: INIT 1-DIMENSIONAL 8BIT ARRAY",8D
_PRN "DIM82: INIT 2-DIMENSIONAL 8BIT ARRAY",8D
_PRN "DIM161: INIT 1-DIMENSIONAL 16BIT ARRAY",8D
_PRN "DIM162: INIT 2-DIMENSIONAL 16BIT ARRAY",8D8D
_WAIT
_PRN "IF YOU NEED FEWER THAN 255 ELEMENTS",8D
_PRN "IN A DIMENSION, I HIGHLY SUGGEST",8D
_PRN "USING THE 8BIT ARRAY MACROS AND,",8D
_PRN "SUBROUTINES, AS THERE IS A SIGNIFICANT",8D
_PRN "SAVING OF BYTES AND CPU CYCLES.",8D
_WAIT
JSR ]HOME
_PRN "LIKE THE DIM MACROS, EACH ARRAY",8D
_PRN "TYPE ALSO HAS A GET AND PUT MACRO AND",8D
_PRN "SET OF SUBROUTINES DEDICATED TO IT:",8D8D
_WAIT
_PRN "GET81: RETRIEVE THE DATA IN A GIVEN",8D
_PRN " ELEMENT AND PUT IN RETURN.",8D
_PRN "GET82: RETRIEVE DATA FROM ELEMENT AT",8D
_PRN " X,Y AND PUT IN RETURN.",8D
_PRN "GET161: GET DATA FROM 16-BIT ELEMENT",8D
_PRN " AND PUT IN RETURN.",8D
_PRN "GET162: GET DATA FROM ELEMENT AT 16BIT",8D
_PRN " X,Y LOCATION AND PUT IN RETURN.",8D8D
_WAIT
_PRN "PUT81: PUT DATA FROM SOURCE LOCATION IN",8D
_PRN " AN ARRAY'S ELEMENT.",8D
_PRN "PUT82: PUT DATA FROM SOURCE ADDRESS IN",8D
_PRN " ARRAY ELEMENT AT X,Y.",8D
_PRN "PUT161: PUT DATA FROM SOURCE ADDRESS IN",8D
_PRN " 16-BIT ARRAY ELEMENT.",8D
_PRN "PUT162: PUT DATA FROM SOURCE INTO 16BIT",8D
_PRN " ARRAY ELEMENT AT X,Y.",8D8D
_WAIT
*
JSR ]HOME
_PRN "ONE-DIMENSIONAL, 8-BIT ARRAYS",8D
_PRN "=============================",8D8D
_PRN "DIM81, GET81, AND PU81 ARE USED FOR",8D
_PRN "1D ARRAYS THAT DON'T NEED MORE THAN",8D
_PRN "A SINGLE DIMENSION OF LESS THAN 255",8D
_PRN "ELEMENTS. FOR MANY USES, THIS SUFFICES;",8D
_PRN "THE FACT THAT THE APPLE ][ IS AN 8-BIT",8D
_PRN "COMPUTER ATTESTS TO THIS FACT.",8D8D
_WAIT
_PRN "HOWEVER, THERE ARE A NUMBER OF CASES ",8D
_PRN "IN WHICH 8-BIT INDEXING ISN'T ENOUGH.",8D
_PRN "AGAIN, MAKE THE CHOICE BASED ON NEED,",8D
_PRN "NOT CONVENIENCE. IF 255 ELEMENTS IS",8D
_PRN "ENOUGH TO ACCOMPLISH THE TASK, USE ",8D
_PRN "THESE MACROS AND SUBROUTINES.",8D8D
_WAIT
JSR ]HOME
_PRN "EIGHT BITS AND ONE DIMENSION: DIM",8D
_PRN "=================================",8D8D
_PRN "THE DIM81 MACRO CREATES A THREE",8D
_PRN "BYTE HEADER THAT HOLDS, IN ORDER:",8D8D
_PRN "BYTE 0: NUMBER OF ELEMENTS",8D
_PRN "BYTE 1: ELEMENT SIZE",8D8D
_PRN "THE GET81 AND PUT81 ROUTINES USE ",8D
_PRN "THIS HEADER TO KNOW HOW MUCH DATA",8D
_PRN "TO READ AND WRITE FROM AN ELEMENT.",8D
_PRN "BASIC CHECKS AGAINST THE INTENDED",8D
_PRN "NUMBER OF ELEMENTS CAN ALSO BE DONE",8D
_PRN "USING THIS HEADER.",8D8D
_WAIT
_PRN " DIM81 #ARRAY1;#10;#2;#$FF",8D8D
_PRN "CREATES AN 8BIT, 1D ARRAY AT THE",8D
_PRN "ADDRESS OF #ARRAY1 WITH TEN ELEMENTS",8D
_PRN "OF 2 BYTES EACH. ALL ELEMENTS ARE",8D
_PRN "FILLED WITH THE LAS PARAMETER, $FF."
_WAIT
JSR ]HOME
_PRN "WE CAN DUMP #ARRAY1 BEFORE AND",8D
_PRN "AFTER USING DIM81 TO SHOW THE",8D
_PRN "DIFFERENCE:",8D8D
_PRN "BEFORE:",8D8D
DUMP #]ARRAY1;#2
DUMP #]ARRAY1+2;#10
DUMP #]ARRAY1+12;#10
_PRN " ",8D8D
_WAIT
DIM81 #]ARRAY1;#10;#2;#$FF
_PRN "AFTER:",8D8D
DUMP #]ARRAY1;#2
DUMP #]ARRAY1+2;#10
DUMP #]ARRAY1+12;#10
_WAIT
JSR ]HOME
_PRN "8 BITS AND ONE DIMENSION: PUT",8D
_PRN "=============================",8D8D
_PRN "THE PUT81 MACRO PUTS THE DATA FROM",8D
_PRN "A SOURCE ADDRESS INTO AN 8BIT, 1D",8D
_PRN "ARRAY ELEMENT. THE SOURCE ADDRESS,",8D
_PRN "ARRAY ADDRESS AND THE ELEMENT NUMBER",8D
_PRN "ARE SPECIFIED AS PARAMETERS, IN",8D
_PRN "THAT ORDER. NOTE THAT THE NUMBER OF",8D
_PRN "BYTES TO COPY INTO THE ELEMENT IS",8D
_PRN "PREDETERMINED BY THE ELEMENT SIZE",8D
_PRN "SET BY DIM81 IN THE HEADER.",8D8D
_PRN "THUS:",8D8D
_WAIT
_PRN " LDA #0",8D
_PRN " STA ]VAR1",8D
_PRN " STA ]VAR1+1",8D
_PRN " PUT81 #]VAR1;#ARRAY1;#3",8D8D
_PRN "WILL PUT $0000 IN ARRAY1'S ",8D
_PRN "ELEMENT 3, WHICH IS TECHNICALLY THE",8D
_PRN "FOURTH ELEMENT DUE TO ZERO INDEXING."
LDA #0
STA ]VAR1
STA ]VAR1+1
PUT81 #]VAR1;#]ARRAY1;#3
_WAIT
JSR ]HOME
_PRN "IF WE DUMP THE ARRAY AGAIN, WE ",8D
_PRN "CAN READILY SEE THE CHANGE:",8D8D
_WAIT
DUMP #]ARRAY1;#2
DUMP #]ARRAY1+2;#10
DUMP #]ARRAY1+12;#10
_WAIT
_PRN " ",8D8D
_PRN "OF COURSE, THIS IS OF LIMITED",8D
_PRN "USE WITHOUT A FUNCTION TO EXTRACT",8D
_PRN "THE ELEMENT INA USEFUL FASHION--",8D
_PRN "RELYING ON THE DUMP MACRO ONLY GOES",8D
_PRN "SO FAR. THAT'S WHERE OUR THIRD MACRO",8D
_PRN "AND SUBROUTINE COMES IN..."
_WAIT
JSR ]HOME
_PRN "8-BIT, 1-DIMENSION ARRAYS: GET",8D
_PRN "==============================",8D8D
_PRN "THE GET81 MACRO GETS THE DATA",8D
_PRN "STORED IN AN ELEMENT AND COPIES IT",8D
_PRN "TO RETURN, STORING THE ELEMENT",8D
_PRN "LENGTH IN RETLEN. THIS ALLOWS YOU",8D
_PRN "TO USE THE ARRAY..WELL, LIKE AN",8D
_PRN "ARRAY. SO:",8D8D
_WAIT
_PRN " GET81 #ARRAY1;#3",8D8D
_PRN "RETRIEVES ELEMENT 3 OF ARRAY1 AND",8D
_PRN "STORES IT IN RETURN FOR USE BY YOUR",8D
_PRN "PROGRAM. WE CAN DUMP RETURN BEFORE",8D
_PRN "AND AFTER USING GET81 TO SHOW",8D
_PRN "THE DIFFERENCE:",8D8D
_WAIT
_PRN "BEFORE:",8D
DUMP #RETURN;RETLEN
_WAIT
_PRN " ",8D8D
_PRN "AFTER: ",8D
GET81 #]ARRAY1;#3
DUMP #RETURN;RETLEN
_WAIT
JSR ]HOME
_PRN "16-BITS AND ONE DIMENSION: DIM161",8D
_PRN "=================================",8D8D
_PRN "DIM161 WORKS IN FORM AND FUNCTION JUST",8D
_PRN "AS DIM81 DOES, EXCEPT IT ACCEPTS",8D
_PRN "A TWO-BYTE VALUE FOR THE NUMBER",8D
_PRN "OF ELEMENTS. BECAUSE OF THIS, THE ARRAY",8D
_PRN "HEADER CREATED IS THREE BYTES INSTEAD",8D
_PRN "OF THE TWO IN 8-BIT ARRAYS. SO:",8D8D
_WAIT
_PRN " DIM161 #ARRAY1;#300;#2;#$00",8D8D
_PRN "WILL INITIALIZE AN ARRAY WITH 0..300",8D
_PRN "ELEMENTS, ONE DIMENSION. AGAIN, THIS",8D
_PRN "CAN TECHNICALLY USE A BIT MORE THAN",8D
_PRN "65,000 ELEMENTS, BUT THIS IS BEYOND",8D
_PRN "IMPRACTICAL FOR THE PURPOSES OF THIS",8D
_PRN "LIBRARY, AS A CONSECUTIVE 64K OF BYTES",8D
_PRN "IS UNLIKELY IN MOST APPLE II SYSTEMS.",8D8D
_WAIT
DIM161 #]ARRAY1;#300;#2;#$00
JSR ]HOME
_PRN "16-BITS AND ONE DIMENSION: PUT",8D
_PRN "==============================",8D8D
_PRN "NOW THAT WE HAVE CREATED OUR ARRAY,",8D
_PRN "WE CAN USE PUT161 TO CHANGE THE DATA",8D
_PRN "IN EACH ELEMENT. AGAIN, THIS WORKS",8D
_PRN "EXACTLY LIKE PUT81, BUT WITH SOME",8D
_PRN "EXTRA BYTES HERE AND THERE TO ACCOUNT",8D
_PRN "FOR THE EXTRA BREADTH. LET'S FILL",8D
_PRN "EACH ELEMENT 0..300 WITH ITS OWN VALUE--",8D
_PRN "THAT IS, 0 WILL HOLD 0, 1 WILL HOLD 1,",8D
_PRN "299 WILL HOLD 2999 AND 300 WILL HOLD",8D
_PRN "300:",8D8D
_WAIT
_PRN " LDA #0",8D
_PRN " STA ]COUNT",8D
_PRN " STA ]COUNT+1",8D
_PRN " TAX",8D
_PRN " TAY",8D
_PRN "LP ",8D
_PRN " PUT161 #]COUNT'#]ARRAY1;]COUNT",8D
_PRN " LDA ]COUNT",8D
_PRN " CLC",8D
_PRN " ADC #1",8D
_PRN " STA ]COUNT",8D
_PRN " LDA ]COUNT+1",8D
_PRN " ADC #0",8D
_PRN " STA ]COUNT+1",8D
_PRN " CMP #$01",8D
_PRN " BNE LP",8D
_PRN " LDA ]COUNT",8D
_PRN " CMP #$2C",8D
_PRN " BNE LP"
_WAIT
*
LDA #0
STA ]COUNT1
STA ]COUNT1+1
TAX
TAY
LP161
PUT161 #]COUNT1;#]ARRAY1;]COUNT1
LDA ]COUNT1
DUMP #]COUNT1;#2
LDA ]COUNT1
CLC
ADC #1
STA ]COUNT1
LDA ]COUNT1+1
ADC #0
STA ]COUNT1+1
CMP #$01
BNE LP161
LDA ]COUNT1
CMP #$2D
BNE LP161
_WAIT
*
JSR ]HOME
_PRN "WE CAN NOW DUMP THE ENTIRE ARRAY",8D
_PRN "TO SEE HOW EACH ELEMENT IS STORED,"
_PRN "ALONG WITH THE THREE BYTE HEADER:",8D8D
_WAIT
DUMP #]ARRAY1;#3
_WAIT
DUMP #]ARRAY1+3;#60
_WAIT
DUMP #]ARRAY1+63;#60
_WAIT
DUMP #]ARRAY1+123;#60
_WAIT
DUMP #]ARRAY1+183;#60
_WAIT
DUMP #]ARRAY1+243;#60
_WAIT
DUMP #]ARRAY1+303;#60
_WAIT
DUMP #]ARRAY1+363;#60
_WAIT
DUMP #]ARRAY1+423;#60
_WAIT
DUMP #]ARRAY1+483;#60
_WAIT
DUMP #]ARRAY1+543;#64
_PRN " ",8D8D
_PRN "WELL THAT CERTAINLY WAS A DUMP...",8D8D
_WAIT
JSR ]HOME
_PRN "16-BITS IN ONE DIMENSION: GET",8D
_PRN "=============================",8D8D
_PRN "AND OF COURSE, WE HAVE THE SAME GET",8D
_PRN "MACRO FOR 16-BIT, 1D ARRAYS, GET162. THIS",8D
_PRN "AGAIN FUNCTIONS THE SAME AS ITS 8-BIT",8D
_PRN "COUNTERPART, EXCEPT THE INDEX IS TWO ",8D
_PRN "BYTES RATHER THAN ONE.",8D8D
_PRN " ",8D8D
_PRN "THUS:",8D8D
_WAIT
_PRN " GET161 #]ARRAY1;#270",8D8D
_PRN "RETURNS: "
GET161 #]ARRAY1;#270
DUMP #RETURN;RETLEN
_WAIT
JSR ]HOME
_PRN "8-BIT, 2D ARRAYS: FML ANOTHER DIM",8D
_PRN "=================================",8D8D
_PRN "AT THIS POINT, YOU SHOULD HAVE A",8D
_PRN "GOOD GRASP AS TO HOW ARRAYS WORK",8D
_PRN "IN THIS LIBRARY. TWO-DIMENSIONAL",8D
_PRN "ARRAYS DO NOT SIGNIFICANTLY DIFFER",8D
_PRN "FROM ONE-DIMENSIONAL ARRAYS; IT JUST",8D
_PRN "MEANS THAT AN EXTRA ELEMENT INDEX IS",8D
_PRN "NEEDED AS A PARAMETER. AS SUCH, WE CAN",8D
_PRN "MOSTLY BREEZE THROUGH THE REST OF THESE.",8D8D
_WAIT
_PRN "TO INITIALIZE A 2D, 8BIT ARRAY:",8D8D
_PRN " DIM82 #ARRAY1;#10;#10;#1;#00",8D8D
_PRN "THIS CREATES AN ARRAY OF TEN BY TEN",8D
_PRN "ELEMENTS (TOTAL OF 100 ELEMENTS) WITH ",8D
_PRN "A LENGTH OF ONE BYTE. EACH ELEMENT",8D
_PRN "IS INITIALIZED TO A VALUE OF 0."
_WAIT
DIM82 #]ARRAY1;#10;#10;#1;#0
JSR ]HOME
_PRN "NOTE THAT WE HAVE A LONGER HEADER",8D
_PRN "THANKS TO THE EXTRA ELEMENT INDEX. THE",8D
_PRN "HEADER CONTAINS THE X-DIMENSION AS ",8D
_PRN "BYTE ZERO, Y-DIMENSION AS BYTE ONE,",8D
_PRN "AND ELEMENT LENGTH AS BYTE TWO, AS SUCH:",8D8D
DUMP #]ARRAY1;#3
_WAIT
_PRN " ",8D8D
_PRN "AND THE REST OF THE ARRAY:",8D8D
DUMP #]ARRAY1+3;#10
DUMP #]ARRAY1+13;#10
DUMP #]ARRAY1+23;#10
DUMP #]ARRAY1+33;#10
DUMP #]ARRAY1+43;#10
DUMP #]ARRAY1+53;#10
DUMP #]ARRAY1+63;#10
DUMP #]ARRAY1+73;#10
DUMP #]ARRAY1+83;#10
DUMP #]ARRAY1+93;#10
_WAIT
JSR ]HOME
_PRN "8-BIT, 2-DIMENSIONAL ARRAYS: PUT, GET",8D
_PRN "=====================================",8D8D
_PRN "AND OF COURSE, JUST AS WITH 1D ARRAYS",8D
_PRN "WE CAN USE PUT82 AND GET82 TO WRITE",8D
_PRN "TO AND READ FROM THE ARRAY:",8D8D
_WAIT
_PRN " LDA #$FF",8D
_PRN " STA ]VAR1",8D
_PRN " PUT82 #]VAR1;#]ARRAY1;#4;#5",8D
_PRN " GET82 #]ARRAY1;#4;#5",8D
_PRN " DUMP #RETURN;RETLEN",8D8D
_PRN "PRODUCES:",8D8D
_WAIT
LDA #$FF
STA ]VAR1
PUT82 #]VAR1;#]ARRAY1;#4;#5
GET82 #]ARRAY1;#4;#5
DUMP #RETURN;RETLEN
_WAIT
JSR ]HOME
_PRN "16-BIT 2D ARRAYS: DIM, GET, PUT",8D
_PRN "===============================",8D8D
_PRN "AND LASTLY, WE CAN USE 16-BIT, TWO-",8D
_PRN "DIMENSIONAL ARRAYS VIA THE DIM162,",8D
_PRN "PUT162, AND GET162 MACROS:",8D8D
_PRN " DIM162 #]ARRAY1;#300;#300;#1;#$00",8D
_PRN " PUT162 #]VAR1;#]ARRAY1;#280;#280",8D
_PRN " GET162 #]ARRAY1;#280;#280",8D
_PRN " DUMP #RETURN;RETLEN",8D8D
_PRN "PRODUCES:",8D8D
_WAIT
DIM162 #]ARRAY1;#300;#2;#1;#$00
PUT162 #]VAR1;#]ARRAY1;#280;#1
GET162 #]ARRAY1;#280;#1
DUMP #RETURN;RETLEN
_WAIT
JSR ]HOME
_PRN " ",8D8D
_PRN "FIN.",8D8D8D
*
JMP REENTRY
*
*``````````````````````````````*
* BOTTOM INCLUDES (ROUTINES) *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
PUT MIN.LIB.REQUIRED
*
** INDIVIDUAL SUBROUTINE INCLUDES
*
** 8-BIT 1-DIMENSIONAL ARRAY SUBROUTINES
*
PUT MIN.SUB.ADIM81
PUT MIN.SUB.AGET81
PUT MIN.SUB.APUT81
*
** 8-BIT 2-DIMENSIONAL ARRAY SUBROUTINES
*
PUT MIN.SUB.ADIM82
PUT MIN.SUB.AGET82
PUT MIN.SUB.APUT82
*
** 16-BIT 1-DIMENSIONAL ARRAYS
*
PUT MIN.SUB.ADIM161
PUT MIN.SUB.APUT161
PUT MIN.SUB.AGET161
*
** 16-BIT 2-DIMENSIONAL ARRAYS
*
PUT MIN.SUB.ADIM162
PUT MIN.SUB.APUT162
PUT MIN.SUB.AGET162