delight-im/str

Convenient object-oriented operations on strings

PHP-Str

Convenient object-oriented operations on strings, _(*1)

Requirements

• PHP 5.3.0+
  • Multibyte String extension (mbstring)

Installation

1. Include the library via Composer [?]:, _(*2)

   $ composer require delight-im/str
   

2. Include the Composer autoloader:, _(*3)

   require __DIR__ . '/vendor/autoload.php';
   

Usage

Usually, you'll want to set up the following shorthand in the global namespace of your PHP code:, _(*4)

function s($str, $charset = null) {
    return new \Delight\Str\Str($str, $charset);
}

This lets you create string objects by simply wrapping strings in s(...)., _(*5)

With that shorthand in place, creating instances from any string is as simple as this:, _(*6)

$str = s('Hello w☺rld');
// or
$str = s('Hello w☺rld', 'UTF-8');

If you don’t want to set up that shorthand, however, you can still create instances easily:, _(*7)

$str = \Delight\Str\Str::from('Hello w☺rld');
// or
$str = \Delight\Str\Str::from('Hello w☺rld', 'UTF-8');

Available methods

• startsWith
  • startsWithBytes
  • startsWithCodePoints
• startsWithIgnoreCase
  • startsWithBytesIgnoreCase
  • startsWithCodePointsIgnoreCase
• contains
  • containsBytes
  • containsCodePoints
• containsIgnoreCase
  • containsBytesIgnoreCase
  • containsCodePointsIgnoreCase
• endsWith
  • endsWithBytes
  • endsWithCodePoints
• endsWithIgnoreCase
  • endsWithBytesIgnoreCase
  • endsWithCodePointsIgnoreCase
• trim
• trimStart
• trimEnd
• first
  • firstBytes
  • firstCodePoints
• last
  • lastBytes
  • lastCodePoints
• byteAt
• codePointAt
• isEmpty
• isAscii
• isPrintableAscii
• toLowerCase
  • toLowerCaseBytes
  • toLowerCaseCodePoints
• isLowerCase
• toUpperCase
  • toUpperCaseBytes
  • toUpperCaseCodePoints
• isUpperCase
• isCapitalized
• truncate
  • truncateBytes
  • truncateCodePoints
• truncateSafely
  • truncateBytesSafely
  • truncateCodePointsSafely
• count
  • countBytes
  • countCodePoints
• length
  • lengthInBytes
  • lengthInCodePoints
• cutStart
  • cutBytesAtStart
  • cutCodePointsAtStart
• cutEnd
  • cutBytesAtEnd
  • cutCodePointsAtEnd
• replace
  • replaceBytes
  • replaceCodePoints
• replaceIgnoreCase
  • replaceBytesIgnoreCase
  • replaceCodePointsIgnoreCase
• replaceFirst
  • replaceFirstBytes
  • replaceFirstCodePoints
• replaceFirstIgnoreCase
  • replaceFirstBytesIgnoreCase
  • replaceFirstCodePointsIgnoreCase
• replacePrefix
  • replacePrefixBytes
  • replacePrefixCodePoints
• replaceLast
  • replaceLastBytes
  • replaceLastCodePoints
• replaceLastIgnoreCase
  • replaceLastBytesIgnoreCase
  • replaceLastCodePointsIgnoreCase
• replaceSuffix
  • replaceSuffixBytes
  • replaceSuffixCodePoints
• split
  • splitBytes
  • splitCodePoints
• splitByRegex
• words
• beforeFirst
  • beforeFirstBytes
  • beforeFirstCodePoints
• beforeLast
  • beforeLastBytes
  • beforeLastCodePoints
• between
  • betweenBytes
  • betweenCodePoints
• afterFirst
  • afterFirstBytes
  • afterFirstCodePoints
• afterLast
  • afterLastBytes
  • afterLastCodePoints
• matches
• equals
• equalsIgnoreCase
• compareTo
  • compareToBytes
  • compareToCodePoints
