/hphp/idl/preg.idl.php

<?php
/**
 * Automatically generated by running "php schema.php preg".
 *
 * You may modify the file, but re-running schema.php against this file will
 * standardize the format without losing your schema changes. It does lose
 * any changes that are not part of schema. Use "note" field to comment on
 * schema itself, and "note" fields are not used in any code generation but
 * only staying within this file.
 */
///////////////////////////////////////////////////////////////////////////////
// Preamble: C++ code inserted at beginning of ext_{name}.h

DefinePreamble(<<<CPP

CPP
);

///////////////////////////////////////////////////////////////////////////////
// Constants
//
// array (
//   'name' => name of the constant
//   'type' => type of the constant
//   'note' => additional note about this constant's schema
// )


///////////////////////////////////////////////////////////////////////////////
// Functions
//
// array (
//   'name'   => name of the function
//   'desc'   => description of the function's purpose
//   'flags'  => attributes of the function, see base.php for possible values
//   'opt'    => optimization callback function's name for compiler
//   'note'   => additional note about this function's schema
//   'return' =>
//      array (
//        'type'  => return type, use Reference for ref return
//        'desc'  => description of the return value
//      )
//   'args'   => arguments
//      array (
//        'name'  => name of the argument
//        'type'  => type of the argument, use Reference for output parameter
//        'value' => default value of the argument
//        'desc'  => description of the argument
//      )
// )

DefineFunction(
  array(
    'name'   => "preg_grep",
    'desc'   => "Returns the array consisting of the elements of the input array that match the given pattern.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "Returns an array indexed using the keys from the input array.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "The pattern to search for, as a string.",
      ),
      array(
        'name'   => "input",
        'type'   => VariantMap,
        'desc'   => "The input array.",
      ),
      array(
        'name'   => "flags",
        'type'   => Int32,
        'value'  => "0",
        'desc'   => "If set to PREG_GREP_INVERT, this function returns the elements of the input array that do not match the given pattern.",
      ),
    ),
    'taint_observer' => false,
  ));

DefineFunction(
  array(
    'name'   => "preg_match",
    'desc'   => "Searches subject for a match to the regular expression given in pattern.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "preg_match() returns the number of times pattern matches. That will be either 0 times (no match) or 1 time because preg_match() will stop searching after the first match. preg_match_all() on the contrary will continue until it reaches the end of subject. preg_match() returns FALSE if an error occurred.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "The pattern to search for, as a string.",
      ),
      array(
        'name'   => "subject",
        'type'   => String,
        'desc'   => "The input string.",
      ),
      array(
        'name'   => "matches",
        'type'   => Variant | Reference,
        'value'  => "null",
        'desc'   => "If matches is provided, then it is filled with the results of search. \$matches[0] will contain the text that matched the full pattern, \$matches[1] will have the text that matched the first captured parenthesized subpattern, and so on.",
      ),
      array(
        'name'   => "flags",
        'type'   => Int32,
        'value'  => "0",
        'desc'   => "flags can be the following flag: PREG_OFFSET_CAPTURE If this flag is passed, for every occurring match the appendant string offset will also be returned. Note that this changes the value of matches into an array where every element is an array consisting of the matched string at offset 0 and its string offset into subject at offset 1.",
      ),
      array(
        'name'   => "offset",
        'type'   => Int32,
        'value'  => "0",
        'desc'   => "Normally, the search starts from the beginning of the subject string. The optional parameter offset can be used to specify the alternate place from which to start the search (in bytes).\n\nUsing offset is not equivalent to passing substr(\$subject, \$offset) to preg_match() in place of the subject string, because pattern can contain assertions such as ^, \$ or (?<=x). Compare:\n\nArray ( )\n\nwhile this example\n\n\n\nwill produce Array ( [0] => Array ( [0] => def [1] => 0 ) )",
      ),
    ),
    'taint_observer' => false,
  ));

