com.hunnysoft.jmime
Class ByteString

java.lang.Object
  com.hunnysoft.jmime.ByteString

public final class ByteString
extends java.lang.Object

Class that represents single-byte character strings or binary strings.

The ByteString class is very similar to java.lang.String, except that the characters it contains are single-byte characters. Alternatively, ByteString can contain binary data, which may contain embedded NUL bytes and which should not be interpreted as character data. As is true for java.lang.String, ByteString is immutable, which means it can't be changed.

The methods in ByteString have been written to look and feel like java.lang.String, so that developers will be able to apply their existing knowledge of java.lang.String to ByteString.

For the sake of efficiency, ByteString does allow access to its internal byte array buffer. Use this feature with caution.

Because an empty byte string is frequently needed in programs, a static instance is provided by this class as ByteString.EMPTY_BYTE_STRING.

See Also:

ByteStringBuffer

Field Summary

static ByteString

EMPTY_BYTE_STRING

Constructor Summary

ByteString()
Default constructor.

ByteString(byte[] bytes)
Constructor that takes a byte array.

ByteString(byte[] bytes, int pos, int len)
Constructor that takes a subarray of bytes.

ByteString(ByteString bstr)
Copy constructor.

ByteString(ByteString bstr, int pos, int len)
Constructor that takes a ByteString substring.

ByteString(java.lang.String str)
Constructor that takes a String argument.

ByteString(java.lang.String str, java.lang.String charset)
Constructor that takes String and encoding arguments.

Method Summary

byte	byteAt(int pos) Returns the byte at the specified position.
int	compareTo(ByteString bstr) Compares this string to another string.
int	compareToIgnoreCase(ByteString bstr) Compares this string to another string, ignoring case.
ByteString	concat(ByteString bstr) Concatenates this string with another string.
byte[]	data() Returns reference to the internal byte array.
boolean	endsWith(ByteString suffix) Returns true if this string ends with the specified string.
boolean	equals(java.lang.Object obj) Compares this string to another object.
boolean	equalsIgnoreCase(ByteString bstr) Returns true if this string equals the specified string in a case sensitive comparison.
byte[]	getBytes() Returns the contents of this string as a byte array.
void	getBytes(int srcOffset, int length, byte[] dstBuffer, int dstOffset) Copies a substring of this string to a byte array.
int	hashCode()
int	indexOf(ByteString bstr) Searches for a string pattern within this string.
int	indexOf(ByteString bstr, int fromIndex) Searches for a string pattern within this string, beginning at a specified position.
int	indexOf(int by) Searches for the specified byte in this string.
int	indexOf(int by, int fromIndex) Searches for the specified byte in the string, beginning at a specified position.
boolean	isEmpty() Returns true if this byte string is empty.
int	lastIndexOf(ByteString bstr) Searches backward for a string pattern within this string.
int	lastIndexOf(ByteString bstr, int fromIndex) Searches backward for a string pattern within this string, beginning at a specified position.
int	lastIndexOf(int by) Searches backward for the specified byte in this string.
int	lastIndexOf(int by, int fromIndex) Searches backward for the specified byte in the string, beginning at a specified position.
int	length() Returns the length of this byte string.
int	offset() Returns the offset into the internal byte array of the beginning of this byte string's content.
boolean	regionMatches(boolean ignoreCase, int offset1, ByteString bstr, int offset2, int length) Compares a substring of this string to a substring of another string, with option for case-insensitive comparison.
boolean	regionMatches(int offset1, ByteString bstr, int offset2, int length) Compares a substring of this string to a substring of another string.
boolean	startsWith(ByteString prefix) Returns true if this string starts with the specified string.
boolean	startsWith(ByteString prefix, int offset) Returns true if this string starts with the specified string.
static int	strcasecmp(byte[] s1, int pos1, int len1, byte[] s2, int pos2, int len2)
static int	strcmp(byte[] s1, int pos1, int len1, byte[] s2, int pos2, int len2)
static int	strncasecmp(byte[] s1, int pos1, int len1, byte[] s2, int pos2, int len2, int len)
static int	strncmp(byte[] s1, int pos1, int len1, byte[] s2, int pos2, int len2, int len)
ByteString	substring(int beginIndex) Returns a substring of this string.
ByteString	substring(int beginIndex, int endIndex) Returns a substring of this string.
ByteString	toLowerCase() Returns a new string equal to this string, but with all lower case characters.
java.lang.String	toString() Returns a String with the same content as this string.
ByteString	toUpperCase() Returns a new string equal to this string, but with all upper case characters.
ByteString	trim() Returns a new string with whitespace characters removed from the beginning and the end.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_BYTE_STRING

