more internal docs added

Rev: doc/internal/.bmmlrc:1.1
Rev: doc/internal/array/allocate_array:1.1
Rev: doc/internal/array/array:1.1
Rev: doc/internal/array/array_index:1.1
Rev: doc/internal/array/free_array:1.1
Rev: doc/internal/mappings/copy_mapping:1.1
Rev: doc/internal/mappings/free_mapping:1.1
Rev: doc/internal/mappings/low_mapping_lookup:1.1
Rev: doc/internal/mappings/m_sizeof:1.1
Rev: doc/internal/mappings/map_delete:1.1
Rev: doc/internal/mappings/mapping:1.1
Rev: doc/internal/mappings/mapping_indices:1.1
Rev: doc/internal/mappings/mapping_insert:1.1
Rev: doc/internal/mappings/mapping_replace:1.1
Rev: doc/internal/mappings/mapping_values:1.1
Rev: doc/internal/mappings/mkmapping:1.1
Rev: doc/internal/pike/error:1.1
Rev: doc/internal/pike/fatal:1.1
Rev: doc/internal/pike/frame:1.1
Rev: doc/internal/pike/type_field:1.1
Rev: doc/internal/program/program:1.1
Rev: doc/internal/strings/free_string:1.2
Rev: doc/internal/strings/make_shared_string:1.2
Rev: doc/internal/strings/pike_string:1.2

doc/internal/.bmmlrc

+prefix internal

doc/internal/array/allocate_array

+NAME
+	allocate_array - allocate an array
+
+SYNTAX
+	#include "array.h"
+
+	struct array *allocate_array(INT32 size);
+
+DESCRIPTION
+	This function allocates an array of size 'size'. The returned
+	array will have 'size' struct svalues in the member 'item'.
+	The array can contain any svalue, and the type field will be
+	initalized to -1.
+
+NOTA BENE
+	When building arrays, it is recommended that you push the values
+	on the stack and call aggregate_array or f_aggregate instead of
+	allocating and filling in the values 'by hand'.
+
+KEYWORDS
+	array
\ No newline at end of file

doc/internal/array/array

+NAME
+	array - the internal representation of an array
+
+DESCRIPTION
+	A Pike array is represented as a 'struct array' with all the
+	needed svalues malloced in the same block. The relevant members
+	are:
+
+	refs    	reference count
+	size    	the number of svalues in the array
+	malloced_size	the number of svalues that can fit in this block
+	type_field	a bitfield indicating what types the array contains
+	item    	the array of svalues
+
+
+SEE ALSO
+	type_field
+
+KEYWORDS
+	internals

doc/internal/array/array_index

+NAME
+	array_index - get an index from an array
+
+SYNTAX
+	#include "array.h"
+
+	void array_index(struct svalue *to, struct array *a, INT32 n);
+
+DESCRIPTION
+	This function frees the contents of the svalue 'to' and replaces
+	it with a copy of the contents from index 'n' in the array 'a'.
+	Basically, what it does is:
+
+		assign_svalue(to, a->item + n);
+
+	The only differance is that it adds some debug and safety
+	measures. Usually you don't really need to use this function.
+
+NOTA BENE
+	If n is out of bounds (n < 0 or n >= a->size) Pike will dump
+	core. If Pike was compiled with DEBUG, a message will be written
+	first stating what the problem was.
+
+SEE ALSO
+	assign_svalue
\ No newline at end of file

doc/internal/array/free_array

+NAME
+	free_array - free one reference to a array
+
+SYNTAX
+	#include "array.h"
+
+	void free_array(struct array *a)
+
+DESCRIPTION
+	This function frees one reference to the array a. If the reference
+	is the last reference to the array, it will free the memory used
+	by the array a.
+
+NOTA BENE
+	free_array is a macro
+
+KEYWORDS
+	array

doc/internal/mappings/copy_mapping

+NAME
+	copy_mapping - copy a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	struct mapping *copy_mapping(struct mapping *m)
+
+DESCRIPTION
+	This function returns a copy of the mapping m. If you change the
+	contents of the new mapping the contents of the mapping m will not
+	change. Note that this function is not recursive.
+
+KEYWORDS
+	mapping	

doc/internal/mappings/free_mapping