DefineFunction(
  array(
    'name'   => "preg_match_all",
    'desc'   => "Searches subject for all matches to the regular expression given in pattern and puts them in matches in the order specified by flags.\n\nAfter the first match is found, the subsequent searches are continued on from end of the last match.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "Returns the number of full pattern matches (which might be zero), or FALSE if an error occurred.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "The pattern to search for, as a string.",
      ),
      array(
        'name'   => "subject",
        'type'   => String,
        'desc'   => "The input string.",
      ),
      array(
        'name'   => "matches",
        'type'   => Variant | Reference,
        'desc'   => "Array of all matches in multi-dimensional array ordered according to flags.",
      ),
      array(
        'name'   => "flags",
        'type'   => Int32,
        'value'  => "0",
        'desc'   => "Can be a combination of the following flags (note that it doesn't make sense to use PREG_PATTERN_ORDER together with PREG_SET_ORDER): PREG_PATTERN_ORDER\n\nOrders results so that \$matches[0] is an array of full pattern matches, \$matches[1] is an array of strings matched by the first parenthesized subpattern, and so on.\n\n\n\n<b>example: </b>, <div align=left>this is a test</div> example: , this is a test\n\nSo, \$out[0] contains array of strings that matched full pattern, and \$out[1] contains array of strings enclosed by tags.",
      ),
      array(
        'name'   => "offset",
        'type'   => Int32,
        'value'  => "0",
        'desc'   => "Orders results so that \$matches[0] is an array of first set of matches, \$matches[1] is an array of second set of matches, and so on.\n\n<b>example: </b>, example: <div align=\"left\">this is a test</div>, this is a test",
      ),
    ),
    'taint_observer' => false,
  ));

