Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!mnetor!uunet!seismo!ut-sally!husc6!rutgers!sri-spam!mordor!lll-tis!ptsfa!ihnp4!inuxc!iuvax!pur-ee!uiucdcs!uxc.cso.uiuc.edu!hamilton From: hamilton@uxc.cso.uiuc.edu Newsgroups: comp.sys.amiga Subject: Re: What is clist.library? Message-ID: <172200085@uxc.cso.uiuc.edu> Date: Sun, 26-Jul-87 17:36:00 EDT Article-I.D.: uxc.172200085 Posted: Sun Jul 26 17:36:00 1987 Date-Received: Tue, 28-Jul-87 04:51:55 EDT References: <18102@cca.CCA.COM> Lines: 128 Nf-ID: #R:cca.CCA.COM:18102:uxc.cso.uiuc.edu:172200085:000:5729 Nf-From: uxc.cso.uiuc.edu!hamilton Jul 26 16:36:00 1987 ewhac@well says: > In article <18102@cca.CCA.COM> bryan@cca.CCA.COM (Bryan Pendleton) writes: > > 1) Does anyone use the clist.library? Is it possible? What is it for? > > Is there any doc. on it other than the function call descriptions > > in the Libraries and Devices manual. These entries do a reasonable > > job of explaining what and how, but not why. Also, a couple of > > examples would help! > > > I asked -=RJ=- about this at the Commodore Show early this year. > Apparently, it's a set of (debugged) string manipulation routines, similar > to string operations you might find in LISP (-=RJ=-'s words). A scan of > available Amiga software some months back revealed that *nobody* uses that > library. If and when 1.3 comes out, the clist.library will probably be > pulled out of the ROM and tossed onto the WorkBench disk. the clist.library functions are VERY similar to Unix's c-list (tty character buffer) routines. clist.library goes much farther. a couple months ago, i posted a cheap example of clist use in a term program i was playing with long ago, when i was worried about serial input overrun. i haven't used clists for anything else, but they are kinda cute. in a nutshell, the clist package provides management of character buffers and manipulation of their contents. you might think of it as a sort of "stdio" for in-ram files. perfect for byte streams between tasks or asynchronous parts of a single task. for instance, in my term program, when a serial input io request completed, i added the io buffer onto a clist and started a new serial input. when a console output io request completed, i emptied the clist to the console io buffer and restarted console output. this allowed serial input to (temporarily) outrun console output. first, you set aside a block of memory for buffers and headers; you need to initialize this memory (the "clist pool") with: (bool) InitCLPool (a0:cLPool,d0:size) where 'cLPool' is a pointer to the memory, and 'size' the size in bytes. zero return means OK, -1 means error ('size' too small). the pool will contain 1 pool header (12? bytes), 0 or more clist headers (@32 bytes), and 0 or more buffers (@32 bytes). next, you need to "open" a clist within the pool: (cList) AllocCList (a1:cLPool) the longword returned is analogous to a file handle. a value of -1 means a clist could not be allocated within 'cLPool' (out of memory). when you are finished with a clist: FreeCList (a0:cList) just like "close". if there are still some buffers allocated to the clist, they will be "flushed" (made available for re-allocation to other clists) for you. you can do this explicitly with: FlushCList (a0:cList) this returns the clist to its initial empty state. to put things into the clist: (long) PutCLChar (a0:cList,d0:byte) put 1 byte (long) PutCLWord (a0:cList,d0:word) put 2 bytes (long) PutCLBuf (a0:cList,a1:buffer,d1:length) put 'length' bytes the value returned is zero for OK, or the number of bytes that could not be added (due to lack of space). PutCLWord won't put partial words. analogous to stdio putc(), putw(), and fputs(). you can un-put the data with: (char) UnPutCLChar (a0:cList) (short) UnPutCLWord (a0:cList) these take data out of the "back" end of the clist. if the clist is empty, they return longword -1. to get data back out: (char) GetCLChar (a0:cList) (short) GetCLWord (a0:cList) (long) GetCLBuf (a0:cList,a1:buffer,d1:maxLength) like getc(), getw(), and fgets(). GetCLChar and GetCLWord return the actual data; if the clist is empty, they return a longword -1. GetCLBuf returns the actual length of the string extracted (<= MaxLength). you can un-get data too: (long) UnGetCLChar (a0:cList,d0:byte) (long) UnGetCLWord (a0:cList,d0:word) these will put data back onto the "front" of the clist. nonzero return means there isn't room. +------------------+ Get* <- | | <- Put* | front back | UnGet* -> | | -> UnPut* +------------------+ Get*'s + Put*'s give you a FIFO queue; Get*'s + UnGet*'s or Put*'s + UnPut*'s give you a LIFO; all of them together give you a double-ended queue. to find out how much data you have in a clist: (long) SizeCList (a0:cList) the result is the number of bytes buffered. you can duplicate a clist with: (clist) CopyCList (a0:cList) this is like a combination of AllocCList/GetCLBuf/PutCLBuf. you can copy part of one clist to a new one: (clist) SubCList (a0:cList,d0:index,d1:length) 'offset' is the start offset, and 'length' is the number of bytes to copy. you can move the contents of one clist onto the end of another: (long) ConcatCList (a0:sourceCList,a1:destCList) 'sourceCList' gets emptied. nonzero return means an error (out of memory) occurred. you can access the interior of a clist as well as the ends: (long) MarkCList (a0:cList,d0:offset) (long) IncrCLMark (a0:cList) (char) PeekCLMark (a0:cList) (clist) SplitCList (a0:cList) "Mark" simply remembers which byte 'offset' points at; "Incr" increments the remembered value. nonzero return means 'offset' was invalid (out of range). "Peek" returns the byte at the mark. "Split" creates a new clist, ans splits the old clist at the mark. the head of the old clist remains unchanged; the tail, starting at the mark, is moved to the new clist. the result will be longword -1 if it fails. wayne hamilton U of Il and US Army Corps of Engineers CERL UUCP: {ihnp4,seismo,pur-ee,convex}!uiucuxc!hamilton ARPA: hamilton@uxc.cso.uiuc.edu USMail: Box 476, Urbana, IL 61801 CSNET: hamilton%uxc@uiuc.csnet Phone: (217)333-8703 CIS: [73047,544] PLink: w hamilton