public static final ByteString EMPTY_BYTE_STRING

Constructor Detail

ByteString

public ByteString()

Default constructor.

ByteString

public ByteString(byte[] bytes)

Constructor that takes a byte array.

This constructor sets the content of its byte array argument as the initial content of the string. For efficiency, the byte array is used directly as the internal buffer of the string. The byte array is not copied. For this reason, the caller should not use the byte array after the call to this constructor.

Parameters:

bytes - byte array to be used as internal buffer of the new string

ByteString

public ByteString(ByteString bstr)

Copy constructor.

This constructor sets the value of the new ByteString to be the same as the constructor's argument.

Parameters:

bstr - string to copy

ByteString

public ByteString(java.lang.String str)

Constructor that takes a String argument.

This constructor converts its String argument into a ByteString. The conversion assumes that the String argument contains only characters from the ISO-8859-1 charset. (The ISO-8859-1 charset was chosen because its 256 code points are the same as the first 256 code points of Unicode.)

Parameters:

str - String to be used as initial value

ByteString

public ByteString(java.lang.String str,
                  java.lang.String charset)
           throws java.io.UnsupportedEncodingException

Constructor that takes String and encoding arguments.

This constructor converts its String argument into a ByteString. The charset parameter indicates the character encoding that the constructor should use to convert from Unicode characters to bytes.

Parameters:

str - String to be used as initial value

charset - character encoding identifier that the constructor should use to convert from Unicode characters to bytes

Throws:

java.io.UnsupportedEncodingException

ByteString

public ByteString(ByteString bstr,
                  int pos,
                  int len)

Constructor that takes a ByteString substring.

This constructor extracts a substring of its ByteString argument to use as its initial content.

Parameters:

bstr - byte string that contains the substring to be used as initial value

pos - offset of the substring

len - length of the substring

Throws:

java.lang.IndexOutOfBoundsException - if pos or len are out of range

ByteString

public ByteString(byte[] bytes,
                  int pos,
                  int len)

Constructor that takes a subarray of bytes.

This constructor sets the content of a subarray of its byte array argument as the initial content of the string. For efficiency, the byte array is used directly as the internal buffer of the string. The bytes in the array are not copied. For this reason, the caller should not use the byte array after the call to this constructor.

Parameters:

bytes - byte array to be used as internal buffer of the new string

pos - offset of subarray to be used as the initial value of the string

len - length of subarray to be used as the initial value of the string

Method Detail

byteAt

public byte byteAt(int pos)

Returns the byte at the specified position.

Parameters:

pos - position in the string of the byte to return

Returns:

byte at the specified position

Throws:

java.lang.IndexOutOfBoundsException - if the specified position is out of range

compareTo

public int compareTo(ByteString bstr)

Compares this string to another string.

Returns -1 is this string is less than the argument. Returns 1 if this string is greater than the argument. Returns 0 if this string and the argument are equal.

Parameters:

bstr - string to compare to

Returns:

respectively, -1, 0, or 1 if this string is <, =, or > the argument

compareToIgnoreCase

public int compareToIgnoreCase(ByteString bstr)

Compares this string to another string, ignoring case.

Returns -1 is this string is less than the argument. Returns 1 if this string is greater than the argument. Returns 0 if this string and the argument are equal.

This method ignores case only for ASCII characters.

Parameters:

bstr - string to compare to

Returns:

respectively, -1, 0, or 1 if this string is <, =, or > the argument

concat

public ByteString concat(ByteString bstr)

Concatenates this string with another string.

This method returns a new ByteString that is formed by concatenating this string with the argument.

Parameters:

bstr - the string to concatenate

Returns:

the concatenated string

endsWith

public boolean endsWith(ByteString suffix)

