Pike has a builtin C-style preprocessor. It works similar to the ANSI-C preprocessor but has a few extra features. These and the default set of preprocessor macros are described here.

The preprocessor is usually accessed via MasterObject->compile_file() or MasterObject->compile_string(), but may be accessed directly by calling cpp().

compile(), cpp(), CompilerEnvironment.CPP

This is the default namespace and contains lots of global symbols.

String containing UTF-8 encoded data.

This is similar to a string(8bit), but allows the compiler to keep track of whether strings are UTF-8 or not.

string_to_utf8(), utf8_to_string()

Zero datatype.

The undefined value; ie a zero for which zero_type() returns 1.

Program used internally by the compiler to create objects that are later modified into instances of the compiled program by the compiler.

__placeholder_object

Object used internally by the compiler.

__null_program

Type constant used for typing extra arguments that are sent to sprintf().

strict_sprintf_format, sprintf_format, sprintf()

Type constant used for typing arguments that are optionally sent to sprintf() depending on the presence of extra arguments.

strict_sprintf_format, sprintf_args, sprintf()

Type constant used for typing the return value from sprintf().

strict_sprintf_format, sprintf_format, sprintf()

Type constant used for typing arguments that are always sent to sprintf() regardless of the presence of extra arguments.

sprintf_format, sprintf_args, sprintf()

Builtin read only variable that evaluates to the current object.

this_program, this_object()

Builtin constant that evaluates to the current function.

continue::this_function, this, this_object()

Builtin constant that evaluates to the current program.

this, this_object()

Create a class that acts as a proxy for the specified program.

Program to generate a proxy for.

The generated class will have the same symbols (public and private) with the same types as in p, where accesses to these will proxy the access to the same symbol in the proxied (aka wrapped) object. With the following exceptions:

protected void create(object(p) obj)

Initialize the object to act as a proxy for obj.

_sprintf(int c, mapping|void params)

Special case for c == 'O', where it will return sprintf("%O(%O)", this_program, obj), and otherwise proxy the call.

void _destruct()/void destroy()

These lfuns will not be present as the act of them being proxied would likely confuse the proxied object.

The same proxy class will be returned if this function is called with the same program multiple times.

Perform a compile-time assertion check.

If constant_expression is false, a compiler error message containing constant_message will be generated.

Note that the function call compiles to the null statement, and thus does not affect the run-time.

cpp::static_assert

Automap execution function.

Function to call for each of the mapped arguments.

Arguments for fun. Either

This function is used by the compiler to implement the automap syntax, and should in normal circumstances never be used directly.

It may however show up during module dumping and in backtraces.

It is an error not to have any Builtin.automap_markers in args.

Builtin.automap_marker, map()

Cast val to the type indicated by type_name.

lfun::cast()

Optional line number of file where the program to be compiled definition starts.

Optional file name where the program to be compiled is defined.

Returns a virgin (ie empty) program suitable as the target argument to PikeCompiler().

__null_program, PikeCompiler, compile_string()

Type attribute handler for "sprintf_format".

Attribute to handle, either "sprintf_format" or "strict_sprintf_format".

Sprintf-style formatting string to generate type information from.

Declared type of the fmt argument (typically string).

Continuation function type after the fmt argument. This is scanned for the type attribute "sprintf_args" to determine where the remaining arguments to sprintf() will come from.

State mapping.

This function is typically called from PikeCompiler()->apply_attribute_constant() and is used to perform stricter compile-time argument checking of sprintf()-style functions.

It currently implements two operating modes depending on the value of attr:

Returns cont_type with "sprintf_args" replaced by the arguments required by the fmt formatting string, and "sprintf_result" replaced by the resulting string type.

PikeCompiler()->apply_attribute_constant(), sprintf()

This function only exists so that it is possible to set a gdb breakpoint on the function pike_gdb_breakpoint.

Return the absolute value for f. If f is an object it must implement lfun::`< and unary lfun::`-.

Return the arcus cosine value for f. The result will be in radians.

cos(), asin()

Return the hyperbolic arcus cosine value for f.

cosh(), asinh()

Add a new predefined constant.

This function is often used to add builtin functions. All programs compiled after the add_constant() function has been called can access value by the name name.

If there is a constant called name already, it will be replaced by by the new definition. This will not affect already compiled programs.

Calling add_constant() without a value will remove that name from the list of constants. As with replacing, this will not affect already compiled programs.

all_constants()

Add a directory to search for include files.

This is the same as the command line option -I.

Note that the added directory will only be searched when using < > to quote the included file.

remove_include_path()

Add a directory to search for modules.

This is the same as the command line option -M.

remove_module_path()

a string containing a path to search for Pike modules. May be a directory, or a path to a ZIP archive. If a ZIP archive path is provided, modules will be loaded from a directory, "modules" within the ZIP archive (see the subpath argument).

if path is a ZIP archive, this argument will determine the path within the archive to be searched.

Add a directory to search for programs.

This is the same as the command line option -P.

remove_program_path()

Construct an array with the arguments as indices.

This function could be written in Pike as:

array aggregate(mixed ... elems) { return elems; }

