*
*``````````````````````````````*
* DEMO.ARRAYS                  *
*                              *
* A DECIDEDLY NON-EXHAUSTIVE   *
* DEMO OF ARRAY FUNCTIONALITY  *
* IN THE APPLEIIASM LIBRARY.   *
*                              *
* AUTHOR:    NATHAN RIGGS      *
* CONTACT:   NATHAN.RIGGS@     *
*            OUTLOOK.COM       *
*                              *
* DATE:      18-MAR-2021       *
* 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.ASM
         USE   MIN.MAC.REQUIRED.ASM
         USE   MIN.MAC.ARR8B1D.ASM
         USE   MIN.MAC.ARR8B2D.ASM
         USE   MIN.MAC.ARR16B1D.ASM
         USE   MIN.MAC.ARR16B2D.ASM
         PUT   MIN.HEAD.ARRAYS.ASM
*
]HOME2   EQU   $FC58
*
*``````````````````````````````*
*      PROGRAM MAIN BODY       *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE ARRAY COLLECTION OF THE APPLEIIASM LIBRARY
** CONTAINS THE CORE FUNCTIONALITY NECESSARY FOR
** USING ARRAYS. CURRENTLY, THERE ARE 4 TYPES OF
** ARRAYS SUPPORTED: 8-BIT, 1 DIMENSIONAL ARRAYS,
** WHICH CAN HOLD UP TO 255 KEYS, 8-BIT, 2-DIMENSIONAL
** ARRAYS THAT CAN HOLD UP TO 255 X 255 ELEMENTS
** ACCESSED VIA AN X,Y COORDINATE; 16-BIT,
** 1-DIMENSION ARRAYS THAT CAN HOLD JUST OVER 65K
** ELEMENTS (A MAXIMUM THAT WOULD TAKE UP MOST OF THE
** MEMORY ON A TYPICAL APPLE II SYSTEM), AND 16-BIT,
** 2-DIMENSIONAL ARRAYS THAT CAN HOLD A MAXIMUM OF
** 65K X 65K ELEMENTS ACCESSED VIA X,Y COORDINATES.
*
** AS IT IS, EACH TYPE OF ARRAY HAS THREE MACROS DEDICATED
** TO IT: AN ARRAY INITIALIZATION MACRO (DIM), A MACRO
** THAT GETS AN ELEMENT VALUE, AND A MACRO THAT ENTERS
** A VALUE AT THE SPECIFIED INDEX ELEMENT. SUPPORT FOR
** SPECIFIC MACROS AND SUBROUTINES THAT ACT ON ARRAYS, SUCH
** AS SORTING ALGORITHMS, MERGING, SEARCHING AND SO ON,
** ARE LIKELY TO BE ADDED IN THE FUTURE, BUT THIS WILL
** REQUIRE A SECOND DISK DEDICATED TO ARRAYS, GIVEN SPACE
** CONSTRAINTS. SUPPORT FOR 8-BIT 3-DIMENSIONAL ARRAYS
** MAY ALSO BE SUPPORTED, BUT THAT DEPENDS ON NECESSITY OR
** DEMAND.
*
** THIS DEMO FILE SHOWS THE USAGE AND PERFORMANCE OF THE
** FOLLOWING MACROS (AND THE SUBROUTINES BEHIND THEM):
*
**  DIM81   : INITIALIZE AN 8-BIT, 1 DIMENSIONAL ARRAY
**  GET81   : RETRIEVE ELEMENT VALUE FROM 8-BIT, 1-D ARRAY
**  PUT81   : PLACE VALUE IN ELEMENT OF 8-BIT, 1-D ARRAY
**  DIM82   : INITIALIZE AN 8-BIT, 2 DIMENSIONAL ARRAY
**  GET82   : RETRIEVE ELEMENT VALUE FROM 8-BIT, 2-D ARRAY
**  PUT82   : PLACE VALUE IN ELEMENT OF 8-BIT, 2-D ARRAY
**  DIM161  : INITIALIZE A 16-BIT, 1 DIMENSIONAL ARRAY
**  GET161  : RETRIEVE ELEMENT VALUE FROM 16-BIT, 1-D ARRAY
**  PUT161  : PLACE VALUE IN ELEMENT OF 16-BIT, 1-D ARRAY
**  DIM162  : INITIALIZE A 16-BIT, 2 DIMENSIONAL ARRAY
**  GET162  : RETRIEVE ELEMENT VALUE FROM 16-BIT, 2-D ARRAY
**  PUT162  : PLACE VALUE IN ELEMENT OF 16-BIT, 2-D ARRAY
*
*``````````````````````````````*
* 8-BIT ARRAY MACRO EXAMPLES   *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** SINCE THESE ROUTINES DO NOT NORMALLY OUTPUT ANYTHING
** ON THEIR OWN, WE WILL BE USING THE DUMP MACRO FROM THE
** REQUIRED LIBRARY COLLECTION IN ORDER TO PEEK AT THE
** ARRAY CONTENTS.
*
** FIRST, LET'S TACKLE ONE-DIMENSIONAL 8-BIT ARRAYS. WE START
** BY INITIALIZING THE ARRAY, WHICH ALWAYS MUST BE DONE BEFORE
** ANY OTHER USE OF AN ARRAY. WE DO THIS WITH THE DIM81 MACRO,
** AS SUCH:
*
         DIM81 #$300;#10;#2;#$EE