Returns true if this string ends with the specified string.

Parameters:

suffix - string to compare

Returns:

true if the end of this string matches the argument

equalsIgnoreCase

public boolean equalsIgnoreCase(ByteString bstr)

Returns true if this string equals the specified string in a case sensitive comparison.

Parameters:

bstr - the string to compare

Returns:

true if this string and the argument are equal

getBytes

public byte[] getBytes()

Returns the contents of this string as a byte array.

This method copies the internal buffer, so it is safe to modify the returned byte array.

Returns:

contents of the string as a byte array

See Also:

data()

getBytes

public void getBytes(int srcOffset,
                     int length,
                     byte[] dstBuffer,
                     int dstOffset)

Copies a substring of this string to a byte array.

Parameters:

srcOffset - offset of the substring to copy

length - length of the substring to copy

dstBuffer - buffer to copy the byte to

dstOffset - offset into dstBuffer where the first byte should be copied to

indexOf

public int indexOf(int by)

Searches for the specified byte in this string.

If the specified byte is found in the string, this method returns the position of the first occurrence of the byte. If the search fails, this method returns -1.

Parameters:

by - the byte to search for

Returns:

position of byte in string, if found; otherwise, -1

indexOf

public int indexOf(int by,
                   int fromIndex)

Searches for the specified byte in the string, beginning at a specified position.

If the specified byte is found in the string at a position greater than or equal to fromIndex, this method returns the position of the first such occurrence. If the search fails, this method returns -1.

Parameters:

by - the byte to search for

fromIndex - position to start searching from

Returns:

position of byte in string, if found; otherwise, -1

indexOf

public int indexOf(ByteString bstr)

Searches for a string pattern within this string.

If the sequence of characters specified by the argument bstr is found within this string, the method returns the position of the first such occurrence. If the search fails, this method returns -1.

Parameters:

bstr - the string pattern to search for

Returns:

position of pattern in string, if found; otherwise, -1

indexOf

public int indexOf(ByteString bstr,
                   int fromIndex)

Searches for a string pattern within this string, beginning at a specified position.

If the sequence of characters specified by the argument bstr is found within this string at a position greater than or equal to fromIndex, the method returns the position of the first such occurrence. If the search fails, this method returns -1.

Parameters:

bstr - the string pattern to search for

fromIndex - position to start searching from

Returns:

position of pattern in string, if found; otherwise, -1

lastIndexOf

public int lastIndexOf(int by)

Searches backward for the specified byte in this string.

If the specified byte is found in the string, this method returns the position of the first occurrence of the byte (in a backward direction). If the search fails, this method returns -1.

Parameters:

by - the byte to search for

Returns:

position of byte in string, if found; otherwise, -1

lastIndexOf

public int lastIndexOf(int by,
                       int fromIndex)

Searches backward for the specified byte in the string, beginning at a specified position.

If the specified byte is found in the string at a position less than or equal to fromIndex, this method returns the position of the first such occurrence (in a backward direction). If the search fails, this method returns -1.

Parameters:

by - the byte to search for

fromIndex - position to start searching from

Returns:

position of byte in string, if found; otherwise, -1

lastIndexOf

public int lastIndexOf(ByteString bstr)

Searches backward for a string pattern within this string.

If the sequence of characters specified by the argument bstr is found within this string, the method returns the position of the first such occurrence (in a backward direction). If the search fails, this method returns -1.

Parameters:

bstr - the string pattern to search for

Returns:

position of pattern in string, if found; otherwise, -1

lastIndexOf

public int lastIndexOf(ByteString bstr,
                       int fromIndex)

Searches backward for a string pattern within this string, beginning at a specified position.

If the sequence of characters specified by the argument bstr is found within this string, the method returns the position of the first such occurrence (in a backward direction). If the search fails, this method returns -1.

Parameters:

bstr - the string pattern to search for

fromIndex - position to start searching from

Returns:

position of pattern in string, if found; otherwise, -1

regionMatches

public boolean regionMatches(int offset1,
                             ByteString bstr,
                             int offset2,
                             int length)

Compares a substring of this string to a substring of another string.

Parameters:

offset1 - offset of the substring of this string