Arrays are dynamically allocated there is no need to declare them like int a[10]=allocate(10); (and it isn't possible either) like in C, just array(int) a=allocate(10); will do.

sizeof(), arrayp(), allocate()

Construct a mapping.

Groups the arguments together two and two in key-index pairs and creates a mapping of those pairs. Generally, the mapping literal syntax is handier: ([ key1:val1, key2:val2, ... ])

sizeof(), mappingp(), mkmapping()

Construct a multiset with the arguments as indices. The multiset will not contain any values. This method is most useful when constructing multisets with map or similar; generally, the multiset literal syntax is handier: (<elem1, elem2, ...>) With it, it's also possible to construct a multiset with values: (<index1: value1, index2: value2, ...>)

sizeof(), multisetp(), mkmultiset()

Returns a mapping containing all global constants, indexed on the name of the constant, and with the value of the constant as value.

add_constant()

Allocate an array of size elements. If init is specified then each element is initialized by copying that value recursively.

sizeof(), aggregate(), arrayp()

This function works just like sscanf(), but returns the matched results in an array instead of assigning them to lvalues. This is often useful for user-defined sscanf strings.

sscanf(), `/()

Return the arcus sine value for f. The result will be in radians.

sin(), acos()

Return the hyperbolic arcus sine value for f.

sinh(), acosh()

Returns the arcus tangent value for f. The result will be in radians.

tan(), asin(), acos(), atan2()

Returns the arcus tangent value for f1/f2, and uses the signs of f1 and f2 to determine the quadrant. The result will be in radians.

tan(), asin(), acos(), atan()

Returns the hyperbolic arcus tangent value for f.

tanh(), asinh(), acosh()

Replace atomically the value for a key in a mapping or array.

Mapping or array to alter.

Key or index to change the value for.

Value to change to. If value is UNDEFINED and map is a mapping this function function behaves exactly as m_delete(map, key).

Returns the previous value for key. If map is a mapping and there was no previous value UNDEFINED is returned.

If map is an object lfun::_m_replace() will be called in it.

m_delete()

Stop execution of the current restartable function for now. Resume when the future completes.

Evaluates to the result of the future if it succeeds.

Throws an error if the future failed.

Calling this special form is similar to the expression:

(future->on_await(continue::this_function), yield())

Use of this from a non-restartable functions causes a compilation warning and falls back to calling future->get(). This will thus then perform a wait blocking the current thread.

No checks that the future has actually completed are performed. It is assumed that nothing else will call the restartable function during the wait.

Concurrent.Future()->get(), yield(), continue::this_function, Restartable functions

Same as sprintf("%t",x);

sprintf()

Return the closest integer value greater or equal to f.

ceil() does not return an int, merely an integer value stored in a float.

floor(), round()

Coerce a placeholder object into a clone of a program.

Clone of __null_program to alter.

Program to coerce the object to be a clone of.

Arguments to pass to lfun::create() in p.

Returns placeholder after successful coercion.

placeholder may also already be a clone of [p], in which case this operation is a no-op.

__null_program

Extract a column from a two-dimensional array.

This function is exactly equivalent to:

map(data, lambda(mixed x,mixed y) { return x[y]; }, index)

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.

rows()

Compile a string to a program.

This function takes a piece of Pike code as a string and compiles it into a clonable program.

The optional argument handler is used to specify an alternative error handler. If it is not specified the current master object will be used.

The optional arguments major and minor are used to tell the compiler to attempt to be compatible with Pike major.minor.

Note that source must contain the complete source for a program. It is not possible to compile a single expression or statement.

Also note that compile() does not preprocess the program. To preprocess the program you can use compile_string() or call the preprocessor manually by calling cpp().

compile_string(), compile_file(), cpp(), master(), CompilationHandler, DefaultCompilerEnvironment

Compile the Pike code contained in the file filename into a program.

This function will compile the file filename to a Pike program that can later be instantiated. It is the same as doing compile_string(Stdio.read_file(filename), filename).

compile(), compile_string(), cpp()

Compile the Pike code in the string source into a program. If filename is not specified, it will default to "-".

Functionally equal to compile(cpp(source, filename)).

compile(), cpp(), compile_file()

Copy a value recursively.

If the result value is changed destructively (only possible for multisets, arrays and mappings) the copied value will not be changed.

The resulting value will always be equal to the copied (as tested with the function equal()), but they may not the the same value (as tested with `==()).

equal()

Return the cosine value for f. f should be specified in radians.

acos(), sin(), tan()

Return the hyperbolic cosine value for f.

acosh(), sinh(), tanh()

Run a string through the preprocessor.

Preprocesses the string data with Pike's builtin ANSI-C look-alike preprocessor. If the current_file argument has not been specified, it will default to "-". charset defaults to "ISO-10646".

If the second argument is a mapping, no other arguments may follow. Instead, they have to be given as members of the mapping (if wanted). The following members are recognized:

compile()

Convert the output from a previous call to time() into a readable string containing the current year, month, day and time.

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.

strftime(), time(), localtime(), gmtime(), mktime()

Decode a value from the string coded_value.

Value to decode.

Codec to use when encoding objects and programs.

String.Buffer to contain a readable dump of the value.

Debug level. Only available when the runtime has been compiled --with-rtl-debug.

This function takes a string created with encode_value() or encode_value_canonic() and converts it back to the value that was coded.

If codec is specified, it's used as the codec for the decode. If none is specified, then one is instantiated through master()->Decoder(). As a compatibility fallback, the master itself is used if it has no Decoder class. If codec is the special value -1, then decoding of types, functions, programs and objects is disabled.

Decoding a coded_value that you have not generated yourself is a security risk that can lead to execution of arbitrary code, unless codec is specified as -1.

encode_value(), encode_value_canonic()

This function makes the thread stop for s seconds.

Only signal handlers can interrupt the sleep. Other callbacks are not called during delay. Beware that this function uses busy-waiting to achieve the highest possible accuracy.

