libs-base/Documentation/libobjects.texi

\input texinfo @c -*-texinfo-*-

@c %**start of header
@settitle User's Guide to the GNU Objective-C Class Library
@setfilename libobjects.info
@c %**end of header
@defcodeindex cl
@defcodeindex pr
@ignore
I'm using cindex for concepts, findex for methods, functions and macros,
prindex for protocols, and clindex for classes.
@end ignore

@ifinfo
@format
START-INFO-DIR-ENTRY
* Libobjects::                      The GNU Objective C Class Library.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@c set the vars LIBOBJECTS_VERSION and GCC_VERSION
@include version.texi

@ifinfo
This file documents the features and implementation of The GNU
Objective-C class library.

Copyright (C) 1993 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through @TeX{} and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU Library General Public License'' is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU Library General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.
@end ifinfo

@iftex
@finalout
@c @smallbook
@c @cropmarks
@end iftex

@setchapternewpage odd

@titlepage
@title User's Guide to the
@title GNU Objective C Class Library
@sp 3
@c @subtitle last updated Oct 26, 1993
@subtitle Version @value{OBJECTS_VERSION}
@subtitle (for use with @samp{gcc} version @value{GCC_VERSION})
@author R. Andrew McCallum (mccallum@@gnu.ai.mit.edu)
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993 Free Software Foundation, Inc.


Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU Library General Public License'' is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU Library General Public License'' may be
included in a translation approved by the author instead of in the original
English.

@strong{Note: The GNU Objective-C library is still in alpha release. You will
be performing a valuable service if you report any bugs you encounter.}

@end titlepage

@ignore
saved copy
* Copying::	    GNU Library Public License says how you can copy
                    and share libobjects.
* Contributors::    People who have contributed to libobjects.
* Installation::    How to configure, compile and install libobjects.
* Trouble::         If you have trouble installing libobjects.

* Overview::        libobjects in brief.
* Organization::    The heirarchy of protocols and classes.
* Conventions::     Stylistic conventions and design philosophy.
* Content Types::   Collections can contain C types as well as objects.

* Creating::        Creating a collection.
* Freeing::         Freeing a collection or its elements.
* Adding::          Adding elements to a collection.
* Removing::        Removing elements from a collection.
* Replacing::       Replacing elements in a collection.
* Enumerating::     Performing an operation with all elements.
* Duplicating::     Making a copy of a collection.
* Archiving::       Writing (and reading) a collection to (from) a file.
* Querying::        Asking questions about a collection and its contents.
* Sorting::         Sorting the contents of a collection.

* Classes::         Choosing the class with the features you need.

* Projects::	    To do list and questions for users.

* Protocol Index::  
* Class Index::
* Method Function Macro Index::
* Concept Index::
@end ignore

@ifinfo
@node Top, Copying, , (DIR)
@top Libobjects

This manual documents how to install and use the GNU Objective-C
Class Library (or @samp{libobjects}), version
@value{LIBOBJECTS_VERSION}, for use with @samp{gcc} version
@value{GCC_VERSION}.

It is nothing but a skeleton now, mostly containing rough notes.
In the future it will be fleshed out and the text will be polished.

@end ifinfo
@menu
* Copying::	    GNU Library Public License says how you can copy
                    and share libobjects.
* Contributors::    People who have contributed to libobjects.
* Installation::    How to configure, compile and install libobjects.
* Trouble::         If you have trouble installing libobjects.

* Overview::        libobjects in brief.
* Organization::    The heirarchy of protocols and classes.
* Conventions::     Stylistic conventions and design philosophy.
* Content Types::   Collections can contain C types as well as objects.

* Creating::        Creating a collection.
* Freeing::         Freeing a collection or its elements.
* Adding::          Adding elements to a collection.
* Removing::        Removing elements from a collection.
* Replacing::       Replacing elements in a collection.
* Enumerating::     Performing an operation with all elements.
* Duplicating::     Making a copy of a collection.
* Archiving::       Writing (and reading) a collection to (from) a file.
* Querying::        Asking questions about a collection and its contents.
* Sorting::         Sorting the contents of a collection.

* Classes::         Choosing the class with the features you need.

* Projects::	    To do list and questions for users.

* Protocol Index::  
* Class Index::
* Method Function Macro Index::
* Concept Index::

@end menu

@node Copying, Contributors, Top, Top
@unnumbered Copying

See the file @samp{COPYING.LIB}.

@node Contributors, Installation, Copying, Top
@unnumbered Contributors to GNU Objective-C Collection library

@itemize @bullet
@item
Andrew McCallum <mccallum@@gnu.ai.mit.edu> designed the protocol and
class heirarchies, and wrote the otherwise unattributed classes.

@item
Kresten Krab Thorup <Kresten_Thorup@@NeXT.COM> made libobjects possible by
writing the GNU Objective-C runtime.  He also contributed the GapArray
and Storage classes.  He also wrote patches to texinfo that make
@code{deftypemethod} possible.

@item Adam Fedor <fedor@@boulder.colorado.edu> wrote the NXStringTable
class. 

