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