signal(), sleep()

Return a readable message that describes where the backtrace trace was made (by backtrace).

It may also be an error object or array (typically caught by a catch), in which case the error message also is included in the description.

Pass linewidth -1 to disable wrapping of the output.

backtrace(), describe_error(), catch(), throw()

Return the error message from an error object or array (typically caught by a catch). The type of the error is checked, hence err is declared as mixed and not object|array.

If an error message couldn't be obtained, a fallback message describing the failure is returned. No errors due to incorrectness in err are thrown.

describe_backtrace(), get_backtrace

Mark an object as destructed.

Calls o->_destruct(), and then clears all variables in the object. If no argument is given, the current object is destructed.

All pointers and function pointers to this object will become zero. The destructed object will be freed from memory as soon as possible.

Returns 1 if o has an lfun::_destruct() that returned 1 and inhibited destruction.

Code a value into a string.

Value to encode.

Codec to use when encoding objects and programs.

String.Buffer to contain a readable dump of the value.

Debug level. Only available when the runtime has been compiled --with-rtl-debug.

This function takes a value, and converts it to a string. This string can then be saved, sent to another Pike process, packed or used in any way you like. When you want your value back you simply send this string to decode_value() and it will return the value you encoded.

Almost any value can be coded, mappings, floats, arrays, circular structures etc.

If codec is specified, it's used as the codec for the encode. If none is specified, then one is instantiated through master()->Encoder(). As a compatibility fallback, the master itself is used if it has no Encoder class.

If codec->nameof(o) returns UNDEFINED for an object, val = o->encode_object(o) will be called. The returned value will be passed to o->decode_object(o, val) when the object is decoded.

When only simple types like int, floats, strings, mappings, multisets and arrays are encoded, the produced string is very portable between pike versions. It can at least be read by any later version.

The portability when objects, programs and functions are involved depends mostly on the codec. If the byte code is encoded, i.e. when Pike programs are actually dumped in full, then the string can probably only be read by the same pike version.

decode_value(), sprintf(), encode_value_canonic()

Code a value into a string on canonical form.

Value to encode.

Codec to use when encoding objects and programs.

String.Buffer to contain a readable dump of the value.

Debug level. Only available when the runtime has been compiled --with-rtl-debug.

Takes a value and converts it to a string on canonical form, much like encode_value(). The canonical form means that if an identical value is encoded, it will produce exactly the same string again, even if it's done at a later time and/or in another Pike process. The produced string is compatible with decode_value().

Note that this function is more restrictive than encode_value() with respect to the types of values it can encode. It will throw an error if it can't encode to a canonical form.

encode_value(), decode_value()

Create an array with an enumeration, useful for initializing arrays or as first argument to map() or foreach().

The defaults are: step = 1, start = 0, operator = `+

Advanced use

The resulting array is calculated like this:

array enumerate(int n, mixed step, mixed start, function operator)
{
  array res = allocate(n);
  for (int i=0; i < n; i++)
  {
    res[i] = start;
    start = operator(start, step);
  }
  return res;
}

map(), foreach()

This function checks if the values a and b are equivalent.

If either of the values is an object the (normalized) result of calling lfun::_equal() will be returned.

Returns 1 if both values are false (zero, destructed objects, prototype functions, etc).

Returns 0 (zero) if the values have different types.

Otherwise depending on the type of the values:

copy_value(), `==()

Throws an error. A more readable version of the code throw( ({ sprintf(f, @args), backtrace() }) ).

Return the natural exponential of f. log( exp( x ) ) == x as long as exp(x) doesn't overflow an int.

pow(), log()

Filters the elements in arr through fun.

arr is treated as a set of elements to be filtered, as follows:

array

multiset

string

Each element is filtered with fun. The return value is of the same type as arr and it contains the elements that fun accepted. fun is applied in order to each element, and that order is retained between the kept elements.

If fun is an array, it should have the same length as arr. In this case, the elements in arr are kept where the corresponding positions in fun are nonzero. Otherwise fun is used as described below.

mapping

The values are filtered with fun, and the index/value pairs it accepts are kept in the returned mapping.

program

The program is treated as a mapping containing the identifiers that are indexable from it and their values.

object

If there is a lfun::cast method in the object, it's called to try to cast the object to an array, a mapping, or a multiset, in that order, which is then filtered as described above.

Unless something else is mentioned above, fun is used as filter like this:

function

fun is called for each element. It gets the current element as the first argument and extra as the rest. The element is kept if it returns true, otherwise it's filtered out.

object