@item 
Paul Kunz <Paul_Kunz@@slac.stanford.edu> did a lot to fix the List
class. 

@item 
Kresten Krab Thorup <krab@@iesd.auc.dk>, Paul Burchard
<burchard@@geom.umn.edu>, Paul Kunz <Paul_Kunz@@slac.stanford.edu>,
Geoffery Knauth <gsk@@marble.com>, Steve Naroff <snaroff@@next.com>,
Richard Stallman <rms@@gnu.ai.mit.edu> and others contributed to
discussions about the library.

@end itemize

@node Installation, Trouble, Contributors, Top
@chapter Installing GNU Objective-C Class Library

@include install.texi


@node Trouble, Overview, Installation, Top
@chapter Trouble in Installation

Try to fix the problem.  Send patches to mccallum@@gnu.ai.mit.edu.

<<This section incomplete>>


@node Overview, Organization, Trouble, Top
@chapter Overview

The GNU classes included in this version of the library fall into five
categories: collections, magnitudes, streams, coders and remote
messaging support.

@c There are several GNU protocols also.  You can recognize the protocols
@c by their name: they all end with ``ing''.

@itemize

@item The collection objects all conform to the @samp{Collecting}
protocol.  Reading @samp{./objects/Collecting.h} is a good place to
start.  Protocols for collections that store their contents with keys
and with indices can be found in @samp{./objects/KeyedCollecting.h} and
@samp{./objects/IndexedCollecting.h} respectively.  Examples of generic
collections are @samp{Set} and @samp{Bag}.  The keyed collections are
@samp{Dictionary} and @samp{MappedCollector}.  The classes @samp{Array},
@samp{Queue}, @samp{GapArray}, @samp{LinkedList}, @samp{BinaryTree},
@samp{RBTree} and @samp{SplayTree} are all indexed collections.

@item The useful magnitude classes are @samp{Time} and @samp{Random}.
The @samp{Random} class works in conjunction with pseudo-random number
generators that conform to the @samp{RandomGenerating} protocol.  The
conforming class @samp{RNGBerkeley} provides identical behavior to the
BSD random() function.  The class @samp{RNGAdditiveCongruential} is an
implementation of the additive congruential method.

@item Stream objects provide a consistent interface for reading and
writing bytes.  Read @samp{./objects/Stream.h} to get the general idea.
@samp{StdioStream} objects work with files, file descriptors, FILE
pointers and pipes to executables.  @samp{MemoryStream} objects work
with memory buffers.

@item Coders provide a formatted way of writing to Streams.  After a
coder is initialized with a stream, the coder can encode/decode
Objective C objects and C types.  See @samp{./objects/Coder.h} for the
abstract superclass interface; see @samp{./objects/Coding.h} for the
protocol adopted by objects that read and write themselves using coders.
The currently available concrete coders are @samp{BinaryCoder}, for
reading and writing a compact stream of illegible bytes, and
@samp{TextCoder}, for reading and writing human-readable text.

Coders and streams can be mixed and matched so that programmers can
choose the destination and the format separately.

Neither the stream or coder class heirarchies are very mature yet.  I
threw them together because I needed them for remote object messaging.

@item The remote object messaging support classes are @samp{Connection},
@samp{Proxy}, @samp{ConnectedCoder}, @samp{Port} and @samp{SocketPort}.

@end itemize

@node Organization, Conventions, Overview, Top
@chapter Organization

The library is built around several protocols:

@itemize

@item
The <Collecting> protocol is root of the collection protocol heirarchy. 
The <Collecting> protocol defines the most general interface to a
collection of elements.  Elements can be added, removed, and replaced.
The contents can be tested, enumerated, and enumerated through various
filters.  Elements may be objects, or any C type included in the 
"elt" union given in elt.h, but all elements of a collection must be of
the same C type.
(For examples see Set and Bag.)

@item
The <KeyedCollecting> protocol inherits from the <Collecting> protocol.
The <KeyedCollecting> protocol defines the interface to a
collection of elements that are accessible by a key, where the key is
some unique element.  Pairs of (key element, content element) may be
added, removed and replaced.  The keys and contents may be tested,
enumerated, and copied.  
(For examples see Dictionary and MappedCollector.)

@item
The <IndexedCollecting> protocol inherits from the 
<KeyedCollecting> protocol.
The <IndexedCollecting> protocol defines the interface to a
collection of elements that are accessible by a key that is an index,
where the indeces in a collection are a contiguous series of unsigned
integers beginning at 0.  This is the root of the protocol heirarchy
for all collections that hold their elements in some order.  Elements
may be accessed, inserted, replaced and removed by their index.  
(For examples see Array and LinkedList.)

@item
The <LinkedListComprising> protocol defines the interface to an object
that may be an element in a LinkedList.  LinkedList is a collection
object based on a doubly linked list.
(For an example see LinkedListNode.)

@item
The <BinaryTreeComprising> protocol defines the interface to an object
that may be an element in a BinaryTree.  BinaryTree is a collection
object based on a binary trees.
(For an example see BinaryTreeNode.)

@end itemize

