Class \Scrivo\ByteArray
Wrapper class for 8 byte character strings.
ByteArray is a primitive wrapper class for 8 byte character strings. So this is a wrapper class for PHP native strings. It's purpose is to create a clear distinction in the code between byte arrays and UTF-8 Strings.
Using only these two classes to handle strings will force you to make a consious decicion each time you work with string data, and thus hopefully prevent error by preventing mixups. A secondary objective is to create a more consistent interface for string handling as PHP itself provides.
Implements
Defined in:
ByteArray.php.
| Attr. | Name / Description |
|---|---|
| public |
ByteArray($str) Construct an ByteArray. |
| Attr. | Type | Name | Description |
|---|---|---|---|
| private | int | $len | The length of the string (characters not bytes). |
| private | string | $pos | The current position when iterating. |
| private | string | $str | The primitive string/byte array. |
| Attr. | Type | Name / Description |
|---|---|---|
| public | mixed |
__get($name) Implementation of the readable properties using the PHP magic method __get(). |
| public | string |
Return the primitive string for this instance. |
| public | int |
compareTo($str) Compare this string to another ByteArray object. |
| public | boolean |
contains($str, $offset, $ignoreCase) Check if the string contains the given substring. |
| public | int |
count() Return the character count of the string. |
| public static | \..\ByteArray |
create($str) Factory method to construct an ByteArray. |
| public | string |
current() Return the current character when iterating. |
| public | boolean |
equals($str) Test if this string equals another ByteArray object. |
| public | \..\ByteArray |
firstOccurranceOf($str, $part, $ignoreCase) Returns the first occurance of a given substring in this string. |
| public | int |
Get the length of the string. |
| public | int |
indexOf($str, $offset, $ignoreCase) Returns the index of the given substring in this string. |
| public | int |
key() Return the index of the current character when iterating. |
| public | int |
lastIndexOf($str, $offset, $ignoreCase) Returns the index of the last occurance of the given substring in this string. |
| public | \..\ByteArray |
lastOccurranceOf($str, $part, $ignoreCase) Returns the last occurance of a given character in this string. |
| public |
next() Move forward in this string to the next character when iterating. |
|
| public | boolean |
offsetExists($offset) Check if the specified index location in this string is valid. |
| public |
offsetGet($offset) Get an UTF-8 character from a string using array brackets. |
|
| public |
offsetSet($offset, $value) Illegal method: set a character at a specified index location. |
|
| public |
offsetUnset($offset) Illegal method: unset a character at a specified index location. |
|
| public | \..\ByteArray |
replace($from, $to) Replace a substring or set of substrings in this string. |
| public |
rewind() Reset the current character index so iterating will (re)start at the beginning of this string. |
|
| public | \..\ByteArray[] |
split($delimiter, $limit) Split this string using a delimiter. |
| public | \..\ByteArray |
substr($start, $length) Get a substring from a string using an offset and a length. |
| public | \..\ByteArray |
substring($start, $end) Get a substring from a string using a start and end index. |
| public | \..\ByteArray |
Get a copy of this string with all of its characters converted to lower case. |
| public | \..\ByteArray |
Get a copy of this string with all of its characters converted to upper case. |
| public | \..\ByteArray |
trim() Get a trimmed copy of this string. |
| private | \..\ByteArray |
unsafeSubstr($start, $length) Get a substring from a string without first checking the boundaries. |
| public | boolean |
valid() Check if the current character index for iterating is valid. |
Constructor
- public ByteArray(string $str="")
-
Construct an ByteArray.
Parameters:
Type Name Def. Description string $str "" The source string.
View source: ByteArray.php line 88.
Members
- private int $len
-
The length of the string (characters not bytes).
Inital value: -1
View source: ByteArray.php line 68.
- private string $pos
-
The current position when iterating.
View source: ByteArray.php line 62.
- private string $str
-
The primitive string/byte array.
View source: ByteArray.php line 56.
Methods
- public mixed __get(string $name)
-
Implementation of the readable properties using the PHP magic method __get().
Parameters:
Type Name Def. Description string $name The name of the property to get.
Returns:
mixed Implementation of the readable properties using the PHP magic method __get().
View source: ByteArray.php line 130.
- public string __toString()
-
Return the primitive string for this instance.
Returns:
string Return the primitive string for this instance.
View source: ByteArray.php line 118.
- public int compareTo(\Scrivo\ByteArray $str)
-
Compare this string to another ByteArray object.
Parameters:
Type Name Def. Description \Scrivo\ByteArray $str The string to compare this string to.
Returns:
int Compare this string to another ByteArray object.
View source: ByteArray.php line 689.
- public boolean contains(\Scrivo\ByteArray $str, int $offset=0, boolean $ignoreCase=false)
-
Check if the string contains the given substring.
This is the test you normally use strpos(...) !== false for.
Parameters:
Type Name Def. Description \Scrivo\ByteArray $str The string to search for.
int $offset 0 An offset from where to start the search.
boolean $ignoreCase false Set to perform an case insensitive lookup.
Returns:
boolean Check if the string contains the given substring.
Throws:
Exception Type Description \Scrivo\SystemException If the $offset is out of range. View source: ByteArray.php line 394.
- public int count()
-
Return the character count of the string.
This is an alias for getLength() and part of the implementation of Countable.
Returns:
int Return the character count of the string.
View source: ByteArray.php line 174.
- public static \Scrivo\ByteArray create(string $str="")
-
Factory method to construct an ByteArray.
Parameters:
Type Name Def. Description string $str "" The source strings.
Returns:
\Scrivo\ByteArray Factory method to construct an ByteArray.
View source: ByteArray.php line 103.
- public string current()
-
Return the current character when iterating.
Note that this method is part of the implementation of Iterator and should not be called from an other context.
Returns:
string Return the current character when iterating.
View source: ByteArray.php line 187.
- public boolean equals(\Scrivo\ByteArray $str)
-
Test if this string equals another ByteArray object.
When you want test ByteArray object for equality, use this method and never the equality operator (==) because then you'll compare objects and therefore all data members of ByteArray and this can give you other results (or cast the ByteArray strings to PHP strings before comparing).
Parameters:
Type Name Def. Description \Scrivo\ByteArray $str The string to compare this string to.
Returns:
boolean Test if this string equals another ByteArray object.
View source: ByteArray.php line 150.
- public \Scrivo\ByteArray firstOccurranceOf(\Scrivo\ByteArray $str, boolean $part=false, boolean $ignoreCase=false)
-
Returns the first occurance of a given substring in this string.
Just like the PHP's native strstr and stristr functions this method returns the substring of this string that start with the first occurance of the given a substring in this string. Note that this method throws an exception if an empty string was given as search string and not a warning as strstr does.
Parameters:
Type Name Def. Description \Scrivo\ByteArray $str The string to search for.
boolean $part false Flag to indicate to return the part of the string before the first occurance of the given substring i.o. the part after the substring.
boolean $ignoreCase false Perform an case insensitive lookup.
Returns:
\Scrivo\ByteArray Returns the first occurance of a given substring in this string.
Throws:
Exception Type Description \Scrivo\SystemException If an empty search string was given. View source: ByteArray.php line 513.
- public int getLength()
-
Get the length of the string.
Returns:
int Get the length of the string.
View source: ByteArray.php line 159.
- public int indexOf(\Scrivo\ByteArray $str, int $offset=0, boolean $ignoreCase=false)
-
Returns the index of the given substring in this string.
Just like the PHP's native strpos and stripos functions this method returns the index of a substring in this string. But there are two important differences: this method returns -1 if the substring was not found, and this method will raise an exception if the given offset was out of range.
Parameters:
Type Name Def. Description \Scrivo\ByteArray $str The string to search for.
int $offset 0 An offset from where to start the search.
boolean $ignoreCase false Set to perform an case insensitive lookup.
Returns:
int Returns the index of the given substring in this string.
Throws:
Exception Type Description \Scrivo\SystemException If the $offset is out of range. View source: ByteArray.php line 429.
- public int key()
-
Return the index of the current character when iterating.
Note that this method is part of the implementation of Iterator and should not be called from an other context.
Returns:
int Return the index of the current character when iterating.
View source: ByteArray.php line 201.
- public int lastIndexOf(\Scrivo\ByteArray $str, int $offset=0, boolean $ignoreCase=false)
-
Returns the index of the last occurance of the given substring in this string.
Just like the PHP's native strrpos and strripos functions this method returns the substring of this string that start with the first occurance of the given a substring in this string. But note that this method will throw an exception if the offset is invalid. Also an negative offset to indicate an offset measured from the end of the string is allowed. But there are two important differences: this method returns -1 if the substring was not found, and this method will raise an exception if the given offset was out of range.
Parameters:
Type Name Def. Description \Scrivo\ByteArray $str The string to search for.
int $offset 0 An offset from where to start the search. A positive value indicates an offset measured from the start of the string, a negative value from the end of the string.
boolean $ignoreCase false Perform an case insensitive lookup.
Returns:
int Returns the index of the last occurance of the given substring in this string.
Throws:
Exception Type Description \Scrivo\SystemException If the $offset is out of range. View source: ByteArray.php line 470.
- public \Scrivo\ByteArray lastOccurranceOf(\Scrivo\ByteArray $str, boolean $part=false, boolean $ignoreCase=false)
-
Returns the last occurance of a given character in this string.
Just like the PHP's native strrchr and strrichr functions this method returns the substring of this string that start with the first occurance of the given a substring in this string. Note that this method throws an exception if an empty string was given as search string and not a warning as strstr does.
Parameters:
Type Name Def. Description \Scrivo\ByteArray $str The character to search for.
boolean $part false Flag to indicate to return part of the string before the last occurance of the given character i.o. the part after the character.
boolean $ignoreCase false Perform an case insensitive lookup.
Returns:
\Scrivo\ByteArray Returns the last occurance of a given character in this string.
Throws:
Exception Type Description \Scrivo\SystemException If a search string of not exactly one character in length was given. View source: ByteArray.php line 555.
- public next()
-
Move forward in this string to the next character when iterating.
Note that this method is part of the implementation of Iterator and should not be called from an other context.
View source: ByteArray.php line 211.
- public boolean offsetExists(int $offset)
-
Check if the specified index location in this string is valid.
Note that this method is part of the implementation of ArrayAccess and should not be called from an other context.
Parameters:
Type Name Def. Description int $offset A character offet in the string.
Returns:
boolean Check if the specified index location in this string is valid.
View source: ByteArray.php line 286.
- public offsetGet(int $offset)
-
Get an UTF-8 character from a string using array brackets.
Note that this method is part of the implementation of ArrayAccess and should not be called from an other context.
Parameters:
Type Name Def. Description int $offset A character offet in the string.
Throws:
Exception Type Description \Scrivo\SystemException If the requested offset was out of range. View source: ByteArray.php line 266.
- public offsetSet(int $offset, string $value)
-
Illegal method: set a character at a specified index location.
Note that this method is part of the implementation of ArrayAccess. ByteArrays are immutable and therefore it is prohibited to set elements (characters) in a string, so this method implementation is not relevant and throws an exception if called.
Parameters:
Type Name Def. Description int $offset string $value Throws:
Exception Type Description \Scrivo\SystemException If this method is called. View source: ByteArray.php line 251.
- public offsetUnset(int $offset)
-
Illegal method: unset a character at a specified index location.
Note that this method is part of the implementation of ArrayAccess. ByteArrays are immutable and therefore it is prohibited to unset elements (characters) in a string, so this method implementation is not relevant and throws an exception if called.
Parameters:
Type Name Def. Description int $offset Throws:
Exception Type Description \Scrivo\SystemException If this method is called. View source: ByteArray.php line 304.
- public \Scrivo\ByteArray replace(\Scrivo\ByteArray $from, \Scrivo\ByteArray $to)
-
Replace a substring or set of substrings in this string.
You can use this method in favour of PHP's native str_replace and strtr functions. This method will do proper type checking for you. Note that you can safely use str_replace: if all input parameter are correct UTF-8 this method is UTF-8 safe too.
Parameters:
Type Name Def. Description \Scrivo\ByteArray $from A (set of) string(s) to replace in this string.
\Scrivo\ByteArray $to A (set of) replacement string(s) to replace the found string(s).
Returns:
\Scrivo\ByteArray Replace a substring or set of substrings in this string.
Throws:
Exception Type Description \Scrivo\SystemException If the input data is not of type ByteArray or ByteArray[], of if the $to parameter is an array and $from isn't or hasn't the same number of elements. View source: ByteArray.php line 594.
- public rewind()
-
Reset the current character index so iterating will (re)start at the beginning of this string.
Note that this method is part of the implementation of Iterator and should not be called from an other context.
View source: ByteArray.php line 222.
- public \Scrivo\ByteArray[] split(\Scrivo\ByteArray $delimiter, int $limit=0)
-
Split this string using a delimiter.
Just like PHP's native explode this method splits a string on boundaries formed by the string delimiter. Note that the behavoir of the limit parameter is a little bit different and that this method will throw an exception if an empty string is passed as a delimiter.
Parameters:
Type Name Def. Description \Scrivo\ByteArray $delimiter The boundary string.
int $limit 0 If limit is set and positive, the returned array will contain a maximum of limit elements with the last element containing the rest of string. If the limit parameter is negative, all components except the last -limit are returned. If the limit is not set or 0 no limit wil be used.
Returns:
\Scrivo\ByteArray[] Split this string using a delimiter.
Throws:
Exception Type Description \Scrivo\SystemException If an empty search string was given. View source: ByteArray.php line 645.
- public \Scrivo\ByteArray substr(int $start, int $length=65535)
-
Get a substring from a string using an offset and a length.
Just like PHP's native substr function this method returns a substring from this string using an offset and a length. But note that this method will throw an exception if the offset is invalid.
Parameters:
Type Name Def. Description int $start Start offset for the substring, use a negative number to use an offset from the end of the string.
int $length 65535 The length of the substring.
Returns:
\Scrivo\ByteArray Get a substring from a string using an offset and a length.
Throws:
Exception Type Description \Scrivo\SystemException if the requested offset was out of range. View source: ByteArray.php line 327.
- public \Scrivo\ByteArray substring(int $start, int $end)
-
Get a substring from a string using a start and end index.
This method is inspired by it's JAVA counterpart and returns a substring of this string using an start and end index.
Parameters:
Type Name Def. Description int $start Start offset for the substring.
int $end The end offset for the substring.
Returns:
\Scrivo\ByteArray Get a substring from a string using a start and end index.
Throws:
Exception Type Description \Scrivo\SystemException if the requested offset was out of range. View source: ByteArray.php line 354.
- public \Scrivo\ByteArray toLowerCase()
-
Get a copy of this string with all of its characters converted to lower case.
Returns:
\Scrivo\ByteArray Get a copy of this string with all of its characters converted to lower case.
View source: ByteArray.php line 666.
- public \Scrivo\ByteArray toUpperCase()
-
Get a copy of this string with all of its characters converted to upper case.
Returns:
\Scrivo\ByteArray Get a copy of this string with all of its characters converted to upper case.
View source: ByteArray.php line 676.
- public \Scrivo\ByteArray trim()
-
Get a trimmed copy of this string.
Returns a copy of the string, with leading and trailing whitespace removed. Whitespace characters are: ' ', \t, \r, \n.
Returns:
\Scrivo\ByteArray Get a trimmed copy of this string.
View source: ByteArray.php line 376.
- private \Scrivo\ByteArray unsafeSubstr(int $start, int $length)
-
Get a substring from a string without first checking the boundaries.
Parameters:
Type Name Def. Description int $start Start offset for the substring, use a negative number to use an offset from the end of the string.
int $length The length of the substring.
Returns:
\Scrivo\ByteArray Get a substring from a string without first checking the boundaries.
View source: ByteArray.php line 79.
- public boolean valid()
-
Check if the current character index for iterating is valid.
Note that this method is part of the implementation of Iterator and should not be called from an other context.
Returns:
boolean Check if the current character index for iterating is valid.
View source: ByteArray.php line 234.
Documentation generated by phpDocumentor 2.0.0a12 and ScrivoDocumentor on August 29, 2013