The object is used as a function like above, i.e. the lfun::`() method in it is called.

multiset

mapping

fun is indexed with each element. The element is kept if the result is nonzero, otherwise it's filtered out.

"zero or left out"

Each element that is callable is called with extra as arguments. The element is kept if the result of the call is nonzero, otherwise it's filtered out. Elements that aren't callable are also filtered out.

string

Each element is indexed with the given string. If the result of that is zero then the element is filtered out, otherwise the result is called with extra as arguments. The element is kept if the return value is nonzero, otherwise it's filtered out.

This is typically used when arr is a collection of objects, and fun is the name of some predicate function in them.

The function is never destructive on arr.

map(), foreach()

Return the closest integer value less or equal to f.

floor() does not return an int, merely an integer value stored in a float.

ceil(), round()

Returns the currently active compilation compatibility handler, or 0 (zero) if none is active.

This function should only be used during a call of compile().

get_active_error_handler(), compile(), master()->get_compilation_handler(), CompilationHandler

Returns the most recent of the currently active pike compilers, or UNDEFINED if none is active.

This function should only be used during a call of compile().

get_active_error_handler(), compile(), master()->get_compilation_handler(), CompilationHandler

Returns the currently active compilation error handler (second argument to compile()), or 0 (zero) if none is active.

This function should only be used during a call of compile().

get_active_compilation_handler(), compile(), CompilationHandler

Returns an array of arrays with all groups in the system groups source. Each element in the returned array has the same structure as in getgrent function.

The groups source is system dependant. Refer to your system manuals for information about how to set the source.

getgrent()

Returns an array with all users in the system.

An array with arrays of userinfo as in getpwent.

getpwent() getpwnam() getpwuid()

Return the backtrace array from an error object or array (typically caught by a catch), or zero if there is none. Errors are thrown on if there are problems retrieving the backtrace.

describe_backtrace(), describe_error()

Gets all groups which a given user is a member of.

UID or loginname of the user

get_all_groups() getgrgid() getgrnam() getpwuid() getpwnam()

Creates and returns a canonical iterator for data.

This function is used by foreach to get an iterator for an object.

Iterator, lfun::_get_iterator

Queries the environment variables.

A cached copy of the real environment is kept to make this function quicker. If the optional flag force_update is nonzero then the real environment is queried and the cache is updated from it. That can be necessary if the environment changes through other means than putenv, typically from a C-level library.

Returns the whole environment as a mapping. Destructive operations on the mapping will not affect the internal environment representation.

Variable names and values cannot be wide strings nor contain '\0' characters. Variable names also cannot contain '=' characters.

On NT the environment variable name is case insensitive.

putenv()

Query the value of a specific environment variable.

Environment variable to query.

A cached copy of the real environment is kept to make this function quicker. If the optional flag force_update is nonzero then the real environment is queried and the cache is updated from it. That can be necessary if the environment changes through other means than putenv, typically from a C-level library.

Returns the value of the environment variable varname if it exists, and 0 (zero) otherwise.

Variable names and values cannot be wide strings nor contain '\0' characters. Variable names also cannot contain '=' characters.

On NT the environment variable name is case insensitive.

putenv()

Get the group entry for the group with the id gid using the systemfunction getgrid(3).

The id of the group

An array with the information about the group

getgrent() getgrnam()

Get the group entry for the group with the name str using the systemfunction getgrnam(3).

The name of the group

An array with the information about the group

getgrent() getgrgid()

Return the high resolution real time spent with threads disabled since the Pike interpreter was started. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.

The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.REAL_TIME_RESOLUTION.

_disable_threads(), gethrtime()

Return the high resolution real time since some arbitrary event in the past. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.

It's system dependent whether or not this time is monotonic, i.e. if it's unaffected by adjustments of the calendaric clock in the system. System.REAL_TIME_IS_MONOTONIC tells what it is. Pike tries to use monotonic time for this function if it's available.

The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.REAL_TIME_RESOLUTION.

System.REAL_TIME_IS_MONOTONIC, System.REAL_TIME_RESOLUTION, time(), System.gettimeofday(), gethrvtime(), Pike.implicit_gc_real_time

Return the CPU time that has been consumed by this process or thread. -1 is returned if the system couldn't determine it. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.

The CPU time includes both user and system time, i.e. it's approximately the same thing you would get by adding together the "utime" and "stime" fields returned by System.getrusage (but perhaps with better accuracy).

It's however system dependent whether or not it's the time consumed in all threads or in the current one only; System.CPU_TIME_IS_THREAD_LOCAL tells which. If both types are available then thread local time is preferred.

The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.CPU_TIME_RESOLUTION.

The garbage collector might run automatically at any time. The time it takes is not included in the figure returned by this function, so that normal measurements aren't randomly clobbered by it. Explicit calls to gc are still included, though.

The special function gauge is implemented with this function.

System.CPU_TIME_IS_THREAD_LOCAL, System.CPU_TIME_RESOLUTION, gauge(), System.getrusage(), gethrtime()

Returns the process ID of this process.

System.getppid(), System.getpgrp()

Get the user entry for login str using the systemfunction getpwnam(3).

The login name of the user whos userrecord is requested.

An array with the information about the user

getpwuid() getpwent()

Get the user entry for UID uid using the systemfunction getpwuid(3).

The uid of the user whos userrecord is requested.

An array with the information about the user

getpwnam() getpwent()

Return the value of a specified attribute, or 0 if it does not exist.

Match strings against a glob pattern.

sscanf(), Regexp

Convert seconds since 00:00:00 UTC, Jan 1, 1970 into components.

This function works like localtime() but the result is not adjusted for the local time zone.

Timestamps prior to 1970-01-01T00:00:00 (ie negative timestamps) were not supported on NT and AIX prior to Pike 9.0.

localtime(), time(), ctime(), mktime(), strptime()

Search for index in haystack.

Returns 1 if index is in the index domain of haystack, or 0 (zero) if not found.

This function is equivalent to (but sometimes faster than):

search(indices(haystack), index) != -1

A negative index in strings and arrays as recognized by the index operators `[]() and `[]=() is not considered a proper index by has_index()

has_value(), has_prefix(), has_suffix(), indices(), search(), values(), zero_type()

Returns 1 if the string s starts with prefix, returns 0 (zero) otherwise.

When s is an object, it needs to implement lfun::_sizeof() and lfun::`[].

has_suffix(), has_value(), search()

Returns 1 if the string s ends with suffix, returns 0 (zero) otherwise.

has_prefix(), has_value(), search()