Here is the object inheritance heirarchy.  All collection abtract
superclasses (classes which are not usable without subclassing) end
with "Collection"; all protocols end with "ing"; all collection
protocols end with "Collecting".

@smallexample
        Collection <Collecting>
            Set
                Bag
            KeyedCollection <KeyedCollecting>
                Dictionary
                MappedCollector
                IndexedCollection <IndexedCollecting>
                    Array
                        Stack
                        GapArray
                        CircularArray
                            Queue
                        Heap
                    LinkedList
                    BinaryTree
                    RBTree
                    EltNodeCollector
                    String
         DelegatePool
         LinkedListNode
             LinkedListEltNode
         BinaryTreeNode
             BinaryTreeEltNode
         RBTreeNode
             RBTreeEltNode
         Stream
             StdioStream
             MemoryStream
         Coder
             TextCoder
             BinaryCoder
                 ConnectedCoder
         Port <Coding>
             SocketPort
         Connection
         Proxy <Coding>
         Magnitude
             Time
         Random
         RNGBerkeley <RandomGenerating>
         RNGAdditiveCongruential <RandomGenerating>
@end smallexample

<<This section unfinished.>>


@node Conventions, Content Types, Organization, Top
@chapter Stylistic Conventions and Design Philosophy

@section Stylistic Conventions

@itemize @bullet

@item
Objective-C source files have file extension @file{.m}. Both
C-compatibility header files and class declaration files have extension
@file{.h}.

@item
Objective-C class names begin with capital letters.  Multi-word class
names capitalize each word, with no underscore separation.

@item 
Include files that define Objective-C classes begin with capital letters
(as do the names of the classes themselves). 

@item
All protocols end with @code{ing}.  All collection protocols end with
@code{Collecting}.  All collection abtract superclasses (classes which
are not usable without subclassing) end with @code{Collection}.

@item 
Include files that supply function prototypes for other C
functions are all lower case.

@item
Instance variables begin with an underscore, are all lower case, and
have underscores separating their component words.  The leading
underscore distinguishes them from local varibles defined inside
methods.

@item 
All include files define a preprocessor variable __X_h_INCLUDE_GNU,
where X is the name of the file, and conditionally compile only if this
has not been already defined. 

@item
The following macros and variables make the relevant version numbers
available: 

@defmac COLL_VERSION
The version number of the collection library.
Declared in @samp{coll/collstd.h}
@end defmac

@defmac COLL_GCC_VERSION
The version number of the compiler used to compile the collection
library. 
Declared in @samp{coll/collstd.h}
@end defmac

@deftypevar {char[]} coll_version
A string containing the version number of the collection library.
Declared in @samp{coll/collstd.h}
@end deftypevar

@deftypevar {char[]} coll_gcc_version
A string containing the version number of the compiler used to compile
the collection library.
Declared in @samp{coll/collstd.h}
@end deftypevar

@end itemize

@section The design philosophy.

Objective-C is not Smalltalk.  Differences that matter to the
Collection heirarchy:

@itemize

@item
There can be only one set of argument types with each selector.
(For instance in Objective-C we can't have "-(double)data" and
"-(char)data".  I can't stand it when some library that I'm forced to
load already defines a selector that I want to use with different
types.)  This isn't an issue in Smalltalk because everything is an
object. 

I make the Collection method names a little more descriptive, while
keeping them close to Smalltalk.  (For instance I think there is a
good reason for using "-addObject:" instead of "-add:")

@item
We will want collections of int's, float's, and other non-Objects.
Using Objective C wrappers around these C primitive types (i.e.
Integer and Float objects) is not an efficient enough option for all
cases. 

We could create two parallel heirarchies, one for Objects and one
for elements passed as void*, but since so much of the functionality
overlaps, I have merged them, and it doesn't actually look all that
bad.

@item
Objective C doesn't have Smalltalk Blocks.  

Passing pointers to functions is a reasonable substitute.  This is made
easier with gcc's nested functions and the LAMBDA() macro defined in
coll/collstd.h.

@item
Smalltalk does automatic garbage collection; Objective C doesn't.

I think it should be made obvious which methods allocate a new
object.  Hence "-shallowCopyAs:[Bag class]" instead of 
"as:[Bag class]".

@item
We have usable Collection classes (Set, Bag, Array, etc) with
functionality matching Smalltalk's objects, but there are good
reasons for not having the abstract superclass structure match
Smalltalk exactly.

@end itemize

<<This section unfinished.>>


@node Content Types, Creating, Conventions, Top
@chapter Content types
@cindex Content types
@cindex Types of storable data

Collections can hold either objects or primitive C types.  More
specifically, collections can hold any of the types in the
@code{elt} union defined in @code{coll/elt.h}.  All contents of a
collection must be of the same type.

You declare which type the collection will hold at collection
initialization time, and the type can not be changed later.  You
specify the type using the Objective-C @code{@@encode()} directive.
You can find out the type held by a collection with the method
@code{contentEncoding} (@pxref{Querying}).

Many operations are independent of the type the collection holds.  For
example the method @code{-(unsigned)count} returns the number of members
in the collection.