• compareToIgnoreCase
  • compareToBytesIgnoreCase
  • compareToCodePointsIgnoreCase
• escapeForHtml
• normalizeLineEndings
• reverse
• acronym

/**
 * Returns whether this string starts with the supplied other string
 *
 * This operation is case-sensitive
 *
 * @param string $prefix the other string to search for
 * @return bool whether the supplied other string can be found at the beginning of this string
 */
function startsWith($prefix);
function startsWithBytes($prefix);
function startsWithCodePoints($prefix);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string starts with the supplied other string
 *
 * This operation is case-insensitive
 *
 * @param string $prefix the other string to search for
 * @return bool whether the supplied other string can be found at the beginning of this string
 */
function startsWithIgnoreCase($prefix);
function startsWithBytesIgnoreCase($prefix);
function startsWithCodePointsIgnoreCase($prefix);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string contains the supplied other string
 *
 * This operation is case-sensitive
 *
 * @param string $infix the other string to search for
 * @return bool whether the supplied other string is contained in this string
 */
function contains($infix);
function containsBytes($infix);
function containsCodePoints($infix);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string contains the supplied other string
 *
 * This operation is case-insensitive
 *
 * @param string $infix the other string to search for
 * @return bool whether the supplied other string is contained in this string
 */
function containsIgnoreCase($infix);
function containsBytesIgnoreCase($infix);
function containsCodePointsIgnoreCase($infix);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string ends with the supplied other string
 *
 * This operation is case-sensitive
 *
 * @param string $suffix the other string to search for
 * @return bool whether the supplied other string can be found at the end of this string
 */
function endsWith($suffix);
function endsWithBytes($suffix);
function endsWithCodePoints($suffix);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string ends with the supplied other string
 *
 * This operation is case-insensitive
 *
 * @param string $suffix the other string to search for
 * @return bool whether the supplied other string can be found at the end of this string
 */
function endsWithIgnoreCase($suffix);
function endsWithBytesIgnoreCase($suffix);
function endsWithCodePointsIgnoreCase($suffix);


////////////////////////////////////////////////////////////////////////////////


/**
 * Removes all whitespace or the specified characters from both sides of this string
 *
 * @param string $charactersToRemove the characters to remove (optional)
 * @param bool $alwaysRemoveWhitespace whether to remove whitespace even if a custom list of characters is provided (optional)
 * @return static this instance for chaining
 */