Search for value in haystack.

Returns 1 if value is in the value domain of haystack, or 0 (zero) if not found.

This function is in all cases except when both arguments are strings equivalent to (but sometimes faster than):

search(values(haystack), value) != -1

If both arguments are strings, has_value() is equivalent to:

search(haystack, value) != -1

has_index(), indices(), search(), has_prefix(), has_suffix(), values(), zero_type()

Return an integer derived from the string s. The same string always hashes to the same value, also between processes, architectures, and Pike versions (see compatibility notes below, though).

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

The hash algorithm was changed in Pike 8.1. If you want a hash that is compatible with Pike 8.0 and earlier, use hash_8_0().

The hash algorithm was also changed in Pike 7.5. If you want a hash that is compatible with Pike 7.4 and earlier, use hash_7_4(). The difference with regards to hash_8_0() only affects wide strings.

The hash algorithm was also changed in Pike 7.1. If you want a hash that is compatible with Pike 7.0 and earlier, use hash_7_0().

This hash function differs from the one provided by hash_value(), in that hash_value() returns a process specific value.

hash_7_0(), hash_7_4(), hash_8_0(), hash_value

Return an integer derived from the string s. The same string always hashes to the same value, also between processes.

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

This function is provided for backward compatibility with code written for Pike up and including version 7.0.

This function is not NUL-safe, and is byte-order dependant.

hash(), hash_7_4

Return an integer derived from the string s. The same string always hashes to the same value, also between processes.

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

This function is provided for backward compatibility with code written for Pike up and including version 7.4.

This function is byte-order dependant for wide strings.

hash_7_6(), hash_7_0

Return an integer derived from the string s. The same string always hashes to the same value, also between processes, architectures, and Pike versions (see compatibility notes below, though).

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

Use hash_value() for in-process hashing (eg, for implementing lfun::_hash()) or one of the cryptographic hash functions.

This function is really bad at hashing strings. Similar string often return similar hash values.

It is especially bad for url:s, paths and similarly formatted strings.

The hash algorithm was changed in Pike 7.5. If you want a hash that is compatible with Pike 7.4 and earlier, use hash_7_4(). The difference only affects wide strings.

The hash algorithm was also changed in Pike 7.1. If you want a hash that is compatible with Pike 7.0 and earlier, use hash_7_0().

This hash function differs from the one provided by hash_value(), in that hash_value() returns a process specific value.

hash(), hash_7_0(), hash_7_4(), hash_value

Return a hash value for the argument. It's an integer in the native integer range.

The hash will be the same for the same value in the running process only (the memory address is typically used as the basis for the hash value).

If the value is an object with an lfun::__hash, that function is called and its result returned.

This is the hashing method used by mappings.

lfun::__hash()

Check if a path p is fully qualified (ie not relative).

Returns 1 if the path is absolute, 0 otherwise.

Get the current index for iter.

get_iterator()

Advance iter one step.

get_iterator()

Get the current value for iter.

get_iterator()

Send a signal to another process.

Some signals and their supposed purpose:

Note that you have to use signame to translate the name of a signal to its number.

Note that the kill function is not available on platforms that do not support signals. Some platforms may also have signals not listed here.

signal(), signum(), signame(), fork()

Limits the value x so that it's between minval and maxval. If x is an object, it must implement the lfun::`< method.

max() and min()

Return an array of all extended attributes set on the file

Load a binary module.

This function loads a module written in C or some other language into Pike. The module is initialized and any programs or constants defined will immediately be available.

When a module is loaded the C function pike_module_init() will be called to initialize it. When Pike exits pike_module_exit() will be called. These two functions must be available in the module.

The current working directory is normally not searched for dynamic modules. Please use "./name.so" instead of just "name.so" to load modules from the current directory.

Convert seconds since 00:00:00 UTC, 1 Jan 1970 into components.

This function returns a mapping with the following components:

