A.3d Alphabetical Listing of PHP Functions (r-z)

int rand([int


min


, int


max


])

Returns a random number from min to max , inclusive. If the min and max parameters are not provided, returns a random number from 0 to the value returned by the getrandmax( ) function.

array range(mixed


first


, mixed


second


)

Creates and returns an array containing integers or characters from first to second , inclusive. If second is a lower value than first , the sequence of values is returned in the opposite order.

string rawurldecode(string


url


)

Returns a string created from decoding the URI-encoded url . Sequences of characters beginning with a % followed by a hexadecimal number are replaced with the literal the sequence represents.

string rawurlencode(string


url


)

Returns a string created by URI encoding url . Certain characters are replaced by sequences of characters beginning with a % followed by a hexadecimal number; for example, spaces are replaced with %20 .

string readdir(int


handle


)

Returns the name of the next file in the directory referenced by handle ; the order in which files in a directory are returned by calls to readdir( ) is undefined. If there are no more files in the directory to return, readdir( ) returns false .

int readfile(string


path


[, bool


include


])

Reads the file at path and outputs the contents. If include is specified and is true , the include path is searched for the file. If path begins with http:// , an HTTP connection is opened and the file is read from it. If path begins with ftp:// , an FTP connection is opened and the file is read from it; the remote server must support passive FTP.

This function returns the number of bytes output.

string readlink(string


path


)

Returns the path contained in the symbolic link file path . If path does not exist or is not a symbolic link file, or if any other error occurs, the function returns false .

string realpath(string


path


)

Expands all symbolic links, resolves references to /./ and /../ , removes extra / characters in path , and returns the result.

void register_shutdown_function(string


function


)

Registers a shutdown function. The function is called when the page completes processing. You can register multiple shutdown functions, and they will be called in the order in which they were registered. If a shutdown function contains an exit command, functions registered after that function will not be called.

Because the shutdown function is called after the page has completely processed , you cannot add data to the page with print( ) , echo( ) , or similar functions or commands.

void register_tick_function(string


name


[, mixed


arg1


[, mixed


arg2


[, ... mixed


argN


]]])

Registers the function name to be called on each tick. The function is called with the given arguments. Obviously, registering a tick function can have a serious impact on the performance of your script.

int rename(string


old


, string


new


)

Renames the file old to new and returns true if the renaming was successful and false if not.

mixed reset(array


array


)

Resets the array 's internal pointer to the first element and returns the value of that element.

void restore_error_handler(  )

Reverts to the error handler in place prior to the most recent call to set_error_handler( ) .

int rewind(int


handle


)

Sets the file pointer for handle to the beginning of the file. Returns true if the operation was successful and false if not.

void rewinddir(int


handle


)

Sets the file pointer for handle to the beginning of the list of files in the directory.

int rmdir(string


path


)

Removes the directory path . If the directory is not empty or the PHP process does not have appropriate permissions, or if any other error occurs, false is returned. If the directory is successfully deleted, true is returned.

double round(double


number


[, int


precision


])

Returns the integer value nearest to number at the precision number of decimal places. The default for precision is (integer rounding). Note that this function provides proper rounding—odd whole numbers are rounded up on a .5, even whole numbers are rounded down on a .5. That is:

$first = round(1.5); // $first is 2
$second = round(2.5); // $second is also 2!