*
** HERE WE ARE INITIALIZING AN ARRAY AT THE ADDRESS #$300,
** WITH 10 ELEMENTS THAT ARE EACH 2 BYTES LONG. EACH ELEMENT
** IS FILLED WITH THE VALUE #$EE TO BEGIN WITH. NOW WE CAN
** USE DUMP TO VIEW THE ARRAY:
*
         JSR   ]HOME2
         _PRN  "8-BIT, 1-DIMENSIONAL ARRAYS",8D
         _PRN  "===========================",8D8D8D
         DUMP  #$300;#2
         DUMP  #$302;#10
         DUMP  #$30C;#10
         _PRN  " ",8D8D
         _WAIT
*
** IT IS IMPORTANT TO NOTE HOW WE ARE VIEWING THE ARRAY HERE.
** FIRST, WE ARE DUMPING THE FIRST TWO BYTES OF THE ARRAY;
** THESE HOLD THE NUMBER OF ELEMENTS IN THE ARRAY AND THE
** LENGTH OF EACH ELEMENT, RESPECTIVELY. AFTERWARDS, WE
** DUMP THE FOLLOWING 20 BYTES, DETERMINED BY THE ELEMENT
** SIZE TIMES THE NUMBER OF ELEMENTS, WHICH HOLDS THE DATA
** OF THE ARRAY. ALL FOUR TYPES OF ARRAYS ARE BUILT IN A
** SIMILAR FASHION, BUT VARY BASED ON THE NEEDS OF EACH TYPE.
** THE DIFFERENCES WILL BE EASY TO DISCERN ONCE WE DUMP
** A 2-DIMENSIONAL ARRAY.
*
** NOW WE CAN PUT A VALUE IN AN ELEMENT. THIS IS EASILY DONE VIA
** THE PUT81 MACRO:
*
         PUT81 #]WORD1;#$300;#5
         DUMP  #$300;#2
         DUMP  #$302;#10
         DUMP  #$30C;#10
         _PRN  " ",8D8D
         _WAIT
*
** TWO THINGS SHOULD BECOME APPARENT AFTER VIEWING THE
** CONTENTS OF THIS ARRAY, AND THESE EXTEND TO ALL TYPES
** OF ARRAYS: FIRST, AN ITEM IS COPIED TO THE ARRAY FROM
** ANOTHER MEMORY ADDRESS, AND THE NUMBER OF BYTES COPIED
** IS DETERMINED BY THE ELEMENT LENGTH OF THE ARRAY;
** SECOND, IT SEEMS AT FIRST AS THOUGH THE ELEMENT ALTERED
** IS AT INDEX 6 RATHER THAN 5, BUT THIS IS BECAUSE ARRAYS
** START AT ELEMENT 0. NOT ELEMENT 1. WHILE THERE WOULD NOT
** BE MUCH OF A PROBLEM TREATING ARRAYS AS STARTING AT
** ELEMENT 1, PROVIDED YOU ARE CAREFUL NOT TO OVERFLOW THE
** ARRAY, INDEXING MIGHT GET CONFUSING.
*
** NOW WE CAN GET BACK THE VALUE WE PLACED IN THE ARRAY
** WITH THE GET81 MACRO, AS SUCH:
*
         GET81 #$300;#5
         DUMP  #RETURN;RETLEN
         _WAIT
*
** NOTE HERE THAT THE VALUE IS PLACED IN #RETURN, AND ITS
** LENGTH IS PLACED IN RETLEN. THIS IS HOW ALL ARRAY GET
** MACROS WORK.
*
** NOW THAT WE HAVE ONE TYPE OF ARRAY DOWN, THE REST OF THEM
** ARE SIMPLE TO UNDERSTAND BECAUSE THEY ALL WORK THE SAME
** WAY. LET'S LOOK AT HOW TWO-DIMENSION ARRAYS ARE HANDLED AT
** THE 8-BIT LEVEL TO HAVE A MORE COMPLETE UNDERSTANDING BEFORE
** MOVING TO 16 BITS, HOWEVER. FIRST, WE INITIALIZE THE ARRAY:
*
         JSR   ]HOME2
         _PRN  "8-BIT, 2-DIMENSIONAL ARRAYS",8D
         _PRN  "---------------------------",8D8D8D
         DIM82 #$300;#5;#5;#1;#$AA
         DUMP  #$300;#3
         DUMP  #$303;#5
         DUMP  #$308;#5
         DUMP  #$30D;#5
         DUMP  #$312;#5
         DUMP  #$317;#5
         _WAIT
         _PRN  " ",8D8D
