Foundation Class Library (Java):

NASStringBuffer is a subclass of Object that resembles the java.lang.StringBuffer class (an object that manages a mutable string). Unlike java.lang.StringBuffer, none of NASStringBuffer's methods are synchronized, so performance is significantly increased.

NASStringBuffer also has additional methods that allow it to be more easily modified than the standard StringBuffer. Unfortunately, it is slower than StringBuffer when converting to a string.

Although anyone developing a NAS application can use NASStringBuffer, this class is typically used in components generated by Netscape Application Builder.

NASStringBuffer replaces the FastStringBuffer class from NAB 3.0.

Package
com.netscape.server.servlet.extension

Constructors
The following constructors are available:


Constructor	Type of NASStringBuffer Created
public NASStringBuffer()	Contains the empty string.
public NASStringBuffer (String aString)	Contains the characters in aString. The buffer is copied, not referenced.
public NASStringBuffer( String aString, int start, int end)	Contains the range of characters in aString from the index start to end, with end excluded.
public NASStringBuffer( char aChar)	Contains the character aChar.
public NASStringBuffer( int size)	Has the given length.
public NASStringBuffer (NASStringBuffer nsb)	Contains another NASStringBuffer's contents. The buffer is copied, not referenced.
public NASStringBuffer (char buff[])	Contains the specified character array. The buffer is copied, not referenced.

Methods


Method	Description
append( )	Appends a character or string to the NASStringBuffer.
charArray( )	Returns the NASStringBuffer's character array.
charAt( )	Returns the character at the specified index.
ensureCapacity( )	Makes sure that the StringBuffer has enough space to contain "newCapacity" characters.
equals( )	Compares the contents of this NASStringBuffer with the contents of another NASStringBuffer.
getChars( )	Copies characters from the NASStringBuffer to the specified destination array.
indexOf( )	Returns the index of the first occurrence of the specified character in the NASStringBuffer.
insert( )	Inserts a character or string into the NASStringBuffer.
length( )	Returns the number of characters in the NASStringBuffer.
moveChars( )	Moves the tail of the string, by removing characters.
removeCharAt( )	Removes the character at the specified index.
replace( )	Replaces the given range with a string, or removes the given range.
setCharAt( )	Sets the value of a character at the specified index.
setLength( )	Truncates the NASStringBuffer to the specified number of characters.
setStringValue( )	Sets the contents of the NASStringBuffer to the characters in the specified string.
tabOrSpaceAt( )	Determines whether a tab or space exists at the specified index.
toString( )	Returns the String for the NASStringBuffer's contents.
trimToSize( )	Truncates the internal character array to match the size of the contained string.
truncateToLength( )	Same as the trimToSize( ) method.

append( )
Appends a character or string to the NASStringBuffer.

Syntax 1

public void append(
	char aChar)

Syntax 2

public void append(
	char str[])

Syntax 3

public void append(
	String aString)

Syntax 4

public void append(
	char str[],
	int offset,
	int length)

aChar. The character to append.

aString. The string to append.

str. The characters to append.

offset. The index of the first character to append. If the offset is invalid, this method throws StringIndexOutOfBoundsException

length. The number of characters to append.

Usage
The first three forms of append( ) let you append a character or a string to the NASStringBuffer. In the last form of this method, characters in the specified character array, str, are appended in order, starting at the specified offset. The length of the NASStringBuffer increases by the specified length.

This method returns the modified NASStringBuffer.

charArray( )
Returns the NASStringBuffer's character array.

Syntax

public char[] charArray()

Usage
Use this method whenever you need to access the character array. However, do not modify this array yourself.

For example, suppose you want to draw the contents of the NASStringBuffer. You can do this by passing the array to the graphic's drawString( ) method that takes a character array, rather than converting the StringBuffer to a String.

Tip
You may want to call trimToSize() first; otherwise, some characters in the array will be out of the "valid" range for the StringBuffer.

charAt( )
Returns the character at the specified index.

Syntax

public char charAt(
	int index)

index. The position of the character.

Usage
If the index is invalid, this method throws StringIndexOutOfBoundsException.

ensureCapacity( )
Makes sure that the StringBuffer has enough space to contain "newCapacity" characters.

Syntax

public void ensureCapacity(
	int newCapacity)

Usage
Called internally.

equals( )
Compares the contents of this NASStringBuffer with the contents of another NASStringBuffer.

Syntax

public boolean equals(
	NASStringBuffer value)

Usage
Specify a value to compare.

getChars( )
Copies characters from the NASStringBuffer to the specified destination array.

Syntax

public void getChars(
	int srcBegin,
	int srcEnd,
	char dst[],
	int dstBegin)

srcBegin. The offset in the source NASStringBuffer at which copying begins.