If you want the rounding taught to you in grade school, either add a small number (smaller than the precision you're after), or, if you're using whole numbers, add .5 and call floor( ) on the result.

void rsort(array


array


[, int


flags


])

Sorts an array in reverse order by value. The optional second parameter contains additional sorting flags. See Chapter 5 and sort for more information on using this function.

string rtrim(string


string


[, string


characters


])

Returns string with all characters in characters stripped from the end. If characters is not specified, the characters stripped are \n , \r , \t , \v , \0 , and spaces.

string serialize(mixed


value


)

Returns a string containing a binary data representation of value . This string can be used to store the data in a database or file, for example, and later restored using unserialize( ) . Except for resources, any kind of value can be serialized.

string set_error_handler(string


function


)

Sets the named function as the current error handler. The error-handler function is called whenever an error occurs; the function can do whatever it wants, but typically will print an error message and clean up after a critical error happens.

The user -defined function is called with two parameters, an error code and a string describing the error. Three additional parameters may also be supplied—the filename in which the error occurred, the line number at which the error occurred, and the context in which the error occurred (which is an array pointing to the active symbol table).

set_error_handler( ) returns the name of the previously installed error-handler function, or false if an error occurred while setting the error handler (e.g., when function doesn't exist).

int set_file_buffer(int


handle


, int


size


)

Sets the file buffer size for the file referenced by handle to size bytes. Writes to a file are committed to disk only when the file's buffer is full. By default, a file's buffer is set to 8 KB. If size is , writes are unbuffered and any write to the file will happen as the write occurs. Returns if the operation is successful and EOF if it fails.

int set_magic_quotes_runtime(int


setting


)

Sets the value of magic_quotes_runtime to either on ( setting =1 ) or off ( setting =0 ). See get_magic_quotes_runtime for more information. Returns the previous value of magic_quotes_runtime .

void set_time_limit(int


timeout


)

Sets the timeout for the current script to timeout seconds and restarts the timeout timer. By default, the timeout is set to 30 seconds or the value for max_execution_time set in the current configuration file. If a script does not finish executing within the time provided, a fatal error is generated and the script is killed . If timeout is , the script will never time out.

void setcookie(string


name


[, string


value


[, int


expiration


[, string


path


[, string


domain


[, bool


is_secure


]]]]])

Generates a cookie and passes it along with the rest of the header information. Because cookies are set in the HTTP header, setcookie( ) must be called before any output is generated.

If only name is specified, the cookie with that name is deleted from the client. The value argument specifies a value for the cookie to take, expiration is a Unix timestamp value defining a time the cookie should expire, and the path and domain parameters define a domain for the cookie to be associated with. If is_secure is true , the cookie will be transmitted only over a secure HTTP connection.

string setlocale(mixed


category


, string


locale


)

Sets the locale for category functions to locale . Returns the current locale after being set, or false if the locale cannot be set. Any number of options for category can be added (or ORed) together. The following options are available:

If locale is or the empty string, the current locale is unaffected.

bool settype(mixed


value


, string


type


)

Converts value to the given type . Possible types are "boolean" , "integer" , "double" , "string" , "array" , and "object" . Returns true if the operation was successful and false if not. Using this function is the same as typecasting value to the appropriate type.

string shell_exec(string


command


)

Executes command via the shell and returns the last line of output from the command's result. This function is called when you use the backtick operator (``).

void shuffle(array


array


)

Rearranges the values in array into a random order. Keys for the values are lost. Before you call shuffle( ) , be sure to seed the random-number generator using srand ( ) .

int similar_text(string


one


, string


two


[, double


percent


])

Calculates the similarity between the strings one and two . If passed by reference, percent gets the percent by which the two strings differ .

double sin(double


value


)

Returns the arc sine of value in radians.

int sizeof(mixed


value


)

This function is an alias for count( ) .

void sleep(int


time


)

Pauses execution of the current script for time seconds.

array socket_get_status(resource


socket


)

Returns an associative array containing information about socket . The following values are returned:

int socket_set_blocking(resource


socket


, bool


mode


)

If mode is true , sets socket to blocking mode; if mode is false , sets socket to nonblocking mode. In blocking mode, functions that get data from a socket (such as fgets( ) ) wait for data to become available in the socket before returning. In nonblocking mode, such calls return immediately, even when the result is empty.

bool socket_set_timeout(int


socket


, int


seconds


, int


microseconds


)

Sets the timeout for socket to the sum of seconds and microseconds . Returns true if the operation was successful and false if not.

void sort(array


array


[, int


flags


])

Sorts the values in the given array in ascending order. For more control over the behavior of the sort, provide the second parameter, which is one of the following values:

See Chapter 5 for more information on using this function.

string soundex(string


string


)

Calculates and returns the soundex key of string . Words that are pronounced similarly (and begin with the same letter) have the same soundex key.

array split(string


pattern


, string


string


[, int


limit


])

Returns an array of strings formed by splitting string on boundaries formed by the regular expression pattern . If limit is specified, at most that many substrings will be returned; the last substring will contain the remainder of string .

If your split is such that you don't need regular expressions, explode( ) performs a similar function and is much faster.

array spliti(string


pattern


, string


string


[, int


limit


])

Returns an array of strings formed by splitting string on boundaries formed by the regular expression pattern . Pattern matching is performed in a case-insensitive manner. If limit is specified, at most that many substrings will be returned; the last substring will contain the remainder of string . This function is a case-insensitive version of split( ) .

string sprintf(string


format


[, mixed


value1


[, ... mixed


valueN


]])

Returns a string created by filling format with the given arguments. See printf for more information on using this function.

string sql_regcase(string


match


)

Creates and returns a regular expression pattern that matches match , ignoring case. The resulting pattern contains each character in match in each case; for example, given "O'Reilly", the function returns "[Oo]['] [Rr][Ee][Ii][Ll][Ll][Yy]".

double sqrt(double


number


)

Returns the square root of number .

void srand(int


seed


)

Seeds the standard pseudorandom-number generator with seed . You should call this function with a varying number, such as that returned by time( ) , before making calls to rand( ) .

mixed sscanf(string


string


, string


format


[, mixed


variable1


...])

Parses string for values of types given in format ; the values found are either returned in an array or, if variable1 through variableN (which must be variables passed by reference) are given, in those variables .

The format string is the same as that used in sprintf( ) . For example:

$name = sscanf("Name: k.tatroe", "Name: %s"); // $name has "k.tatroe"
list($month, $day, $year) = sscanf("June 30, 2001", "%s %d, %d");
$count = sscanf("June 30, 2001", "%s %d, %d", &$month, &$day, &$year);

array stat(string


path


)

Returns an associative array of information about the file path . If path is a symbolic link, information about the file path references is returned. See fstat for a list of the values returned and their meanings.

string str_pad(string


string


, string


length


[, string


pad


[, int


type


]])

Pads string using pad until it is at least length characters and returns the resulting string. By specifying type , you can control where the padding occurs. The following values for type are accepted:

string str_repeat(string


string


, int


count


)

Returns a string consisting of count copies of string appended to each other. If count is not greater than 0, an empty string is returned.

mixed str_replace(mixed


search


, mixed


replace


, mixed


string


)

Searches for all occurrences of search in subject and replaces them with replace . If all three parameters are strings, a string is returned. If string is an array, the replacement is performed for every element in the array and an array of results is returned. If search and replace are both arrays, elements in search are replaced with the elements in replace with the same numeric indexes. Finally, if search is an array and replace is a string, any occurrence of any element in search is changed to replace .

int strcasecmp(string


one


, string


two


)

Compares two strings; returns a number less than 0 if one is less than two , 0 if the two strings are equal, and a number greater than 0 if one is greater than two . The comparison is case-insensitive—that is, "Alphabet" and "alphabet" are considered equal. This function is a case-insensitive version of strcmp( ) .

string strchr(string


string


, string


character


)

This function is an alias of strstr ( ) .

int strcmp(string


one


, string


two


)

Compares two strings; returns a number less than 0 if one is less than two , 0 if the two strings are equal, and a number greater than 0 if one is greater than two . The comparison is case-sensitive—that is, "Alphabet" and "alphabet" are not considered equal.

int strcoll(string


one


, string


two


)

Compares two strings using the rules of the current locale; returns a number less than 0 if one is less than two , 0 if the two strings are equal, and a number greater than 0 if one is greater than two . The comparison is case-sensitive—that is, "Alphabet" and "alphabet" are not considered equal.

int strcspn(string


string


, string


characters


)

Returns the position of the first instance of a character from characters in string .

string strftime(string


format


[, int


timestamp


])

Formats a time and date according to the format string provided in the first parameter and the current locale. If the second parameter is not specified, the current time and date is used. The following characters are recognized in the format string:

string stripcslashes(string


string


, string


characters


)

Converts instances of characters after a backslash in string by removing the backslash before them. You can specify ranges of characters by separating them by two periods; for example, to unescape characters between a and q , use "a..q" . Multiple characters and ranges can be specified in characters . The stripcslashes( ) function is the inverse of addcslashes( ) .

string stripslashes(string


string


)

Converts instances of escape sequences that have special meaning in SQL queries in string by removing the backslash before them. Single quotes ( ' ), double quotes ( " ), backslashes ( \ ), and the NUL-byte ( "\0" ) are escaped. This function is the inverse of addslashes( ) .

string strip_tags(string


string


[, string


allowed


])

Removes PHP and HTML tags from string and returns the result. The allowed parameter can be specified to not remove certain tags. The string should be a comma-separated list of the tags to ignore; for example, "<b>,<i>" will leave bold and italics tags.

string stristr(string


string


, string


search


)

Looks for search inside of string , using a case-insensitive comparison. Returns the portion of string from the first occurrence of search to the end of string . If search is not found, the function returns false . This function is a case-insensitive version of strstr( ) .

int strlen(string


string


)

Returns the number of characters in string .

int strnatcasecmp(string


one


, string


two


)

Compares two strings; returns a number less than 0 if one is less than two , 0 if the two strings are equal, and a number greater than 0 if one is greater than two . The comparison is case-insensitive—that is, "Alphabet" and "alphabet" are not considered equal. The function uses a "natural order" algorithm—numbers in the strings are compared more naturally than computers normally do. For example, the values "1", "10", and "2" are sorted in that order by strcmp( ) , but strnatcmp( ) orders them "1", "2", and "10". This function is a case-insensitive version of strnatcmp( ) .

int strnatcmp(string


one


, string


two


)

Compares two strings; returns a number less than 0 if one is less than two , 0 if the two strings are equal, and a number greater than 0 if one is greater than two . The comparison is case-sensitive—that is, "Alphabet" and "alphabet" are not considered equal. The strnatcmp( ) function uses a "natural order" algorithm—numbers in the strings are compared more naturally than computers normally do. For example, the values "1", "10", and "2" are sorted in that order by strcmp( ) , but strnatcmp( ) orders them "1", "2", and "10".

int strncmp(string


one


, string


two


[, int


length


])

Compares two strings; returns a number less than 0 if one is less than two , 0 if the two strings are equal, and a number greater than 0 if one is greater than two . The comparison is case-sensitive—that is, "Alphabet" and "alphabet" are not considered equal. If specified, no more than length characters are compared. If either string is shorter than length characters, the length of that string determines how many characters are compared.

int strpos(string


string


, string


value


[, int


offset


])

Returns the position of the first occurrence of value in string . If specified, the function begins its search at position offset . Returns false if value is not found.

string strrchr(string


string


, string


character


)

Returns the portion of string from the last occurrence of character until the end of string . If character is not found, the function returns false . If character contains more than one character, only the first is used.

string strrev(string


string


)

Returns a string containing the characters of string in reverse order. For example:

$string = strrev("Hello, world"); // contains "dlrow ,olleH"

int strrpos(string


string


, string


search


)

Returns the position of the last occurrence of search in string , or false if search is not found.

int strspn(string


string


, string


characters


)

Returns the length of the substring in string that consists solely of characters in characters .

string strstr(string


string


, string


character


)

Returns the portion of string from the first occurrence of character until the end of string . If character is not found, the function returns false . If character contains more than one character, only the first is used.

string strtok(string


string


, string


token


)
string strtok(string


token


)

Breaks string into tokens separated by any of the characters in token and returns the next token found. The first time you call strtok( ) on a string, use the first function prototype; afterwards, use the second, providing only the tokens. The function contains an internal pointer for each string it is called with. For example:

$string = "This is the time for all good men to come to the aid of their country."
$current = strtok($string, " .;,\"'");
while(!($current === FALSE)) {
   print($current . "<br />";
}

string strtolower(string


string


)

Returns string with all alphabetic characters converted to lowercase. The table used for converting characters is locale-specific .

int strtotime(string


time


[, int


timestamp


])

Converts an English description of a time and date into a Unix timestamp value. Optionally, a timestamp can be given that the function uses as the "now" value; if not, the current date and time is used.

The descriptive string can be in a number of formats. For example, all of the following will work:

echo strtotime("now");
echo strtotime("+1 week");
echo strtotime("-1 week 2 days 4 seconds");
echo strtotime("2 January 1972");

string strtoupper(string


string


)

Returns string with all alphabetic characters converted to uppercase. The table used for converting characters is locale-specific.

string strtr(string


string


, string


from


, string


to


)

Returns a string created by translating in string every occurrence of a character in from to the character in to with the same position.

string strval(mixed


value


)

Returns the string equivalent for value . If value is a nonscalar value (object or array), the function returns an empty string.

string substr(string


string


, int


offset


[, int


length


])

Returns the substring of string . If offset is positive, the substring starts at that character; if it is negative, the substring starts at the character offset characters from the string's end. If length is given and is positive, that many characters from the start of the substring are returned. If length is given and is negative, the substring ends length characters from the end of string . If length is not given, the substring contains all characters to the end of string .

int substr_count(string


string


, string


search


)

Returns the number of times search appears in string .

string substr_replace(string


string


, string


replace


, string


offset


[, int


length


])

Replaces a substring in string with replace . The substring replaced is selected using the same rules as those of substr( ) .

int symlink(string


path


, string


new


)

Creates a symbolic link to path at the path new . Returns true if the link was successfully created and false if not.

int syslog(int


priority


, string


message


)

Sends an error message to the system logging facility. On Unix systems, this is syslog(3) ; on Windows NT, the messages are logged in the NT Event Log. The message is logged with the given priority, which is one of the following (listed in decreasing order of priority):

If message contains the characters %m , they are replaced with the current error message, if any is set. Returns true if the logging succeeded and false if a failure occurred.

string system(string


command


[, int


return


])

Executes command via the shell and returns the last line of output from the command's result. If return is specified, it is set to the return status of the command .

double tan(double


value


)

Returns the arc tangent of value in radians.

string tempnam(string


path


, string


prefix


)

Generates and returns a unique filename in the directory path . If path does not exist, the resulting temporary file may be located in the system's temporary directory. The filename is prefixed with prefix . Returns a null string if the operation could not be performed.

int time(  )

Returns the current Unix timestamp.

int tmpfile(  )

Creates a temporary file with a unique name, opens it with write privileges, and returns a resource to the file.

bool touch(string


path


[, int


time


])

Sets the modification date of path to time (a Unix timestamp value). If not specified, time defaults to the current time. If the file does not exist, it is created. Returns true if the function completed without error and false if an error occurred.

void trigger_error(string


error


[, int


type


])

Triggers an error condition; if the type is not given, it defaults to E_USER_NOTICE . The following types are valid:

The error string will be truncated to 1KB of text if it is longer than 1KB.

string trim(string


string


)

Returns string with all whitespace characters stripped from the beginning and end; the characters stripped are \n , \r , \t , \v , \0 , and spaces.

void uasort(array


array


, string


function


)

Sorts an array using a user-defined function, maintaining the keys for the values. See Chapter 5 and usort for more information on using this function.

string ucfirst(string


string


)

Returns string with the first character, if alphabetic, converted to uppercase. The table used for converting characters is locale-specific.

string ucwords(string


string


)

Returns string with the first character of each word, if alphabetic, converted to uppercase. The table used for converting characters is locale-specific.

void uksort(array


array


, string


function


)

Sorts an array by keys using a user-defined function, maintaining the keys for the values. SeeChapter 5 and usort for more information on using this function.

int umask([int


mask


])

Sets PHP's default permissions to mask and returns the previous mask if successful, or false if an error occurred. The previous default permissions are restored at the end of the current script. If mask is not supplied, the current permissions are returned.

string uniqid(string


prefix


[, bool


more_entropy


])

Returns a unique identifier, prefixed with prefix , based on the current time in microseconds. If more_entropy is specified and is true , additional random characters are added to the end of the string. The resulting string is either 13 characters (if more_entropy is unspecified or false ) or 23 characters (if more_entropy is true ) long.

int unlink(string


path


)

Deletes the file path . Returns true if the operation was successful and false if not.

array unpack(string


format


, string


data


)

Returns an array of values retrieved from the binary string data , which was previously packed using the pack( ) function and the format format .

void unregister_tick_function(string


name


)

Removes the function name , previously set using register_tick_function( ) , as a tick function. It will no longer be called during each tick.

mixed unserialize(string


data


)

Returns the value stored in data , which must be a value previously serialized using serialize( ) .

void unset(mixed


name


[, mixed


name2


[, ... mixed


nameN


]])

Removes the given variables entirely; PHP will no longer know about the variables, even if they previously had values.

string urldecode(string


url


)

Returns a string created from decoding the URI-encoded url . Sequences of characters beginning with a % followed by a hexadecimal number are replaced with the literal the sequence represents. See rawurldecode , which this function differs from in only in that it decodes plus signs ( + ) as spaces.

string urlencode(string


url


)

Returns a string created by URI encoding url . Certain characters are replaced by sequences of characters beginning with a % followed by a hexadecimal number; for example, spaces are replaced with %20 . This function differs from rawurlencode( ) in that it encodes spaces as plus signs ( + ).

void user_error(string


error


[, int


type


])

This function is an alias for trigger_error( ) .

void usleep(int


time


)

Pauses execution of the current script for time microseconds.

void usort(array


array


, string


function


)

Sorts an array using a user-defined function. The supplied function is called with two parameters. It should return an integer less than if the first argument is less than the second, 0 if the first and second arguments are equal, and an integer greater than 0 if the first argument is greater than the second. The sort order of two elements that compare equal is undefined. See Chapter 5 for more information on using this function.

void var_dump(mixed


name


[, mixed


name2


[, ... mixed


nameN


]])

Outputs information, including the variable's type and value, about the given variables. The output is similar to that provided by print_r( ) .

int version_compare(string


one


, string


two


[, string


operator


])

Compares two strings of the format "4.1.0" and returns -1 if one is less than two , if they are equal, and 1 if one is greater than two . If operator is specified, the operator is used to make a comparison between the version strings, and the value of the comparison using that operator is returned. The possible operators are < or lt ; <= or le ; > or gt ; >= or ge ; == , = , or eq ; and != , <> , and ne .

void vprintf(string


format


[, array


values


])

Prints a string created by filling format with the arguments given in the array values . See printf for more information on using this function.

string vsprintf(string


format


[, array


values


])

Creates and returns a string created by filling format with the arguments given in the array values . See printf for more information on using this function.

string wordwrap(string


string


[, int


size


[, string


postfix


[, int


force


]]])

Inserts postfix into string every size characters and at the end of the string, and returns the resulting string. While inserting breaks, the function attempts to not break in the middle of a word. If not specified, postfix defaults to \r\n and size defaults to 76 . If force is given and is true , the string is always wrapped to the given length (this makes the function behave the same as chunk_split( ) ).

string zend_logo_guid(  )

string zend_version(  )