*!
*! Except of course it is a lot shorter and faster.
*! That is, it indices every index in the array data on the value of
*! the argument index and returns an array with the results.
*!
*! @seealso
*! @[rows()]
*/

*! This function changes the trace level for the subsystem identified
*! by @[facility] to @[level]. If @[facility] is zero or left out, it
*! changes the global trace level which affects all subsystems.

/*! @decl mapping(string:float) gc_parameters (void|mapping(string:mixed) params)
*! @belongs Pike
*!
*! Set and get various parameters that control the operation of the
*! garbage collector. The passed mapping contains the parameters to
*! set. If a parameter is missing from the mapping, the current value
*! will be filled in instead. The same mapping is returned. Thus an
*! empty mapping, or no argument at all, causes a mapping with all
*! current settings to be returned.
*!
*! The following parameters are recognized:
*!
*! @mapping
*! @member int "enabled"

*! If this is 1 then the gc is enabled as usual. If it's 0 then all
*! automatically scheduled gc runs are disabled and the parameters
*! below have no effect, but explicit runs through the @[gc]
*! function still works as usual. If it's -1 then the gc is
*! completely disabled so that even explicit @[gc] calls won't do
*! anything.

*! @member float "garbage_ratio_low"
*! As long as the gc time is less than gc_time_ratio, aim to run
*! the gc approximately every time the ratio between the garbage
*! and the total amount of allocated things is this.
*! @member float "time_ratio"
*! When more than this fraction of the cpu time is spent in the gc,
*! aim for gc_garbage_ratio_high instead of gc_garbage_ratio_low.
*! @member float "garbage_ratio_high"
*! Upper limit for the garbage ratio - run the gc as often as it
*! takes to keep it below this.
*! @member float "average_slowness"
*! When predicting the next gc interval, use a decaying average
*! with this slowness factor. It should be a value between 0.0 and
*! 1.0 that specifies the weight to give to the old average value.
*! The remaining weight up to 1.0 is given to the last reading.
*! @endmapping
*!
*! @seealso
*! @[gc], @[Debug.gc_status]
*/
PIKEFUN mapping(string:mixed) gc_parameters (void|mapping(string:mixed) params)
errname Pike.gc_parameters;
optflags OPT_SIDE_EFFECT;
{
struct pike_string *str;
struct svalue *set;
struct svalue get;
if (!params) {
push_mapping (allocate_mapping (5));

*! Like @[localtime], this function might throw an error if the
*! ctime(2) call failed on the system. It's platform dependent what
*! time ranges that function can handle, e.g. Windows doesn't handle
*! a negative @[timestamp].

*! Count the number of non-overlapping times the string @[needle]
*! occurs in the string @[haystack]. The special cases for the needle
*! @expr{""@} is that it occurs one time in the empty string, zero
*! times in a one character string and between every character
*! (length-1) in any other string.

/*! @decl mixed lfun::_random()
*! Called by @[random]. Typical uses is when the object implements
*! a ADT, then a call to this lfun should return a random member of
*! the ADT or range implied by the ADT.
*! @seealso
*! @[predef::random()]
*/

/*! @decl array(Pike.BacktraceFrame) backtrace()
*!
*! FIXME: This documentation is not up to date!
*!
*! Get a description of the current call stack.
*!
*! The description is returned as an array with one entry for each call
*! frame on the stack.
*!
*! Each entry has this format:
*! @array
*! @elem string file
*! A string with the filename if known, else zero.
*! @elem int line
*! An integer containing the linenumber if known, else zero.
*! @elem function fun
*! The function that was called at this level.
*! @elem mixed|void ... args
*! The arguments that the function was called with.
*! @endarray
*!
*! The current call frame will be last in the array.
*!
*! @note
*! Please note that the frame order may be reversed in a later version

*!
*! Note that the arguments reported in the backtrace are the current
*! values of the variables, and not the ones that were at call-time.
*! This can be used to hide sensitive information from backtraces
*! (eg passwords).
*!
*! @seealso
*! @[catch()], @[throw()]
*/
PMOD_EXPORT
PIKEFUN array(mixed) backtrace()
efun;
optflags OPT_EXTERNAL_DEPEND;
{
low_backtrace(& Pike_interpreter);
}

#define INITIAL_BUF_LEN 4096
/*! @module String
*/
/*! @class Buffer
*! A buffer, used for building strings. It's
*! conceptually similar to a string, but you can only @[add]
*! strings to it, and you can only @[get] the value from it once.
*!
*! There is a reason for those seemingly rather odd limitations,
*! it makes it possible to do some optimizations that really speed
*! things up.
*!
*! You do not need to use this class unless you add very many
*! strings together, or very large strings.
*!
*! @example
*! For the fastest possible operation, write your code like this:
*!

*!
*! This is a "compiled" version of the @[replace] function applied on
*! a string, with more than one replace string. The replace strings
*! are given to the create method as a @i{from@} and @i{to@} array
*! and are then analyzed. The @expr{`()@} is then called with a
*! string and the replace rules in the Replace object will be
*! applied. The Replace object is used internally by the Pike
*! optimizer and need not be used manually.

*!
*! This is a "compiled" version of the @[replace] function applied on
*! a string, with just one replace string. The replace strings are
*! given to the create method as a @i{from@} and @i{tom@} string and
*! are then analyzed. The @expr{`()@} is then called with a string
*! and the replace rule in the Replace object will be applied. The
*! Replace object is used internally by the Pike optimizer and need
*! not be used manually.

*! @param initial_bias
*! The initial bias for the variable-length integer thresholding.
*! initial_bias % base must be <= base - tmin.
*! @param initial_n
*! The first code point outside the "basic" set of code points.
*! @param delim
*! The "basic" code point used as the delimiter.
*! @param digits
*! The "basic" code points used as digits. The length of the string
*! should be the same as the base parameter.
*/

/*! @module System
*/
/*! @class Time
*!
*! The current time as a structure containing a sec and a usec
*! member.
*/
PIKECLASS Time
{
CVAR int hard_update;
/*! @decl int sec;
*! @decl int usec;
*!
*! The number of seconds and microseconds since the epoch and the
*! last whole second, respectively. (See also @[predef::time()])
*!
*! Please note that these variables will continually update when
*! they are requested, there is no need to create new Time()
*! objects.
*/
/*! @decl int usec_full;
*!
*! The number of microseconds since the epoch. Please note that
*! pike has to have been compiled with bignum support for this
*! variable to contain sensible values.
*/
PIKEFUN int `->( string x )
{
extern struct timeval current_time;
struct pike_string *usec;
struct pike_string *sec;