Other operations need to take arguments of different types depending on
whether the contents are objects or some other type.  In this case there
will be two methods, distinguished by the words @code{Object} and
@code{Element} in their method name.  For example,
@code{-removeObject:anObject} vs
@code{-(elt)removeElement:(elt)anElement}.

<<Unfinished.>>

@node Creating, Freeing, Content Types, Top
@chapter Creating a Collection

@menu
* Basic Creating::
* Keyed Creating::
@end menu

@node Basic Creating, Keyed Creating, , Creating
@section Basic Creating

@deftypemethod Collection {} @keyword{-init}
@end deftypemethod

@deftypemethod Collection {} @keyword{-initEncoding:} (const char *)@var{contentEncoding}
@end deftypemethod

Create with @code{alloc} and @code{init}.  Specify the type of contents
using @code{initEncoding:}.  For example:

@smallexample
id arrayHoldingInts = [[Array alloc] initEncoding:@@encode(int)];
@end smallexample

<<This section unfinished.>>

@node Keyed Creating, , Basic Creating, Creating
@section Keyed Creating


@node Freeing, Adding, Creating, Top
@chapter Freeing a Collection or its Elements

You can free all the objects in a collection and empty it using
@code{freeObjects}.  You can emtpy a collection without freeing the
contents using @code{empty}.  You can free a collection without freeing
the contents using @code{free}.

<<This section unfinished.>>


@node Adding, Removing, Freeing, Top
@chapter Adding Elements to a Collection

Talk about adding.

@menu
* Basic Adding::
* Keyed Adding::
* Indexed Adding::
@end menu

@node Basic Adding, Keyed Adding, , Adding
@section Basic Adding

Adding, adding if absent, adding a copy, adding all contents of another
collection, adding contents if absent, adding with varargs.

@deftypemethod Collection {} @keyword{-addObject:} @var{newObject}
@deftypemethodx Collection {} @keyword{-addElement:} (elt)@var{newElement}
Adds @var{newObject} to the receiving collection.  Returns self.
@end deftypemethod

@deftypemethod Collection {} @keyword{-addObjectIfAbsent:} @var{newObject}
@deftypemethodx Collection {} @keyword{-addElementIfAbsent:} (elt)@var{newElement}
Adds @var{newObject} to the receiving collection only if @var{newObject}
isn't there already.  Returns self.
@end deftypemethod

@deftypemethod Collection {} @keyword{-addContentsOf:} (id <Collecting>)@var{newObject}
Adds all the elements in @var{aCollection} to the receiving collection.
Returns self. 
@end deftypemethod

@deftypemethod Collection {} @keyword{-addContentsOfIfAbsent:} (id <Collecting>)@var{newObject}
<<Undocumented>>  Returns self. 
@end deftypemethod

@deftypemethod Collection {} @keyword{-addObjectsCount:} (unsigned)@var{count}, ...
@deftypemethodx Collection {} @keyword{-addElementsCount:} (unsigned)@var{count}, ...
<<Undocumented>>  Returns self. 

Here is an example
@smallexample
id o1 = [[Foo alloc] init];
id o2 = [[Bar alloc] init];
id myArray = [[[Array alloc] init] addObjectsCount: 2, o1, o2];
@end smallexample
@end deftypemethod

@node Keyed Adding, Indexed Adding, Basic Adding, Adding
@section Keyed Adding

If the collection's contents are accessible by a key, members can be
inserted at a specified key.  See KeyedCollecting protocol.

@deftypemethod KeyedCollection {} @keyword{-insertObject:} @var{newContentObject} @keyword{atKey:} (elt)@var{aKey}
@deftypemethodx KeyedCollection {} @keyword{-insertElement:} (elt)@var{newContentElement} @keyword{atKey:} (elt)@var{aKey}
<<Undocumented>>  returns self.
@end deftypemethod

@node Indexed Adding, , Keyed Adding, Adding
@section Indexed Adding

Furthermore, if the collections contents are accessible by an index (an
unsigned integer key), members can be appended, prepended.  Inserted
members push other members down to make room.
See IndexedCollecting protocol.

@deftypemethod IndexedCollection {} @keyword{-insertObject:} @var{newObject} @keyword{atIndex:} (unsigned)@var{index}
@deftypemethodx IndexedCollecting {} @keyword{-insertElement:} (elt)@var{newElement} @keyword{atIndex:} (unsigned)@var{index}
<<Undocumented>>  returns self.
@end deftypemethod

@deftypemethod IndexedCollection {} @keyword{-insertObject:} @var{newObject} @keyword{before:} @var{oldObject}
@deftypemethodx IndexedCollecting {} @keyword{-insertElement:} (elt)@var{newElement} @keyword{before:} @var{oldObject}
<<Undocumented>>  returns self.
@end deftypemethod

@deftypemethod IndexedCollection {} @keyword{-insertObject:} @var{newObject} @keyword{after:} @var{oldObject}
@deftypemethodx IndexedCollecting {} @keyword{-insertElement:} (elt)@var{newElement} @keyword{after:} @var{oldObject}
<<Undocumented>>  returns self.
@end deftypemethod

