Add Safe PHP functions

vendor/thecodingmachine/safe/generated/strings.php

@@ -0,0 +1,561 @@
+<?php
+
+namespace Safe;
+
+use Safe\Exceptions\StringsException;
+
+/**
+ * convert_uudecode decodes a uuencoded string.
+ *
+ * @param string $data The uuencoded data.
+ * @return string Returns the decoded data as a string.
+ * @throws StringsException
+ *
+ */
+function convert_uudecode(string $data): string
+{
+    error_clear_last();
+    $result = \convert_uudecode($data);
+    if ($result === false) {
+        throw StringsException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ * convert_uuencode encodes a string using the uuencode
+ * algorithm.
+ *
+ * Uuencode translates all strings (including binary data) into printable
+ * characters, making them safe for network transmissions. Uuencoded data is
+ * about 35% larger than the original.
+ *
+ * @param string $data The data to be encoded.
+ * @return string Returns the uuencoded data.
+ * @throws StringsException
+ *
+ */
+function convert_uuencode(string $data): string
+{
+    error_clear_last();
+    $result = \convert_uuencode($data);
+    if ($result === false) {
+        throw StringsException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ * Decodes a hexadecimally encoded binary string.
+ *
+ * @param string $data Hexadecimal representation of data.
+ * @return string Returns the binary representation of the given data.
+ * @throws StringsException
+ *
+ */
+function hex2bin(string $data): string
+{
+    error_clear_last();
+    $result = \hex2bin($data);
+    if ($result === false) {
+        throw StringsException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ * Calculates the MD5 hash of the file specified by the
+ * filename parameter using the
+ * RSA Data Security, Inc.
+ * MD5 Message-Digest Algorithm, and returns that hash.
+ * The hash is a 32-character hexadecimal number.
+ *
+ * @param string $filename The filename
+ * @param bool $raw_output When TRUE, returns the digest in raw binary format with a length of
+ * 16.
+ * @return string Returns a string on success, FALSE otherwise.
+ * @throws StringsException
+ *
+ */
+function md5_file(string $filename, bool $raw_output = false): string
+{
+    error_clear_last();
+    $result = \md5_file($filename, $raw_output);
+    if ($result === false) {
+        throw StringsException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ * Calculates the metaphone key of str.
+ *
+ * Similar to soundex metaphone creates the same key for
+ * similar sounding words. It's more accurate than
+ * soundex as it knows the basic rules of English
+ * pronunciation.  The metaphone generated keys are of variable length.
+ *
+ * Metaphone was developed by Lawrence Philips
+ * &lt;lphilips at verity dot com&gt;. It is described in ["Practical
+ * Algorithms for Programmers", Binstock &amp; Rex, Addison Wesley,
+ * 1995].
+ *
+ * @param string $str The input string.
+ * @param int $phonemes This parameter restricts the returned metaphone key to
+ * phonemes characters in length.
+ * The default value of 0 means no restriction.
+ * @return string Returns the metaphone key as a string.
+ * @throws StringsException
+ *
+ */
+function metaphone(string $str, int $phonemes = 0): string
+{
+    error_clear_last();
+    $result = \metaphone($str, $phonemes);
+    if ($result === false) {
+        throw StringsException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ *
+ *
+ * @param string $filename The filename of the file to hash.
+ * @param bool $raw_output When TRUE, returns the digest in raw binary format with a length of
+ * 20.
+ * @return string Returns a string on success, FALSE otherwise.
+ * @throws StringsException
+ *
+ */
+function sha1_file(string $filename, bool $raw_output = false): string
+{
+    error_clear_last();
+    $result = \sha1_file($filename, $raw_output);
+    if ($result === false) {
+        throw StringsException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ * Returns a string produced according to the formatting string
+ * format.
+ *
+ * @param string $format The format string is composed of zero or more directives:
+ * ordinary characters (excluding %) that are
+ * copied directly to the result and conversion
+ * specifications, each of which results in fetching its
+ * own parameter.  This applies to both sprintf
+ * and printf.
+ *
+ * Each conversion specification consists of a percent sign
+ * (%), followed by one or more of these
+ * elements, in order:
+ *
+ *
+ *
+ * An optional sign specifier that forces a sign
+ * (- or +) to be used on a number. By default, only the - sign is used
+ * on a number if it's negative. This specifier forces positive numbers
+ * to have the + sign attached as well.
+ *
+ *
+ *
+ *
+ * An optional padding specifier that says
+ * what character will be used for padding the results to the
+ * right string size.  This may be a space character or a
+ * 0 (zero character).  The default is to pad
+ * with spaces.  An alternate padding character can be specified
+ * by prefixing it with a single quote (').
+ * See the examples below.
+ *
+ *
+ *
+ *
+ * An optional alignment specifier that says
+ * if the result should be left-justified or right-justified.
+ * The default is right-justified; a -
+ * character here will make it left-justified.
+ *
+ *
+ *
+ *
+ * An optional number, a width specifier
+ * that says how many characters (minimum) this conversion should
+ * result in.
+ *
+ *
+ *
+ *
+ * An optional precision specifier in the form
+ * of a period (.) followed by an optional decimal digit string
+ * that says how many decimal digits should be displayed for
+ * floating-point numbers. When using this specifier on a string,
+ * it acts as a cutoff point, setting a maximum character limit to
+ * the string. Additionally, the character to use when padding a
+ * number may optionally be specified between the period and the
+ * digit.
+ *
+ *
+ *
+ *
+ * A type specifier that says what type the
+ * argument data should be treated as.  Possible types:
+ *
+ *
+ * % - a literal percent character. No
+ * argument is required.
+ *
+ *
+ * b - the argument is treated as an
+ * integer and presented as a binary number.
+ *
+ *
+ * c - the argument is treated as an
+ * integer and presented as the character with that ASCII
+ * value.
+ *
+ *
+ * d - the argument is treated as an
+ * integer and presented as a (signed) decimal number.
+ *
+ *
+ * e - the argument is treated as scientific
+ * notation (e.g. 1.2e+2).
+ * The precision specifier stands for the number of digits after the
+ * decimal point since PHP 5.2.1. In earlier versions, it was taken as
+ * number of significant digits (one less).
+ *
+ *
+ * E - like %e but uses
+ * uppercase letter (e.g. 1.2E+2).
+ *
+ *
+ * f - the argument is treated as a
+ * float and presented as a floating-point number (locale aware).
+ *
+ *
+ * F - the argument is treated as a
+ * float and presented as a floating-point number (non-locale aware).
+ * Available since PHP 5.0.3.
+ *
+ *
+ * g - shorter of %e and
+ * %f.
+ *
+ *
+ * G - shorter of %E and
+ * %F.
+ *
+ *
+ * o - the argument is treated as an
+ * integer and presented as an octal number.
+ *
+ *
+ * s - the argument is treated as and
+ * presented as a string.
+ *
+ *
+ * u - the argument is treated as an
+ * integer and presented as an unsigned decimal number.
+ *
+ *
+ * x - the argument is treated as an integer
+ * and presented as a hexadecimal number (with lowercase
+ * letters).
+ *
+ *
+ * X - the argument is treated as an integer
+ * and presented as a hexadecimal number (with uppercase
+ * letters).
+ *
+ *
+ *
+ *
+ *
+ *
+ * A type specifier that says what type the
+ * argument data should be treated as.  Possible types:
+ *
+ *
+ * % - a literal percent character. No
+ * argument is required.
+ *
+ *
+ * b - the argument is treated as an
+ * integer and presented as a binary number.
+ *
+ *
+ * c - the argument is treated as an
+ * integer and presented as the character with that ASCII
+ * value.
+ *
+ *
+ * d - the argument is treated as an
+ * integer and presented as a (signed) decimal number.
+ *
+ *
+ * e - the argument is treated as scientific
+ * notation (e.g. 1.2e+2).
+ * The precision specifier stands for the number of digits after the
+ * decimal point since PHP 5.2.1. In earlier versions, it was taken as
+ * number of significant digits (one less).
+ *
+ *
+ * E - like %e but uses
+ * uppercase letter (e.g. 1.2E+2).
+ *
+ *
+ * f - the argument is treated as a
+ * float and presented as a floating-point number (locale aware).
+ *
+ *
+ * F - the argument is treated as a
+ * float and presented as a floating-point number (non-locale aware).
+ * Available since PHP 5.0.3.
+ *
+ *
+ * g - shorter of %e and
+ * %f.
+ *
+ *
+ * G - shorter of %E and
+ * %F.
+ *
+ *
+ * o - the argument is treated as an
+ * integer and presented as an octal number.
+ *
+ *
+ * s - the argument is treated as and
+ * presented as a string.
+ *
+ *
+ * u - the argument is treated as an
+ * integer and presented as an unsigned decimal number.
+ *
+ *
+ * x - the argument is treated as an integer
+ * and presented as a hexadecimal number (with lowercase
+ * letters).
+ *
+ *
+ * X - the argument is treated as an integer
+ * and presented as a hexadecimal number (with uppercase
+ * letters).
+ *
+ *
+ *
+ * Variables will be co-erced to a suitable type for the specifier:
+ *
+ * Type Handling
+ *
+ *
+ *
+ * Type
+ * Specifiers
+ *
+ *
+ *
+ *
+ * string
+ * s
+ *
+ *
+ * integer
+ *
+ * d,
+ * u,
+ * c,
+ * o,
+ * x,
+ * X,
+ * b
+ *
+ *
+ *
+ * double
+ *
+ * g,
+ * G,
+ * e,
+ * E,
+ * f,
+ * F
+ *
+ *
+ *
+ *
+ *
+ *
+ * Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
+ *
+ * The format string supports argument numbering/swapping.  Here is an
+ * example:
+ *
+ * Argument swapping
+ *
+ *
+ * ]]>
+ *
+ *
+ * This will output "There are 5 monkeys in the tree".  But
+ * imagine we are creating a format string in a separate file,
+ * commonly because we would like to internationalize it and we
+ * rewrite it as:
+ *
+ * Argument swapping
+ *
+ *
+ * ]]>
+ *
+ *
+ * We now have a problem.  The order of the placeholders in the
+ * format string does not match the order of the arguments in the
+ * code.  We would like to leave the code as is and simply indicate
+ * in the format string which arguments the placeholders refer to.
+ * We would write the format string like this instead:
+ *
+ * Argument swapping
+ *
+ *
+ * ]]>
+ *
+ *
+ * An added benefit here is that you can repeat the placeholders without
+ * adding more arguments in the code.  For example:
+ *
+ * Argument swapping
+ *
+ *
+ * ]]>
+ *
+ *
+ * When using argument swapping, the n$
+ * position specifier must come immediately
+ * after the percent sign (%), before any other
+ * specifiers, as shown in the example below.
+ *
+ * Specifying padding character
+ *
+ *
+ * ]]>
+ *
+ * The above example will output:
+ *
+ *
+ *
+ *
+ *
+ * Position specifier with other specifiers
+ *
+ *
+ * ]]>
+ *
+ * The above example will output:
+ *
+ *
+ *
+ *
+ *
+ * The above example will output:
+ *
+ * The above example will output:
+ *
+ * Attempting to use a position specifier greater than
+ * PHP_INT_MAX will result in
+ * sprintf generating warnings.
+ *
+ * The c type specifier ignores padding and width
+ * @param mixed $params
+ * @return string Returns a string produced according to the formatting string
+ * format.
+ * @throws StringsException
+ *
+ */
+function sprintf(string $format, ...$params): string
+{
+    error_clear_last();
+    if ($params !== []) {
+        $result = \sprintf($format, ...$params);
+    } else {
+        $result = \sprintf($format);
+    }
+    if ($result === false) {
+        throw StringsException::createFromPhpError();
+    }
+    return $result;
+}
+
+
+/**
+ * Returns the portion of string specified by the
+ * start and length parameters.
+ *
+ * @param string $string The input string. Must be one character or longer.
+ * @param int $start If start is non-negative, the returned string
+ * will start at the start'th position in
+ * string, counting from zero. For instance,
+ * in the string 'abcdef', the character at
+ * position 0 is 'a', the
+ * character at position 2 is
+ * 'c', and so forth.
+ *
+ * If start is negative, the returned string
+ * will start at the start'th character
+ * from the end of string.
+ *
+ * If string is less than
+ * start characters long, FALSE will be returned.
+ *
+ *
+ * Using a negative start
+ *
+ *
+ * ]]>
+ *
+ *
+ * @param int $length If length is given and is positive, the string
+ * returned will contain at most length characters
+ * beginning from start (depending on the length of
+ * string).
+ *
+ * If length is given and is negative, then that many
+ * characters will be omitted from the end of string
+ * (after the start position has been calculated when a
+ * start is negative).  If
+ * start denotes the position of this truncation or
+ * beyond, FALSE will be returned.
+ *
+ * If length is given and is 0,
+ * FALSE or NULL, an empty string will be returned.
+ *
+ * If length is omitted, the substring starting from
+ * start until the end of the string will be
+ * returned.
+ * @return string Returns the extracted part of string;, or
+ * an empty string.
+ * @throws StringsException
+ *
+ */
+function substr(string $string, int $start, int $length = null): string
+{
+    error_clear_last();
+    if ($length !== null) {
+        $result = \substr($string, $start, $length);
+    } else {
+        $result = \substr($string, $start);
+    }
+    if ($result === false) {
+        throw StringsException::createFromPhpError();
+    }
+    return $result;
+}