srcEnd. The offset in the source NASStringBuffer at which copying ends.

dst. The destination array, to which data is copied.

dstBegin. The offset at which copying into the destination array begins.

Usage
Use getChars( ) to copy characters to an array. The first character to be copied is at the index srcBegin, and the last character to be copied is at srcEnd - 1. The total number of characters to be copied is srcEnd - srcBegin.

These characters are copied into a subarray of the specified destination array, dst. This subarray begins at the index dstBegin and ends at the following index:

dstBegin + (srcEnd - srcBegin) - 1

If any index is invalid, this method throws StringIndexOutOfBoundsException.

indexOf( )
Returns the index of the first occurrence of the specified character in the NASStringBuffer.

Syntax 1

public int indexOf(
	char aChar,
	int offset)

Syntax 2

public int indexOf(
	char aChar

aChar. The character whose position you are looking for.

offset. The starting position for searching in the NASStringBuffer.

Usage
You can use indexOf( ) in two forms. The first form starts at the specified offset in NASStringBuffer and returns the index of the specified character's first occurrence. If the offset is invalid, this method throws StringIndexOutOfBoundsException.

The second form is similar, except that is starts at the beginning of the NASStringBuffer and is equivalent to the following code:

indexOf(aChar, 0);

insert( )
Inserts a character or string into the NASStringBuffer.

Syntax 1

public void insert(
	int index,
	char aChar)

Syntax 2

public void insert(
	int index,
	String aString)

Syntax 3

public void insert(
	int offset,
	char str[])

index. The position in the NASStringBuffer.

aChar. The character to insert.

aString. The string to insert.

offset. The starting position for searching in the NASStringBuffer.

str. The character array to insert.

Usage
The first two forms of the insert( ) method insert either a character or a string at the specified index.

If the index equals or exceeds the number of characters in the buffer, then this method appends the item. If the index is invalid, this method throws StringIndexOutOfBoundsException.

In the last form of this method, characters in the specified character array, str, are appended in order, starting at the specified offset. The length of the NASStringBuffer increases by the length of the argument.

This method returns the modified NASStringBuffer.

length( )
Returns the number of characters in the NASStringBuffer.

Syntax

public int length()

moveChars( )
Moves the tail of the string, by removing characters.

Syntax

public void moveChars(
	int fromIndex,
	int toIndex)

fromIndex. Position of the first character to move. The affected characters range from this position to the end of the NASStringBuffer.

toIndex. Position to move the affected characters.

Usage
If characters are moved to an index within the existing string, the previous characters are overwritten by the move.

removeCharAt( )
Removes the character at the specified index.

Syntax

public void removeCharAt(
	int index)

index. The index of the character to remove.

Usage
If the index is invalid, this method throws StringIndexOutOfBoundsException.

replace( )
Replaces the given range with a string, or removes the given range.

Syntax

public void replace(
	int begin,
	int end,
	String value)

begin. The index of the beginning of the range.

end. The index of the end of the range.

value. The string that replaces the range. If null, the range is removed.

Usage
Use replace( ) to remove or replace characters in a NASStringBuffer. If either of the range indexes is invalid, this method throws StringIndexOutOfBoundsException.

setCharAt( )
Sets the value of a character at the specified index.

Syntax

public void setCharAt(
	int index,
	char ch)

index. The position of the character to set.

ch. The value to set the character to.

Usage
If the index is invalid, this method throws StringIndexOutOfBoundsException.

setLength( )
Truncates the NASStringBuffer to the specified number of characters.

Syntax

public void setLength(
	int length)

length. Number of characters to remain in the truncated NASStringBuffer. If the specified length is invalid, this method does nothing.

setStringValue( )
Sets the contents of the NASStringBuffer to the characters in the specified string.

Syntax

public void setStringValue(
	String aString)

aString. The string to use as the new contents of NASStringBuffer.

tabOrSpaceAt( )
Determines whether a tab or space exists at the specified index.

Syntax

public boolean tabOrSpaceAt(
	int index)

index. The position in the NASStringBuffer.

Usage
The tabOrSpaceAt( ) method returns true if the specified index contains a tab or a space; otherwise, this method returns false. If the index is invalid, this method throws StringIndexOutOfBoundsException.

toString( )
Returns the String for the NASStringBuffer's contents.

Syntax

public String toString()

Usage
This method overrides toString( ) in the Object class.

trimToSize( )
Truncates the internal character array to match the size of the contained string.

Syntax

public void trimToSize()

Usage
Use trimToSize( ) when more space than necessary is allocated to the NASStringBuffer, and you want to free this space for other uses.

truncateToLength( )
Same as the trimToSize( ) method.

Syntax

public void truncateToLength(
	int aLength)