@deftypemethod IndexedCollection {} @keyword{insertContentsOf:} (id <Collecting>)@var{aCollection} @keyword{atIndex:} (unsigned)@var{index}
<<Undocumented>>  returns self.
@end deftypemethod

@deftypemethod IndexedCollection {} @keyword{-appendObject:} @var{newObject}
@deftypemethodx IndexedCollecting {} @keyword{-appendElement:} (elt)@var{newElement}
@deftypemethodx IndexedCollection {} @keyword{-prependObject:} @var{newObject}
@deftypemethodx IndexedCollecting {} @keyword{-prependElement:} (elt)@var{newElement}
<<Undocumented>>  returns self.
@end deftypemethod

@deftypemethod IndexedCollection {} @keyword{-appendContentsOf:} (id <Collecting>)@var{aCollection}
@deftypemethodx IndexedCollection {} @keyword{-prependContentsOf:} (id <Collecting>)@var{aCollection}
<<Undocumented>>  returns self.
@end deftypemethod

<<This section unfinished.>>


@node Removing, Replacing, Adding, Top
@chapter Removing Elements from a Collection

About removing...

@menu
* Basic Removing::
* Keyed Removing::
* Indexed Removing::
@end menu

@node Basic Removing, Keyed Removing, , Removing

@node Keyed Removing, Indexed Removing, Basic Removing, Removing

@node Indexed Removing, , Keyed Removing, Removing


<<This section unfinished.>>

@node Replacing, Enumerating, Removing, Top
@chapter Replacing Elements in a Collection

@menu
* Basic Replacing::
* Keyed Replacing::
* Indexed Replacing::
@end menu

@node Basic Replacing, Keyed Replacing, , Replacing

@node Keyed Replacing, Indexed Replacing, Basic Replacing, Replacing

@node Indexed Replacing, , Keyed Replacing, Replacing

<<This section unfinished.>>


@node Enumerating, Duplicating, Replacing, Top
@chapter Enumerating the Contents of a Collection

Enumeration methods allow you to perform a specified operation on the
members of a collection.  You can operate on all the members, operate on
all the members until a flag is set, operate only on the members that
pass some test, or operate on the results of passing the members through
a modifying function.  Each of the enumerators come in pairs: one method
for enumerating in place, and another method that is ``safe'' for
enumerating when the operation changes the contents of the receiving
collection.  If the contents of the collection are changed during the
enumeration you must use the ``safe'' methods.

@menu
* Safe vs Unsafe Enumerating::  Enumerations while changing the contents

* Basic Enumerating::           Enumerations available for all collections
* Keyed Enumerating::           Enumerations on collections with keys
* Indexed Enumerating::         Enumerations on ordered collections

* LAMBDA::                      Defining functions in place with LAMBDA()
@end menu

@node Safe vs Unsafe Enumerating, Basic Enumerating, , Enumerating
@section Safe vs Unsafe Enumerating

The simple enumerators operate on the collection in-place.  If the
contents of the collection change during the enumeration, you must use
the ``safe'' version of the enumerator instead.  

It works by making a shallow copy of the receiver, performing the
enumeration using the shallow copy, then freeing the shallow copy.

All enumerators have both ``safe'' and plain versions.

<<This section unfinished.>>

@node Basic Enumerating, Keyed Enumerating, Safe vs Unsafe Enumerating, Enumerating
@section Basic Enumerating

The most basic enumerator is
@deftypemethod Collection {} @keyword{-withObjectsCall:} (void(*)(id))@var{func}
@deftypemethodx Collection {} @keyword{-safeWithObjectsCall:} (void(*)(id))@var{func}
@deftypemethodx Collection {} @keyword{-withElementsCall:} (void(*)(elt))@var{func}
@deftypemethodx Collection {} @keyword{-safeWithElementsCall:} (void(*)(elt))@var{func}
Calls the function @var{func} with each the members of the collection.
Returns self.
@end deftypemethod

@deftypemethod {Collection} {(void*)} -newEnumState
@end deftypemethod

@deftypemethod {Collection} {} -freeEnumState: (void**)@var{enumStatePtr}
@end deftypemethod

@deftypemethod {Collection} {(BOOL)} -getNextObject: (id *)@var{anObjectPtr} @keyword{withEnumState:} (void**)@var{enumState} 
@deftypemethodx {Collection} {(BOOL)} -getNextElement: (elt *)@var{anElementPtr} @keyword{withEnumState:} (void**)@var{enumState} 
@refill
@end deftypemethod

@example
void print_first_difference (id coll1, id coll2)
  @{
    void *enumState1, *enumState2;
    id object1, object2;

    enumState1 = [coll1 newEnumState];
    enumState2 = [coll2 newEnumState];
    while ([coll1 getNextObject:&object1 withEnumState:&enumState1]
           && [coll2 getNextObject:&object2 withEnumState:&enumState2])
      @{
        if ([object1 compare:object2])
          @{
            [object1 printForDebugger];
            [object2 printForDebugger];
          @}
      @}
    [coll1 freeEnumState:&enumState1];
    [coll2 freeEnumState:&enumState2];
  @}