function trim($charactersToRemove = null, $alwaysRemoveWhitespace = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Removes all whitespace or the specified characters from the start of this string
 *
 * @param string $charactersToRemove the characters to remove (optional)
 * @param bool $alwaysRemoveWhitespace whether to remove whitespace even if a custom list of characters is provided (optional)
 * @return static this instance for chaining
 */
function trimStart($charactersToRemove = null, $alwaysRemoveWhitespace = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Removes all whitespace or the specified characters from the end of this string
 *
 * @param string $charactersToRemove the characters to remove (optional)
 * @param bool $alwaysRemoveWhitespace whether to remove whitespace even if a custom list of characters is provided (optional)
 * @return static this instance for chaining
 */
function trimEnd($charactersToRemove = null, $alwaysRemoveWhitespace = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the first character or the specified number of characters from the start of this string
 *
 * @param int|null $length the number of characters to return from the start (optional)
 * @return static a new instance of this class
 */
function first($length = null);
function firstBytes($length = null);
function firstCodePoints($length = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the last character or the specified number of characters from the end of this string
 *
 * @param int|null $length the number of characters to return from the end (optional)
 * @return static a new instance of this class
 */
function last($length = null);
function lastBytes($length = null);
function lastCodePoints($length = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the byte at the specified position of this string
 *
 * @param int $index the zero-based position of the byte to return
 * @return string the byte at the specified position
 */
function byteAt($index);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the code point at the specified position of this string
 *
 * @param int $index the zero-based position of the code point to return
 * @return string the code point at the specified position
 */
function codePointAt($index);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string is empty
 *
 * @return bool
 */
public function isEmpty();


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string consists entirely of ASCII characters
 *
 * @return bool
 */
public function isAscii();


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string consists entirely of printable ASCII characters
 *
 * @return bool
 */
public function isPrintableAscii();


////////////////////////////////////////////////////////////////////////////////


/**
 * Converts this string to lowercase
 *
 * @return static this instance for chaining
 */
function toLowerCase();
function toLowerCaseBytes();
function toLowerCaseCodePoints();


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string is entirely lowercase
 *
 * @return bool
 */
function isLowerCase();


////////////////////////////////////////////////////////////////////////////////


/**
 * Converts this string to uppercase
 *
 * @return static this instance for chaining
 */
function toUpperCase();
function toUpperCaseBytes();
function toUpperCaseCodePoints();


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string is entirely uppercase
 *
 * @return bool
 */
function isUpperCase();


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string has its first letter written in uppercase
 *
 * @return bool
 */
function isCapitalized();


////////////////////////////////////////////////////////////////////////////////


/**
 * Truncates this string so that it has at most the specified length
 *
 * @param int $maxLength the maximum length that this string may have (including any ellipsis)
 * @param string|null $ellipsis the string to use as the ellipsis (optional)
 * @return static a new instance of this class
 */
function truncate($maxLength, $ellipsis = null);
function truncateBytes($maxLength, $ellipsis = null);
function truncateCodePoints($maxLength, $ellipsis = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Truncates this string so that it has at most the specified length
 *
 * This method tries *not* to break any words whenever possible
 *
 * @param int $maxLength the maximum length that this string may have (including any ellipsis)
 * @param string|null $ellipsis the string to use as the ellipsis (optional)
 * @return static a new instance of this class
 */
function truncateSafely($maxLength, $ellipsis = null);
function truncateBytesSafely($maxLength, $ellipsis = null);
function truncateCodePointsSafely($maxLength, $ellipsis = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Counts the occurrences of the specified substring in this string
 *
 * @param string $substring the substring whose occurrences to count
 * @return int the number of occurrences
 */
function count($substring = null);
function countBytes($substring = null);
function countCodePoints($substring = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the length of this string
 *
 * @return int the number of characters
 */
function length();
function lengthInBytes();
function lengthInCodePoints();


////////////////////////////////////////////////////////////////////////////////


/**
 * Removes the specified number of characters from the start of this string
 *
 * @param int $length the number of characters to remove
 * @return static a new instance of this class
 */
function cutStart($length);
function cutBytesAtStart($length);
function cutCodePointsAtStart($length);


////////////////////////////////////////////////////////////////////////////////


/**
 * Removes the specified number of characters from the end of this string
 *
 * @param int $length the number of characters to remove
 * @return static a new instance of this class
 */
function cutEnd($length);
function cutBytesAtEnd($length);
function cutCodePointsAtEnd($length);


////////////////////////////////////////////////////////////////////////////////


/**
 * Replaces all occurrences of the specified search string with the given replacement
 *
 * @param string $searchFor the string to search for
 * @param string $replaceWith the string to use as the replacement (optional)
 * @return static this instance for chaining
 */
function replace($searchFor, $replaceWith = null);
function replaceBytes($searchFor, $replaceWith = null);
function replaceCodePoints($searchFor, $replaceWith = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Replaces all occurrences of the specified search string with the given replacement
 *
 * This operation is case-insensitive
 *
 * @param string $searchFor the string to search for
 * @param string $replaceWith the string to use as the replacement (optional)
 * @return static a new instance of this class
 */
function replaceIgnoreCase($searchFor, $replaceWith = null);
function replaceBytesIgnoreCase($searchFor, $replaceWith = null);
function replaceCodePointsIgnoreCase($searchFor, $replaceWith = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Replaces the first occurrence of the specified search string with the given replacement
 *
 * @param string $searchFor the string to search for
 * @param string $replaceWith the string to use as the replacement (optional)
 * @return static a new instance of this class
 */
function replaceFirst($searchFor, $replaceWith = null);
function replaceFirstBytes($searchFor, $replaceWith = null);
function replaceFirstCodePoints($searchFor, $replaceWith = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Replaces the first occurrence of the specified search string with the given replacement
 *
 * This operation is case-insensitive
 *
 * @param string $searchFor the string to search for
 * @param string $replaceWith the string to use as the replacement (optional)
 * @return static a new instance of this class
 */
function replaceFirstIgnoreCase($searchFor, $replaceWith = null);
function replaceFirstBytesIgnoreCase($searchFor, $replaceWith = null);
function replaceFirstCodePointsIgnoreCase($searchFor, $replaceWith = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Replaces the specified part in this string only if it starts with that part
 *
 * @param string $searchFor the string to search for
 * @param string $replaceWith the string to use as the replacement (optional)
 * @return static a new instance of this class
 */
function replacePrefix($searchFor, $replaceWith = null);
function replacePrefixBytes($searchFor, $replaceWith = null);
function replacePrefixCodePoints($searchFor, $replaceWith = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Replaces the last occurrence of the specified search string with the given replacement
 *
 * @param string $searchFor the string to search for
 * @param string $replaceWith the string to use as the replacement (optional)
 * @return static a new instance of this class
 */
function replaceLast($searchFor, $replaceWith = null);
function replaceLastBytes($searchFor, $replaceWith = null);
function replaceLastCodePoints($searchFor, $replaceWith = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Replaces the last occurrence of the specified search string with the given replacement
 *
 * This operation is case-insensitive
 *
 * @param string $searchFor the string to search for
 * @param string $replaceWith the string to use as the replacement (optional)
 * @return static a new instance of this class
 */
function replaceLastIgnoreCase($searchFor, $replaceWith = null);
function replaceLastBytesIgnoreCase($searchFor, $replaceWith = null);
function replaceLastCodePointsIgnoreCase($searchFor, $replaceWith = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Replaces the specified part in this string only if it ends with that part
 *
 * @param string $searchFor the string to search for
 * @param string $replaceWith the string to use as the replacement (optional)
 * @return static a new instance of this class
 */
function replaceSuffix($searchFor, $replaceWith = null);
function replaceSuffixBytes($searchFor, $replaceWith = null);
function replaceSuffixCodePoints($searchFor, $replaceWith = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Splits this string into an array of substrings at the specified delimiter
 *
 * @param string $delimiter the delimiter to split the string at
 * @param int|null $limit the maximum number of substrings to return (optional)
 * @return static[] an array containing the substrings (which are instances of this class as well)
 */
function split($delimiter, $limit = null);
function splitBytes($delimiter, $limit = null);
function splitCodePoints($delimiter, $limit = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Splits this string into an array of substrings at the specified delimiter pattern
 *
 * @param string $delimiterPattern the regular expression (PCRE) to split the string at
 * @param int|null $limit the maximum number of substrings to return (optional)
 * @param int|null $flags any combination (bit-wise ORed) of PHP's `PREG_SPLIT_*` flags
 * @return static[] an array containing the substrings (which are instances of this class as well)
 */
function splitByRegex($delimiterPattern, $limit = null, $flags = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Splits this string into its single words
 *
 * @param int|null the maximum number of words to return from the start (optional)
 * @return static[] the new instances of this class
 */
function words($limit = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the part of this string *before* the *first* occurrence of the search string
 *
 * @param string $search the search string that should delimit the end
 * @return static a new instance of this class
 */
function beforeFirst($search);
function beforeFirstBytes($search);
function beforeFirstCodePoints($search);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the part of this string *before* the *last* occurrence of the search string
 *
 * @param string $search the search string that should delimit the end
 * @return static a new instance of this class
 */
function beforeLast($search);
function beforeLastBytes($search);
function beforeLastCodePoints($search);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the part of this string between the two specified substrings
 *
 * If there are multiple occurrences, the part with the maximum length will be returned
 *
 * @param string $start the substring whose first occurrence should delimit the start
 * @param string $end the substring whose last occurrence should delimit the end
 * @return static a new instance of this class
 */
function between($start, $end);
function betweenBytes($start, $end);
function betweenCodePoints($start, $end);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the part of this string *after* the *first* occurrence of the search string
 *
 * @param string $search the search string that should delimit the start
 * @return static a new instance of this class
 */
function afterFirst($search);
function afterFirstBytes($search);
function afterFirstCodePoints($search);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns the part of this string *after* the *last* occurrence of the search string
 *
 * @param string $search the search string that should delimit the start
 * @return static a new instance of this class
 */
function afterLast($search);
function afterLastBytes($search);
function afterLastCodePoints($search);


////////////////////////////////////////////////////////////////////////////////


/**
 * Matches this string against the specified regular expression (PCRE)
 *
 * @param string $regex the regular expression (PCRE) to match against
 * @param mixed|null $matches the array that should be filled with the matches (optional)
 * @param bool|null $returnAll whether to return all matches and not only the first one (optional)
 * @return bool whether this string matches the regular expression
 */
function matches($regex, &$matches = null, $returnAll = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string matches the other string
 *
 * @param string $other the other string to compare with
 * @return bool whether the two strings are equal
 */
function equals($other);


////////////////////////////////////////////////////////////////////////////////


/**
 * Returns whether this string matches the other string
 *
 * This operation is case-sensitive
 *
 * @param string $other the other string to compare with
 * @return bool whether the two strings are equal
 */
function equalsIgnoreCase($other);


////////////////////////////////////////////////////////////////////////////////


/**
 * Compares this string to another string lexicographically
 *
 * @param string $other the other string to compare to
 * @param bool|null $human whether to use human sorting for numbers (e.g. `2` before `10`) (optional)
 * @return int an indication whether this string is less than (< 0), equal (= 0) or greater (> 0)
 */
function compareTo($other, $human = null);
function compareToBytes($other, $human = null);
function compareToCodePoints($other, $human = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Compares this string to another string lexicographically
 *
 * This operation is case-sensitive
 *
 * @param string $other the other string to compare to
 * @param bool|null $human whether to use human sorting for numbers (e.g. `2` before `10`) (optional)
 * @return int an indication whether this string is less than (< 0), equal (= 0) or greater (> 0)
 */
function compareToIgnoreCase($other, $human = null);
function compareToBytesIgnoreCase($other, $human = null);
function compareToCodePointsIgnoreCase($other, $human = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Escapes this string for safe use in HTML
 *
 * @return static this instance for chaining
 */
function escapeForHtml();


////////////////////////////////////////////////////////////////////////////////


/**
 * Normalizes all line endings in this string by using a single unified newline sequence (which may be specified manually)
 *
 * @param string|null $newlineSequence the target newline sequence to use (optional)
 * @return static this instance for chaining
 */
function normalizeLineEndings($newlineSequence = null);


////////////////////////////////////////////////////////////////////////////////


/**
 * Reverses this string
 *
 * @return static a new instance of this class
 */
function reverse();


////////////////////////////////////////////////////////////////////////////////


/**
 * Turns this string into an acronym (abbreviation)
 *
 * @param bool|null $excludeLowerCase whether to exclude lowercase letters from the result (optional)
 * @return static a new instance of this class
 */
function acronym($excludeLowerCase = null);

Checking the length of a string

$length = count($strInstance);
// or
$length = $strInstance->length();
// or
$length = $strInstance->count();

Creating instances from all entries in an array

$instances = \Delight\Str\Str::fromArray($arrayOfStrings);

Contributing

All contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed., _(*8)

License

This project is licensed under the terms of the MIT License., _(*9)