
     aaaallllllllooooccccaaaatttteeee____mmmmaaaappppppppiiiinnnngggg((((3333))))    MMMMuuuuddddOOOOSSSS ((((5555 SSSSeeeepppp 1111999999994444))))     aaaallllllllooooccccaaaatttteeee____mmmmaaaappppppppiiiinnnngggg((((3333))))

     NNNNAAAAMMMMEEEE
          allocate_mapping() - pre-allocate space for a mapping

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          mapping allocate_mapping( int size );

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          Returns a mapping with space for 'size' elements
          preallocated.

          For example:

               mapping x;
               int y = 200;

               x = allocate_mapping(y);

          where y is the initial size of the mapping.  Using
          allocate_mapping is the preferred way to initalize the
          mapping if you have some idea of how many elements the map
          will contain (200 in this case).  The reason is that
          allocating storage all at once is slightly more memory
          efficient.  Thus if you are using mappings to store a soul
          with 200 entries, the above initialization would be quite
          appropriate.  Note, that the above initialization does not
          restrict you to 200 entries.  It just that the first 200
          entries will be stored more efficiently.  Note: if you will
          be deleting many elements from the mapping, you should use x
          = ([]) to initialize the mapping rather than using
          allocate_mapping().

          Note: at this point in time, `size' is meaningless, x =
          allocate_mapping(200); is equivalent to x = ([ ]);

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
          map_delete(3)

     Page 1                                          (printed 3/16/95)