@end example

@deftypemethod {Collection} {} -withElementsCall: (void(*)(elt))@var{aFunc} @keyword{whileTrue:} (BOOL*)@var{flag} 
@deftypemethodx {Collection} {} -safeWithElementsCall: (void(*)(elt))@var{aFunc} @keyword{whileTrue:} (BOOL*)@var{flag} 
@refill
@end deftypemethod


@node Keyed Enumerating, Indexed Enumerating, Basic Enumerating, Enumerating
@section Keyed Enumerating


@node Indexed Enumerating, LAMBDA, Keyed Enumerating, Enumerating
@section Indexed Enumerating

@deftypemethod {IndexedCollection} {(BOOL)} -getPrevObject: (id *) @var{anObjectPtr} @keyword{withEnumState:} (void**)@var{enumState} 
@deftypemethodx {IndexedCollection} {(BOOL)} -getPrevElement: (elt *) @var{anElementPtr} @keyword{withEnumState:} (void**)@var{enumState} 
@refill
@end deftypemethod

@deftypemethod {IndexedCollection} {} -withObjectsInReverseCall: (void(*)(id))@var{aFunc} 
@deftypemethodx {IndexedCollection} {} -safeWithObjectsInReverseCall: (void(*)(id))@var{aFunc} 
@deftypemethodx {IndexedCollection} {} -withElementsInReverseCall: (void(*)(elt))@var{aFunc} 
@deftypemethodx {IndexedCollection} {} -safeWithElementsInReverseCall: (void(*)(elt))@var{aFunc} 
@refill
@end deftypemethod

@deftypemethod {IndexedCollection} {} -withObjectsInReverseCall: (void(*)(id)) @var{aFunc} @keyword{whileTrue:} (BOOL *)@var{flag} 
@deftypemethodx {IndexedCollection} {} -safeWithObjectsInReverseCall: (void(*)(id)) @var{aFunc} @keyword{whileTrue:} (BOOL *)@var{flag} 
@deftypemethodx {IndexedCollection} {} -withElementsInReverseCall: (void(*)(elt)) @var{aFunc} @keyword{whileTrue:} (BOOL *)@var{flag} 
@deftypemethodx {IndexedCollection} {} -safeWithElementsInReverseCall: (void(*)(elt)) @var{aFunc} @keyword{whileTrue:} (BOOL *)@var{flag} 
@refill
@end deftypemethod

@deftypemethod {IndexedCollection} {} -makeObjectsPerformInReverse: (SEL) @var{aSel} 
@deftypemethodx {IndexedCollection} {} -safeMakeObjectsPerformInReverse: (SEL) @var{aSel} 
@deftypemethodx {IndexedCollection} {} -makeObjectsPerformInReverse: (SEL) @var{aSel} @keyword{with:} @var{argObject} 
@deftypemethodx {IndexedCollection} {} -safeMakeObjectsPerformInReverse: (SEL) @var{aSel} @keyword{with:} @var{argObject} 
@refill
@end deftypemethod


@node LAMBDA, , Indexed Enumerating, Enumerating
@section Defining Functions In Place with LAMBDA()
@cindex Defining Functions In Place
@cindex Function definitions with LAMBDA

NOTE:  The LAMBDA macro does not work on all systems.  We are waiting
for a general fix.  You should avoid using it until then.

There may not already be a function that does the operation you want
performed during an enumeration.  In this case you will have to
write such a function yourself.

If the function will be used more than once, you should write it as C
functions are usually defined.  However, if the function will only be
used for this one enumeration and the function is small, using the
@code{LAMBDA} macro may be easier and more clear.

@defmac LAMBDA(@var{RETTYPE}, @var{ARGS}, @var{BODY})
@code{LAMBDA} is a macro for defining a nested function and returning
a pointer to that function.  You can use @code{LAMBDA} wherever a
function pointer is required.  @var{RETTYPE} is the C type returned by
the function.  @var{ARGS} is the parenthesis-enclosed list of arguments
to the function.  (Declare them just like in an ANSI function
definition.)  @var{BODY} is the curly-bracket-enclosed body of the
function. 

For example, you could create a pointer to a function that adds its
arguments like this:
@smallexample
LAMBDA(int, (int a, int b), @{return a + b;@})
@end smallexample
@end defmac

@code{LAMBDA} is particularly convenient for enumeration methods because
the macro can be placed in the position of the method argument.  For
instance, you can write:
@example
  - fooMethod
  @{
    id newColl;
    ...
    newColl = [self emptyCopyAs:[Array class]];
    [self withObjectsCall:
          LAMBDA(void, (id o), @{[newColl addObject:[o copy]];@})];
    return self;
  @}
@end example
instead of writing:
@smallexample
  - fooMethod
  @{
    id newColl = [self emptyCopyAs:[Array class]];
    void myTmpFunc(id o)
      @{
        [newColl addObject:[o copy]];
      @}
    ...
    [self withObjectsCall:myTmpFunc];
    return self;
  @}
