autodoc.git/
autodoc.xml
Branch:
Tag:
Non-build tags
All tags
No tags
1996-11-01
1996-11-01 23:55:42 by Fredrik Hübinette (Hubbe) <hubbe@hubbe.net>
6130720bdec5bde5ba72e0948f64755616d0f0b5 (
1694
lines) (+
1121
/-
573
)
[
Show
|
Annotate
]
Branch:
8.0
internal section added
Rev: doc/index.bmml:1.2
1:
<?xml version='1.0' encoding='utf-8'?> <autodoc>
+
<namespace name='c'>
+
<docgroup homogen-name='IS_ZERO' homogen-type='method'>
+
<method name='IS_ZERO'/><doc placeholder='true'>
+
<text>
+
<p><tt>IS_ZERO</tt> - is this svalue considered 'false'</p>
+
+
<tt><p>#include <simulate.h><br/>
+
+
</p>
+
<p>int IS_ZERO(struct svalue *<i>s</i>);<br/>
+
</p>
+
</tt>
+
<p>IS_ZERO returns true if the svalue 's' is a zero. (or an object with
+
`! operator that returned true..)</p>
+
</text>
+
+
<group><note/><text>
+
<p>IS_ZERO is actually a macro</p>
+
+
svalue</text></group>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::is_eq' to='is_eq'>is_eq</ref>, <ref resolved='c::is_equal' to='is_equal'>is_equal</ref> and <ref resolved='c::is_lt' to='is_lt'>is_lt</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='add_shared_strings' homogen-type='method'>
+
<method name='add_shared_strings'/><doc placeholder='true'>
+
<text>
+
<p><tt>add_shared_strings</tt> - add two pike strings</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *add_shared_strings(struct pike_string *a,<br/>
+
<dl><group><text>struct pike_string *b);<br/>
+
</text></group></dl></p>
+
</tt>
+
<p>This function builds the string a+b, that is the string a with the
+
string b appended to it. Note that the string returned will have
+
an extra reference.</p>
+
+
pike_string</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::begin_shared_string' to='begin_shared_string'>begin_shared_string</ref> and <ref resolved='c::make_shared_string' to='make_shared_string'>make_shared_string</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='allocate_array' homogen-type='method'>
+
<method name='allocate_array'/><doc placeholder='true'>
+
<text>
+
<p><tt>allocate_array</tt> - allocate an array</p>
+
+
<tt><p>#include "array.h"<br/>
+
+
</p>
+
<p>struct array *allocate_array(INT32 <i>size</i>);<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
</text>
+
+
<group><note/><text>
+
<p>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'.</p>
+
+
array</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='array' homogen-type='method'>
+
<method name='array'/><doc placeholder='true'>
+
<text>
+
<p><tt>array</tt> - the internal representation of an array</p>
+
+
<p>A Pike array is represented as a 'struct array' with all the
+
needed svalues malloced in the same block. The relevant members
+
are:
+
</p>
+
<p><matrix>
+
<r><c> refs </c><c> reference count </c></r>
+
<r><c> size </c><c> the number of svalues in the array </c></r>
+
<r><c> malloced_size </c><c> the number of svalues that can fit in this block </c></r>
+
<r><c> type_field </c><c> a bitfield indicating what types the array contains </c></r>
+
<r><c> item </c><c> the array of svalues </c></r>
+
</matrix>
+
</p>
+
</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::type_field' to='type_field'>type_field</ref></p>
+
+
internals</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='array_index' homogen-type='method'>
+
<method name='array_index'/><doc placeholder='true'>
+
<text>
+
<p><tt>array_index</tt> - get an index from an array</p>
+
+
<tt><p>#include "array.h"<br/>
+
+
</p>
+
<p>void array_index(struct svalue *<i>to</i>, struct array *<i>a</i>, INT32 <i>n</i>);<br/>
+
</p>
+
</tt>
+
<p>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:
+
</p>
+
<p><matrix>
+
<r><c> </c><c> assign_svalue(to, a->item + n); </c></r>
+
<r><c> </c></r>
+
</matrix>
+
+
</p>
+
<p>The only differance is that it adds some debug and safety
+
measures. Usually you don't really need to use this function.</p>
+
</text>
+
+
<group><note/><text>
+
<p>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.</p>
+
</text></group>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::assign_svalue' to='assign_svalue'>assign_svalue</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='assign_svalue' homogen-type='method'>
+
<method name='assign_svalue'/><doc placeholder='true'>
+
<text>
+
<p><tt>assign_svalue</tt> - copy svalues from one place to another</p>
+
+
<tt><p>#include <svalue.h><br/>
+
+
</p>
+
<p>void assign_svalue(struct svale *<i>to</i>, struct svalue *<i>from</i>);<br/>
+
</p>
+
</tt>
+
<p>This function copies an svalue from one struct svalue to another.
+
It frees the contents of 'to' first and updates the involved
+
refcounts.</p>
+
+
svalue</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::free_svalue' to='free_svalue'>free_svalue</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='begin_shared_string' homogen-type='method'>
+
<method name='begin_shared_string'/><doc placeholder='true'>
+
<text>
+
<p><tt>begin_shared_string</tt> - allocate space for a shared string</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *begin_shared_string(INT32 <i>len</i>);<br/>
+
</p>
+
</tt>
+
<p>This function allocates space for a shared string of length 'len'.
+
You should then MEMCPY 'len' bytes into the s->str. (s being the
+
returned value) And then call end_shared_string.</p>
+
+
pike_string</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::end_shared_string' to='end_shared_string'>end_shared_string</ref> and <ref resolved='c::make_shared_string' to='make_shared_string'>make_shared_string</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='binary_findstring' homogen-type='method'>
+
<method name='binary_findstring'/><doc placeholder='true'>
+
<text>
+
<p><tt>binary_findstring</tt> - find a string</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *binary_findstring(char *<i>str</i>, INT32 <i>length</i>);<br/>
+
</p>
+
</tt>
+
<p>This function looks for the 'str' with length 'len' in the
+
global hash table. It returns the shared string if found, otherwise
+
zero. It does not increase/decrease the references to the string.</p>
+
+
pike_string</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::findstring' to='findstring'>findstring</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='copy_mapping' homogen-type='method'>
+
<method name='copy_mapping'/><doc placeholder='true'>
+
<text>
+
<p><tt>copy_mapping</tt> - copy a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>struct mapping *copy_mapping(struct mapping *m)<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
+
mapping</text>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='end_shared_string' homogen-type='method'>
+
<method name='end_shared_string'/><doc placeholder='true'>
+
<text>
+
<p><tt>end_shared_string</tt> - link a shared string into the hashtable</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *end_shared_string(struct pike_string *<i>p</i>);<br/>
+
</p>
+
</tt>
+
<p>This function the prepared output from a begin_shared_string and
+
links the string into the hash table. If an identical string is
+
already present in the hash table, p is freed and that string is
+
returned instead. The returned string will have one extra reference
+
added.</p>
+
</text>
+
+
<group><example/><text>
+
<tt><p>#include "global.h"<br/>
+
#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *mkcharstring(int ch)<br/>
+
{<br/>
+
<dl><group><text>struct pike_string *ret;<br/>
+
ret=begin_shared_string(1);<br/>
+
ret->str[0]=ch;<br/>
+
return end_shared_string(ret);<br/>
+
</text></group></dl>}<br/>
+
</p>
+
</tt>
+
pike_string</text></group>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::begin_shared_string' to='begin_shared_string'>begin_shared_string</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='error' homogen-type='method'>
+
<method name='error'/><doc placeholder='true'>
+
<text>
+
<p><tt>error</tt> - throw an error</p>
+
+
<tt><p>#include "error.h"<br/>
+
+
</p>
+
<p>void error(char *<i>format_string</i>, ...);<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
+
internals</text>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='fatal' homogen-type='method'>
+
<method name='fatal'/><doc placeholder='true'>
+
<text>
+
<p><tt>fatal</tt> - print a message and dump core</p>
+
+
<tt><p>#include "error.h"<br/>
+
+
</p>
+
<p>void fatal(char *<i>format_string</i>, ...);<br/>
+
</p>
+
</tt>
+
<p>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...</p>
+
+
internal</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::error' to='error'>error</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='findstring' homogen-type='method'>
+
<method name='findstring'/><doc placeholder='true'>
+
<text>
+
<p><tt>findstring</tt> - find a string</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *findstring(char *<i>str</i>);<br/>
+
</p>
+
</tt>
+
<p>This function looks for the null terminated C string 'str' in the
+
global hash table. It returns the shared string if found, otherwise
+
zero. It does not increase/decrease the references to the string.</p>
+
+
pike_string</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::make_shared_string' to='make_shared_string'>make_shared_string</ref> and <ref resolved='c::binary_findstring' to='binary_findstring'>binary_findstring</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='frame' homogen-type='method'>
+
<method name='frame'/><doc placeholder='true'>
+
<text>
+
<p><tt>frame</tt> - the current frame of exectution</p>
+
+
<p>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:
+
</p>
+
<p><matrix>
+
<r><c> current_object </c><c> same as the Pike function this_object() </c></r>
+
<r><c> context.program </c><c> the program in which this function resides </c></r>
+
<r><c> current_storage </c><c> a 'char *' pointer into the data area for this </c></r>
+
</matrix>
+
<dl><group><text><matrix>
+
<r><c> </c><c> object. This is the pointer to the area reserved </c></r>
+
<r><c> </c></r>
+
</matrix>
+
<dl><group><text><matrix>
+
<r><c> </c><c> for you if you have done add_storage() earlier. </c></r>
+
<r><c> </c></r>
+
</matrix>
+
</text></group></dl></text></group></dl></p>
+
+
internals</text>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='free_array' homogen-type='method'>
+
<method name='free_array'/><doc placeholder='true'>
+
<text>
+
<p><tt>free_array</tt> - free one reference to a array</p>
+
+
<tt><p>#include "array.h"<br/>
+
+
</p>
+
<p>void free_array(struct array *a)<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
</text>
+
+
<group><note/><text>
+
<p>free_array is a macro</p>
+
+
array</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='free_mapping' homogen-type='method'>
+
<method name='free_mapping'/><doc placeholder='true'>
+
<text>
+
<p><tt>free_mapping</tt> - free one reference to a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>void free_mapping(struct mapping *m)<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
</text>
+
+
<group><note/><text>
+
<p>free_mapping is a macro</p>
+
+
mapping</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='free_string' homogen-type='method'>
+
<method name='free_string'/><doc placeholder='true'>
+
<text>
+
<p><tt>free_string</tt> - free a pike string</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>void free_string(struct pike_string *p)<br/>
+
</p>
+
</tt>
+
<p>This function frees the string 'p'. What it actually does is that it
+
decreases the reference count of 'p' and frees the memory reserved
+
for it if the refereneces reach zero.</p>
+
</text>
+
+
<group><note/><text>
+
<p>free_string is actually a macro</p>
+
+
pike_string</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='free_svalue' homogen-type='method'>
+
<method name='free_svalue'/><doc placeholder='true'>
+
<text>
+
<p><tt>free_svalue</tt> - free the contents of an svalue</p>
+
+
<tt><p>#include <svalue.h><br/>
+
+
</p>
+
<p>void free_svalue(struct svalue *<i>s</i>);<br/>
+
</p>
+
</tt>
+
<p>This function frees the contents of an svalue with respect to
+
ref counts. It does not however free the storage for svalue itself.
+
That is up to the caller to do.</p>
+
+
svalue</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::assign_svalue' to='assign_svalue'>assign_svalue</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='is_eq' homogen-type='method'>
+
<method name='is_eq'/><doc placeholder='true'>
+
<text>
+
<p><tt>is_eq</tt> - compare two svalues</p>
+
+
<tt><p>#include <svalue.h><br/>
+
+
</p>
+
<p>int is_eq(struct svalue *<i>a</i>, struct svalue *<i>b</i>);<br/>
+
</p>
+
</tt>
+
<p>This is the equivialent of the Pike operator `==. It compares two
+
svalues and returns one if they are the same. Otherwise zero.</p>
+
+
svalue</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::is_equal' to='is_equal'>is_equal</ref>, <ref resolved='c::is_lt' to='is_lt'>is_lt</ref> and <ref resolved='c::IS_ZERO' to='IS_ZERO'>IS_ZERO</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='is_equal' homogen-type='method'>
+
<method name='is_equal'/><doc placeholder='true'>
+
<text>
+
<p><tt>is_equal</tt> - compare two svalues recursively</p>
+
+
<tt><p>#include <svalue.h><br/>
+
+
</p>
+
<p>int is_equal(struct svalue *<i>a</i>, struct svalue *<i>b</i>);<br/>
+
</p>
+
</tt>
+
<p>This is the equivialent of the Pike function equal(), it compares
+
two svalues recursively and returns 1 if their contents are equal,
+
zero otherwise.</p>
+
+
svalue</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::is_eq' to='is_eq'>is_eq</ref>, <ref resolved='c::is_lt' to='is_lt'>is_lt</ref> and <ref resolved='c::IS_ZERO' to='IS_ZERO'>IS_ZERO</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='is_lt' homogen-type='method'>
+
<method name='is_lt'/><doc placeholder='true'>
+
<text>
+
<p><tt>is_lt</tt> - compare two svalues</p>
+
+
<tt><p>#include <svalue.h><br/>
+
+
</p>
+
<p>int is_lt(struct svalue *<i>a</i>, struct svalue *<i>b</i>);<br/>
+
</p>
+
</tt>
+
<p>This is the equivialent of the Pike operator `<. It compares the
+
contents of two svalues and returns true if the 'a' is lesser than
+
'b'. It will give an error if the types are not comparable.</p>
+
</text>
+
+
<group><note/><text>
+
<p>is_gt, is_ge and is_le are also available. They are all macros that
+
call this function.</p>
+
+
svalue</text></group>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::is_eq' to='is_eq'>is_eq</ref> and <ref resolved='c::is_equal' to='is_equal'>is_equal</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='low_mapping_lookup' homogen-type='method'>
+
<method name='low_mapping_lookup'/><doc placeholder='true'>
+
<text>
+
<p><tt>low_mapping_lookup</tt> - lookup a key in a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>struct svalue *low_mapping_lookup(struct mapping *m,<br/>
+
<dl><group><text>struct svalue *key);<br/>
+
</text></group></dl></p>
+
</tt>
+
<p>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.</p>
+
</text>
+
+
<group><note/><text>
+
<p>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.</p>
+
</text></group>
+
+
<group><note/><text>
+
<p>This function is intended for _reading_ mappings, it is forbidden
+
to change the contents of the returned svalue.</p>
+
+
mapping</text></group>
+
+
<group><seealso/><text>
+
<p><ref to='map_insert'>map_insert</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='m_sizeof' homogen-type='method'>
+
<method name='m_sizeof'/><doc placeholder='true'>
+
<text>
+
<p><tt>m_sizeof</tt> - return the number of key-value pairs in a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>int m_sizeof(struct mapping *m)<br/>
+
</p>
+
</tt>
+
<p>This function returns the number of key-index pairs in the mapping,
+
just like the function sizeof() in Pike.</p>
+
</text>
+
+
<group><note/><text>
+
<p>m_sizeof is a macro</p>
+
+
mapping</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='make_shared_binary_string' homogen-type='method'>
+
<method name='make_shared_binary_string'/><doc placeholder='true'>
+
<text>
+
<p><tt>make_shared_binary_string</tt> - make a shared string</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *make_shared_binary_string(const char *<i>str</i>, int <i>len</i>);<br/>
+
</p>
+
</tt>
+
<p>This function makes a shared string from the memory area beginning
+
at 'str' and ends at str+len. The returned string will have one
+
extra reference.</p>
+
+
pike_string</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::make_shared_string' to='make_shared_string'>make_shared_string</ref>, <ref resolved='c::begin_shared_string' to='begin_shared_string'>begin_shared_string</ref>, <ref resolved='c::push_string' to='push_string'>push_string</ref> and <ref resolved='c::free_string' to='free_string'>free_string</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='make_shared_string' homogen-type='method'>
+
<method name='make_shared_string'/><doc placeholder='true'>
+
<text>
+
<p><tt>make_shared_string</tt> - make a shared string</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *make_shared_string(const char *<i>str</i>);<br/>
+
</p>
+
</tt>
+
<p>This function does the same thing as make_shared_binary_string, but
+
expects a zero terminated string instead.</p>
+
+
pike_string</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::make_shared_binary_string' to='make_shared_binary_string'>make_shared_binary_string</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='map_delete' homogen-type='method'>
+
<method name='map_delete'/><doc placeholder='true'>
+
<text>
+
<p><tt>map_delete</tt> - delete an item from a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>void map_delete(struct mapping *<i>m</i>, struct svalue *<i>key</i>);<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
+
mapping</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::mapping_insert' to='mapping_insert'>mapping_insert</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='mapping' homogen-type='method'>
+
<method name='mapping'/><doc placeholder='true'>
+
<text>
+
<p><tt>mapping</tt> - internal pike mappings</p>
+
+
<p>'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.
+
</p>
+
<p>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.</p>
+
+
internals</text>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='mapping_indices' homogen-type='method'>
+
<method name='mapping_indices'/><doc placeholder='true'>
+
<text>
+
<p><tt>mapping_indices</tt> - return all the keys from a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>struct array *mapping_indices(struct mapping *m)<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
+
mapping</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::mapping_values' to='mapping_values'>mapping_values</ref> and <ref resolved='c::mkmapping' to='mkmapping'>mkmapping</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='mapping_insert' homogen-type='method'>
+
<method name='mapping_insert'/><doc placeholder='true'>
+
<text>
+
<p><tt>mapping_insert</tt> - insert a key-value pair into a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>void mapping_insert(struct mapping *m,<br/>
+
<dl><group><text>struct svalue *key,<br/>
+
struct svalue *value)<br/>
+
</text></group></dl></p>
+
</tt>
+
<p>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</p>
+
+
mapping</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::map_delete' to='map_delete'>map_delete</ref> and <ref resolved='c::low_mapping_lookup' to='low_mapping_lookup'>low_mapping_lookup</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='mapping_replace' homogen-type='method'>
+
<method name='mapping_replace'/><doc placeholder='true'>
+
<text>
+
<p><tt>mapping_replace</tt> - replace values in a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>void mapping_replace(struct mapping *m,<br/>
+
<dl><group><text>struct svalue *from,<br/>
+
struct svalue *to)<br/>
+
</text></group></dl></p>
+
</tt>
+
<p>This function replaces all values of the value 'from' in the mapping
+
'm' with 'to'. It is a part of the Pike function replace().</p>
+
+
mapping</text>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='mapping_values' homogen-type='method'>
+
<method name='mapping_values'/><doc placeholder='true'>
+
<text>
+
<p><tt>mapping_values</tt> - return all the values from a mapping</p>
+
+
<tt><p>#include "mapping.h"<br/>
+
+
</p>
+
<p>struct array *mapping_values(struct mapping *m)<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
</text>
+
+
<group><example/><text>
+
<tt><p>struct mapping *slow_copy_mapping(struct mapping *m)<br/>
+
{<br/>
+
<dl><group><text>struct array *indices, *values;<br/>
+
indices=mapping_indices(m);<br/>
+
values=mapping_indices(m);<br/>
+
m=mkmapping(indices,values);<br/>
+
free_array(indices);<br/>
+
free_array(values);<br/>
+
return m;<br/>
+
</text></group></dl>}<br/>
+
</p>
+
</tt>
+
mapping</text></group>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::mapping_indices' to='mapping_indices'>mapping_indices</ref>, <ref resolved='c::copy_mapping' to='copy_mapping'>copy_mapping</ref> and <ref resolved='c::mkmapping' to='mkmapping'>mkmapping</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='mkmapping' homogen-type='method'>
+
<method name='mkmapping'/><doc placeholder='true'>
+
<text>
+
<p><tt>mkmapping</tt> - make a mapping</p>
+
+
<tt><p>#include <mapping.h><br/>
+
+
</p>
+
<p>struct mapping *mkmapping(struct array *keys, struct array *values)<br/>
+
</p>
+
</tt>
+
<p>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.</p>
+
+
mapping</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::mapping_indices' to='mapping_indices'>mapping_indices</ref> and <ref resolved='c::mapping_values' to='mapping_values'>mapping_values</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='my_strcmp' homogen-type='method'>
+
<method name='my_strcmp'/><doc placeholder='true'>
+
<text>
+
<p><tt>my_strcmp</tt> - my own strcmp function</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>int my_strcmp(struct pike_string *a, struct pike_string *b)<br/>
+
</p>
+
</tt>
+
<p>This function compares two pike strings and takes locales into
+
account if the system supports locales. It returns zero if the
+
strings are the same, a number greater than zero zero if 'a'
+
is greater than 'b', and a number below zero otherwise.</p>
+
+
pike_string</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::make_shared_string' to='make_shared_string'>make_shared_string</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='pike_string' homogen-type='method'>
+
<method name='pike_string'/><doc placeholder='true'>
+
<text>
+
<p><tt>pike_string</tt> - internal pike shared strings</p>
+
+
<p>This is the internal type for representing pike strings. They have
+
ref counts and they are shared though a global hash table. The C
+
type is a struct pike_string that has two public members: str and
+
len. str is an array of char which contain the actual string. It
+
is guaranteed that the string is null terminated, but the string
+
can also contain zeroes before the end. len is of course the
+
length of the string. Since strings are shared you may _never_
+
modify the contents of a string, except for adding/subtracting
+
references when approperiate. The only exception to this is when
+
creating a new shared string with begin_shared_string which has
+
not yet been linked to the hash table with end_shared_string.</p>
+
+
internals</text>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='program' homogen-type='method'>
+
<method name='program'/><doc placeholder='true'>
+
<text>
+
<p><tt>program</tt> - internal representation of a program</p>
+
+
<p>A 'struct program' is basically what C++ hackers call a 'class'.
+
It contains the byte code, information about line numbers,
+
global variables etc. etc. Mostly you won't have to bother with
+
any of the contents of a 'struct program'. Usually you only need
+
to create them with start_new_program()/end_c_program() or
+
clone them with clone().</p>
+
</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::frame' to='frame'>frame</ref></p>
+
+
internal</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='push_string' homogen-type='method'>
+
<method name='push_string'/><doc placeholder='true'>
+
<text>
+
<p><tt>push_string</tt> - push a string on the pike stack</p>
+
+
<tt><p>#include "interpret.h"<br/>
+
+
</p>
+
<p>void push_string(struct pike_string *p)<br/>
+
</p>
+
</tt>
+
<p><matrix>
+
<r><c> This function pushes the string p on the pike stack. Note that this </c></r>
+
<r><c> function does _not_ add any extra references to 'p'. Most functions </c></r>
+
<r><c> that create shared strings give one extra reference to them though. </c></r>
+
<r><c> If you get your string from a function that does not add extra </c><c> </c></r>
+
<r><c> references you will have to add a reference manually. </c></r>
+
</matrix>
+
</p>
+
</text>
+
+
<group><note/><text>
+
<p>push_string is actually a macro</p>
+
+
pike_string</text></group>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='string_replace' homogen-type='method'>
+
<method name='string_replace'/><doc placeholder='true'>
+
<text>
+
<p><tt>string_replace</tt> - do string replacements</p>
+
+
<tt><p>#include "stralloc.h"<br/>
+
+
</p>
+
<p>struct pike_string *string_replace(struct pike_string *str,<br/>
+
<dl><group><text>struct pike_string *from,<br/>
+
struct pike_string *to);<br/>
+
</text></group></dl></p>
+
</tt>
+
<p>This function builds a new string from 'str' with all occurances
+
of 'from' replaced by 'to'. Note that the new string will have one
+
extra reference.</p>
+
+
pike_string</text>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='svalue' homogen-type='method'>
+
<method name='svalue'/><doc placeholder='true'>
+
<text>
+
<p><tt>svalue</tt> - internal type for storing Pike values</p>
+
+
<p>The 'struct svalue' contains one Pike 'value', variables, arrays
+
and the evaluator are all svalues. An svalue consists of three
+
elements: type, subtype and a union containing the actual value.
+
The type is a short which tells you what type the svalue is. The
+
value is one of the following:
+
</p>
+
<p><matrix>
+
<r><c> T_ARRAY </c><c> When type is T_ARRAY, the array is stored in </c></r>
+
<r><c> </c></r>
+
</matrix>
+
<dl><group><text><matrix>
+
<r><c> </c><c> the 'array' member of the union. So if sval is </c></r>
+
<r><c> </c></r>
+
</matrix>
+
<matrix>
+
<r><c> </c><c> the pointer to the svalue, you would use sval->u.array </c></r>
+
<r><c> </c></r>
+
</matrix>
+
<matrix>
+
<r><c> </c><c> to access the actual array. </c></r>
+
<r><c> </c></r>
+
</matrix>
+
</text></group></dl><matrix>
+
<r><c> T_MAPPING </c><c> In this case, you use sval->u.mapping. </c></r>
+
<r><c> T_MULTISET </c><c> sval->u.multiset </c></r>
+
<r><c> T_OBJECT </c><c> sval->u.object </c></r>
+
<r><c> T_FUNCTION </c><c> Functions are a bit more difficult, sval->u.object </c></r>
+
</matrix>
+
<dl><group><text><matrix>
+
<r><c> </c><c> is the object the function is in, and sval->subtype </c></r>
+
<r><c> </c></r>
+
</matrix>
+
<matrix>
+
<r><c> </c><c> is the number of the function in that object. </c></r>
+
<r><c> </c></r>
+
</matrix>
+
</text></group></dl><matrix>
+
<r><c> T_PROGRAM </c><c> sval->u.program is the struct program you want. </c></r>
+
<r><c> T_STRING </c><c> sval->u.string </c></r>
+
<r><c> T_FLOAT </c><c> sval->u.float_number </c></r>
+
<r><c> T_INT </c><c> sval->u.integer, a special case is that sval->subtype </c></r>
+
</matrix>
+
<dl><group><text><matrix>
+
<r><c> </c><c> is used in some cases to represent the value </c></r>
+
<r><c> </c><c> 'undefined'. This is what zero_type detects. </c></r>
+
</matrix>
+
</text></group></dl>
+
</p>
+
<p>There are lots of functions operating on svalues, so you shouldn't
+
have to do all that much stuff with them yourself. However, for now
+
you do need to check the type and extract the proper member of the
+
union yourself when writing your own C functions for Pike.</p>
+
+
internals</text>
+
+
</doc>
+
</docgroup>
+
<docgroup homogen-name='type_field' homogen-type='method'>
+
<method name='type_field'/><doc placeholder='true'>
+
<text>
+
<p><tt>type_field</tt> - bit field used for optimizations</p>
+
+
<p>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.
+
</p>
+
<p>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.</p>
+
</text>
+
+
<group><seealso/><text>
+
<p><ref resolved='c::mapping' to='mapping'>mapping</ref>, <ref resolved='c::array' to='array'>array</ref> and <ref resolved='c::svalue' to='svalue'>svalue</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
+
</namespace>
<namespace name='cpp'> <doc placeholder='true'> <text>
265:
</doc> </docgroup>
-
<docgroup homogen-name='IS_ZERO' homogen-type='method'>
-
<method name='IS_ZERO'/><doc placeholder='true'>
-
<text>
-
<p><tt>IS_ZERO</tt> - is this svalue considered 'false'</p>
-
-
<tt><p>#include <simulate.h><br/>
-
-
</p>
-
<p>int IS_ZERO(struct svalue *<i>s</i>);<br/>
-
</p>
-
</tt>
-
<p>IS_ZERO returns true if the svalue 's' is a zero. (or an object with
-
`! operator that returned true..)</p>
-
</text>
-
-
<group><note/><text>
-
<p>IS_ZERO is actually a macro</p>
-
-
svalue</text></group>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::is_eq' to='is_eq'>is_eq</ref>, <ref resolved='predef::is_equal' to='is_equal'>is_equal</ref> and <ref resolved='predef::is_lt' to='is_lt'>is_lt</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='PI' homogen-type='constant'> <constant name='PI'/><doc placeholder='true'> <text>
886:
</doc> </docgroup>
-
<docgroup homogen-name='add_shared_strings' homogen-type='method'>
-
<method name='add_shared_strings'/><doc placeholder='true'>
-
<text>
-
<p><tt>add_shared_strings</tt> - add two pike strings</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *add_shared_strings(struct pike_string *a,<br/>
-
<dl><group><text>struct pike_string *b);<br/>
-
</text></group></dl></p>
-
</tt>
-
<p>This function builds the string a+b, that is the string a with the
-
string b appended to it. Note that the string returned will have
-
an extra reference.</p>
-
-
pike_string</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::begin_shared_string' to='begin_shared_string'>begin_shared_string</ref> and <ref to='make_shared_string'>make_shared_string</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='aggregage_list' homogen-type='method'> <method name='aggregage_list'/><doc placeholder='true'> <text>
1190:
</doc> </docgroup>
-
<docgroup homogen-name='assign_svalue' homogen-type='method'>
-
<method name='assign_svalue'/><doc placeholder='true'>
-
<text>
-
<p><tt>assign_svalue</tt> - copy svalues from one place to another</p>
-
-
<tt><p>#include <svalue.h><br/>
-
-
</p>
-
<p>void assign_svalue(struct svale *<i>to</i>, struct svalue *<i>from</i>);<br/>
-
</p>
-
</tt>
-
<p>This function copies an svalue from one struct svalue to another.
-
It frees the contents of 'to' first and updates the involved
-
refcounts.</p>
-
-
svalue</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::free_svalue' to='free_svalue'>free_svalue</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='atan' homogen-type='method'> <method name='atan'/><doc placeholder='true'> <text>
1262:
</doc> </docgroup>
-
<docgroup homogen-name='begin_shared_string' homogen-type='method'>
-
<method name='begin_shared_string'/><doc placeholder='true'>
-
<text>
-
<p><tt>begin_shared_string</tt> - allocate space for a shared string</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *begin_shared_string(INT32 <i>len</i>);<br/>
-
</p>
-
</tt>
-
<p>This function allocates space for a shared string of length 'len'.
-
You should then MEMCPY 'len' bytes into the s->str. (s being the
-
returned value) And then call end_shared_string.</p>
-
-
pike_string</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::end_shared_string' to='end_shared_string'>end_shared_string</ref> and <ref to='make_shared_string'>make_shared_string</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
-
<docgroup homogen-name='binary_findstring' homogen-type='method'>
-
<method name='binary_findstring'/><doc placeholder='true'>
-
<text>
-
<p><tt>binary_findstring</tt> - find a string</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *binary_findstring(char *<i>str</i>, INT32 <i>length</i>);<br/>
-
</p>
-
</tt>
-
<p>This function looks for the 'str' with length 'len' in the
-
global hash table. It returns the shared string if found, otherwise
-
zero. It does not increase/decrease the references to the string.</p>
-
-
pike_string</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::findstring' to='findstring'>findstring</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='break' homogen-type='method'> <method name='break'/><doc placeholder='true'> <text>
1479:
<docgroup homogen-name='catch' homogen-type='method'> <method name='catch'/><doc placeholder='true'> <text>
-
<p><tt>catch</tt> - catch errorrs</p>
-
-
<tt><p>catch { commands }<br/>
-
or<br/>
-
catch ( expression )<br/>
-
</p>
-
</tt>
-
<p>catch traps exceptions such as run time errors or calls to throw() and
-
returns the argument given to throw. For a run time error, this value
-
is ({ "error message", backtrace }) </p>
-
</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::throw' to='predef::throw'>builtin/throw</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
-
<docgroup homogen-name='catch' homogen-type='method'>
-
<method name='catch'/><doc placeholder='true'>
-
<text>
+
<p><tt>catch</tt> - catch errors</p> <tt><p>catch { commands }<br/>
1883:
</doc> </docgroup>
-
<docgroup homogen-name='end_shared_string' homogen-type='method'>
-
<method name='end_shared_string'/><doc placeholder='true'>
-
<text>
-
<p><tt>end_shared_string</tt> - link a shared string into the hashtable</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *end_shared_string(struct pike_string *<i>p</i>);<br/>
-
</p>
-
</tt>
-
<p>This function the prepared output from a begin_shared_string and
-
links the string into the hash table. If an identical string is
-
already present in the hash table, p is freed and that string is
-
returned instead. The returned string will have one extra reference
-
added.</p>
-
</text>
-
-
<group><example/><text>
-
<tt><p>#include "global.h"<br/>
-
#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *mkcharstring(int ch)<br/>
-
{<br/>
-
<dl><group><text>struct pike_string *ret;<br/>
-
ret=begin_shared_string(1);<br/>
-
ret->str[0]=ch;<br/>
-
return end_shared_string(ret);<br/>
-
</text></group></dl>}<br/>
-
</p>
-
</tt>
-
pike_string</text></group>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::begin_shared_string' to='begin_shared_string'>begin_shared_string</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='equal' homogen-type='method'> <method name='equal'/><doc placeholder='true'> <text>
2314:
</doc> </docgroup>
-
<docgroup homogen-name='findstring' homogen-type='method'>
-
<method name='findstring'/><doc placeholder='true'>
-
<text>
-
<p><tt>findstring</tt> - find a string</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *findstring(char *<i>str</i>);<br/>
-
</p>
-
</tt>
-
<p>This function looks for the null terminated C string 'str' in the
-
global hash table. It returns the shared string if found, otherwise
-
zero. It does not increase/decrease the references to the string.</p>
-
-
pike_string</text>
-
-
<group><seealso/><text>
-
<p><ref to='make_shared_string'>make_shared_string</ref> and <ref resolved='predef::binary_findstring' to='binary_findstring'>binary_findstring</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='float' homogen-type='method'> <method name='float'/><doc placeholder='true'> <text>
2501:
</doc> </docgroup>
-
<docgroup homogen-name='free_string' homogen-type='method'>
-
<method name='free_string'/><doc placeholder='true'>
-
<text>
-
<p><tt>free_string</tt> - free a pike string</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>void free_string(struct pike_string *p)<br/>
-
</p>
-
</tt>
-
<p>This function frees the string 'p'. What it actually does is that it
-
decreases the reference count of 'p' and frees the memory reserved
-
for it if the refereneces reach zero.</p>
-
</text>
-
-
<group><note/><text>
-
<p>free_string is actually a macro</p>
-
-
pike_string</text></group>
-
-
</doc>
-
</docgroup>
-
<docgroup homogen-name='free_svalue' homogen-type='method'>
-
<method name='free_svalue'/><doc placeholder='true'>
-
<text>
-
<p><tt>free_svalue</tt> - free the contents of an svalue</p>
-
-
<tt><p>#include <svalue.h><br/>
-
-
</p>
-
<p>void free_svalue(struct svalue *<i>s</i>);<br/>
-
</p>
-
</tt>
-
<p>This function frees the contents of an svalue with respect to
-
ref counts. It does not however free the storage for svalue itself.
-
That is up to the caller to do.</p>
-
-
svalue</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::assign_svalue' to='assign_svalue'>assign_svalue</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='function' homogen-type='method'> <method name='function'/><doc placeholder='true'> <text>
3053:
</doc> </docgroup>
+
<docgroup homogen-name='implode_nicely' homogen-type='method'>
+
<method name='implode_nicely'/><doc placeholder='true'>
+
<text>
+
<p><tt>implode_nicely</tt> - make an english comma separated list</p>
+
+
<tt><p>#include <string.h><br/>
+
+
</p>
+
<p>string implode_nicely(string *words, string|void separator)<br/>
+
</p>
+
</tt>
+
<p>This function implodes a list of words to a readable string.
+
If the separator is omitted, the default is 'and'.</p>
+
</text>
+
+
<group><example/><text>
+
<tt><p>> implode_nicely(({"green"}));<br/>
+
Result: green<br/>
+
> implode_nicely(({"green","blue"}));<br/>
+
Result: green and blue<br/>
+
> implode_nicely(({"green","blue","white"}));<br/>
+
Result: green, blue and white<br/>
+
> implode_nicely(({"green","blue","white"}),"or");<br/>
+
Result: green, blue or white<br/>
+
</p>
+
</tt>
+
string</text></group>
+
+
<group><seealso/><text>
+
<p><ref resolved='predef::`*' to='`*'>`*</ref></p>
+
</text></group>
+
+
</doc>
+
</docgroup>
<docgroup homogen-name='index' homogen-type='method'> <method name='index'/><doc placeholder='true'> <text>
3248:
</doc> </docgroup>
-
<docgroup homogen-name='is_eq' homogen-type='method'>
-
<method name='is_eq'/><doc placeholder='true'>
-
<text>
-
<p><tt>is_eq</tt> - compare two svalues</p>
-
-
<tt><p>#include <svalue.h><br/>
-
-
</p>
-
<p>int is_eq(struct svalue *<i>a</i>, struct svalue *<i>b</i>);<br/>
-
</p>
-
</tt>
-
<p>This is the equivialent of the Pike operator `==. It compares two
-
svalues and returns one if they are the same. Otherwise zero.</p>
-
-
svalue</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::is_equal' to='is_equal'>is_equal</ref>, <ref resolved='predef::is_lt' to='is_lt'>is_lt</ref> and <ref resolved='predef::IS_ZERO' to='IS_ZERO'>IS_ZERO</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
-
<docgroup homogen-name='is_equal' homogen-type='method'>
-
<method name='is_equal'/><doc placeholder='true'>
-
<text>
-
<p><tt>is_equal</tt> - compare two svalues recursively</p>
-
-
<tt><p>#include <svalue.h><br/>
-
-
</p>
-
<p>int is_equal(struct svalue *<i>a</i>, struct svalue *<i>b</i>);<br/>
-
</p>
-
</tt>
-
<p>This is the equivialent of the Pike function equal(), it compares
-
two svalues recursively and returns 1 if their contents are equal,
-
zero otherwise.</p>
-
-
svalue</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::is_eq' to='is_eq'>is_eq</ref>, <ref resolved='predef::is_lt' to='is_lt'>is_lt</ref> and <ref resolved='predef::IS_ZERO' to='IS_ZERO'>IS_ZERO</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
-
<docgroup homogen-name='is_lt' homogen-type='method'>
-
<method name='is_lt'/><doc placeholder='true'>
-
<text>
-
<p><tt>is_lt</tt> - compare two svalues</p>
-
-
<tt><p>#include <svalue.h><br/>
-
-
</p>
-
<p>int is_lt(struct svalue *<i>a</i>, struct svalue *<i>b</i>);<br/>
-
</p>
-
</tt>
-
<p>This is the equivialent of the Pike operator `<. It compares the
-
contents of two svalues and returns true if the 'a' is lesser than
-
'b'. It will give an error if the types are not comparable.</p>
-
</text>
-
-
<group><note/><text>
-
<p>is_gt, is_ge and is_le are also available. They are all macros that
-
call this function.</p>
-
-
svalue</text></group>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::is_eq' to='is_eq'>is_eq</ref> and <ref resolved='predef::is_equal' to='is_equal'>is_equal</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='kill' homogen-type='method'> <method name='kill'/><doc placeholder='true'> <text>
3658:
</doc> </docgroup>
-
<docgroup homogen-name='make_shared_binary_string' homogen-type='method'>
-
<method name='make_shared_binary_string'/><doc placeholder='true'>
-
<text>
-
<p><tt>make_shared_binary_string</tt> - make a shared string</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *make_shared_binary_string(const char *<i>str</i>, int <i>len</i>);<br/>
-
</p>
-
</tt>
-
<p>This function makes a shared string from the memory area beginning
-
at 'str' and ends at str+len. The returned string will have one
-
extra reference.</p>
-
-
pike_string</text>
-
-
<group><seealso/><text>
-
<p><ref to='make_shared_string'>make_shared_string</ref>, <ref resolved='predef::begin_shared_string' to='begin_shared_string'>begin_shared_string</ref>, <ref resolved='predef::push_string' to='push_string'>push_string</ref> and <ref resolved='predef::free_string' to='free_string'>free_string</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
-
<docgroup homogen-name='make_shared_binary_string' homogen-type='method'>
-
<method name='make_shared_binary_string'/><doc placeholder='true'>
-
<text>
-
<p><tt>make_shared_binary_string</tt> - make a shared string</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *make_shared_string(const char *<i>str</i>);<br/>
-
</p>
-
</tt>
-
<p>This function does the same thing as make_shared_binary_string, but
-
expects a zero terminated string instead.</p>
-
-
pike_string</text>
-
-
<group><seealso/><text>
-
<p><ref resolved='predef::make_shared_binary_string' to='make_shared_binary_string'>make_shared_binary_string</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='map' homogen-type='method'> <method name='map'/><doc placeholder='true'> <text>
4063:
</doc> </docgroup>
-
<docgroup homogen-name='my_strcmp' homogen-type='method'>
-
<method name='my_strcmp'/><doc placeholder='true'>
-
<text>
-
<p><tt>my_strcmp</tt> - my own strcmp function</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>int my_strcmp(struct pike_string *a, struct pike_string *b)<br/>
-
</p>
-
</tt>
-
<p>This function compares two pike strings and takes locales into
-
account if the system supports locales. It returns zero if the
-
strings are the same, a number greater than zero zero if 'a'
-
is greater than 'b', and a number below zero otherwise.</p>
-
-
pike_string</text>
-
-
<group><seealso/><text>
-
<p><ref to='make_shared_string'>make_shared_string</ref></p>
-
</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='next_object' homogen-type='method'> <method name='next_object'/><doc placeholder='true'> <text>
4324:
</doc> </docgroup>
-
<docgroup homogen-name='pike_string' homogen-type='method'>
-
<method name='pike_string'/><doc placeholder='true'>
-
<text>
-
<p><tt>pike_string</tt> - internal pike shared strings</p>
-
-
<p>This is the internal type for representing pike strings. They have
-
ref counts and they are shared though a global hash table. The C
-
type is a struct pike_string that has two public members: str and
-
len. str is an array of char which contain the actual string. It
-
is guaranteed that the string is null terminated, but the string
-
can also contain zeroes before the end. len is of course the
-
length of the string. Since strings are shared you may _never_
-
modify the contents of a string, except for adding/subtracting
-
references when approperiate. The only exception to this is when
-
creating a new shared string with begin_shared_string which has
-
not yet been linked to the hash table with end_shared_string.</p>
-
-
internals</text>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='popen' homogen-type='method'> <method name='popen'/><doc placeholder='true'> <text>
4446:
</doc> </docgroup>
-
<docgroup homogen-name='push_string' homogen-type='method'>
-
<method name='push_string'/><doc placeholder='true'>
-
<text>
-
<p><tt>push_string</tt> - push a string on the pike stack</p>
-
-
<tt><p>#include "interpret.h"<br/>
-
-
</p>
-
<p>void push_string(struct pike_string *p)<br/>
-
</p>
-
</tt>
-
<p><matrix>
-
<r><c> This function pushes the string p on the pike stack. Note that this </c></r>
-
<r><c> function does _not_ add any extra references to 'p'. Most functions </c></r>
-
<r><c> that create shared strings give one extra reference to them though. </c></r>
-
<r><c> If you get your string from a function that does not add extra </c><c> </c></r>
-
<r><c> references you will have to add a reference manually. </c></r>
-
</matrix>
-
</p>
-
</text>
-
-
<group><note/><text>
-
<p>push_string is actually a macro</p>
-
-
pike_string</text></group>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='putenv' homogen-type='method'> <method name='putenv'/><doc placeholder='true'> <text>
4643:
</doc> </docgroup>
-
<docgroup homogen-name='read_
bytes
' homogen-type='method'>
-
<method name='read_
bytes
'/><doc placeholder='true'>
+
<docgroup homogen-name='read_
file
' homogen-type='method'>
+
<method name='read_
file
'/><doc placeholder='true'>
<text>
-
<p><tt>read_
bytes
</tt> - read a number of lines into a string from file</p>
+
<p><tt>read_
file
</tt> - read a number of lines into a string from file</p>
<tt><p>#include <stdio.h><br/>
5584:
</doc> </docgroup>
-
<docgroup homogen-name='string_replace' homogen-type='method'>
-
<method name='string_replace'/><doc placeholder='true'>
-
<text>
-
<p><tt>string_replace</tt> - do string replacements</p>
-
-
<tt><p>#include "stralloc.h"<br/>
-
-
</p>
-
<p>struct pike_string *string_replace(struct pike_string *str,<br/>
-
<dl><group><text>struct pike_string *from,<br/>
-
struct pike_string *to);<br/>
-
</text></group></dl></p>
-
</tt>
-
<p>This function builds a new string from 'str' with all occurances
-
of 'from' replaced by 'to'. Note that the new string will have one
-
extra reference.</p>
-
-
pike_string</text>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='stringp' homogen-type='method'> <method name='stringp'/><doc placeholder='true'> <text>
5748:
</doc> </docgroup>
-
<docgroup homogen-name='svalue' homogen-type='method'>
-
<method name='svalue'/><doc placeholder='true'>
-
<text>
-
<p><tt>svalue</tt> - internal type for storing Pike values</p>
-
-
<p>The 'struct svalue' contains one Pike 'value', variables, arrays
-
and the evaluator are all svalues. An svalue consists of three
-
elements: type, subtype and a union containing the actual value.
-
The type is a short which tells you what type the svalue is. The
-
value is one of the following:
-
</p>
-
<p><matrix>
-
<r><c> T_ARRAY </c><c> When type is T_ARRAY, the array is stored in </c></r>
-
<r><c> </c></r>
-
</matrix>
-
<dl><group><text><matrix>
-
<r><c> </c><c> the 'array' member of the union. So if sval is </c></r>
-
<r><c> </c></r>
-
</matrix>
-
<matrix>
-
<r><c> </c><c> the pointer to the svalue, you would use sval->u.array </c></r>
-
<r><c> </c></r>
-
</matrix>
-
<matrix>
-
<r><c> </c><c> to access the actual array. </c></r>
-
<r><c> </c></r>
-
</matrix>
-
</text></group></dl><matrix>
-
<r><c> T_MAPPING </c><c> In this case, you use sval->u.mapping. </c></r>
-
<r><c> T_MULTISET </c><c> sval->u.multiset </c></r>
-
<r><c> T_OBJECT </c><c> sval->u.object </c></r>
-
<r><c> T_FUNCTION </c><c> Functions are a bit more difficult, sval->u.object </c></r>
-
</matrix>
-
<dl><group><text><matrix>
-
<r><c> </c><c> is the object the function is in, and sval->subtype </c></r>
-
<r><c> </c></r>
-
</matrix>
-
<matrix>
-
<r><c> </c><c> is the number of the function in that object. </c></r>
-
<r><c> </c></r>
-
</matrix>
-
</text></group></dl><matrix>
-
<r><c> T_PROGRAM </c><c> sval->u.program is the struct program you want. </c></r>
-
<r><c> T_STRING </c><c> sval->u.string </c></r>
-
<r><c> T_FLOAT </c><c> sval->u.float_number </c></r>
-
<r><c> T_INT </c><c> sval->u.integer, a special case is that sval->subtype </c></r>
-
</matrix>
-
<dl><group><text><matrix>
-
<r><c> </c><c> is used in some cases to represent the value </c></r>
-
<r><c> </c><c> 'undefined'. This is what zero_type detects. </c></r>
-
</matrix>
-
</text></group></dl>
-
</p>
-
<p>There are lots of functions operating on svalues, so you shouldn't
-
have to do all that much stuff with them yourself. However, for now
-
you do need to check the type and extract the proper member of the
-
union yourself when writing your own C functions for Pike.</p>
-
-
internals</text>
-
-
</doc>
-
</docgroup>
+
<docgroup homogen-name='switch' homogen-type='method'> <method name='switch'/><doc placeholder='true'> <text>
6095:
</doc> </docgroup>
+
<docgroup homogen-name='uniq' homogen-type='method'>
+
<method name='uniq'/><doc placeholder='true'>
+
<text>
+
<p><tt>uniq</tt> - return one of each element</p>
+
+
<tt><p>#include <array.h><br/>
+
+
</p>
+
<p>array uniq(array <i>a</i>);<br/>
+
</p>
+
</tt>
+
<p>This function returns an copy of the array a with all duplicate
+
values removed. The order of the values in the result is undefined.</p>
+
+
array</text>
+
+
</doc>
+
</docgroup>
<docgroup homogen-name='upper_case' homogen-type='method'> <method name='upper_case'/><doc placeholder='true'> <text>