DefineFunction(
  array(
    'name'   => "preg_replace",
    'desc'   => "Searches subject for matches to pattern and replaces them with replacement.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "preg_replace() returns an array if the subject parameter is an array, or a string otherwise.\n\nIf matches are found, the new subject will be returned, otherwise subject will be returned unchanged or NULL if an error occurred.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => Variant,
        'desc'   => "The pattern to search for. It can be either a string or an array with strings.\n\nThe e modifier makes preg_replace() treat the replacement parameter as PHP code after the appropriate references substitution is done. Tip: make sure that replacement constitutes a valid PHP code string, otherwise PHP will complain about a parse error at the line containing preg_replace().",
      ),
      array(
        'name'   => "replacement",
        'type'   => Variant,
        'desc'   => "The string or an array with strings to replace. If this parameter is a string and the pattern parameter is an array, all patterns will be replaced by that string. If both pattern and replacement parameters are arrays, each pattern will be replaced by the replacement counterpart. If there are fewer elements in the replacement array than in the pattern array, any extra patterns will be replaced by an empty string.\n\nreplacement may contain references of the form \\\\n or (since PHP 4.0.4) \$n, with the latter form being the preferred one. Every such reference will be replaced by the text captured by the n'th parenthesized pattern. n can be from 0 to 99, and \\\\0 or \$0 refers to the text matched by the whole pattern. Opening parentheses are counted from left to right (starting from 1) to obtain the number of the capturing subpattern. To use backslash in replacement, it must be doubled (\"\\\\\\\\\" PHP string).\n\nWhen working with a replacement pattern where a backreference is immediately followed by another number (i.e.: placing a literal number immediately after a matched pattern), you cannot use the familiar \\\\1 notation for your backreference. \\\\11, for example, would confuse preg_replace() since it does not know whether you want the \\\\1 backreference followed by a literal 1, or the \\\\11 backreference followed by nothing. In this case the solution is to use \\\${1}1. This creates an isolated \$1 backreference, leaving the 1 as a literal.\n\nWhen using the e modifier, this function escapes some characters (namely ', \", \\ and NULL) in the strings that replace the backreferences. This is done to ensure that no syntax errors arise from backreference usage with either single or double quotes (e.g. 'strlen(\\'\$1\\')+strlen(\"\$2\")'). Make sure you are aware of PHP's string syntax to know exactly how the interpreted string will look like.",
      ),
      array(
        'name'   => "subject",
        'type'   => Variant,
        'desc'   => "The string or an array with strings to search and replace.\n\nIf subject is an array, then the search and replace is performed on every entry of subject, and the return value is an array as well.",
      ),
      array(
        'name'   => "limit",
        'type'   => Int32,
        'value'  => "-1",
        'desc'   => "The maximum possible replacements for each pattern in each subject string. Defaults to -1 (no limit).",
      ),
      array(
        'name'   => "count",
        'type'   => Variant | Reference,
        'value'  => "null",
        'desc'   => "If specified, this variable will be filled with the number of replacements done.",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_NONE",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));

DefineFunction(
  array(
    'name'   => "preg_replace_callback",
    'desc'   => "The behavior of this function is almost identical to preg_replace(), except for the fact that instead of replacement parameter, one should specify a callback.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "preg_replace_callback() returns an array if the subject parameter is an array, or a string otherwise. On errors the return value is NULL\n\nIf matches are found, the new subject will be returned, otherwise subject will be returned unchanged.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => Variant,
        'desc'   => "The pattern to search for. It can be either a string or an array with strings.",
      ),
      array(
        'name'   => "callback",
        'type'   => Variant,
        'desc'   => "A callback that will be called and passed an array of matched elements in the subject string. The callback should return the replacement string.\n\nYou'll often need the callback function for a preg_replace_callback() in just one place. In this case you can use an anonymous function (since PHP 5.3.0) or create_function() to declare an anonymous function as callback within the call to preg_replace_callback(). By doing it this way you have all information for the call in one place and do not clutter the function namespace with a callback function's name not used anywhere else.\n\nExample #1 preg_replace_callback() and create_function()",
      ),
      array(
        'name'   => "subject",
        'type'   => Variant,
        'desc'   => "The string or an array with strings to search and replace.",
      ),
      array(
        'name'   => "limit",
        'type'   => Int32,
        'value'  => "-1",
        'desc'   => "The maximum possible replacements for each pattern in each subject string. Defaults to -1 (no limit).",
      ),
      array(
        'name'   => "count",
        'type'   => Variant | Reference,
        'value'  => "null",
        'desc'   => "If specified, this variable will be filled with the number of replacements done.",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_NONE",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));

DefineFunction(
  array(
    'name'   => "preg_split",
    'desc'   => "Split the given string by a regular expression.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "Returns an array containing substrings of subject split along boundaries matched by pattern.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => Variant,
        'desc'   => "The pattern to search for, as a string.",
      ),
      array(
        'name'   => "subject",
        'type'   => Variant,
        'desc'   => "The input string.",
      ),
      array(
        'name'   => "limit",
        'type'   => Int32,
        'value'  => "-1",
        'desc'   => "If specified, then only substrings up to limit are returned with the rest of the string being placed in the last substring. A limit of -1, 0 or null means \"no limit\" and, as is standard across PHP, you can use null to skip to the flags parameter.",
      ),
      array(
        'name'   => "flags",
        'type'   => Int32,
        'value'  => "0",
        'desc'   => "flags can be any combination of the following flags (combined with the | bitwise operator): PREG_SPLIT_NO_EMPTY If this flag is set, only non-empty pieces will be returned by preg_split().",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_MUTATED",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));

DefineFunction(
  array(
    'name'   => "preg_quote",
    'desc'   => "preg_quote() takes str and puts a backslash in front of every character that is part of the regular expression syntax. This is useful if you have a run-time string that you need to match in some text and the string may contain special regex characters.\n\nThe special regular expression characters are: . \\ + * ? [ ^ ] \$ ( ) { } = ! < > | : -",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => String,
      'desc'   => "Returns the quoted string.",
    ),
    'args'   => array(
      array(
        'name'   => "str",
        'type'   => String,
        'desc'   => "The input string.",
      ),
      array(
        'name'   => "delimiter",
        'type'   => String,
        'value'  => "null_string",
        'desc'   => "If the optional delimiter is specified, it will also be escaped. This is useful for escaping the delimiter that is required by the PCRE functions. The / is the most commonly used delimiter.",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_MUTATED",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));

DefineFunction(
  array(
    'name'   => "preg_last_error",
    'desc'   => "Returns the error code of the last PCRE regex execution.\n\nExample #1 preg_last_error() example\n\n\n\nBacktrack limit was exhausted!",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Int64,
      'desc'   => "Returns one of the following constants (explained on their own page): PREG_NO_ERROR PREG_INTERNAL_ERROR PREG_BACKTRACK_LIMIT_ERROR (see also pcre.backtrack_limit) PREG_RECURSION_LIMIT_ERROR (see also pcre.recursion_limit) PREG_BAD_UTF8_ERROR PREG_BAD_UTF8_OFFSET_ERROR (since PHP 5.3.0)",
    ),
    'taint_observer' => false,
  ));

DefineFunction(
  array(
    'name'   => "ereg_replace",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => String,
      'desc'   => "The modified string is returned. If no matches are found in string, then it will be returned unchanged.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "A POSIX extended regular expression.",
      ),
      array(
        'name'   => "replacement",
        'type'   => String,
        'desc'   => "If pattern contains parenthesized substrings, replacement may contain substrings of the form \\\\digit, which will be replaced by the text matching the digit'th parenthesized substring; \\\\0 will produce the entire contents of string. Up to nine substrings may be used. Parentheses may be nested, in which case they are counted by the opening parenthesis.",
      ),
      array(
        'name'   => "str",
        'type'   => String,
        'desc'   => "The input string.",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_NONE",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));

DefineFunction(
  array(
    'name'   => "eregi_replace",
    'desc'   => "This function is identical to ereg_replace() except that this ignores case distinction when matching alphabetic characters. WarningThis function has been DEPRECATED as of PHP 5.3.0. Relying on this feature is highly discouraged.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => String,
      'desc'   => "The modified string is returned. If no matches are found in string, then it will be returned unchanged.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "A POSIX extended regular expression.",
      ),
      array(
        'name'   => "replacement",
        'type'   => String,
        'desc'   => "If pattern contains parenthesized substrings, replacement may contain substrings of the form \\\\digit, which will be replaced by the text matching the digit'th parenthesized substring; \\\\0 will produce the entire contents of string. Up to nine substrings may be used. Parentheses may be nested, in which case they are counted by the opening parenthesis.",
      ),
      array(
        'name'   => "str",
        'type'   => String,
        'desc'   => "The input string.",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_NONE",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));

DefineFunction(
  array(
    'name'   => "ereg",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "Returns the length of the matched string if a match for pattern was found in string, or FALSE if no matches were found or an error occurred.\n\nIf the optional parameter regs was not passed or the length of the matched string is 0, this function returns 1.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "Case sensitive regular expression.",
      ),
      array(
        'name'   => "str",
        'type'   => String,
        'desc'   => "The input string.",
      ),
      array(
        'name'   => "regs",
        'type'   => Variant | Reference,
        'value'  => "null",
        'desc'   => "If matches are found for parenthesized substrings of pattern and the function is called with the third argument regs, the matches will be stored in the elements of the array regs.\n\n\$regs[1] will contain the substring which starts at the first left parenthesis; \$regs[2] will contain the substring starting at the second, and so on. \$regs[0] will contain a copy of the complete string matched.",
      ),
    ),
    'taint_observer' => false,
  ));

DefineFunction(
  array(
    'name'   => "eregi",
    'desc'   => "This function is identical to ereg() except that it ignores case distinction when matching alphabetic characters. WarningThis function has been DEPRECATED as of PHP 5.3.0. Relying on this feature is highly discouraged.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "Returns the length of the matched string if a match for pattern was found in string, or FALSE if no matches were found or an error occurred.\n\nIf the optional parameter regs was not passed or the length of the matched string is 0, this function returns 1.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "Case insensitive regular expression.",
      ),
      array(
        'name'   => "str",
        'type'   => String,
        'desc'   => "The input string.",
      ),
      array(
        'name'   => "regs",
        'type'   => Variant | Reference,
        'value'  => "null",
        'desc'   => "If matches are found for parenthesized substrings of pattern and the function is called with the third argument regs, the matches will be stored in the elements of the array regs.\n\n\$regs[1] will contain the substring which starts at the first left parenthesis; \$regs[2] will contain the substring starting at the second, and so on. \$regs[0] will contain a copy of the complete string matched.",
      ),
    ),
    'taint_observer' => false,
  ));

DefineFunction(
  array(
    'name'   => "split",
    'desc'   => "Splits a string into array by regular expression. WarningThis function has been DEPRECATED as of PHP 5.3.0. Relying on this feature is highly discouraged.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "Returns an array of strings, each of which is a substring of string formed by splitting it on boundaries formed by the case-sensitive regular expression pattern.\n\nIf there are n occurrences of pattern, the returned array will contain n+1 items. For example, if there is no occurrence of pattern, an array with only one element will be returned. Of course, this is also true if string is empty. If an error occurs, split() returns FALSE.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "Case sensitive regular expression.\n\nIf you want to split on any of the characters which are considered special by regular expressions, you'll need to escape them first. If you think split() (or any other regex function, for that matter) is doing something weird, please read the file regex.7, included in the regex/ subdirectory of the PHP distribution. It's in manpage format, so you'll want to do something along the lines of man /usr/local/src/regex/regex.7 in order to read it.",
      ),
      array(
        'name'   => "str",
        'type'   => String,
        'desc'   => "The input string.",
      ),
      array(
        'name'   => "limit",
        'type'   => Int32,
        'value'  => "-1",
        'desc'   => "If limit is set, the returned array will contain a maximum of limit elements with the last element containing the whole rest of string.",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_NONE",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));

DefineFunction(
  array(
    'name'   => "spliti",
    'desc'   => "Splits a string into array by regular expression.\n\nThis function is identical to split() except that this ignores case distinction when matching alphabetic characters. WarningThis function has been DEPRECATED as of PHP 5.3.0. Relying on this feature is highly discouraged.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => Variant,
      'desc'   => "Returns an array of strings, each of which is a substring of string formed by splitting it on boundaries formed by the case insensitive regular expression pattern.\n\nIf there are n occurrences of pattern, the returned array will contain n+1 items. For example, if there is no occurrence of pattern, an array with only one element will be returned. Of course, this is also true if string is empty. If an error occurs, spliti() returns FALSE.",
    ),
    'args'   => array(
      array(
        'name'   => "pattern",
        'type'   => String,
        'desc'   => "Case insensitive regular expression.\n\nIf you want to split on any of the characters which are considered special by regular expressions, you'll need to escape them first. If you think spliti() (or any other regex function, for that matter) is doing something weird, please read the file regex.7, included in the regex/ subdirectory of the PHP distribution. It's in manpage format, so you'll want to do something along the lines of man /usr/local/src/regex/regex.7 in order to read it.",
      ),
      array(
        'name'   => "str",
        'type'   => String,
        'desc'   => "The input string.",
      ),
      array(
        'name'   => "limit",
        'type'   => Int32,
        'value'  => "-1",
        'desc'   => "If limit is set, the returned array will contain a maximum of limit elements with the last element containing the whole rest of string.",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_NONE",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));

DefineFunction(
  array(
    'name'   => "sql_regcase",
    'desc'   => "Creates a regular expression for a case insensitive match. WarningThis function has been DEPRECATED as of PHP 5.3.0. Relying on this feature is highly discouraged.",
    'flags'  =>  HasDocComment,
    'return' => array(
      'type'   => String,
      'desc'   => "Returns a valid regular expression which will match string, ignoring case. This expression is string with each alphabetic character converted to a bracket expression; this bracket expression contains that character's uppercase and lowercase form. Other characters remain unchanged.",
    ),
    'args'   => array(
      array(
        'name'   => "str",
        'type'   => String,
        'desc'   => "The input string.",
      ),
    ),
    'taint_observer' => array(
      'set_mask'   => "TAINT_BIT_MUTATED",
      'clear_mask' => "TAINT_BIT_NONE",
    ),
  ));


///////////////////////////////////////////////////////////////////////////////
// Classes
//
// BeginClass
// array (
//   'name'   => name of the class
//   'desc'   => description of the class's purpose
//   'flags'  => attributes of the class, see base.php for possible values
//   'note'   => additional note about this class's schema
//   'parent' => parent class name, if any
//   'ifaces' => array of interfaces tihs class implements
//   'bases'  => extra internal and special base classes this class requires
//   'footer' => extra C++ inserted at end of class declaration
// )
//
// DefineConstant(..)
// DefineConstant(..)
// ...
// DefineFunction(..)
// DefineFunction(..)
// ...
// DefineProperty
// DefineProperty
//
// array (
//   'name'  => name of the property
//   'type'  => type of the property
//   'flags' => attributes of the property
//   'desc'  => description of the property
//   'note'  => additional note about this property's schema
// )
//
// EndClass()