@end smallexample
In these examples, there may be many lines of code between the
declarations at the top of the method and the @code{withObjectsCall:} at
the bottom of the method.  Using @code{LAMBDA} allows you to declare
the function where it is used, instead of arbitrarily far from where it
is used.

The name @code{LAMBDA} comes from lambda calculus and LISP.

The @code{LAMBDA} macro and some similar macros are defined in
@samp{coll/collstd.h}. 

@section Filtered Enumerating

@section Enumerating with Keyed Collections

@section Enumerating with Indexed Collections

<<This section unfinished.>>


@node Duplicating, Archiving, Enumerating, Top
@chapter Duplicating

Talk about shallow and deep copies.

<<This section unfinished.>>


@node Archiving, Querying, Duplicating, Top
@chapter Archiving

You can write collections to a stream.  You can read them back in again.
Talk about the @code{-awake} method.

@deftypemethod Collection {} @keyword{-write:} (TypedStream*)@var{aStream}
<<Undocumented>>  Returns self.
@end deftypemethod

@deftypemethod Collection {} @keyword{-read:} (TypedStream*)@var{aStream}
<<Undocumented>>  Returns self.
@end deftypemethod

<<This section unfinished.>>


@node Querying, Sorting, Archiving, Top
@chapter Querying

<<This section unfinished.>>

@menu
* Basic Querying::
* Keyed Querying::
* Indexed Querying::
@end menu

@node Basic Querying, Keyed Querying, , Querying
@section Basic Querying

@deftypemethod Collection {(BOOL)} @keyword{-isEmpty}
Returns YES if the receiver contains no members; returns NO otherwise.
@end deftypemethod

@deftypemethod Collection {(const char *)} @keyword{-contentEncoding}
Returns a description of the C type that the receiving collection can
hold.  The description is a string of the form returned by the
Objective-C @code{@@encode} directive.
@end deftypemethod

@node Keyed Querying, Indexed Querying, Basic Querying, Querying
@section Keyed Querying

@node Indexed Querying, , Keyed Querying, Querying
@section Indexed Querying

@node Sorting, Classes, Querying, Top
@chapter Sorting

<<This section unfinished.>>


@node Classes, Projects, Sorting, Top
@chapter Choosing the Right Class

Talk about keys or no keys, ordered or not ordered.  Talk about the
classes the require protocol-conforming objects as members.

@menu
* Set::
* Bag::

* Dictionary::
* MappedCollector::

* Array::
* Stack::
* Queue::
* GapArray::

* LinkedList::
* BinaryTree::
* RBTree::
* SplayTree::
* EltNodeCollector::

* Collection::
* KeyedCollection::
* IndexedCollection::
@end menu

<<This section unfinished.>>

@node Set, Bag, , Classes
@section Set

<<This section unfinished.>>

@node Bag, Dictionary, Set, Classes
@section Bag

A Bag is ...

@menu
* Basic Creating::
* Freeing::
* Bag Adding::
* Basic Adding::
* Keyed Adding::
* Indexed Adding::
* Bag Removing::
* Basic Removing::
* Keyed Removing::
* Indexed Removing::
* Basic Removing::
* Keyed Removing::
* Indexed Removing::
* Basic Enumerating::
* Keyed Enumerating::
* Indexed Enumerating::


@end menu

@node Bag Adding, Bag Removing, , Bag

@deftypemethod Bag {} @keyword{-addObject:} @var{newObject} withOccurrences: (unsigned)@var{count}
@deftypemethodx Bag {} @keyword{-addElement:} (elt)@var{newElement} withOccurrences: (unsigned)@var{count}
@end deftypemethod

@node Bag Removing, , Bag Adding, Bag

@deftypemethod Bag {} @keyword{-removeObject:} @var{oldObject} occurrences: (unsigned)@var{count}
@deftypemethodx Bag {} @keyword{-removeElement:} (elt)@var{oldElement} occurrences: (unsigned)@var{count}
@end deftypemethod

<<This section unfinished.>>

@node Dictionary, MappedCollector, Bag, Classes
@section Dictionary

A Dictionary is ...

@node MappedCollector, Array, Dictionary, Classes
@section MappedCollector

A MappedCollector is ...

@node Array, Stack, MappedCollector, Classes
@section Array

An Array is ...

@menu
* Array Capacity Management::
* Basic Creating::
* Freeing::
* Basic Adding::
* Keyed Adding::
* Indexed Adding::
* Basic Removing::
* Keyed Removing::
* Indexed Removing::
* Basic Replacing::
* Keyed Replacing::
* Indexed Replacing::
* Basic Enumerating::
* Keyed Enumerating::
* Indexed Enumerating::
* Duplicating::
* Archiving::
* Basic Querying::
* Keyed Querying::
* Indexed Querying::
@end menu

@node Array Capacity Management, , , Array
@section Array Methods

@deftypemethod {Array} {(unsigned)} @keyword{+defaultCapacity}
@refill
@end deftypemethod

@deftypemethod {Array} {(unsigned)} @keyword{+defaultGrowFactor}
@refill
@end deftypemethod