*
** AND NOW THAT WE HAVE DECLARED THE 2D, 8BIT ARRAY,
** ADDING A VALUE AND RETRIVING IT IS EASY:
*
         PUT82 #]WORD1;#$300;#3;#3
         GET82 #$300;#3;#3
         DUMP  #RETURN;RETLEN
         _WAIT
*
*
** IN THE ABOVE CODE, YOU CAN SEE THAT WE INITIALIZE
** THE 2-DIMENSIONAL ARRAY AT #$300, WHICH WRITES OVER
** THE PREVIOUS 1-DIMENSIONAL ARRAY. THERE ARE NO
** PROTECTIONS AGAINST THIS; YOU ARE EXPECTED TO KEEP
** TRACK OF THE LOCATIONS YOURSELF. AFTER THE ADDRESS,
** THE LENGTHS OF EACH DIMENSION ARE DECLARED (IN THIS
** CASE, 5 EACH), THEN THE LENGTH OF EACH ELEMENT IN
** THE ARRAY. FINALLY, THE DEFAULT VALUE, #$AA, IS
** PROVIDED. THE ARRAY IS THEN LISTED WITH THE DUMP
** COMMAND, 5 ELEMENTS AT A TIME.
*
** NOW ARMED WITH EXAMPLES OF 1 DIMENSIONAL AND TWO
** DIMENSIONAL ARRAYS, IT CAN BE EASILY INFERRED HOW
** THE REST OF THE MACROS WORK. THE ONLY REAL DIFFERENCE
** IS THAT 16-BIT ARRAYS USE TWO BYTES FOR THE NUMBER OF
** ELEMENTS IN EACH DIMENSION, RATHER THAN A SINGLE BYTE
** (THUS THE 16-BIT DESCRIPTION). THUS, WE CAN DECLARE
** A 16-BIT, 1-DIMENSIONAL ARRAY AS WELL AS PUT AND GET
** TO AND FROM IT AS SUCH:
*
         JSR   ]HOME2
         DIM161 #$300;#10;#1;#$55
         PUT161 #]WORD1;#$300;#3
         GET161 #$300;#3
         _PRN  "16-BIT, 1-DIMENSIONAL ARRAYS",8D
         _PRN  "============================",8D8D8D
         DUMP  #$300;#3
         DUMP  #$303;#10
         _PRN  " ",8D8D
         DUMP  #RETURN;RETLEN
         _WAIT
*
** AND AS YOU WOULD EXPECT, 16-BIT 2 DIMENSIONAL ARRAYS
** WORK IN MUCH THE SAME WAY:
*
         JSR   ]HOME2
         DIM162 #$300;#3;#3;#1;#$66
         PUT162 #]WORD1;#$300;#0;#0
         GET162 #$300;#0;#0
         _PRN  "16-BIT, 2-DIMENSIONAL ARRAYS",8D
         _PRN  "============================",8D8D8D
         DUMP  #$300;#5
         DUMP  #$305;#3
         DUMP  #$308;#3
         DUMP  #$30B;#3
         _PRN  " ",8D8D
         DUMP  #RETURN;RETLEN
         _WAIT
         JSR   ]HOME2
         _PRN  " ",8D8D
         _PRN  "FIN.",8D8D
*
         JMP   REENTRY
*
*``````````````````````````````*
* BOTTOM INCLUDES (ROUTINES)   *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
         PUT   MIN.LIB.REQUIRED.ASM
*
** INDIVIDUAL SUBROUTINE INCLUDES
*
** 8-BIT 1-DIMENSIONAL ARRAY SUBROUTINES
*
         PUT   MIN.SUB.ADIM81.ASM
         PUT   MIN.SUB.AGET81.ASM
         PUT   MIN.SUB.APUT81.ASM
*
** 8-BIT 2-DIMENSIONAL ARRAY SUBROUTINES
*
         PUT   MIN.SUB.ADIM82.ASM
         PUT   MIN.SUB.AGET82.ASM
         PUT   MIN.SUB.APUT82.ASM
*
** 16-BIT 1-DIMENSIONAL ARRAYS
*
         PUT   MIN.SUB.ADIM161.ASM
         PUT   MIN.SUB.APUT161.ASM
         PUT   MIN.SUB.AGET161.ASM
*
** 16-BIT 2-DIMENSIONAL ARRAYS
*
         PUT   MIN.SUB.ADIM162.ASM
         PUT   MIN.SUB.APUT162.ASM
         PUT   MIN.SUB.AGET162.ASM
*
** VARIABLES
*
]WORD1   HEX   FFFF
