Class ImmutableString

A String object stores a native PHP string and implements an advanced interface. Strings are per default immutable.

Strings operations are based on an associated character set, which defaults to the currently active character set during creating of the ImmutableString object. Therefore if String instances are equal but differ in their character set, their hash values do not match.

Due to backward-incompatible changes in PHP 7, string and other native type names will be reserved keywords. Therefore this class had been renamed from previously Core\String in Medusa Core 3.2.

Core\Object implements Core\Chainable

Core\Set implements Core\Accessor

Core\Type\ImmutableString implements ArrayAccess, Core\Comparable, Core\Equality, Iterator, Core\Masquerade

Direct known subclasses

Core\String\Encrypted

Namespace: Core\Type
Package: Core\Type\String
Since: 3.0
Requires: PHP 5.3
Version: 2.0
Located at Type/ImmutableString.inc.php

Methods summary

`public`	# `__construct( $string, $charset = null )` Initialises a new String instance. Initialises a new String instance. Parameters `$string` string or String instance to initialise String object with. `$charset` set instance or name of character set to use. Defaults to the currently active character set. Throws `Core\Exception\InvalidArgument` The provided character set name or alias is invalid. Since 3.0
`public string`	# `__toString( )` Returns the native representation of the string. Returns the native representation of the string. Returns string The content of the binary string buffer. Since 3,0 Overrides `Core\Object::__toString`
`public String`	# `camelCase( string $chars = null )` Transforms the string into camelcase. Transforms the string into camelcase. Parameters `$chars` String of separator characters used in source string. These characters are removed from the source string and the immediately following character is transformed to its uppercase equivalent. Default to `"_-"`. Returns String New string instance with camelcase variant of source string. Since 3.2
`public static string`	# `camelCaseStr( string $string, string $chars = null )` Transforms a given string into camelcase. Transforms a given string into camelcase. Parameters `$string` String to transform. `$chars` String of separator characters used in source string. These characters are removed from the source string and the immediately following character is transformed to its uppercase equivalent. Default to `"_-"`. Returns string Camelcase variant of source string. Since 3.2
`public integer`	# `compareTo( $value )` Compares the current string with another value or object. Compares the current string with another value or object. Comparison might not work as expected for character sets that do not represent their characters in binary order. Parameters `$value` to compare current String with. If the provided value is not a String instance, it is converted to a String object using the currently active character set and compared afterwards. Returns integer Returns < 0 if the current String is less than the argument; > 0 if the current String is greater than the parameter object, and 0 if both are equal. Strings are compared by their represented data and not the actual representation; therefore two String instances compare equal if both represent the same Unicode string even though both instances are based on different character sets. Since 3.0 Implementation of `Core\Comparable::compareTo()`
`public String`	# `convertTo( Core\Charset\|string $charsetNameOrObject )` Returns a String instance representing the same Unicode string with a different character set. Returns a String instance representing the same Unicode string with a different character set. Parameters `$charsetNameOrObject` Character set instance or name of converted result. Returns String New string instance with a different character set than the current String instance or the current instance, if the character sets match. Since 3.0
`public string`	# `current( )` Returns the current character string (used by iterators). Returns the current character string (used by iterators). Returns string Current character string. Since 3.0 Implementation of `Iterator::current()`
`public String`	# `deCamelCase( string $character )` Reverts a camelcase transformation. Reverts a camelcase transformation. Parameters `$character` Single character or string to insert between words that start with an uppercase letter. The uppercase letter is transformed to lowercase. Returns String New string instance with non-camelcase variant of source string. Since 3.2
`public static string`	# `deCamelCaseStr( string $string, string $character )` Reverts a camelcase transformation. Reverts a camelcase transformation. Parameters `$string` String in camelcase format to transform. `$character` Single character or string to insert between words that start with an uppercase letter. The uppercase letter is transformed to lowercase. Returns string Non-camelcase variant of source string. Since 3.2
`public string`	# `hash( )` Returns a hash value based on the actual string. The calculated hash value is based on the binary String and the associated character set. Returns a hash value based on the actual string. The calculated hash value is based on the binary String and the associated character set. Returns string Hash value of the object. Since 3.0 Overrides `Core\Object::hash`
`public boolean`	# `isEqualTo( $value )` Tests, whether the current String is equal to another value or object. Two String instances are equal if and only if they are based on the same character set and their string buffers are binary equal. Tests, whether the current String is equal to another value or object. Two String instances are equal if and only if they are based on the same character set and their string buffers are binary equal. If the provided argument is not a String instance, it is converted to a String if the currently active character set is equal to the character set used by the current String prior to testing for equality; if the character sets do not match, `false` is returned. To test for equality based on the represented Unicode string, use the compareTo() method: if (0 == $s1->compareTo($s2)) { // Strings s1 and s2 represent the same Unicode string, even though // their instances may use different character sets. ... } To test for binary string buffer equality, use the following code: if ($s->binaryString == $someBinaryString) { // Both strings are binary equivalent, regardless of their // character sets. ... } Parameters `$value` or object to test for equality with the current String. If the provided value is not a String instance, the value is automatically converted to a String before testing for equality. Returns boolean Returns `true`, if the provided value and the current String are equal, otherwise `false`. Since 3.0 Implementation of `Core\Equality::isEqualTo()`
`public integer`	# `key( )` Returns the index of the current character pointer (used by iterators). Returns the index of the current character pointer (used by iterators). Returns integer Current index of character pointer. Since 3.0 Implementation of `Iterator::key()`
`public static String`	# `mask( $value )` Returns a new String instance from the provided value. Returns a new String instance from the provided value. This method uses late static binding to retrieve the name of the class called to initialise a new String-based instance. Subclasses in general are not required to re-implement this method. Parameters `$value` to embed in String instance. Returns String New String instance from the specified value. Throws `Core\Exception\InvalidArgument` This masquerade cannot mask the provided value. Since 3.1 Implementation of `Core\Masquerade::mask()`
`public`	# `next( )` Sets the internal pointer on the next character (used by iterators). Sets the internal pointer on the next character (used by iterators). Since 3.0 Implementation of `Iterator::next()`
`public boolean`	# `offsetExists( $index )` Tests, whether a character string index is in the allowed range. Tests, whether a character string index is in the allowed range. Parameters `$index` index of desired character string of the String object. Returns boolean `true`, if the index is in the allowed range, otherwise `false`. Since 3.0 Implementation of `ArrayAccess::offsetExists()`
`public string`	# `offsetGet( $index )` Returns the character string at the given position. Returns the character string at the given position. Parameters `$index` index of desired character string of the String object. Returns string Character string at the desired index. Throws `Core\Exception\OutOfBounds` The requested index is invalid. Since 3.0 Implementation of `ArrayAccess::offsetGet()`
`public`	# `offsetSet( integer $index, string $value )` Not available for immutable String instances; raises an exception. Not available for immutable String instances; raises an exception. Parameters `$index` `$value` Throws `Core\Exception\MutationAttempt` Write access denied to immutable String instance. Since 3.0 Implementation of `ArrayAccess::offsetSet()`
`public`	# `offsetUnset( integer $index )` Not available for immutable String instances; raises an exception. Not available for immutable String instances; raises an exception. Parameters `$index` Throws `Core\Exception\MutationAttempt` Write access denied to immutable String instance. Since 3.0 Implementation of `ArrayAccess::offsetUnset()`
`public`	# `rewind( )` Resets the internal pointer to the first character (used by iterators). Resets the internal pointer to the first character (used by iterators). Since 3.0 Implementation of `Iterator::rewind()`
`public string[]`	# `splitSettingList( )` Returns an array of list elements extracted from the current string. Returns an array of list elements extracted from the current string. A simple list is a string of list entries separated by a space, semicolon, comma, control character or `NUL`. Empty entries are ignored. The internal binary string is processed, hence the returned array stores fragments encoded in the internal character set. Returns string[] Array of list elements. Since 3.1
`public static string[]`	# `splitSettingListStr( string $string )` Returns an array of list elements extracted from the given string. Returns an array of list elements extracted from the given string. A simple list is a string of list entries separated by a space, semicolon, comma, control character or `NUL`. Empty entries are ignored. Parameters `$string` Returns string[] Array of list elements. Since 3.1
`public string`	# `unmask( )` Returns the internal binary string. Returns the internal binary string. Subclasses that store the internal string value in a modified form, e.g. encrypted, must return the original string data. Returns string Binary string stored by this String instance. Since 3.1 Implementation of `Core\Masquerade::unmask()`
`public boolean`	# `valid( )` Tests, whether the current iteration value is valid (used by iterators). Tests, whether the current iteration value is valid (used by iterators). Returns boolean `true`, if the current value is valid, otherwise `false`. Since 3.0 Implementation of `Iterator::valid()`