+NAME
+	free_mapping - free one reference to a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	void free_mapping(struct mapping *m)
+
+DESCRIPTION
+	This function frees one reference to the mapping m. If the reference
+	is the last reference to the mapping, it will free the memory used
+	by the mapping m.
+
+NOTA BENE
+	free_mapping is a macro
+
+KEYWORDS
+	mapping

doc/internal/mappings/low_mapping_lookup

+NAME
+	low_mapping_lookup - lookup a key in a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	struct svalue *low_mapping_lookup(struct mapping *m,
+	                                  struct svalue *key);
+
+DESCRIPTION
+	This function looks up the key-index pair that has the key 'key' in
+	the mapping 'm' and returns a pointer to the 'value'. If no such
+	key-index pair is found, zero is returned.
+
+NOTA BENE
+	Any call to an internal Pike function may re-allocate the mapping
+	'm', which means that the pointer returned from this call is only
+	valid until your next function call.
+
+NOTA BENE
+	This function is intended for _reading_ mappings, it is forbidden
+	to change the contents of the returned svalue.
+
+KEYWORDS
+	mapping
+
+SEE ALSO
+	map_insert
\ No newline at end of file

doc/internal/mappings/m_sizeof

+NAME
+	m_sizeof - return the number of key-value pairs in a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	int m_sizeof(struct mapping *m)
+
+DESCRIPTION
+	This function returns the number of key-index pairs in the mapping,
+	just like the function sizeof() in Pike.
+
+NOTA BENE
+	m_sizeof is a macro
+
+KEYWORDS
+	mapping

doc/internal/mappings/map_delete

+NAME
+	map_delete - delete an item from a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	void map_delete(struct mapping *m, struct svalue *key);
+
+DESCRIPTION
+	This function removes the key-index pair that has they key 'key'
+	from the mapping. If there is no such key-index pair in the mapping
+	nothing will be done.
+
+KEYWORDS
+	mapping
+
+SEE ALSO
+	mapping_insert

doc/internal/mappings/mapping

+NAME
+	mapping - internal pike mappings
+
+DESCRIPTION
+	'struct mapping' is the C representation of a Pike mapping. The struct
+	itself contains no user servicable parts except for the member 'refs'
+	which has to be increased when putting a 'struct mapping *' into a
+	svalue. Never _ever_ decrease the ref counter manually, use
+	free_mapping instead. Also note that you should never ever allocate
+	a mapping statically, you should always use the functions provided by
+	pike to allocate mappings.
+
+	A mapping is basically a hash table with a linked list of key-value
+	pairs in each hash bin. The hash table and the key-index pairs are
+	allocated together in one large block to minimize memory fragmentation.
+	Also note that whenever you search for a specific key-value pair in
+	the mapping that key-value pair is propagated to the top of the linked
+	list in that hash bin, which makes the search time very very small for
+	most cases.
+
+KEYWORDS
+	internals

doc/internal/mappings/mapping_indices

+NAME
+	mapping_indices - return all the keys from a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	struct array *mapping_indices(struct mapping *m)
+
+DESCRIPTION
+	This function returns an array with all the keys from the mapping m.
+	The keys in the array are ordered in the same order as the values
+	when using mapping_values. But only if no other mapping operations
+	are done in between.
+
+KEYWORDS
+	mapping
+
+SEE ALSO
+	mapping_values, mkmapping

doc/internal/mappings/mapping_insert

+NAME
+	mapping_insert - insert a key-value pair into a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	void mapping_insert(struct mapping *m,
+	                    struct svalue *key,
+	                    struct svalue *value)
+
+DESCRIPTION
+	This function inserts a new key-value pair into the mapping m.
+	If there is a already key-value pair with the same key in the mapping
+	it will be replaced with the new key-value pair. If there isn't
+	such a key-value pair in the mapping the mapping will grow in size
+	to accomodate the new key-value pair. This is identical to the
+	Pike operation: m[key]=value
+
+KEYWORDS
+	mapping
+
+SEE ALSO
+	map_delete, low_mapping_lookup

doc/internal/mappings/mapping_replace

