From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16410 invoked by alias); 6 Mar 2010 04:16:41 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: X-Seq: 27773 Received: (qmail 15754 invoked from network); 6 Mar 2010 04:16:30 -0000 X-Spam-Checker-Version: SpamAssassin 3.2.5 (2008-06-10) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VERIFIED autolearn=ham version=3.2.5 Received-SPF: pass (ns1.primenet.com.au: SPF record at _spf.google.com designates 209.85.221.203 as permitted sender) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:from:to:cc:subject:date :message-id:x-mailer:in-reply-to:references; bh=HVm3WhuVYpxcNkPa6EbR78BV3g63JKNBERnBBYPn1f8=; b=UBfBHJDCPi/oSEDm0rOrges3kgYxudfUOxhx+F2jRTLnYHbkp3q2k5lMvyNK1shjdJ /Tm8JQg8X8thCKtGIgN9z7qL2HmYX5YxQwghdZSXIMftYv8Qoy5zSaBGpDZsBJ0BD0E2 4Z0r/iLGG6gPX5h8wVjSK++8cmF3SqEE4waok= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references; b=wKRGDCcwLGwnQ169a86k6Nvjyuw+D/IiQp0Lmiijucr+NRXRD4U1SomLOdkbrMrrAU V38TcVtZ43PL/5exjEHlY7klGhBEgh39u7wLdt6IDYToDyVFjBSS51M5A4OY7KoYXils 9nt0cypVUjuQy1lB2mbmIk0XqtXuqbDIWpm/E= From: Michael Hwang To: zsh-workers@zsh.org Cc: Michael Hwang Subject: [PATCH] Added LinkList documentation to linklist.c Date: Fri, 5 Mar 2010 22:48:48 -0500 Message-Id: <1267847328-9284-1-git-send-email-michael.a.hwang@gmail.com> X-Mailer: git-send-email 1.6.6.1 In-Reply-To: <201003011812.o21ICUCu026435@news01.csr.com> References: <201003011812.o21ICUCu026435@news01.csr.com> After getting an intimate look at LinkList, I've decided that I don't want to change it either. But I may as well add some documentation. I hope it's acceptable to have these ASCII drawings in the source code. Michael Hwang --- Src/linklist.c | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 70 insertions(+), 0 deletions(-) diff --git a/Src/linklist.c b/Src/linklist.c index b51d881..1e364fb 100644 --- a/Src/linklist.c +++ b/Src/linklist.c @@ -30,6 +30,72 @@ #include "zsh.mdh" #include "linklist.pro" +/* + * Anatomy of a LinkList + * + * LinkList with 4 nodes: + * + * LinkList is a first last flags (LinkList) + * union; see zsh.h next prev dat (LinkNode) + * +-------+------+------+ + * | | | | See comment in subst.c + * +------------> | | | | | | about LF_ARRAY. + * | +---|---+---|--+------+ + * | | | + * | +------------+ +--------------+ + * | | | + * | \|/ \|/ + * | +----+ +----+ +----+ +----+ + * | | | | | | | | \/ | X here is NULL. + * | | -------> | -------> | -------> | /\ | + * | |next| |next| |next| |next| + * | +----+ +----+ +----+ +----+ + * | | | | | | | | | + * +------ | <------- | <------- | <------- | + * |prev| |prev| |prev| |prev| + * +----+ +----+ +----+ +----+ + * | | | | | | | | Pointers to data, + * |dat | |dat | |dat | |dat | usually char **. + * +----+ +----+ +----+ +----+ + * LinkNode LinkNode LinkNode LinkNode + * + * + * Empty LinkList: + * first last flags + * +------+------+-------+ + * +---> | NULL | | 0 | + * | | | | | | + * | +------+---|--+-------+ + * | | + * +----------------+ + * + * Traversing a LinkList: + * Traversing forward through a list uses an iterator-style paradigm. + * for (LinkNode node = firstnode(list); node; incnode(node)) { + * // Access/manipulate the node using macros (see zsh.h) + * } + * + * Traversing backwards is the same, with a small caveat. + * for (LinkNode node = lastnode(list); node != &list->node; decnode(node)) { + * // The loop condition should be obvious given the above diagrams. + * } + * + * If you're going to be moving back and forth, best to AND both + * conditions. + * + * while (node && node != &list->node) { + * // If both incnode(list) and decnode(list) are used, and it's + * // unknown at which end of the list traversal will stop. + * } + * + * Macros and functions prefixed with 'z' (ie znewlinklist, + * zinsertlinknode) use permanent allocation, which you have to free + * manually (with freelinklist(), maybe?). Non-z-prefixed + * macros/functions allocate from heap, which will be automatically + * freed. + * + */ + /* Get an empty linked list header */ /**/ @@ -240,6 +306,8 @@ countlinknodes(LinkList list) return ct; } +/* Make specified node first, moving preceding nodes to end */ + /**/ mod_export void rolllist(LinkList l, LinkNode nd) @@ -252,6 +320,8 @@ rolllist(LinkList l, LinkNode nd) l->list.last->next = 0; } +/* Create linklist of specified size. node->dats are not initialized. */ + /**/ mod_export LinkList newsizedlist(int size) -- 1.6.6.1