@deftypemethod {Array} {} @keyword{-initEncoding:} (const char *)
@var{contentEncoding} @keyword{capacity:} (unsigned) @var{aCapacity} 
@refill
@end deftypemethod

@deftypemethod {Array} {} -setCapacity: (unsigned) @var{newCapacity} 
@refill
@end deftypemethod

@deftypemethod {Array} {} -setGrowFactor: (unsigned) @var{aNum} 
@refill
@end deftypemethod

@node Stack, Queue, Array, Classes
@section Stack

@menu
* Stack Methods::
* Array Capacity Management::
* Basic Creating::
* Freeing::
* Basic Adding::
* Keyed Adding::
* Indexed Adding::
* Basic Removing::
* Keyed Removing::
* Indexed Removing::
* Basic Replacing::
* Keyed Replacing::
* Indexed Replacing::
* Basic Enumerating::
* Keyed Enumerating::
* Indexed Enumerating::
* Duplicating::
* Archiving::
* Basic Querying::
* Keyed Querying::
* Indexed Querying::
@end menu

@node Stack Methods, , , Stack

@deftypemethod {Stack} {} -pushObject: @var{newObject}
@deftypemethodx {Stack} {} -pushElement: (elt)@var{newElement}
@end deftypemethod

@deftypemethod {Stack} {} -popObject: @var{newObject}
@deftypemethodx {Stack} {} -popElement: (elt)@var{newElement}
@end deftypemethod

@deftypemethod {Stack} {} -topObject
@deftypemethodx {Stack} {(elt)} -topElement
@end deftypemethod

@deftypemethod {Stack} {} -exchangeTop
@end deftypemethod

@node Queue, GapArray, Stack, Classes

@node GapArray, LinkedList, Queue, Classes

@node LinkedList, BinaryTree, GapArray, Classes

@node BinaryTree, RBTree, LinkedList, Classes

@node RBTree, SplayTree, BinaryTree, Classes

@node SplayTree, EltNodeCollector, RBTree, Classes

@node EltNodeCollector, Collection, SplayTree, Classes

@node Collection, KeyedCollection, EltNodeCollector, Classes

A Collection is ...

@menu
* Basic Creating::
* Freeing::
* Basic Adding::
* Basic Removing::
* Basic Replacing::
* Basic Enumerating::
* Duplicating::
* Archiving::
* Basic Querying::
@end menu

@node KeyedCollection, IndexedCollection, Collection, Classes
@section KeyedCollection

@menu
* Basic Creating::
* Keyed Creating::
* Freeing::
* Basic Adding::
* Keyed Adding::
* Basic Removing::
* Keyed Removing::
* Basic Replacing::
* Keyed Replacing::
* Basic Enumerating::
* Keyed Enumerating::
* Duplicating::
* Archiving::
* Basic Querying::
* Keyed Querying::
@end menu

@node IndexedCollection, , KeyedCollection, Classes
@section IndexedCollection

@menu
* Basic Creating::
* Freeing::
* Basic Adding::
* Keyed Adding::
* Indexed Adding::
* Basic Removing::
* Keyed Removing::
* Indexed Removing::
* Basic Replacing::
* Keyed Replacing::
* Indexed Replacing::
* Basic Enumerating::
* Keyed Enumerating::
* Indexed Enumerating::
* Duplicating::
* Archiving::
* Basic Querying::
* Keyed Querying::
* Indexed Querying::
@end menu


@node Projects, Protocol Index, Classes, Top
@chapter To Do List and Questions

@include todo.texi

@section How to contribute

Programmers who have written Objective-C classes that they believe to be
of general interest are encouraged to write to
mccallum@@gnu.ai.mit.edu.  Contributing code is not difficult. Here are
some general guidelines:

@itemize @bullet

@item
FSF must maintain the right to accept or reject potential contributions.
Generally, the only reasons for rejecting contributions are cases where
they duplicate existing or nearly-released code, contain unremovable
specific machine dependencies, or are somehow incompatible with the
rest of the library. 

@item
Acceptance of contributions means that the code is accepted for adaptation
into libobjects.  FSF must reserve the right to make various editorial changes
in code. Very often, this merely entails formatting, maintenance of various
conventions, etc. Contributors are always given authorship credit and shown
the final version for approval.

@item
Contributors must assign their copyright to FSF via a form sent out
upon acceptance. Assigning copyright to FSF ensures that the code
may be freely distributed.

@item
Assistance in providing documentation, test files, and debugging
support is strongly encouraged.

@end itemize

Extensions, comments, and suggested modifications of existing libobjects
features are also very welcome.

@node Protocol Index, Class Index, Projects, Top
@unnumbered Protocol Index
@printindex pr


@node Class Index, Method Function Macro Index, Protocol Index, Top
@unnumbered Class Index
@printindex cl


@node Method Function Macro Index, Concept Index, Class Index, Top
@unnumbered Method, Function and Macro Index
@printindex fn

@node Concept Index, , Method Function Macro Index, Top
@unnumbered Concept Index
@printindex cp

@summarycontents
@contents

@bye