index/src/IString.php

199 lines
6.5 KiB
PHP
Raw Normal View History

2022-09-13 13:13:11 +00:00
<?php
// IString.php
// Created: 2021-06-20
2023-11-09 12:58:04 +00:00
// Updated: 2023-11-09
2022-09-13 13:13:11 +00:00
namespace Index;
use ArrayAccess;
use Countable;
use IteratorAggregate;
use JsonSerializable;
use Stringable;
use Index\Serialisation\IBencodeSerialisable;
2023-11-09 12:58:04 +00:00
/**
* @deprecated IString, AString and WString are deprecated and will be removed. Use XString methods instead.
*/
2022-09-13 13:13:11 +00:00
interface IString extends ArrayAccess, Countable, IteratorAggregate, JsonSerializable, Stringable, IComparable, ICloneable, IEquatable, IBencodeSerialisable {
/**
* Default trim characters.
*
* @var string
*/
const TRIM_CHARS = " \n\r\t\v\0";
/**
* Gets the length of the string.
*
* @return int Length of the string.
*/
function getLength(): int;
/**
* Returns whether the string is empty.
*
* @return bool true if the string is empty, false if not.
*/
function isEmpty(): bool;
/**
* Returns the index of a substring.
*
* @see https://www.php.net/manual/en/function.strpos
* @param IString|string $text Substring to look for.
* @param int $offset Offset from which to start looking.
* @return int Offset at which the substring can be found, -1 if the substring can't be found.
*/
function indexOf(IString|string $text, int $offset = 0): int;
/**
* Checks whether the string contains a substring.
*
* @see https://www.php.net/manual/en/function.str-contains
* @param IString|string $text Substring to look for.
* @return bool true if it could be found, false if not.
*/
function contains(IString|string $text): bool;
/**
* Returns a ranged substring.
*
* @see https://www.php.net/manual/en/function.substr
* @param int $offset Offset from which to start.
* @param int|null $length Amount of character to copy, null for the remainder of the string.
* @return IString An instance of IString containing the substring.
*/
function substring(int $offset, int|null $length = null): IString;
/**
* Checks if a string starts with a given substring.
*
* @see https://www.php.net/manual/en/function.str-starts-with
* @param IString|string $text The substring to check for.
* @return bool true if the substring was found, false if not.
*/
function startsWith(IString|string $text): bool;
/**
* Checks if a string ends with a given substring.
*
* @see https://www.php.net/manual/en/function.str-ends-with
* @param IString|string $text The substring to check for.
* @return bool true if the substring was found, false if not.
*/
function endsWith(IString|string $text): bool;
/**
* Replace a substring with another substring.
*
* @see https://www.php.net/manual/en/function.str-replace
* @param IString|string $search Substring that should be replaced.
* @param IString|string $replace Replacement values for what was found with search.
* @return IString A new IString instance with the replaced values.
*/
function replace(IString|string $search, IString|string $replace): IString;
/**
* Concatenates two strings with this one in the first position.
*
* @param IString|string $string String that should be appended.
* @return IString A new IString instance with the combined value.
*/
function append(IString|string $string): IString;
/**
* Concatenates two strings with this one in the last position.
*
* @param IString|string $string String that should be prepended.
* @return IString A new IString instance with the combined value.
*/
function prepend(IString|string $string): IString;
/**
* Split a string by a separator string into an array.
*
* Calling split with an empty string will not work, use ->chunk(1) instead.
*
* @see https://www.php.net/manual/en/function.explode
* @param IString|string $separator The boundary string.
* @param int $limit Maximum number of elements expected in the array.
* @return array The resulting array of substrings.
*/
function split(IString|string $separator, int $limit = PHP_INT_MAX): array;
/**
* Splits a string in substring chunks of a given length.
*
* @see https://www.php.net/manual/en/function.str-split.php
* @param int $chunkSize Maximum length of a chunk.
* @return array The resulting array of substrings.
*/
function chunk(int $chunkSize): array;
/**
* Strip whitespace or other characters from the beginning and end of a string.
*
* @see https://www.php.net/manual/en/function.trim
* @param IString|string $characters Characters to strip.
* @return IString A new instance of IString with the characters removed.
*/
function trim(IString|string $characters = self::TRIM_CHARS): IString;
/**
* Strip whitespace or other characters from the beginning of a string.
*
* @see https://www.php.net/manual/en/function.ltrim.php
* @param IString|string $characters Characters to strip.
* @return IString A new instance of IString with the characters removed.
*/
function trimStart(IString|string $characters = self::TRIM_CHARS): IString;
/**
* Strip whitespace or other characters from the end of a string.
*
* @see https://www.php.net/manual/en/function.rtrim.php
* @param IString|string $characters Characters to strip.
* @return IString A new instance of IString with the characters removed.
*/
function trimEnd(IString|string $characters = self::TRIM_CHARS): IString;
/**
* Convert string to lowercase.
*
* @see https://www.php.net/manual/en/function.strtolower.php
* @return IString A new IString instance with all lowercase characters.
*/
function toLower(): IString;
/**
* Convert string to uppercase.
*
* @see https://www.php.net/manual/en/function.strtoupper.php
* @return IString A new IString instance with all uppercase characters.
*/
function toUpper(): IString;
/**
* Reverses a string.
*
* @see https://www.php.net/manual/en/function.strrev
* @return IString A new IString instance containing the reversed string.
*/
function reverse(): IString;
/**
* Counts unique characters in a string.
*
* @return int Unique character count.
*/
function countUnique(): int;
2022-09-13 13:13:11 +00:00
/**
* Returns a copy of the standard PHP string.
*
* @return string PHP string.
*/
function __toString(): string;
}