An error is thrown if the localtime(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.

Prior to Pike 7.5 the field "timezone" was sometimes not present, and was sometimes not adjusted for daylight-saving time.

Timestamps prior to 1970-01-01T00:00:00 (ie negative timestamps) were not supported on NT and AIX prior to Pike 9.0. Note also that dst-handling may be incorrect for such timestamps.

Calendar, gmtime(), time(), ctime(), mktime(), strptime()

Return the natural logarithm of f. exp( log(x) ) == x for x > 0.

pow(), exp()

Convert a string or character to lower case.

Returns a copy of the string s with all upper case characters converted to lower case, or the character c converted to lower case.

Assumes the string or character to be coded according to ISO-10646 (aka Unicode). If they are not, Charset.decoder can do the initial conversion for you.

Prior to Pike 7.5 this function only accepted strings.

upper_case(), Charset.decoder

Add a member to a multiset.

m_delete()

Clear the contents of a mapping or multiset.

This function clears the content of the mapping or multiset map so that it becomes empty. This is an atomic operation.

If map is an object lfun::_m_clear() will be called in it.

m_delete()

If map is an object that implements lfun::_m_delete(), that function will be called with index as its single argument.

Otherwise if map is a mapping or multiset the entry with index index will be removed from map destructively.

If the mapping or multiset does not have an entry with index index, nothing is done.

The value that was removed will be returned, and UNDEFINED otherwise.

Note that m_delete() changes map destructively.

mappingp()

Applies fun to the elements in arr and collects the results.

arr is treated as a set of elements, as follows:

array

multiset

string

fun is applied in order to each element. The results are collected, also in order, to a value of the same type as arr, which is returned.

mapping

fun is applied to the values, and each result is assigned to the same index in a new mapping, which is returned.

program

The program is treated as a mapping containing the identifiers that are indexable from it and their values.

object

If there is a lfun::cast method in the object, it's called to try to cast the object to an array, a mapping, or a multiset, in that order, which is then handled as described above.

fun is applied in different ways depending on its type:

function

fun is called for each element. It gets the current element as the first argument and extra as the rest. The result of the call is collected.

object

fun is used as a function like above, i.e. the lfun::`() method in it is called.

array

Each element of the fun array will be called for each element of arr.

multiset

mapping

fun is indexed with each element. The result of that is collected.

"zero or left out"

Each element that is callable is called with extra as arguments. The result of the calls are collected. Elements that aren't callable gets zero as result.

string

Each element is indexed with the given string. If the result of that is zero then a zero is collected, otherwise it's called with extra as arguments and the result of that call is collected.

This is typically used when arr is a collection of objects, and fun is the name of some function in them.

The function is never destructive on arr.

filter(), enumerate(), foreach()

Return the current master object.

May return UNDEFINED if no master has been loaded yet.

replace_master()

Returns the largest value among args. Compared objects must implement the lfun::`< method.

min() and limit()

Returns the smallest value among args. Compared objects must implement the lfun::`< method.

max() and limit()

Make a mapping from two arrays.

Makes a mapping ind[x]:val[x], 0 <= x < sizeof(ind).

ind and val must have the same size.

This is the inverse operation of indices() and values().

indices(), values()

This function creates a multiset from an array.

aggregate_multiset()

This function converts information about date and time into an integer which contains the number of seconds since 00:00:00 UTC, Jan 1, 1970.

You can either call this function with a mapping containing the following elements:

Or you can just send them all on one line as the second syntax suggests.

For proper UTC calculations ensure that isdst = 0 and timezone = 0; omitting either one of these parameters will mess up the UTC calculation.

On some operating systems (notably AIX and Win32), dates before 00:00:00 UTC, Jan 1, 1970 were not supported prior to Pike 9.0.

On most 32-bit systems, the supported range of dates is from Dec 13, 1901 20:45:52 UTC through to Jan 19, 2038 03:14:07 UTC (inclusive).

On most 64-bit systems, the supported range of dates is expressed in 56 bits and is thus practically unlimited (at least up to 1141 milion years in the past and into the future).

time(), ctime(), localtime(), gmtime(), strftime()

Replaces "\" with "/" if runing on MS Windows. It is adviced to use System.normalize_path instead.

Find out if an object identifier is a variable.

This function returns 1 if var exists as a non-protected variable in o, and returns 0 (zero) otherwise.

indices(), values()

Returns 1 if arg is an object, 0 (zero) otherwise.

mappingp(), programp(), arrayp(), stringp(), functionp(), multisetp(), floatp(), intp()

Return n raised to the power of x. If both n and x are integers the result will be an integer. If n is an object its pow method will be called with x as argument.

exp(), log()

Sets the environment variable varname to value.

If value is omitted or zero, the environment variable varname is removed.

varname and value cannot be wide strings nor contain '\0' characters. varname also cannot contain '=' characters.

On NT the environment variable name is case insensitive.

getenv()

Get a random value generated by the default RandomSystem.

RandomSystem()->random(), random_string()

This function sets the initial value for the random generator.

random()

Random.Deterministic

Get a string of random characters 0..255 with the length len from the default RandomSystem.

RandomSystem()->random_string(), random()

Remove a directory to search for include files.

This function performs the reverse operation of add_include_path().

add_include_path()

Remove a directory to search for modules.

This function performs the reverse operation of add_module_path().

add_module_path()

Remove a directory to search for programs.

This function performs the reverse operation of add_program_path().

add_program_path()

Remove the specified extended attribute.

Generic replace function.

This function can do several kinds replacement operations, the different syntaxes do different things as follows:

If all the arguments are strings, a copy of s with every occurrence of from replaced with to will be returned. Special case: to will be inserted between every character in s if from is the empty string.

If the first argument is a string, and the others array(string), a string with every occurrance of from[i] in s replaced with to[i] will be returned. Instead of the arrays from and to a mapping equivalent to mkmapping(from, to) can be used.

If the first argument is an array or mapping, the values of a which are `==() with from will be replaced with to destructively. a will then be returned.

Note that replace() on arrays and mappings is a destructive operation.

Replace the master object with o.

This will let you control many aspects of how Pike works, but beware that master.pike may be required to fill certain functions, so it is usually a good idea to have your master inherit the original master and only re-define certain functions.

FIXME: Tell how to inherit the master.

master()

Reverses a string, array or int.

String to reverse.

Array to reverse.

Integer to reverse.

Object to reverse.

Optional start index of the range to reverse. Default: 0 (zero).

Optional end index of the range to reverse. Default for strings: sizeof(s)-1. Default for arrays: sizeof(a)-1. Default for integers: Pike.get_runtime_info()->int_size - 1.

Optional arguments that are to be passed to lfun::_reverse().

This function reverses a string, char by char, an array, value by value or an int, bit by bit and returns the result. It's not destructive on the input value. For objects it simply calls lfun::_reverse() in the object, and returns the result.

Reversing strings can be particularly useful for parsing difficult syntaxes which require scanning backwards.

sscanf()

Return the closest integer value to f.

round() does not return an int, merely an integer value stored in a float.

floor(), ceil()

Select a set of rows from an array.

This function is en optimized equivalent to:

map(index, lambda(mixed x) { return data[x]; })

That is, it indices data on every index in the array index and returns an array with the results.

column()

Search for needle in haystack.

Item to search in. This can be one of:

If the optional argument start is present search is started at this position. This has no effect on mappings.

If the optional argument end is present, the search will terminate at this position (exclusive) if not found earlier.

Returns the position of needle in haystack if found.

If not found the returned value depends on the type of haystack:

If start is supplied to an iterator object without an lfun::_search(), haystack will need to implement Iterator()->set_index().

For mappings and object UNDEFINED will be returned when not found. In all other cases -1 will be returned when not found.

indices(), values(), zero_type(), has_value(), has_prefix(), has_suffix()

Set the value m to use weak or normal references in its indices and/or values (whatever is applicable). state is a bitfield built by using | between the following flags:

If a flag is absent, the corresponding field will use normal references. state can also be 1 as a compatibility measure; it's treated like Pike.WEAK.

m will be returned.

Set the attribute attr to the value value.

The flags parameter can be used to refine the semantics of the operation.

Stdio.XATTR_CREATE specifies a pure create, which fails if the named attribute exists already.

Stdio.XATTR_REPLACE specifies a pure replace operation, which fails if the named attribute does not already exist.

By default (no flags), the extended attribute will be created if need be, or will simply replace the value if the attribute exists.

1 if successful, 0 otherwise, setting errno.

Check the sign of a value.

Returns -1 if value is less than zero, 1 if value is greater than zero and 0 (zero) otherwise.

abs()

Trap signals.

This function allows you to trap a signal and have a function called when the process receives a signal. Although it IS possible to trap SIGBUS, SIGSEGV etc, I advise you not to; Pike should not receive any such signals, and if it does, it is because of bugs in the Pike interpreter. And all bugs should be reported, no matter how trifle.

The callback will receive the signal number as its only argument.

See the documentation for kill() for a list of signals.

If no second argument is given, the signal handler for that signal is restored to the default handler.

If the second argument is zero, the signal will be completely ignored.

Returns the previous signal function, or 0 if none had been registered.

kill(), signame(), signum()

Returns a string describing the signal sig.

kill(), signum(), signal()

Get a signal number given a descriptive string.

This function is the inverse of signame().

signame(), kill(), signal()

Returns the sine value for f. f should be specified in radians.

asin(), cos(), tan()

Returns the hyperbolic sine value for f.

asinh(), cosh(), tanh()

Size query.

The result will be as follows:

lfun::_sizeof()

This function makes the thread stop for s seconds.

Only signal handlers can interrupt the sleep, and only when abort_on_signal is set. If more than one thread is running the signal must be sent to the sleeping thread. Other callbacks are not called during sleep.

If s is zero then this thread will yield to other threads but not sleep otherwise. Note that Pike yields internally at regular intervals so it's normally not necessary to do this.

signal(), delay()

Sort arrays destructively.

This function sorts the array index destructively. That means that the array itself is changed and returned, no copy is created.

If extra arguments are given, they are supposed to be arrays of the same size as index. Each of these arrays will be modified in the same way as index. I.e. if index 3 is moved to position 0 in index index 3 will be moved to position 0 in all the other arrays as well.

The sort order is as follows:

• Integers and floats are sorted in ascending order.

• Strings are sorted primarily on the first characters that are different, and secondarily with shorter strings before longer. Different characters are sorted in ascending order on the character value. Thus the sort order is not locale dependent.

• Arrays are sorted recursively on the first element. Empty arrays are sorted before nonempty ones.

• Multisets are sorted recursively on the first index. Empty multisets are sorted before nonempty ones.

• Objects are sorted in ascending order according to `<(), `>() and `==().

• Other types aren't reordered.

• Different types are sorted in this order: Arrays, mappings, multisets, objects, functions, programs, strings, types, integers and floats. Note however that objects can control their ordering wrt other types with `<, `> and `==, so this ordering of types only applies to objects without those functions.

The first argument is returned.

The sort is stable, i.e. elements that are compare-wise equal aren't reordered.

Array.sort_array, reverse()

Print formated output to string.

The format string is a string containing a description of how to output the data in args. This string should generally speaking have one %<modifiers><operator> format specifier (examples: %s, %0d, %-=20s) for each of the arguments.

The following modifiers are supported:

The following operators are supported:

Most modifiers and operators are combinable in any fashion, but some combinations may render strange results.

If an argument is an object that implements lfun::_sprintf(), that callback will be called with the operator as the first argument, and the current modifiers as the second. The callback is expected to return a string.

sprintf-style formatting is applied by many formatting functions, such write() and werror(). It is also possible to get sprintf-style compile-time argument checking by using the type-attributes sprintf_format or strict_sprintf_format in combination with sprintf_args.

The 'q' operator was added in Pike 7.7.

Support for specifying modifiers via a mapping was added in Pike 7.8. This support can be tested for with the constant String.__HAVE_SPRINTF_STAR_MAPPING__.

Support for specifying little endian byte order to 'F' was added in Pike 7.8. This support can be tested for with the constant String.__HAVE_SPRINTF_NEGATIVE_F__.

lfun::_sprintf(), strict_sprintf_format, sprintf_format, sprintf_args, String.__HAVE_SPRINTF_STAR_MAPPING__, String.__HAVE_SPRINTF_NEGATIVE_F__.

Returns the square root of f, or in the integer case, the square root truncated to the closest lower integer. If the argument is an object, the lfun _sqrt in the object will be called.

pow(), log(), exp(), floor(), lfun::_sqrt

The purpose of sscanf is to match a string data against a format string and place the matching results into a list of variables. The list of lvalues are destructively modified (which is only possible because sscanf really is a special form, rather than a pike function) with the values extracted from the data according to the format specification. Only the variables up to the last matching directive of the format string are touched.

The format string may contain strings separated by special matching directives like %d, %s %c and %f. Every such directive corresponds to one of the lvalues, in the order they are listed. An lvalue is the name of a variable, a name of a local variable, an index into an array, mapping or object. It is because of these lvalues that sscanf can not be implemented as a normal function.

Whenever a percent character is found in the format string, a match is performed, according to which operator and modifiers follow it:

Similar to sprintf, you may supply modifiers between the % character and the operator, to slightly change its behaviour from the default:

Sscanf does not use backtracking. Sscanf simply looks at the format string up to the next % and tries to match that with the string. It then proceeds to look at the next part. If a part does not match, sscanf immediately returns how many % were matched. If this happens, the lvalues for % that were not matched will not be changed.

The number of directives matched in the format string. Note that a string directive (%s or %[]) counts as a match even when matching just the empty string (which either may do).

sprintf, array_sscanf

Convert the structure to a string.

%a

The abbreviated weekday name according to the current locale

%A

The full weekday name according to the current locale.

%b

The abbreviated month name according to the current locale.

%B

The full month name according to the current locale.

%c

The preferred date and time representation for the current locale.

%C

The century number (year/100) as a 2-digit integer.

%d

The day of the month as a decimal number (range 01 to 31).

%D

Equivalent to %m/%d/%y. (for Americans only. Americans should note that in other countries %d/%m/%y is rather common. This means that in international context this format is ambiguous and should not be used.)

%e

Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space.

%E

Modifier: use alternative format, see below.

%F

Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)

