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.

Constructor summary
Attr. Name / Description
public

ByteArray($str)

Construct an ByteArray.

Member summary
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.

Method summary
Attr. Type Name / Description
public mixed

__get($name)

Implementation of the readable properties using the PHP magic method __get().
public string

__toString()

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

getLength()

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

toLowerCase()

Get a copy of this string with all of its characters converted to lower case.
public \..\ByteArray

toUpperCase()

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