Methods inherited from Core\Set

__get(), __isset()

Methods inherited from Core\Object

__autocreateFactory(), __call(), __processParameters(), attachMethod(), chain(), getValueForKey(), getValueForKeyPath(), getValueForUndefinedKey(), issetValueForKey(), setValueForKey(), setValueForKeyPath(), setValueForUndefinedKey(), uuid()

Constants summary

Constants inherited from Core\Object

AnyParameterType, AutochainParameterType, AutocreateParameterType, BooleanParameterType, CharParameterType, EnumParameterType, IntegerParameterType, RealParameterType, StringParameterType, UserParameterType

Properties summary

`protected string`	`$_v_binaryString` The original, binary string used to initialise the instance. The original, binary string used to initialise the instance. Since 3.0	#
`protected Core\Charset`	`$_v_charset` The character set instance. Defaults to the currently active character set during initialisation. The character set instance. Defaults to the currently active character set during initialisation. Since 3.0	#
`protected integer`	`$_v_length` Buffered string length value in characters (not bytes). Buffered string length value in characters (not bytes). Since 3.0	#
`protected string`	`$_hash` Hash. Hash.	#
`protected integer`	`$_position` Iterator position. Iterator position.	#

Magic properties

`public read-only string`	`$binaryString` Internal binary string representation.
`public read-only Core\Charset`	`$charset` Character set of the internal binary string.
`public read-only string`	`$hash` Hash based on binary string and character set.
`public read-only integer`	`$length` Length of the string in characters (not bytes).

Magic properties inherited from Core\Object

$uuid

Namespaces

Classes

Class ImmutableString

Direct known subclasses

Methods summary

Parameters

Throws

Since

Returns

Since

Overrides

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Implementation of

Parameters

Returns

Since

Returns

Since

Implementation of

Parameters

Returns

Since

Parameters

Returns

Since

Returns

Since

Overrides

Parameters

Returns

Since

Implementation of

Returns

Since

Implementation of

Parameters

Returns

Throws

Since

Implementation of

Since

Implementation of

Parameters

Returns

Since

Implementation of

Parameters

Returns

Throws

Since

Implementation of

Parameters

Throws

Since

Implementation of

Parameters

Throws

Since

Implementation of

Since

Implementation of

Returns

Since

Parameters

Returns

Since

Returns

Since

Implementation of

Returns

Since

Implementation of