%G

The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.

%g

Like %G, but without century, that is, with a 2-digit year (00-99). (TZ)

%h

Equivalent to %b.

%H

The hour as a decimal number using a 24-hour clock (range 00 to 23).

%I

The hour as a decimal number using a 12-hour clock (range 01 to 12).

%j

The day of the year as a decimal number (range 001 to 366).

%m

The month as a decimal number (range 01 to 12).

%M

The minute as a decimal number (range 00 to 59).

%n

A newline character. (SU)

%O

Modifier: use alternative format, see below. (SU)

%p

Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".

%P

Like %p but in lowercase: "am" or "pm" or a corresponding string for the current locale.

%r

The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to %I:%M:%S %p.

%R

The time in 24-hour notation (%H:%M). (SU) For a version including the seconds, see %T below.

%s

The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)

%S

The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.)

%t

A tab character. (SU)

%T

The time in 24-hour notation (%H:%M:%S). (SU)

%u

The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w. (SU)

%U

The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.

%V

The ISO 8601 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See also %U and %W.

%w

The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.

ctime(), mktime(), strptime(), Gettext.setlocale

Replace the most obviously non-unicode characters from s with the unicode replacement character.

This will replace characters outside the ranges 0x00000000-0x0000d7ff and 0x0000e000-0x0010ffff with 0xffea (the replacement character).

