====================================================================== Documentation for module "Rows" Author: Nicolas Benezan, Postwiesenstr. 2, 7000 Stuttgart 60, Germany supported by Michael Frie฿ [mif] (thanks !!!) ====================================================================== Copyright remarks ญญญญญญญญญญญญญญญญญ (C) Copyright 1988 by Nicolas Benezan. All rights reserved. The whole package (source, documentation and code) is donated to public domain and may be copied and redistributed providing that... * my name and this copyright remark and * the completeness of the package remain intact, * it's distributet for non-profit only. Commercial use without my explicit, written permission is not allowed. Contact me to get it and, perhaps, to pay some fee. Improvements and new ideas are welcome, as long as the changes are well documented inline and in the documentation files. I would like to know, if you make major changes and repost it. Contents ญญญญญญญญ * Package * Introduction * Generic Data Types * New Data Type "Row" * Row-Operators * Test module Package ญญญญญญญ The whole package "Rows" consist of following files: Rows.doc This documentation file Rows.dok German documentation Rows.def Definition module Rows.mod Implementation module Rows.sym Symbol file Rows.obj Compiled object code RowDemo.mod Test module RowDemo.obj Compiled test module RowDemo Executable test module Introduction ญญญญญญญญญญญญ Often, you need basic data structures and operations on them, which are not implemented in Modula-II. However, Modula-II supports development of generic data types. The best known example of generic data type is "File". You can import "File" and procedures operating on it from system module "FileSystem". The one thing, you have to know, is the abstract concept of files, not the implementation. This module offers a generic type "Row". Generic Data Types ญญญญญญญญญญญญญญญญญญ In Modula-II (as well as in most other high-level languages) you can create new types by declaration. New types can consist of structures and components, but every component type has to be known before declaration of the new type (either by declaration or as an simple data type - for example BOOLEAN). Modula-II knows four structure methods for building new types: ARRAY, SET, RECORD and POINTER. With last one you can create a large scale of new types. For example a list: TYPE listptr = POINTER TO list; list = RECORD item : T0; next : listptr END; To use this list you develop some procedures for initialization, insert an item, read an item and so on. All procedures are independent of your component type T0, but your type "list" depends on it. A generic data type now can be used with ANY (!) component type! The concept of Modula-II supports development of modules that present data capsules exporting a generic type and procedures working on it. But this support is not perfect, you have to avoid type checking of parameters. Only the size of parameters is checked. Data can have equal or smaller (think of string constants) size than the size declared by Dim(). If you want to know more about principles of generic data types and data capsules, you should refer to the module "List" and documentation by Michael Frie฿ [mif] ("List" and some other generic data types are included in the AmokLib and Amok-PD-Disk #7). New Data Type "Row" ญญญญญญญญญญญญญญญญญญญ "Row" is a data type somwhere in between ARRAYs and dynamically linked lists [1]. ARRAYs are declared statically, this means, their size and the size of each component has to be known before compiling. Lists (components linked by pointers) are fully dynamic. Your programm can insert and remove components while running and the list grows and shrinks in memory. Rowss are a sort of compromise. They are declared at run time, so their component and total size needn't be known before compiling. But once they are there, they can't change size. On the one hand, this is a disadvantage but on the other hand you have random access to any components of a Row and don't have to scan the list sequentially. The components of a Row are referenced by index (like ARRAYs) and not by pointers (like lists). If you have to access completely different parts of the data very often, your code will execute much faster using Rows than using lists. Row-Operators ญญญญญญญญญญญญญ In following operators and their abstract intention are listed. You can find more details in definition module. * Dim() Declares and initialize a new Row for further use. * Discard() Discard a Row, i.e. all elements and the Row itself, and deallocates memory. * Write() Copies data TO an element of a Row (the corresponding ARRAY-assignment would be Array[index]:=Data) * Read() Copies data FROM an element of a Row (the corresponding ARRAY-assignment would be Data:=Array[index]) * High() and CompSize() If you have Procedures which have Rows as parameters you might wish something like HIGH() for ARRAYs to handle Rows of different size. You can find out the maximum index of a Row with High() and its component size with CompSize(). * Import() and Export() These Procedures help you to Read/Write Rows from/to disk-(or other Dos-) files. They provide an interface to the data buffer of a Row in memory. But be careful ! You are responsible to do correct size and compatiblity checking. Because of the restrictions of Modula-2 the Module Rows can't do it for you. If you want to know more about procedures listed above and the meaning of their parameters, please refer to the definition module. Test module ญญญญญญญญญญญ The module "RowDemo" tests and demonstrates Rows and their usage. It Dim()s a Row with a random number of elements, then it fills the Row with random numbers and finally it sorts the numbers. I used the well known "HeapSort" algorithm in which I only changed ":="-assignments into Read()/Write()-statements (because of Rows). If you watch the free memory display of the workbench while running RowDemo you'll see that Rows consume more or less memory depending on their size. (Note: I don't want to demonstrate speed of HeapSort but the usage of Rows. So do not complain about its speed. I know it could be faster.)