+NAME
+	mapping_replace - replace values in a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	void mapping_replace(struct mapping *m,
+	                     struct svalue *from,
+	                     struct svalue *to)
+
+DESCRIPTION
+	This function replaces all values of the value 'from' in the mapping
+	'm' with 'to'. It is a part of the Pike function replace().
+
+KEYWORDS
+	mapping

doc/internal/mappings/mapping_values

+NAME
+	mapping_values - return all the values from a mapping
+
+SYNTAX
+	#include "mapping.h"
+
+	struct array *mapping_values(struct mapping *m)
+
+DESCRIPTION
+	This function returns an array with all the values from the mapping m.
+	The values in the array are ordered in the same order as the keys
+	when using mapping_indices, but only if no other mapping operations
+	are done between the mapping_values and the mapping_indices.
+
+EXAMPLE
+	struct mapping *slow_copy_mapping(struct mapping *m)
+	{
+	  struct array *indices, *values;
+	  indices=mapping_indices(m);
+	  values=mapping_indices(m);
+	  m=mkmapping(indices,values);
+	  free_array(indices);
+	  free_array(values);
+	  return m;
+	}
+
+KEYWORDS
+	mapping
+
+SEE ALSO
+	mapping_indices, copy_mapping, mkmapping

doc/internal/mappings/mkmapping

+NAME
+	mkmapping - make a mapping
+
+SYNTAX
+	#include <mapping.h>
+
+	struct mapping *mkmapping(struct array *keys, struct array *values)
+
+DESCRIPTION
+	This function is the same as the Pike function mkmapping. It
+	makes a mapping out of an array of keys and an array of values.
+	Note that the returned mapping will have one extra reference.
+
+KEYWORDS
+	mapping
+
+SEE ALSO
+	mapping_indices, mapping_values
\ No newline at end of file

doc/internal/pike/error

+NAME
+	error - throw an error
+
+SYNTAX
+	#include "error.h"
+
+	void error(char *format_string, ...);
+
+DESCRIPTION
+	This function takes the same kind of arguments as printf, puts it
+	all together to a string and throws this as an error message
+	togehter with a backtrace that tells the catcher where the error
+	was. Note that this function does _not_ return. Instead it calls
+	the C function lonjump and continues executing from the most
+	resent active catch() call.
+
+KEYWORDS
+	internals

doc/internal/pike/fatal

+NAME
+	fatal - print a message and dump core
+
+SYNTAX
+	#include "error.h"
+
+	void fatal(char *format_string, ...);
+
+DESCRIPTION
+	This function takes the same type of argument as 'printf', and
+	prints these with any available debug information. (A trace of
+	the 512 last executed instructions if you compiled with DEBUG.)
+	Then it forces the driver to dump core so you can examine the
+	bug with a debugger. Use with extreme caution, an error() might
+	sometimes be a lot better...
+
+KEYWORDS
+	internal
+
+SEE ALSO
+	error

doc/internal/pike/frame

+NAME
+	frame - the current frame of exectution
+
+DESCRIPTION
+	The frame pointer is called 'fp' and is of type 'struct frame'.
+	The frame pointer contains information about what function we
+	are executing in, what is the current object, the current program,
+	where the local variables are etc. It also contains a pointer to
+	the previous frame in the call stack. The most important members
+	of 'fp' are:
+
+	current_object	same as the Pike function this_object()
+	context.program	the program in which this function resides
+	current_storage	a 'char *' pointer into the data area for this
+	          	object. This is the pointer to the area reserved
+	             	for you if you have done add_storage() earlier.
+
+KEYWORDS
+	internals

doc/internal/pike/type_field

+NAME
+	type_field - bit field used for optimizations
+
+DESCRIPTION
+	Type fields are used by arrays, mappings and some svalue operations
+	for optimization. The type field consists of OR:ed bits, one for
+	each type. The bit for an array is 1<<T_ARRAY (same as BIT_ARRAY)
+	The bit for a string is 1<<T_STRING (or BIT_STRING) etc.
+
+	A bit field never has to be exact, it needs to have at least those
+	bits that are present in the operation. It is never harmful to have
+	too many bits though. It seldom pays off to calculate the bit field
+	explicitly, so if you don't know what types are involved you should
+	use -1 for the type field.
+
+SEE ALSO
+	mapping, array, svalue