value = $value; } public function getLength(): int { return strlen($this->value); } public function isEmpty(): bool { return $this->value === ''; } public function __toString(): string { return $this->value; } /** * Checks if an offset exists in the string. * * You should call isset($string[$offset]) instead of $string->offsetExists($offset). * * @see https://www.php.net/manual/en/arrayaccess.offsetexists.php * @param int $offset Character offset. * @return bool true if it exists, false if not. */ public function offsetExists(mixed $offset): bool { return isset($this->value[$offset]); } /** * Gets an offset from the string. * * You should do $string[$offset] instead of $string->offsetGet($offset). * * @see https://www.php.net/manual/en/arrayaccess.offsetget.php * @param int $offset Character offset. * @return string Character at that offset. */ public function offsetGet(mixed $offset): mixed { return $this->value[$offset]; } /** * Gets an iterator object for this string. * * @return StringIterator An iterator for this string. */ public function getIterator(): Traversable { return new StringIterator($this); } /** * Returns the data which should be serialized as json. * * @see https://www.php.net/manual/en/jsonserializable.jsonserialize.php * @return mixed Data to be passed to json_encode. */ public function jsonSerialize(): mixed { return $this->value; } public function bencodeSerialise(): mixed { return $this->value; } /** * Gets a serialized representation of this object. * * @return array Serialized data. */ public function __serialize(): array { return [$this->value]; } /** * Reconstructs an object from a serialized string. * * @param array $serialized Serialized data. */ public function __unserialize(array $serialized): void { $this->value = $serialized[0]; } /** * Checks whether this string is identical to another. * * @param mixed $other An instance of AString or a PHP string. * @return bool true if the strings have the same value, false if not. */ public function equals(mixed $other): bool { return $this->compare($other) === 0; } /** * Compares whether this string is identical to another. * * @param mixed $other An instance of IString or a PHP string. */ public function compare(mixed $other): int { return strcmp($this->value, (string)$other); } /** * Creates a new identical AString instance. * * This method is somewhat pointless, given the immutable nature of this object, * but rather people calling this instead of calling ->substring(0); * * @return AString A new identical instance of AString. */ public function clone(): mixed { return new AString($this->value); } public function indexOf(IString|string $text, int $offset = 0): int { $pos = strpos($this->value, (string)$text, $offset); if($pos === false) return -1; return $pos; } public function contains(IString|string $text): bool { return str_contains($this->value, (string)$text); } public function substring(int $offset, int|null $length = null): IString { return new AString(substr($this->value, $offset, $length)); } public function replace(IString|string $search, IString|string $replace): IString { return new AString(str_replace((string)$search, (string)$replace, $this->value)); } public function append(IString|string $string): IString { return new AString($this->value . (string)$string); } public function prepend(IString|string $string): IString { return new AString(((string)$string) . $this->value); } public function split(IString|string $separator, int $limit = PHP_INT_MAX): array { $separator = (string)$separator; if(empty($separator)) throw new InvalidArgumentException('$separator may not be empty.'); return XArray::select( explode($separator, $this->value, $limit), fn($str) => new AString($str) ); } public function chunk(int $chunkSize): array { return XArray::select( str_split($this->value, $chunkSize), fn($str) => new AString($str) ); } public function trim(IString|string $characters = IString::TRIM_CHARS): IString { return new AString(trim($this->value, (string)$characters)); } public function trimStart(IString|string $characters = IString::TRIM_CHARS): IString { return new AString(ltrim($this->value, (string)$characters)); } public function trimEnd(IString|string $characters = IString::TRIM_CHARS): IString { return new AString(rtrim($this->value, (string)$characters)); } public function toLower(): IString { return new AString(strtolower($this->value)); } public function toUpper(): IString { return new AString(strtoupper($this->value)); } public function reverse(): IString { return new AString(strrev($this->value)); } public function startsWith(IString|string $text): bool { return str_starts_with($this->value, (string)$text); } public function endsWith(IString|string $text): bool { return str_ends_with($this->value, (string)$text); } /** * Casts this AString to a WString. * * @param ?string $encoding Intended encoding, null for the Index-level default. * @param bool $convert true to convert the string to the target encoding, false to leave the bytes as-is. * @return WString A WString of the provided encoding with the value of this AString. */ public function toWString(?string $encoding = null, bool $convert = true): WString { $value = $this->value; $encoding ??= WString::getDefaultEncoding(); if($convert) $value = mb_convert_encoding($value, $encoding, 'ascii'); return new WString($value, $encoding); } /** * Joins an iterable object together with a separator to create a string. * * @param iterable $source Source object. * @param IString|string $separator Separator to use as glue. * @return AString Resulting string. */ public static function join(iterable $source, IString|string $separator = ''): AString { if(!is_array($source)) { $parts = []; foreach($source as $value) $parts[] = $value; $source = $parts; } return new AString(implode((string)$separator, $source)); } /** * Returns a reusable empty string instance. * * @return AString An empty string. */ public static function empty(): AString { static $empty = null; $empty ??= new AString(''); return $empty; } /** * Converts a value to AString. * * @param mixed $value Source value. * @return AString An AString representing the given value. */ public static function cast(mixed $value): AString { if($value instanceof AString) return $value; if($value instanceof WString) return $value->toAString(); return new AString((string)$value); } }