📄 swarm.collections.sgml.reference.html
字号:
<HTML><HEAD><TITLE>Collections Library</TITLE><METANAME="GENERATOR"CONTENT="Modular DocBook HTML Stylesheet Version 1.53"><LINKREL="HOME"TITLE="Documentation Set for Swarm 2.1.1"HREF="set.html"><LINKREL="UP"TITLE="Reference Guide for Swarm 2.1.1"HREF="book930.html"><LINKREL="PREVIOUS"TITLE="General"HREF="swarm.defobj.generic.module.html"><LINKREL="NEXT"TITLE="ArchiverArray"HREF="swarm.collections.archiverarray.protocol.html"></HEAD><BODYCLASS="REFERENCE"BGCOLOR="#FFFFFF"TEXT="#000000"LINK="#0000FF"VLINK="#840084"ALINK="#0000FF"><DIVCLASS="NAVHEADER"><TABLEWIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><THCOLSPAN="3"ALIGN="center">Documentation Set for Swarm 2.1.1</TH></TR><TR><TDWIDTH="10%"ALIGN="left"VALIGN="bottom"><AHREF="swarm.defobj.generic.module.html">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="swarm.collections.archiverarray.protocol.html">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><DIVCLASS="REFERENCE"><ANAME="SWARM.COLLECTIONS.SGML.REFERENCE"></A><DIVCLASS="TITLEPAGE"><H1CLASS="TITLE">II. Collections Library</H1><DIVCLASS="PARTINTRO"><ANAME="AEN5735"></A><TABLECLASS="SIDEBAR"BORDER="1"CELLPADDING="5"><TR><TD><DIVCLASS="SIDEBAR"><P><B>Overview</B></P><P>The object types of the collections library establish a general-purpose foundation to maintain object references or other values as members of structured collections. Customization options consolidate a wide range of basic collection structures into a few core types (Array, List, Set, Map). These types are defined strictly by their interface, not their internal implementation. Specialized options, however, give control and flexibility for efficient, low-level use (such as implementing other libraries).</P></DIV></TD></TR></TABLE><DIVCLASS="SECT1"><H1CLASS="SECT1"><ANAME="SWARM.COLLECTIONS.SGML.SECT1.DEPEND">1. Dependencies</A></H1><P>Following are the other header files imported by <collections.h>:</P><TABLEBORDER="0"BGCOLOR="#E0E0E0"WIDTH="100%"><TR><TD><PRECLASS="PROGRAMLISTING">#import <defobj.h></PRE></TD></TR></TABLE><P>The collections library follows the <AHREF="swarm.library.sgml.appendix.html">library interface conventions</A> of the <AHREF="swarm.defobj.sgml.reference.html">defobj library</A>. It also depends on standard supertypes and classes defined by this library. Initialization of the collections library automatically initializes the defobj library as well. Since defobj also requires the collections library, both must always be linked into an application together.</P></DIV><DIVCLASS="SECT1"><H1CLASS="SECT1"><ANAME="SWARM.COLLECTIONS.SGML.SECT1.COMPAT">2. Compatibility</A></H1><P>No explicit incompatibilites for particular versions of Swarm</P></DIV><DIVCLASS="SECT1"><H1CLASS="SECT1"><ANAME="SWARM.COLLECTIONS.SGML.SECT1.USAGE">3. Usage Guide</A></H1><P>This section of documentation is not yet available. In the meantime, see the <AHREF="swarm.grid.sgml.appendix.html">GridTurtle test programs</A> for the most complete examples of collections library usage. If you can't find an example there that exercises a message or option that you want to use, chances are it's not implemented.</P></DIV><DIVCLASS="SECT1"><H1CLASS="SECT1"><ANAME="SWARM.COLLECTIONS.SGML.SECT1.ADVUSAGE">4. Advanced Usage Guide</A></H1><P>Unavailable</P></DIV><DIVCLASS="SECT1"><H1CLASS="SECT1"><ANAME="SWARM.COLLECTIONS.SGML.SECT1.SUBCLASS">5. Subclassing Reference</A></H1><P>Until the collections library has been fully implemented, subclassing conventions from collections implementation classes are still in flux. In general, these classes will be among the most complex uses of multiple classes selected to implement an independent object type. (See <AHREF="swarm.library.sgml.appendix.html">library definition conventions</A> for a summary of the distinction between types and classes.) New methods are being developed to simplify subclassing from such implementations. In the meantime, if you need to use to a collection within the implementation of your own class, just put an instance variable in your class and put the collection in that, and pass through the messages of the collection you want to have available on your class to this variable. In many if not most cases, this is better design anyway, because you control all use of the underlying structure.</P></DIV><DIVCLASS="SECT1"><H1CLASS="SECT1"><ANAME="SWARM.COLLECTIONS.SGML.SECT1.DESIGN">6. Interface Design Notes</A></H1><P>A collections library is one of the most important foundation services for object-oriented programming. Most object-oriented systems provide at least the start of a general-purpose collections library. The GNUSTEP, project, for example, provides the libobject library (currently in alpha test at <AHREF="ftp://alpha.prep.ai.mit.edu/"TARGET="_top"></A>) which includes a collections library along with other services intended to parallel those of the OpenStep framework developed by Next.</P><P>Swarm has implemented its own collection library to meet the specialized needs of its agent simulation framework. </P></DIV><DIVCLASS="SECT1"><H1CLASS="SECT1"><ANAME="SWARM.COLLECTIONS.SGML.SECT1.IMPL">7. Implementation Notes</A></H1><P>Unavailable</P></DIV></DIV><DIVCLASS="TOC"><DL><DT><B>Table of Contents</B></DT><DT><AHREF="swarm.collections.archiverarray.protocol.html">ArchiverArray</A> — Array encapsulation for serialization.</DT><DT><AHREF="swarm.collections.archiverkeyword.protocol.html">ArchiverKeyword</A> — Keyword encapsulation for serialization.</DT><DT><AHREF="swarm.collections.archiverlist.protocol.html">ArchiverList</A> — Archiver list encapsulation for serialization.</DT><DT><AHREF="swarm.collections.archiverpair.protocol.html">ArchiverPair</A> — List pair encapsulation for serialization.</DT><DT><AHREF="swarm.collections.archiverquoted.protocol.html">ArchiverQuoted</A> — Archiver serialization object for (quote x) or 'x</DT><DT><AHREF="swarm.collections.archivervalue.protocol.html">ArchiverValue</A> — Value encapsulation for serialization.</DT><DT><AHREF="swarm.collections.array.protocol.html">Array</A> — Collection supporting access only by relative position.</DT><DT><AHREF="swarm.collections.collection.protocol.html">Collection</A> — A generic collection interface.</DT><DT><AHREF="swarm.collections.comparefunction.protocol.html">CompareFunction</A> — Interface for defining the compare function to use when comparing to members in a collection.</DT><DT><AHREF="swarm.collections.defaultmember.protocol.html">DefaultMember</A> — Methods for setting and getting the default member in a collection.</DT><DT><AHREF="swarm.collections.foreach.protocol.html">ForEach</A> — Messages for performing the same message on objects in a collection.</DT><DT><AHREF="swarm.collections.foreachkey.protocol.html">ForEachKey</A> — Exactly the same as the ForEach protocol, but only for KeyedCollections.</DT><DT><AHREF="swarm.collections.index.protocol.html">Index</A> — Reference into the enumeration sequence for a collection.</DT><DT><AHREF="swarm.collections.inputstream.protocol.html">InputStream</A> — Stream of input data.</DT><DT><AHREF="swarm.collections.keyedcollection.protocol.html">KeyedCollection</A> — Member identity definition shared by Set and Map types.</DT><DT><AHREF="swarm.collections.keyedcollectionindex.protocol.html">KeyedCollectionIndex</A> — Index behavior shared by Set and Map types.</DT><DT><AHREF="swarm.collections.list.protocol.html">List</A> — Collection of members in an externally assigned linear sequence.</DT><DT><AHREF="swarm.collections.listindex.protocol.html">ListIndex</A> — Index with insertion capability at any point in list.</DT><DT><AHREF="swarm.collections.listshuffler.protocol.html">ListShuffler</A> — A class to randomize the order of a given Swarm List</DT><DT><AHREF="swarm.collections.map.protocol.html">Map</A> — Collection of associations from key objects to member objects.</DT><DT><AHREF="swarm.collections.mapindex.protocol.html">MapIndex</A> — The index behavior for a Map.</DT><DT><AHREF="swarm.collections.memberblock.protocol.html">MemberBlock</A> — A way to wrap an existing C array for access as an object collection.</DT><DT><AHREF="swarm.collections.memberslot.protocol.html">MemberSlot</A> — Allocation in member/key for fast setMember:/setKey:</DT><DT><AHREF="swarm.collections.offsets.protocol.html">Offsets</A> — Methods for accessing collection members by position.</DT><DT><AHREF="swarm.collections.orderedset.protocol.html">OrderedSet</A> — A set of members in an externally assigned linear sequence.</DT><DT><AHREF="swarm.collections.outputstream.protocol.html">OutputStream</A> — Stream of output bytes.</DT><DT><AHREF="swarm.collections.permutation.protocol.html">Permutation</A> — A class that represents a permutation of elements of a collection</DT><DT><AHREF="swarm.collections.permutationitem.protocol.html">PermutationItem</A> — An element of a Permutation</DT><DT><AHREF="swarm.collections.permutedindex.protocol.html">PermutedIndex</A> — General PermutedIndex class. </DT><DT><AHREF="swarm.collections.set.protocol.html">Set</A> — Collection of members each having a defined identity.</DT><DT><AHREF="swarm.collections.string.protocol.html">String</A> — Character string object (later to support collection behavior).</DT><DT><AHREF="swarm.collections.generic.module.html">General</A> — Standard collection types</DT></DL></DIV></DIV><DIVCLASS="TITLEPAGE"><DIVCLASS="ABSTRACT"><P><B>Documentation and Implementation Status</B></P><P>The collections library has an almost complete set of Interface Reference documents, and the design of the interface is almost entirely final. The implementation of the collections library, however, doesn't yet implement many of the more advanced features of this interface.</P><P>Collections library development has concentrated on the specific features needed by the activity library. This library uses collections for its underlying support of actions to be executed in schedules. The collections library itself is still being completed for use as a general-purpose library.</P><P>The Array and List types have all basic capability fully implemented. Set and Map have basic messages defined, but currently rely on a crude implementation based on sorted lists. (This implementation is more than adequate for the usually small and relatively static schedule structures in the activity library, and is the most forgiving when change does take place within members being traversed.) Much more efficient implementations based on both balanced trees and hash tables are in the works.</P><P>OrderedSet is currently supported only with the low-level option for an internal member slot, and the implemented messages do not match the ones documented in the Interface Reference. Support for groups of duplicate members is missing from both Set and Map.</P><P>None of the special options for restricted usage modes on any type of collection (e.g., read-only restriction) has been implemented. Stack and Queue are not implemented, but are nothing more than restricted uses of a List. There is no support for any member type except id or smaller (other member types will depend on a data type facility to be supplied by defobj).</P><P>Even though incomplete, the portion of capability that is implemented has been exercised very heavily. The interfaces to Set and Map structures will remain the same even as their underlying implementations improve, so there is no harm in using them. See the <AHREF="swarm.grid.sgml.appendix.html">GridTurtle test programs</A> for the most complete examples of collections usage.</P><P>The collections library follows the documentation structure suggested by the <AHREF="swarm.defobj.sgml.reference.html">library interface conventions</A> of the defobj library. There are placeholders at least for each section of documentation (some of which merely indicate that the section is not available yet) so that all links should at least link up with something, whether or not there's anything there.</P><P>Throughout the documentation, a parenthesized comment that starts with (.. indicates an editorial comment on the current status of implementation or documentation.</P><P>The documentation priority for all libraries is to complete at least their interface reference documents, so that there is the equivalent of Unix "man pages" that summarize all basic capability. A second priority is to complete the complementary "Usage Guide" documents. Unlike the reference documents, the Usage Guide will have a task-oriented organization, and will lead the initial user through actual code examples in the rough order a typical user is likely to need them. It will serve the role of a tutorial on each library.</P><P>The Usage Guide code examples have not yet been developed. For the time being, a directory of test programs (<AHREF="swarm.grid.sgml.appendix.html">GridTurtle test programs</A>, contained within the documentation release directory) provides code examples of many of the basic features of the defobj, collections, and activity libraries. These code examples also help indicate the portions of the libraries which are fully implemented and working, since they are run on each new release of these libraries.</P></DIV><AHREF="swarm.collections.generic.revhistory.html">Revision History (collections)</A></DIV></DIV><DIVCLASS="NAVFOOTER"><HRALIGN="LEFT"WIDTH="100%"><TABLEWIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top"><AHREF="swarm.defobj.generic.module.html">Prev</A></TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="set.html">Home</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top"><AHREF="swarm.collections.archiverarray.protocol.html">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top">General</TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="book930.html">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top">ArchiverArray</TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -