ObjectiveLib  1.0.0
Public Member Functions | Static Public Member Functions | Protected Attributes
OLText Class Reference

A immutable piece of text. More...

#import <ObjectiveLib/Text.h>

Inheritance diagram for OLText:
Inheritance graph
[legend]

List of all members.

Public Member Functions

(olchar- at:
 Return the character at index.
(uint8_t *) - bytesWithEncoding:returnedCount:
 Return the text encoded with the given encoding.
(int) - compare:
 Compare this object to another.
(id) - copyWithZone:
 Return a copy of this object.
(const char *) - cString
 Return a "C string".
(BOOL) - empty
 Return whether this text is empty.
(void) - encodeWithCoder:
 Encode the text.
(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.
(unsigned) - hash
 Return a hash code.
(BOOL) - isEqual:
 Return whether this text object is equal to another one.
(unsigned) - length
 Return the length of the text.
(unsigned) - maxSize
 Return the maximum size of a text object.
(uint8_t *) - nullTerminatedBytesWithEncoding:
 Return the text encoded with the given encoding.
(unsigned) - rfindChar:fromOffset:
 Find a character.
(unsigned) - size
 Return the size of the text.
(OLText *) - substrFromOffset:count:
 Extract a subsequence.
(NSString *) - toNSString
 Convert this text object to an instance of NSString.
(void) - writeSelfToStream:
 Write this object to a stream.
Initializers and Deallocators
(id) - init
 Initialize a new text object.
(id) - initWithBytes:count:encoding:
 Initialize a new text object.
(id) - initWithChars:count:
 Initialize a new text object.
(id) - initWithCoder:
 Initialize the text object.
(id) - initWithCString:
 Initialize the text object.
(id) - initWithNSString:
(id) - initWithObjectInStream:
 Initialize the text object.
(id) - initWithText:
 Initialize the text object.
(id) - initWithText:offset:count:
 Initialize the text object.
(void) - dealloc
 Reduce the reference count to the text by one and deallocate the memory if the reference count becomes zero.

Static Public Member Functions

(void) + initialize
 Initialize the class.
(id) + textWithBytes:count:encoding:
 Create and return a new text object.
(id) + textWithCString:
 Create and return a new text object.
(id) + textWithNSString:
 Create and return a new text object.
(id) + textWithText:
 Create and return a new text object.

Protected Attributes

struct _OLTextReference * reference
 The opaque structure that holds the data.

Detailed Description

A immutable piece of text.

Text stored in an instance of OLText can be queried, searched, converted to other encodings and subsequences can be extracted, but the text itself cannot be changed. In order to mutate a piece of text an instance of the class OLTextBuffer must be used, and then an immutable OLText object can be derived.

OLText objects maintain their data by reference counting. Therefore, copying a piece of text is a very inexpensive operation, as the reference count is simply incremented.

See also:
OLTextBuffer

Member Function Documentation

- (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:
indexthe index of the character to return
Returns:
the character at index
- (uint8_t*) bytesWithEncoding: (const char *)  enc
returnedCount: (unsigned *)  rc 

Return the text encoded with the given encoding.

The length of the returned array will be placed in rc.

Note:
The returned array must be freed with objc_free.
Exceptions:
NSInvalidArgumentExceptionif the given encoding is not supported
Parameters:
encthe encoding with which to encode the text
rcthe length of the returned array
Returns:
an array of encoded text
- (int) compare: (id)  other

Compare this object to another.

OLText objects can be compared to other OLText objects, to NSString objects under OpenStep and to OLConstantString objects if OpenStep is not present. The two objects, if compatible, will be compared lexicographically.

Parameters:
otherthe 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) copyWithZone: (NSZone *)  zone

Return a copy of this object.

A new object is returned that refers to the same text as this object. The reference count is merely incremented. The new object will be allocated from zone.

Parameters:
zonethe zone from which to allocate new memory
Returns:
a copy of this object
- (const char*) cString

Return a "C string".

The returned array is an array of bytes encoded with the default encoding for the platform. This encoding should be set with a previous call to setlocale. The returned array should not be freed by the caller.

Returns:
an array encoded with the default encoding
- (void) dealloc

Reduce the reference count to the text by one and deallocate the memory if the reference count becomes zero.

- (BOOL) empty

Return whether this text is empty.

Returns:
YES if the text is empty, NO otherwise
- (void) encodeWithCoder: (NSCoder *)  encoder

Encode the text.

This should not be confused with the notion of "encoding" the text in the sense of a "text encoding". Encoding in this context refers to the act of saving the text to an archive. The text is saved to an archive using encoder. The test can be retrieved from the archive using the initializer initWithCoder:.

Parameters:
encoderthe coder which will save the text to the archive
- (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.
Parameters:
chthe character for which to search
offsetthe 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 object 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:
textthe set of characters against which to compare
offsetthe 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 object 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:
textthe set of characters against which to compare
offsetthe 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 object 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:
textthe set of characters against which to compare
offsetthe 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 object 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:
textthe set of characters against which to compare
offsetthe 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 object 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:
textthe subsequence for which to search
offsetthe 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
- (void) getCharacters: (olchar *)  buffer
fromOffset: (unsigned)  offset
count: (unsigned)  num 

Extract a range of characters.

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

Note:
No range checking is performed on the validity of the arguments passed.
Parameters:
bufferthe destination buffer
offsetthe starting offset
numthe number of characters to copy
- (unsigned) hash

Return a hash code.

The hash code for this text object is computed using OLHash.

Returns:
the hash code
- (id) init

Initialize a new text object.

The text is empty.

Returns:
a reference to this text
+ (void) initialize

Initialize the class.

This for the runtime system to call. Please don't call this method.

- (id) initWithBytes: (const uint8_t *)  bytes
count: (unsigned)  num
encoding: (const char *)  enc 

Initialize a new text object.

The bytes given will be converted from the encoding enc to UTF-16.

Exceptions:
NSInvalidArgumentExceptionif the given encoding is not supported
Parameters:
bytesthe bytes containing the text encoded with the given encoding
numthe number of bytes
encthe encoding used for the data in bytes
Returns:
a reference to this text object
- (id) initWithChars: (const olchar *)  chs
count: (unsigned)  num 

Initialize a new text object.

The new object will contain the characters pointed to by the parameter chs.

Parameters:
chsthe characters to copy into the new text object
numthe number of characters
Returns:
a reference to this text object
- (id) initWithCoder: (NSCoder *)  decoder

Initialize the text object.

Creates a new text object from an archive and returns it.

Postcondition:
The text returned will be identical to the text saved to the archive using the encodeWithCoder: message.
Parameters:
decoderthe coder which will decode the archived text
Returns:
a reference to this text object
- (id) initWithCString: (const char *)  chs

Initialize the text object.

The text in chs is assumed to be in the default encoding for the platform. This locale is assumed to have been set by a previous call to setlocale. The "C string" chs should be null-terminated.

Parameters:
chsthe characters to encode with UTF-16 and store
Returns:
a reference to this text object

Initialize the text object.

Creates a new text object from an object input stream.

Postcondition:
The text returned will be identical to the text saved to the stream using the writeSelfToStream: message.
Parameters:
streamthe input stream from which to read the text
Returns:
a reference to this text object

Reimplemented from <OLStreamable>.

- (id) initWithText: (OLText *)  text

Initialize the text object.

The given text object text is copied, meaning that the reference count to its data is incremented.

Parameters:
textthe text to copy
Returns:
a reference to this text object
- (id) initWithText: (OLText *)  text
offset: (unsigned)  roff
count: (unsigned)  num 

Initialize the text object.

A span of num characters is copied from the given text object text starting at roff.

Note:
The boundaries of the text object from which to copy are not checked, meaning that if any character designated to be copied is not actually controlled by the give text object, the results will be undefined.
Parameters:
textthe text object from which to copy characters
roffthe beginning offset from which to copy
numthe number of characters to copy
Returns:
a reference to this text object
- (BOOL) isEqual: (id)  object

Return whether this text object is equal to another one.

This message returns YES if compare: returns zero.

Parameters:
objectthe object to test
Returns:
YES if object is equal to this text object
- (unsigned) length

Return the length of the text.

This is message returns the same value as size.

Returns:
the length
- (unsigned) maxSize

Return the maximum size of a text object.

Returns:
the maximum size
- (uint8_t*) nullTerminatedBytesWithEncoding: (const char *)  enc

Return the text encoded with the given encoding.

The resulting array will be null-terminated.

Note:
The returned array must be freed with objc_free.
Exceptions:
NSInvalidArgumentExceptionif the given encoding is not supported
Parameters:
encthe encoding with which to encode the text
Returns:
an array of encoded text
- (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 object.

Note:
The starting offset is not checked to make sure it is within the bounds of the text.
Parameters:
chthe character for which to search
offsetthe 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.

This is message returns the same value as length.

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. Additionally, no range checking is performed on the validity of the arguments passed.
Parameters:
offsetthe offset from which to start the new object
numthe number of characters in the new object
Returns:
a new text object that contains the indicated subsequence
+ (id) textWithBytes: (const uint8_t *)  bytes
count: (unsigned)  num
encoding: (const char *)  enc 

Create and return a new text object.

The text is encoded from the given encoding enc to the internal encoding used by all text objects of UTF-16.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Exceptions:
NSInvalidArgumentExceptionif the given encoding is not supported
Parameters:
bytesthe bytes containing the text encoded with the given encoding
numthe number of bytes
encthe encoding used for the data in bytes
Returns:
a reference to the new text object
+ (id) textWithCString: (const char *)  chs

Create and return a new text object.

The text in chs is assumed to be in the default encoding for the platform. This locale is assumed to have been set by a previous call to setlocale. The "C string" chs should be null-terminated.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
chsthe characters to encode with UTF-16 and store
Returns:
a reference to the new text object
+ (id) textWithNSString: (NSString *)  str

Create and return a new text object.

The text is copied from the NSString object. The returned text will be autoreleased before being returned.

Parameters:
strthe NSString to copy
Returns:
a reference to the new text object
+ (id) textWithText: (OLText *)  text

Create and return a new text object.

The given text object text is copied, meaning that the reference count to its data is incremented.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
textthe text to copy
Returns:
a reference to the new text object
- (NSString*) toNSString

Convert this text object to an instance of NSString.

The returned NSString is autoreleased for being returned.

Returns:
a NSString that contains the text of this object
- (void) writeSelfToStream: (OLObjectOutStream *)  stream

Write this object to a stream.

The text is written in a platform-neutral way and may be recovered with the initializer initWithObjectInStream:.

Exceptions:
OLInputOutputExceptionif there is an error writing to the stream
Parameters:
streamthe stream to which to write

Reimplemented from <OLStreamable>.


Member Data Documentation

- (struct _OLTextReference*) reference [protected]

The opaque structure that holds the data.


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

ObjectiveLibGenerated Sat Feb 15 2014 07:45:35, © 2004-2007 Will Mason