Charset.encoder(), string_to_unicode(), unicode_to_string(), utf8_to_string(), string_to_utf8()

Converts a string into an UTF16 compliant byte-stream.

String to convert to UTF16.

Byte-order for the output. One of:

Throws an error if characters not legal in an UTF16 stream are encountered. Valid characters are in the range 0x00000 - 0x10ffff, except for characters 0xfffe and 0xffff.

Characters in range 0x010000 - 0x10ffff are encoded using surrogates.

Charset.decoder(), string_to_utf8(), unicode_to_string(), utf8_to_string()

Convert a string into a UTF-8 compliant byte-stream.

String to encode into UTF-8.

Bitmask with extension options.

Throws an error if characters not valid in an UTF-8 stream are encountered. Valid characters are in the ranges 0x00000000-0x0000d7ff and 0x0000e000-0x0010ffff.

Charset.encoder(), string_to_unicode(), unicode_to_string(), utf8_to_string()

Returns 1 if arg is a string, 0 (zero) otherwise.

intp(), programp(), arrayp(), multisetp(), objectp(), mappingp(), floatp(), functionp()

Parse the given data using the format in format as a date.

%%

The % character.

%a or %A

The weekday name according to the C locale, in abbreviated form or the full name.

%b or %B or %h

The month name according to the C locale, in abbreviated form or the full name.

%c

The date and time representation for the C locale.

%C

The century number (0-99).

%d or %e

The day of month (1-31).

%D

Equivalent to %m/%d/%y.

%H

The hour (0-23).

%I

The hour on a 12-hour clock (1-12).

%j

The day number in the year (1-366).

%m

The month number (1-12).

%M

The minute (0-59).

%n

Arbitrary whitespace.

%p

The C locale's equivalent of AM or PM.

%R

Equivalent to %H:%M.

%S

The second (0-60; 60 may occur for leap seconds; earlier also 61 was allowed).

%t

Arbitrary whitespace.

%T

Equivalent to %H:%M:%S.

%U

The week number with Sunday the first day of the week (0-53).

%w

The weekday number (0-6) with Sunday = 0.

%W

The week number with Monday the first day of the week (0-53).

%x

The date, using the C locale's date format.

%X

The time, using the C locale's time format.

%y

The year within century (0-99). When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969-1999); values in the range 00-68 refer to years in the twenty-first century (2000-2068).

%Y

The year, including century (for example, 1991).