bstr - string containing substring to compare to

offset2 - offset of the substring of bstr

length - length of substrings to compare

Returns:

true if the two substrings are equal

regionMatches

public boolean regionMatches(boolean ignoreCase,
                             int offset1,
                             ByteString bstr,
                             int offset2,
                             int length)

Compares a substring of this string to a substring of another string, with option for case-insensitive comparison.

Parameters:

ignoreCase - if true, comparison is case-insensitive

offset1 - offset of the substring of this string

bstr - string containing substring to compare to

offset2 - offset of the substring of bstr

length - length of substrings to compare

Returns:

true if the two substrings are equal

startsWith

public boolean startsWith(ByteString prefix,
                          int offset)

Returns true if this string starts with the specified string.

Parameters:

offset - position in this string to start the comparison

prefix - string to compare

Returns:

true if the end of this string matches the argument

startsWith

public boolean startsWith(ByteString prefix)

Returns true if this string starts with the specified string.

Parameters:

prefix - string to compare

Returns:

true if the end of this string matches the argument

substring

public ByteString substring(int beginIndex,
                            int endIndex)

Returns a substring of this string.

Parameters:

beginIndex - offset into this string of the beginning of the substring

endIndex - offset into this string of the end of the substring

Returns:

new string that is a substring of this string

substring

public ByteString substring(int beginIndex)

Returns a substring of this string.

This method is equivalent to substring(beginIndex,endIndex) with endIndex set to the length of this string.

Parameters:

beginIndex - offset into this string of the beginning of the substring

Returns:

new string that is a substring of this string

toLowerCase

public ByteString toLowerCase()

Returns a new string equal to this string, but with all lower case characters.

Returns:

new, lower-case-only string

toString

public java.lang.String toString()

Returns a String with the same content as this string.

This method converts the bytes in this string to characters in the returned string. The conversion is performed using the ISO-8859-1 character set and code points.

Overrides:

toString in class java.lang.Object

Returns:

new String that equivalent to this string

toUpperCase

public ByteString toUpperCase()

Returns a new string equal to this string, but with all upper case characters.

Returns:

new, upper-case-only string

trim

public ByteString trim()

Returns a new string with whitespace characters removed from the beginning and the end.

Returns:

new string with whitespace characters removed from beginning and end

equals

public boolean equals(java.lang.Object obj)

Compares this string to another object.

Overrides:

equals in class java.lang.Object

Returns:

true the argument is a ByteString and the contents are the same as the contents of this ByteString

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

data

public byte[] data()

Returns reference to the internal byte array.

This method provides access to the internal byte array maintained by this ByteString. The purpose is mainly for the package itself to use in order to perform its tasks more efficiently by eliminating a lot of copying. However, the method is public so that other packages may also gain access to the internal byte array. The returned byte array should be treated as a read-only array. All the code in this package itself treats the returned byte array as read-only, and does not modify it in any way.

If you use this method, you must use it together with the methods offset() and length(), in order to access the correct elements of the internal array.

Returns:

reference to the internal byte array

See Also:

offset(), length()

offset

public int offset()

Returns the offset into the internal byte array of the beginning of this byte string's content.

This method is intended to be used together with the methods data() and length(), in order to access the correct elements of the internal array.

Returns:

offset into the internal byte array of the beginning of the content

See Also:

data(), length()

length

public int length()

Returns the length of this byte string.

Returns:

length of this byte string

isEmpty

public boolean isEmpty()

Returns true if this byte string is empty.

Returns:

true is this byte string is empty

strcmp

public static int strcmp(byte[] s1,
                         int pos1,
                         int len1,
                         byte[] s2,
                         int pos2,
                         int len2)

strncmp

public static int strncmp(byte[] s1,
                          int pos1,
                          int len1,
                          byte[] s2,
                          int pos2,
                          int len2,
                          int len)

strcasecmp

public static int strcasecmp(byte[] s1,
                             int pos1,
                             int len1,
                             byte[] s2,
                             int pos2,
                             int len2)

strncasecmp

public static int strncasecmp(byte[] s1,
                              int pos1,
                              int len1,
                              byte[] s2,
                              int pos2,
                              int len2,
                              int len)