OLTextBuffer Class Reference
[Text]

A mutable buffer for manipulating text. More...

#import <ObjectiveLib/Text.h>

List of all members.

Public Member Functions
(OLTextBuffer *)	- appendChar:
	Append a character.
(OLTextBuffer *)	- appendChars:fromOffset:count:
	Append some characters.
(OLTextBuffer *)	- appendText:
	Append a text object.
(OLTextBuffer *)	- appendTextBuffer:
	Append another text buffer.
(OLTextBuffer *)	- assignAt:character:
	Assign a character.
(olchar)	- at:
	Return the character at index.
(unsigned)	- capacity
	Return the capacity of this buffer.
(void)	- clear
	Erase all characters.
(int)	- compare:
	Compare this object to another.
(id)	- copy
	Return a copy of this text buffer.
(BOOL)	- empty
	Return whether this text buffer is empty.
(OLTextBuffer *)	- eraseAt:
	Erase a character.
(OLTextBuffer *)	- eraseFromOffset:count:
	Erase a group of characters.
(unsigned)	- findChar:fromOffset:
	Find a character.
(unsigned)	- findFirstNotOf:fromOffset:
	Find a character not in a set.
(unsigned)	- findFirstOf:fromOffset:
	Find a character of a set.
(unsigned)	- findLastNotOf:fromOffset:
	Find a character not in a set.
(unsigned)	- findLastOf:fromOffset:
	Find a character of a set.
(unsigned)	- findText:fromOffset:
	Find a subsequence.
(void)	- getCharacters:fromOffset:count:
	Extract a range of characters.
(OLTextBuffer *)	- insertChar:atOffset:
	Insert a character.
(OLTextBuffer *)	- insertChars:atOffset:count:
	Insert an array of characters.
(OLTextBuffer *)	- insertText:atOffset:
	Insert a chunk of text.
(BOOL)	- isEqual:
	Return whether this text buffer is equal to another one.
(unsigned)	- length
	Return the length of the text buffer.
(OLTextBuffer *)	- replaceFromOffset:count:withText:
	Replace a range of characters.
(void)	- reserve:
	Ensure that the capacity of the text buffer is at least of a certain size.
(OLTextBuffer *)	- resize:filledWith:
	Resize the text buffer.
(OLTextBuffer *)	- reverse
	Reverse the order of characters.
(unsigned)	- rfindChar:fromOffset:
	Find a character.
(unsigned)	- size
	Return the size of the text buffer.
(OLText *)	- substrFromOffset:count:
	Extract a subsequence.
(OLText *)	- text
	Return the text.
Initializers and Deallocators
(id)	- free
	Free all memory allocated by this buffer and destroy the object.
(id)	- init
	Initialize a new text buffer.
(id)	- initWithCapacity:
	Initialize a new text buffer.
(id)	- initWithText:
	Initialize a new text buffer.
Static Public Member Functions
(id)	+ textBuffer
	Create and return a new, empty text buffer.
(id)	+ textBufferWithText:
	Create and return a new text buffer that holds a copy of the give text object.
Protected Attributes
olchar *	begin
	The array of characters under control of this object.
unsigned	capacity
	The capacity of the array.
unsigned	size
	The size of the array.

---

Detailed Description

A mutable buffer for manipulating text.

OLTextBuffer is like a mutable version of OLText. It is meant to be used when manipulating text, but not to be treated as a mutable replacement for OLText. The usage model would be something like, create a OLTextBuffer instance, build the desired sequence of characters, then convert it to OLText with the text (OLTextBuffer) method for general use, archiving or streaming.

Note:

Most of the methods that mutate the text buffer return a reference to the buffer to enable chaining of mutations. For example,

 OLTextBuffer* buffer = [[OLTextBuffer alloc] init];
 [buffer [[appendText: [OLText textWithCString: "You're cute"]] appendChar: OL_EXCLAMATION_CHAR]];

See also:

OLText

---

Member Function Documentation

- (OLTextBuffer*) appendChar:

(olchar)

ch

Append a character.

The given character will be appended to the current array.

Parameters:

ch

the character to append

Returns:

a reference to this text buffer

- (OLTextBuffer*) appendChars:		(const olchar *)	chars
fromOffset:		(unsigned)	offset
count:		(unsigned)	num

Append some characters.

A span of characters from the array chars starting at offset offset and extending num characters will be appended to the current array.

Parameters:

	chars	the array from which to copy characters
	offset	the offset from which to start copying
	num	the number of characters to append

Returns:

a reference to this text buffer

- (OLTextBuffer*) appendText:

(OLText *)

text

Append a text object.

All the characters of the given object will be appended to this array.

Parameters:

text

the text to append

Returns:

a reference to this text buffer

- (OLTextBuffer*) appendTextBuffer:

(OLTextBuffer *)

buffer

Append another text buffer.

All the characters of the given buffer will be appended to this array.

Parameters:

buffer

the buffer to append

Returns:

a reference to this text buffer

- (OLTextBuffer*) assignAt:		(unsigned)	index
character:		(olchar)	ch

Assign a character.

The character at index is replaced.

Note:

The index is not checked to make sure it is within the bounds of the text buffer.

Parameters:

	index	the index at which to replace the value of the character
	ch	the new character for index

Returns:

a reference to this text buffer

- (olchar) at:

(unsigned)

index

Return the character at index.

Note:

If index is out of the range controlled by this object, the result will be undefined.

Parameters:

index

the index of the character to return

Returns:

the character at index

- (unsigned) capacity

Return the capacity of this buffer.

Returns:

the capacity

- (void) clear

Erase all characters.

- (int) compare:

(id)

other

Compare this object to another.

The two objects, if compatible, will be compared lexicographically.

Parameters:

other

the object to which to compare this one

Returns:

a value greater than, equal to, or less than zero accoringly as this object is greater than, equal to, or less than other

- (id) copy

Return a copy of this text buffer.

Returns:

a copy

- (BOOL) empty

Return whether this text buffer is empty.

Returns:

YES if the buffer is empty, NO if not

- (OLTextBuffer*) eraseAt:

(unsigned)

index

Erase a character.

The character at the given index will be erased and the indices of all subsequent characters will be shifted down one position.

Note:

If index is out of the range controlled by this object, the result will be undefined.

Parameters:

index

the index at which to erase

Returns:

a reference to this text buffer

- (OLTextBuffer*) eraseFromOffset:		(unsigned)	offset
count:		(unsigned)	num

Erase a group of characters.

The given number of characters starting at the given offset will be removed.

Note:

No bounds checking is performed on the input parameters.

Parameters:

	offset	the offset from which to erase
	num	the number of characters to erase

Returns:

a reference to this text buffer

- (unsigned) findChar:		(olchar)	ch
fromOffset:		(unsigned)	offset

Find a character.

The character is searched for from the given offset.

Note:

The starting offset is not checked to make sure it is within the bounds of the text buffer.

Parameters:

	ch	the character for which to search
	offset	the offset from which to start

Returns:

the index of the character or UINT_MAX if the character cannot be found

- (unsigned) findFirstNotOf:		(OLText *)	text
fromOffset:		(unsigned)	offset

Find a character not in a set.

The characters of this text buffer are searched until one is found that is not contained in the given set, text.

Note:

The starting offset is not checked to make sure it is within the bounds of the text.

Parameters:

	text	the set of characters against which to compare
	offset	the starting offset in this text object of the search

Returns:

the index of the first character not in text or UINT_MAX if all characters of text are contained in this text object

- (unsigned) findFirstOf:		(OLText *)	text
fromOffset:		(unsigned)	offset

Find a character of a set.

The characters of this text buffer are searched until one is found that is contained in the given set, text.

Note:

The starting offset is not checked to make sure it is within the bounds of the text.

Parameters:

	text	the set of characters against which to compare
	offset	the starting offset in this text object of the search

Returns:

the index of the first character in text or UINT_MAX if no characters of text are contained in this text object

- (unsigned) findLastNotOf:		(OLText *)	text
fromOffset:		(unsigned)	offset

Find a character not in a set.

The characters of this text buffer are searched until one is found that is not contained in the given set, text. The search begins at offset and proceeds backwards, towards the beginning of this text object.

Note:

The starting offset is not checked to make sure it is within the bounds of the text.

Parameters:

	text	the set of characters against which to compare
	offset	the starting offset in this text object of the search

Returns:

the index of the last character not in text or UINT_MAX if all characters of text are contained in this text object

- (unsigned) findLastOf:		(OLText *)	text
fromOffset:		(unsigned)	offset

Find a character of a set.

The characters of this text buffer are searched until one is found that is contained in the given set, text. The search begins at offset and proceeds backwards, towards the beginning of this text object.

Note:

The starting offset is not checked to make sure it is within the bounds of the text.

Parameters:

	text	the set of characters against which to compare
	offset	the starting offset in this text object of the search

Returns:

the index of the last character in text or UINT_MAX if no characters of text are contained in this text object

- (unsigned) findText:		(OLText *)	text
fromOffset:		(unsigned)	offset

Find a subsequence.

This text buffer is searched until the subsequence represented by text is found.

Note:

The starting offset is not checked to make sure it is within the bounds of the text.

Parameters:

	text	the subsequence for which to search
	offset	the starting offset in this text object of the search

Returns:

the beginning index of the subsequence or UINT_MAX if the subsequence cannot be found

- (id) free

Free all memory allocated by this buffer and destroy the object.

- (void) getCharacters:		(olchar *)	buffer
fromOffset:		(unsigned)	offset
count:		(unsigned)	num

Extract a range of characters.

A range of characters from this text buffer is copied to a buffer.

Note:

No range checking is performed on the validity of the arguments passed.

Parameters:

	buffer	the destination buffer
	offset	the starting offset
	num	the number of characters to copy

- (id) init

Initialize a new text buffer.

The resuling buffer contains no text. The buffer will have an initial capacity of 32 characters. This will grow as needed.

Returns:

a reference to this text buffer

- (id) initWithCapacity:

(unsigned)

cap

Initialize a new text buffer.

The resuling buffer contains no text. The buffer will have an initial capacity of cap characters. This will grow as needed.

Parameters:

cap

the capacity with which to start

Returns:

a reference to this text buffer

- (id) initWithText:

(OLText *)

text

Initialize a new text buffer.

The buffer will start with a copy of the given text.

Parameters:

text

the text to copy into the buffer

Returns:

a reference to this text buffer

- (OLTextBuffer*) insertChar:		(olchar)	ch
atOffset:		(unsigned)	offset

Insert a character.

The given character is inserted at the given offset and the indices of all subsequent characters are shifted up by one.

Note:

The offset for the insertion is not checked to determine whether it is actually in the sequence controller by this text buffer.

Parameters:

	ch	the character to insert
	offset	the offset at which to insert ch

Returns:

a reference to this text buffer

- (OLTextBuffer*) insertChars:		(const olchar *)	chars
atOffset:		(unsigned)	offset
count:		(unsigned)	num

Insert an array of characters.

The given number of haracters from the given array are inserted from the given offset.

Note:

No range checking is performed on the validity of the arguments passed.

Parameters:

	chars	the array from which to copy characters
	offset	the index in chars from which to start copying
	num	the number of characters to insert

Returns:

a reference to this text buffer

- (OLTextBuffer*) insertText:		(OLText *)	text
atOffset:		(unsigned)	offset

Insert a chunk of text.

The given text is inserted into the buffer at the given offset.

Note:

The offset for the insertion is not checked to determine whether it is actually in the sequence controller by this text buffer.

Parameters:

	text	the text object to insert
	offset	the offset at which to insert the characters from text

Returns:

a reference to this text buffer

- (BOOL) isEqual:

(id)

object

Return whether this text buffer is equal to another one.

This message returns YES if compare: returns zero.

Parameters:

object

the object to test

Returns:

YES if object is equal to this text object

- (unsigned) length

Return the length of the text buffer.

This is message returns the same value as size. The number of characters controlled by the buffer is returned, not the capacity.

Returns:

the length

- (OLTextBuffer*) replaceFromOffset:		(unsigned)	offset
count:		(unsigned)	num
withText:		(OLText *)	text

Replace a range of characters.

The given number of characters are replaced from the given offset with the given text object.

Note:

None of the input parameters is checked to be sure that it actually refers to a part of the text buffer that is under its conrol.

Parameters:

	offset	the starting offset of the characters to replace
	num	the number of characters to replace
	text	the text to insert as a replacement

Returns:

a reference to this text buffer

- (void) reserve:

(unsigned)

cap

Ensure that the capacity of the text buffer is at least of a certain size.

After sending this message the capacity of the text buffer will be no less than the given value.

Parameters:

cap

the new desired capacity

- (OLTextBuffer*) resize:		(unsigned)	newLength
filledWith:		(olchar)	ch

Resize the text buffer.

If the given size is greater than the current size, not the current capacity, then the remainder will be filled with the given character. If the give size is less than the current size, then the size will be truncated.

Parameters:

	newLength	the new size of the text buffer
	ch	the character with which to fill the empty space if the new size is greater than the current size

Returns:

a reference to this text buffer

- (OLTextBuffer*) reverse

Reverse the order of characters.

After sending this message the characters will be in reverse order from the order in which they were before.

Returns:

a reference to this text buffer

- (unsigned) rfindChar:		(olchar)	ch
fromOffset:		(unsigned)	offset

Find a character.

The character is searched for from the given offset backwards, towards the beginning of this text buffer.

Note:

The starting offset is not checked to make sure it is within the bounds of the text.

Parameters:

	ch	the character for which to search
	offset	the offset from which to start

Returns:

the last index of the character or UINT_MAX if the character cannot be found

- (unsigned) size

Return the size of the text buffer.

This is message returns the same value as length. The number of characters controlled by the buffer is returned, not the capacity.

Returns:

the size

- (OLText*) substrFromOffset:		(unsigned)	offset
count:		(unsigned)	num

Extract a subsequence.

A new text object is created from the indicated subsequence of this one.

Note:

If OpenStep is present the returned object will be autoreleased before being returned.

No range checking is performed on the validity of the arguments passed.

Parameters:

	offset	the offset from which to start the new object
	num	the number of characters in the new object

Returns:

a new text object that contains the indicated subsequence

- (OLText*) text

Return the text.

All of the text controlled by this buffer will be used to create a new text object.

Note:

If OpenStep is present the returned object will be autoreleased before being returned.

Returns:

a text object that represents this buffer

+ (id) textBuffer

Create and return a new, empty text buffer.

Note:

If OpenStep is present the returned object will be autoreleased before being returned.

Returns:

a new text buffer

+ (id) textBufferWithText:

(OLText *)

text

Create and return a new text buffer that holds a copy of the give text object.

Note:

If OpenStep is present the returned object will be autoreleased before being returned.

Parameters:

text

the text to copy into this buffer

Returns:

a new text buffer

---

Member Data Documentation

- (olchar*) begin [protected]

The array of characters under control of this object.

- (unsigned) capacity [protected]

The capacity of the array.

- (unsigned) size [protected]

The size of the array.

---

The documentation for this class was generated from the following file:

• Text.h

---

Generated Sun Apr 22 15:19:08 2007, © 2004-2007 Will Mason