A class for handling strings. More...

#include <ObjFW/ObjFW.h>

Inheritance diagram for OFString:

Instance Methods
(instancetype)	- init
	Initializes an already allocated OFString to be empty.

(instancetype)	- initWithUTF8String:
	Initializes an already allocated OFString from a UTF-8 encoded C string.

(instancetype)	- initWithUTF8String:length:
	Initializes an already allocated OFString from a UTF-8 encoded C string with the specified length.

(instancetype)	- initWithUTF8StringNoCopy:freeWhenDone:
	Initializes an already allocated OFString from an UTF-8 encoded C string without copying the string, if possible.

(instancetype)	- initWithUTF8StringNoCopy:length:freeWhenDone:
	Initializes an already allocated OFString from an UTF-8 encoded C string with the specified length without copying the string, if possible.

(instancetype)	- initWithCString:encoding:
	Initializes an already allocated OFString from a C string with the specified encoding.

(instancetype)	- initWithCString:encoding:length:
	Initializes an already allocated OFString from a C string with the specified encoding and length.

(instancetype)	- initWithData:encoding:
	Initializes an already allocated OFString from OFData with the specified encoding.

(instancetype)	- initWithString:
	Initializes an already allocated OFString with another string.

(instancetype)	- initWithCharacters:length:
	Initializes an already allocated OFString with a Unicode string with the specified length.

(instancetype)	- initWithUTF16String:
	Initializes an already allocated OFString with a UTF-16 string.

(instancetype)	- initWithUTF16String:length:
	Initializes an already allocated OFString with a UTF-16 string with the specified length.

(instancetype)	- initWithUTF16String:byteOrder:
	Initializes an already allocated OFString with a UTF-16 string, assuming the specified byte order if no byte order mark is found.

(instancetype)	- initWithUTF16String:length:byteOrder:
	Initializes an already allocated OFString with a UTF-16 string with the specified length, assuming the specified byte order if no byte order mark is found.

(instancetype)	- initWithUTF32String:
	Initializes an already allocated OFString with a UTF-32 string.

(instancetype)	- initWithUTF32String:length:
	Initializes an already allocated OFString with a UTF-32 string with the specified length.

(instancetype)	- initWithUTF32String:byteOrder:
	Initializes an already allocated OFString with a UTF-32 string, assuming the specified byte order if no byte order mark is found.

(instancetype)	- initWithUTF32String:length:byteOrder:
	Initializes an already allocated OFString with a UTF-32 string with the specified length, assuming the specified byte order if no byte order mark is found.

(instancetype)	- initWithFormat:
	Initializes an already allocated OFString with a format string.

(instancetype)	- initWithFormat:arguments:
	Initializes an already allocated OFString with a format string.

(instancetype)	- initWithContentsOfFile:
	Initializes an already allocated OFString with the contents of the specified file in the specified encoding.

(instancetype)	- initWithContentsOfFile:encoding:
	Initializes an already allocated OFString with the contents of the specified file in the specified encoding.

(instancetype)	- initWithContentsOfIRI:
	Initializes an already allocated OFString with the contents of the specified IRI.

(instancetype)	- initWithContentsOfIRI:encoding:
	Initializes an already allocated OFString with the contents of the specified IRI in the specified encoding.

(size_t)	- getCString:maxLength:encoding:
	Writes the OFString into the specified C string with the specified encoding.

(size_t)	- getLossyCString:maxLength:encoding:
	Writes the OFString into the specified C string with the specified encoding, replacing characters that cannot be represented in the specified encoding with a question mark.

(const char *)	- cStringWithEncoding:
	Returns the OFString as a C string in the specified encoding.

(const char *)	- lossyCStringWithEncoding:
	Returns the OFString as a C string in the specified encoding, replacing characters that cannot be represented in the specified encoding with a question mark.

(const char *)	- insecureCStringWithEncoding:
	Returns the OFString as an insecure C string (meaning it can contain `\0`) in the specified encoding.

(size_t)	- cStringLengthWithEncoding:
	Returns the number of bytes the string needs in the specified encoding.

(OFComparisonResult)	- compare:
	Compares the string to another string.

(OFComparisonResult)	- caseInsensitiveCompare:
	Compares the string to another string without caring about the case.

(OFUnichar)	- characterAtIndex:
	Returns the Unicode character at the specified index.

(void)	- getCharacters:inRange:
	Copies the Unicode characters in the specified range to the specified buffer.

(OFRange)	- rangeOfString:
	Returns the range of the first occurrence of the string.

(OFRange)	- rangeOfString:options:
	Returns the range of the string.

(OFRange)	- rangeOfString:options:range:
	Returns the range of the string in the specified range.

(size_t)	- indexOfCharacterFromSet:
	Returns the index of the first character from the set.

(size_t)	- indexOfCharacterFromSet:options:
	Returns the index of the first character from the set.

(size_t)	- indexOfCharacterFromSet:options:range:
	Returns the index of the first character from the set.

(bool)	- containsString:
	Returns whether the string contains the specified string.

(OFString *)	- substringFromIndex:
	Creates a substring from the specified index to the end.

(OFString *)	- substringToIndex:
	Creates a substring from the beginning to the specified index.

(OFString *)	- substringWithRange:
	Creates a substring with the specified range.

(long long)	- longLongValueWithBase:
	The value of the string in the specified base as a `long long`.

(unsigned long long)	- unsignedLongLongValueWithBase:
	The value of the string in the specified base as an `unsigned long long`.

(OFString *)	- stringByAppendingString:
	Creates a new string by appending another string.

(OFString *)	- stringByAppendingFormat:
	Creates a new string by appending the specified format.

(OFString *)	- stringByAppendingFormat:arguments:
	Creates a new string by appending the specified format.

(OFString *)	- stringByReplacingOccurrencesOfString:withString:
	Creates a new string by replacing the occurrences of the specified string with the specified replacement.

(OFString *)	- stringByReplacingOccurrencesOfString:withString:options:range:
	Creates a new string by replacing the occurrences of the specified string in the specified range with the specified replacement.

(bool)	- hasPrefix:
	Checks whether the string has the specified prefix.

(bool)	- hasSuffix:
	Checks whether the string has the specified suffix.

(OFArray *)	- componentsSeparatedByString:
	Separates the string into an array of strings, split by the specified delimiter.

(OFArray *)	- componentsSeparatedByString:options:
	Separates the string into an array of strings, split by the specified delimiter.

(OFArray *)	- componentsSeparatedByCharactersInSet:
	Separates the string into an array of strings, split by characters in the specified set.

(OFArray *)	- componentsSeparatedByCharactersInSet:options:
	Separates the string into an array of strings, split by characters in the specified set.

(const OFChar16 *)	- UTF16StringWithByteOrder:
	Returns the string in UTF-16 encoding with the specified byte order.

(const OFChar32 *)	- UTF32StringWithByteOrder:
	Returns the string in UTF-32 encoding with the specified byte order.

(OFData *)	- dataWithEncoding:
	Returns the string as OFData with the specified encoding.

(void)	- writeToFile:
	Writes the string into the specified file using UTF-8 encoding.

(void)	- writeToFile:encoding:
	Writes the string into the specified file using the specified encoding.

(void)	- writeToIRI:
	Writes the string to the specified IRI using UTF-8 encoding.

(void)	- writeToIRI:encoding:
	Writes the string to the specified IRI using the specified encoding.

(void)	- enumerateLinesUsingBlock:
	block The block to call for each line

(id)	- objectByParsingJSONWithDepthLimit:
	Creates an object from the JSON value of the string.

(OFString *)	- stringByAppendingPathComponent:
	Creates a new string by appending a path component.

(OFString *)	- stringByAppendingPathExtension:
	Creates a new string by appending a path extension.

(OFString *)	- stringByAddingPercentEncodingWithAllowedCharacters:
	Percent-encodes a string for use in an IRI, but does not escape the specified allowed characters.

(OFString *)	- stringByXMLUnescapingWithDelegate:
	Unescapes XML in the string and uses the specified delegate for unknown entities.

(OFString *)	- stringByXMLUnescapingWithBlock:
	Unescapes XML in the string and uses the specified block for unknown entities.

Instance Methods inherited from OFObject
(nullable OFMethodSignature *)	- methodSignatureForSelector:
	Returns the method signature for the specified selector.

(void)	- dealloc
	Deallocates the object.

(void)	- performSelector:afterDelay:
	Performs the specified selector after the specified delay.

(void)	- performSelector:withObject:afterDelay:
	Performs the specified selector with the specified object after the specified delay.

(void)	- performSelector:withObject:withObject:afterDelay:
	Performs the specified selector with the specified objects after the specified delay.

(void)	- performSelector:withObject:withObject:withObject:afterDelay:
	Performs the specified selector with the specified objects after the specified delay.

(void)	- performSelector:withObject:withObject:withObject:withObject:afterDelay:
	Performs the specified selector with the specified objects after the specified delay.

(void)	- performSelector:onThread:waitUntilDone:
	Performs the specified selector on the specified thread.

(void)	- performSelector:onThread:withObject:waitUntilDone:
	Performs the specified selector on the specified thread with the specified object.

(void)	- performSelector:onThread:withObject:withObject:waitUntilDone:
	Performs the specified selector on the specified thread with the specified objects.

(void)	- performSelector:onThread:withObject:withObject:withObject:waitUntilDone:
	Performs the specified selector on the specified thread with the specified objects.

(void)	- performSelector:onThread:withObject:withObject:withObject:withObject:waitUntilDone:
	Performs the specified selector on the specified thread with the specified objects.

(void)	- performSelectorOnMainThread:waitUntilDone:
	Performs the specified selector on the main thread.

(void)	- performSelectorOnMainThread:withObject:waitUntilDone:
	Performs the specified selector on the main thread with the specified object.

(void)	- performSelectorOnMainThread:withObject:withObject:waitUntilDone:
	Performs the specified selector on the main thread with the specified objects.

(void)	- performSelectorOnMainThread:withObject:withObject:withObject:waitUntilDone:
	Performs the specified selector on the main thread with the specified objects.

(void)	- performSelectorOnMainThread:withObject:withObject:withObject:withObject:waitUntilDone:
	Performs the specified selector on the main thread with the specified objects.

(void)	- performSelector:onThread:afterDelay:
	Performs the specified selector on the specified thread after the specified delay.

(void)	- performSelector:onThread:withObject:afterDelay:
	Performs the specified selector on the specified thread with the specified object after the specified delay.

(void)	- performSelector:onThread:withObject:withObject:afterDelay:
	Performs the specified selector on the specified thread with the specified objects after the specified delay.

(void)	- performSelector:onThread:withObject:withObject:withObject:afterDelay:
	Performs the specified selector on the specified thread with the specified objects after the specified delay.

(void)	- performSelector:onThread:withObject:withObject:withObject:withObject:afterDelay:
	Performs the specified selector on the specified thread with the specified objects after the specified delay.

(nullable id)	- forwardingTargetForSelector:
	This method is called when resolveClassMethod: or resolveInstanceMethod: returned false. It should return a target to which the message should be forwarded.

(void)	- doesNotRecognizeSelector:
	Handles messages which are not understood by the receiver.

Instance Methods inherited from <OFObject>
(unsigned long)	- hash
	Returns a hash for the object.

(unsigned int)	- retainCount
	Returns the retain count.

(bool)	- isProxy
	Returns whether the object is a proxy object.

(bool)	- isKindOfClass:
	Returns a boolean whether the object is of the specified kind.

(bool)	- isMemberOfClass:
	Returns a boolean whether the object is a member of the specified class.

(bool)	- respondsToSelector:
	Returns a boolean whether the object responds to the specified selector.

(nullable IMP)	- methodForSelector:
	Returns the implementation for the specified selector.

(nullable id)	- performSelector:
	Performs the specified selector.

(nullable id)	- performSelector:withObject:
	Performs the specified selector with the specified object.

(nullable id)	- performSelector:withObject:withObject:
	Performs the specified selector with the specified objects.

(nullable id)	- performSelector:withObject:withObject:withObject:
	Performs the specified selector with the specified objects.

(nullable id)	- performSelector:withObject:withObject:withObject:withObject:
	Performs the specified selector with the specified objects.

(bool)	- isEqual:
	Checks two objects for equality.

(instancetype)	- retain
	Increases the retain count.

(void)	- release
	Decreases the retain count.

(instancetype)	- autorelease
	Adds the object to the topmost autorelease pool of the thread's autorelease pool stack.

(instancetype)	- self
	Returns the receiver.

(bool)	- allowsWeakReference
	Returns whether the object allows a weak reference.

(bool)	- retainWeakReference
	Retain a weak reference to this object.

Instance Methods inherited from <OFCopying>
(id)	- copy
	Copies the object.

Instance Methods inherited from <OFMutableCopying>
(id)	- mutableCopy
	Creates a mutable copy of the object.

Instance Methods inherited from <OFComparing>
(OFComparisonResult)	- compare:
	Compares the object to another object.

Instance Methods inherited from <OFJSONRepresentation>
(OFString *)	- JSONRepresentationWithOptions:
	Returns the JSON representation of the object as a string.

Class Methods
(instancetype)	+ string
	Creates a new OFString.

(instancetype)	+ stringWithUTF8String:
	Creates a new OFString from a UTF-8 encoded C string.

(instancetype)	+ stringWithUTF8String:length:
	Creates a new OFString from a UTF-8 encoded C string with the specified length.

(instancetype)	+ stringWithUTF8StringNoCopy:freeWhenDone:
	Creates a new OFString from a UTF-8 encoded C string without copying the string, if possible.

(instancetype)	+ stringWithUTF8StringNoCopy:length:freeWhenDone:
	Creates a new OFString from a UTF-8 encoded C string with the specified length without copying the string, if possible.

(instancetype)	+ stringWithCString:encoding:
	Creates a new OFString from a C string with the specified encoding.

(instancetype)	+ stringWithCString:encoding:length:
	Creates a new OFString from a C string with the specified encoding and length.

(instancetype)	+ stringWithData:encoding:
	Creates a new OFString from OFData with the specified encoding.

(instancetype)	+ stringWithString:
	Creates a new OFString from another string.

(instancetype)	+ stringWithCharacters:length:
	Creates a new OFString from a Unicode string with the specified length.

(instancetype)	+ stringWithUTF16String:
	Creates a new OFString from a UTF-16 encoded string.

(instancetype)	+ stringWithUTF16String:length:
	Creates a new OFString from a UTF-16 encoded string with the specified length.

(instancetype)	+ stringWithUTF16String:byteOrder:
	Creates a new OFString from a UTF-16 encoded string, assuming the specified byte order if no byte order mark is found.

(instancetype)	+ stringWithUTF16String:length:byteOrder:
	Creates a new OFString from a UTF-16 encoded string with the specified length, assuming the specified byte order if no byte order mark is found.

(instancetype)	+ stringWithUTF32String:
	Creates a new OFString from a UTF-32 encoded string.

(instancetype)	+ stringWithUTF32String:length:
	Creates a new OFString from a UTF-32 encoded string with the specified length.

(instancetype)	+ stringWithUTF32String:byteOrder:
	Creates a new OFString from a UTF-32 encoded string, assuming the specified byte order if no byte order mark is found.

(instancetype)	+ stringWithUTF32String:length:byteOrder:
	Creates a new OFString from a UTF-32 encoded string with the specified length, assuming the specified byte order if no byte order mark is found.

(instancetype)	+ stringWithFormat:
	Creates a new OFString from a format string.

(instancetype)	+ stringWithContentsOfFile:
	Creates a new OFString with the contents of the specified UTF-8 encoded file.

(instancetype)	+ stringWithContentsOfFile:encoding:
	Creates a new OFString with the contents of the specified file in the specified encoding.

(instancetype)	+ stringWithContentsOfIRI:
	Creates a new OFString with the contents of the specified IRI.

(instancetype)	+ stringWithContentsOfIRI:encoding:
	Creates a new OFString with the contents of the specified IRI in the specified encoding.

(OFString *)	+ pathWithComponents:
	Creates a path from the specified path components.

Class Methods inherited from OFObject
(void)	+ load
	A method which is called once when the class is loaded into the runtime.

(void)	+ unload
	A method which is called when the class is unloaded from the runtime.

(void)	+ initialize
	A method which is called the moment before the first call to the class is being made.

(instancetype)	+ alloc
	Allocates memory for an instance of the class and sets up the memory pool for the object.

(Class)	+ class
	Returns the class.

(OFString *)	+ className
	Returns the name of the class as a string.

(bool)	+ isSubclassOfClass:
	Returns a boolean whether the class is a subclass of the specified class.

(nullable Class)	+ superclass
	Returns the superclass of the class.

(bool)	+ instancesRespondToSelector:
	Checks whether instances of the class respond to a given selector.

(bool)	+ conformsToProtocol:
	Checks whether the class conforms to a given protocol.

(nullable IMP)	+ instanceMethodForSelector:
	Returns the implementation of the instance method for the specified selector.

(nullable OFMethodSignature *)	+ instanceMethodSignatureForSelector:
	Returns the method signature of the instance method for the specified selector.

(OFString *)	+ description
	Returns a description for the class, which is usually the class name.

(nullable IMP)	+ replaceClassMethod:withMethodFromClass:
	Replaces a class method with a class method from another class.

(nullable IMP)	+ replaceInstanceMethod:withMethodFromClass:
	Replaces an instance method with an instance method from another class.

(void)	+ inheritMethodsFromClass:
	Adds all methods from the specified class to the class that is the receiver.

(bool)	+ resolveClassMethod:
	Try to resolve the specified class method.

(bool)	+ resolveInstanceMethod:
	Try to resolve the specified instance method.

(id)	+ copy
	Returns the class.

Properties
size_t	length
	The length of the string in Unicode code points.

const char *	UTF8String
	The OFString as a UTF-8 encoded C string.

size_t	UTF8StringLength
	The number of bytes the string needs in UTF-8 encoding.

OFString *	uppercaseString
	The string in uppercase.

OFString *	lowercaseString
	The string in lowercase.

OFString *	capitalizedString
	The string in capitalized form.

long long	longLongValue
	The decimal value of the string as a `long long`.

unsigned long long	unsignedLongLongValue
	The decimal value of the string as an `unsigned long long`.

float	floatValue
	The float value of the string as a float.

double	doubleValue
	The double value of the string as a double.

const OFUnichar *	characters
	The string as an array of Unicode characters.

const OFChar16 *	UTF16String
	The string in UTF-16 encoding with native byte order.

size_t	UTF16StringLength
	The length of the string in UTF-16 characters.

const OFChar32 *	UTF32String
	The string in UTF-32 encoding with native byte order.

OFString *	stringByDeletingLeadingWhitespaces
	The string with leading whitespaces deleted.

OFString *	stringByDeletingTrailingWhitespaces
	The string with trailing whitespaces deleted.

OFString *	stringByDeletingEnclosingWhitespaces
	The string with leading and trailing whitespaces deleted.

OFString *	stringByExpandingWindowsEnvironmentStrings
	The string with the Windows Environment Strings expanded.

OFString *	stringByMD5Hashing
	The MD5 hash of the string as a string.

OFString *	stringByRIPEMD160Hashing
	The RIPEMD-160 hash of the string as a string.

OFString *	stringBySHA1Hashing
	The SHA-1 hash of the string as a string.

OFString *	stringBySHA224Hashing
	The SHA-224 hash of the string as a string.

OFString *	stringBySHA256Hashing
	The SHA-256 hash of the string as a string.

OFString *	stringBySHA384Hashing
	The SHA-384 hash of the string as a string.

OFString *	stringBySHA512Hashing
	The SHA-512 hash of the string as a string.

id	objectByParsingJSON
	The string interpreted as JSON and parsed as an object.

bool	absolutePath
	Whether the path is an absolute path.

OFArray *	pathComponents
	The components of the string when interpreted as a path.

OFString *	lastPathComponent
	The last path component of the string when interpreted as a path.

OFString *	pathExtension
	The file extension of string when interpreted as a path.

OFString *	stringByDeletingLastPathComponent
	The directory name of the string when interpreted as a path.

OFString *	stringByDeletingPathExtension
	The string with the file extension of the path removed.

OFString *	stringByStandardizingPath
	The string interpreted as a path with relative sub paths resolved.

OFString *	stringByRemovingPercentEncoding
	The string with percent encoding removed.

id	objectByParsingPropertyList
	The string interpreted as a property list and parsed as an object.

OFString *	stringByXMLEscaping
	The string in a form escaped for use in an XML document.

OFString *	stringByXMLUnescaping
	The string with XML entities unescapted.

Properties inherited from OFObject
OFString *	className
	The name of the object's class.

OFString *	description
	A description for the object.

Properties inherited from <OFJSONRepresentation>
OFString *	JSONRepresentation
	The JSON representation of the object as a string.

Properties inherited from <OFMessagePackRepresentation>
OFData *	messagePackRepresentation
	The MessagePack representation of the object as OFData.

Detailed Description

A class for handling strings.

Method Documentation

◆ caseInsensitiveCompare:

- (OFComparisonResult) caseInsensitiveCompare: (OFString *) string

Compares the string to another string without caring about the case.

Parameters

string The string to compare the string to

Returns: The result of the comparison

◆ characterAtIndex:

- (OFUnichar) characterAtIndex: (size_t) index

Returns the Unicode character at the specified index.

Parameters

index The index of the Unicode character to return

Returns: The Unicode character at the specified index

◆ compare:

- (OFComparisonResult) compare: (OFString *) string

Compares the string to another string.

Parameters

string The string to compare the string to

Returns: The result of the comparison

◆ componentsSeparatedByCharactersInSet:

- (OFArray *) componentsSeparatedByCharactersInSet: (OFCharacterSet *) characterSet

Separates the string into an array of strings, split by characters in the specified set.

Parameters

characterSet The character set for separating

Returns: An autoreleased OFArray with the separated string

◆ componentsSeparatedByCharactersInSet:options:

- (OFArray *) componentsSeparatedByCharactersInSet:		(OFCharacterSet *)	characterSet
options:		(OFStringSeparationOptions)	options

Separates the string into an array of strings, split by characters in the specified set.

Parameters

characterSet	The character set for separating
options	Options according to which the string should be separated

Returns: An autoreleased OFArray with the separated string

◆ componentsSeparatedByString:

- (OFArray *) componentsSeparatedByString: (OFString *) delimiter

Separates the string into an array of strings, split by the specified delimiter.

Parameters

delimiter The delimiter for separating

Returns: An autoreleased OFArray with the separated string

◆ componentsSeparatedByString:options:

- (OFArray *) componentsSeparatedByString:		(OFString *)	delimiter
options:		(OFStringSeparationOptions)	options

Separates the string into an array of strings, split by the specified delimiter.

Parameters

delimiter	The delimiter for separating
options	Options according to which the string should be separated

Returns: An autoreleased OFArray with the separated string

◆ containsString:

- (bool) containsString: (OFString *) string

Returns whether the string contains the specified string.

Parameters

string The string to search

Returns: Whether the string contains the specified string

◆ cStringLengthWithEncoding:

- (size_t) cStringLengthWithEncoding: (OFStringEncoding) encoding

Returns the number of bytes the string needs in the specified encoding.

Parameters

encoding The encoding for the string

Returns: The number of bytes the string needs in the specified encoding.

Exceptions

OFInvalidEncodingException The string cannot be represented in the specified encoding

◆ cStringWithEncoding:

- (const char *) cStringWithEncoding: (OFStringEncoding) encoding

Returns the OFString as a C string in the specified encoding.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

Parameters

encoding The encoding for the C string

Returns: The OFString as a C string in the specified encoding

Exceptions

OFInvalidEncodingException The string cannot be represented in the specified encoding

◆ dataWithEncoding:

- (OFData *) dataWithEncoding: (OFStringEncoding) encoding

Returns the string as OFData with the specified encoding.

Parameters

encoding The encoding to use for the returned OFData

Returns: The string as OFData with the specified encoding

Exceptions

OFInvalidEncodingException The string cannot be represented in the specified encoding

◆ enumerateLinesUsingBlock:

- (void) enumerateLinesUsingBlock: (OFStringLineEnumerationBlock) block

block The block to call for each line

Enumerates all lines in the receiver using the specified block.

◆ getCharacters:inRange:

- (void) getCharacters:		(OFUnichar *)	buffer
inRange:		(OFRange)	range

Copies the Unicode characters in the specified range to the specified buffer.

Parameters

buffer	The buffer to store the Unicode characters
range	The range of the Unicode characters to copy

◆ getCString:maxLength:encoding:

- (size_t) getCString:	(char *)	cString
maxLength:	(size_t)	maxLength
encoding:	(OFStringEncoding)	encoding

Writes the OFString into the specified C string with the specified encoding.

Parameters

cString	The C string to write into
maxLength	The maximum number of bytes to write into the C string, including the terminating zero
encoding	The encoding to use for writing into the C string

Returns: The number of bytes written into the C string, without the terminating zero

Exceptions

OFInvalidEncodingException The string cannot be represented in the specified encoding

◆ getLossyCString:maxLength:encoding:

- (size_t) getLossyCString:	(char *)	cString
maxLength:	(size_t)	maxLength
encoding:	(OFStringEncoding)	encoding

Writes the OFString into the specified C string with the specified encoding, replacing characters that cannot be represented in the specified encoding with a question mark.

Parameters

cString	The C string to write into
maxLength	The maximum number of bytes to write into the C string, including the terminating zero
encoding	The encoding to use for writing into the C string

Returns: The number of bytes written into the C string, without the terminating zero

◆ hasPrefix:

- (bool) hasPrefix: (OFString *) prefix

Checks whether the string has the specified prefix.

Parameters

prefix The prefix to check for

Returns: A boolean whether the string has the specified prefix

◆ hasSuffix:

- (bool) hasSuffix: (OFString *) suffix

Checks whether the string has the specified suffix.

Parameters

suffix The suffix to check for

Returns: A boolean whether the string has the specified suffix

◆ indexOfCharacterFromSet:

- (size_t) indexOfCharacterFromSet: (OFCharacterSet *) characterSet

Returns the index of the first character from the set.

Parameters

characterSet The set of characters to search for

Returns: The index of the first occurrence of a character from the set or OFNotFound if it was not found

◆ indexOfCharacterFromSet:options:

- (size_t) indexOfCharacterFromSet:		(OFCharacterSet *)	characterSet
options:		(OFStringSearchOptions)	options

Returns the index of the first character from the set.

Parameters

characterSet	The set of characters to search for
options	Options modifying search behavior

Returns: The index of the first occurrence of a character from the set or OFNotFound if it was not found

◆ indexOfCharacterFromSet:options:range:

- (size_t) indexOfCharacterFromSet:	(OFCharacterSet *)	characterSet
options:	(OFStringSearchOptions)	options
range:	(OFRange)	range

Returns the index of the first character from the set.

Parameters

characterSet	The set of characters to search for
options	Options modifying search behavior
range	The range in which to search

Returns: The index of the first occurrence of a character from the set or OFNotFound if it was not found

◆ init

- (instancetype) init

Initializes an already allocated OFString to be empty.

Returns: An initialized OFString

Reimplemented from OFObject.

◆ initWithCharacters:length:

- (instancetype) initWithCharacters:		(const OFUnichar *)	characters
length:		(size_t)	length

Initializes an already allocated OFString with a Unicode string with the specified length.

Parameters

characters	An array of Unicode characters
length	The length of the Unicode character array

Returns: An initialized OFString

◆ initWithContentsOfFile:

- (instancetype) initWithContentsOfFile: (OFString *) path

Initializes an already allocated OFString with the contents of the specified file in the specified encoding.

Parameters

path	The path to the file

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ initWithContentsOfFile:encoding:

- (instancetype) initWithContentsOfFile:		(OFString *)	path
encoding:		(OFStringEncoding)	encoding

Initializes an already allocated OFString with the contents of the specified file in the specified encoding.

Parameters

path	The path to the file
encoding	The encoding of the file

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ initWithContentsOfIRI:

- (instancetype) initWithContentsOfIRI: (OFIRI *) IRI

Initializes an already allocated OFString with the contents of the specified IRI.

If the IRI's scheme is file, it tries UTF-8 encoding.

If the IRI's scheme is http or https, it tries to detect the encoding from the HTTP headers. If it could not detect the encoding using the HTTP headers, it tries UTF-8.

Parameters

IRI	The IRI to the contents for the string

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not in the expected encoding

◆ initWithContentsOfIRI:encoding:

- (instancetype) initWithContentsOfIRI:		(OFIRI *)	IRI
encoding:		(OFStringEncoding)	encoding

Initializes an already allocated OFString with the contents of the specified IRI in the specified encoding.

Parameters

IRI	The IRI to the contents for the string
encoding	The encoding to assume

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ initWithCString:encoding:

- (instancetype) initWithCString:		(const char *)	cString
encoding:		(OFStringEncoding)	encoding

Initializes an already allocated OFString from a C string with the specified encoding.

Parameters

cString	A C string to initialize the OFString with
encoding	The encoding of the C string

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ initWithCString:encoding:length:

- (instancetype) initWithCString:	(const char *)	cString
encoding:	(OFStringEncoding)	encoding
length:	(size_t)	cStringLength

Initializes an already allocated OFString from a C string with the specified encoding and length.

Parameters

cString	A C string to initialize the OFString with
encoding	The encoding of the C string
cStringLength	The length of the C string

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ initWithData:encoding:

- (instancetype) initWithData:		(OFData *)	data
encoding:		(OFStringEncoding)	encoding

Initializes an already allocated OFString from OFData with the specified encoding.

Parameters

data	OFData with the contents of the string
encoding	The encoding in which the string is stored in the OFData

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ initWithFormat:

- (instancetype) initWithFormat:		(OFConstantString *)	format
,		(...)

Initializes an already allocated OFString with a format string.

See printf for the format syntax. As an addition, %@ is available as format specifier for objects, C for OFUnichar and S for const OFUnichar *.

Parameters

format A string used as format to initialize the OFString

Returns: An initialized OFString

Exceptions

OFInvalidFormatException	The specified format is invalid
OFInvalidEncodingException	The resulting string is not in not in UTF-8 encoding

◆ initWithFormat:arguments:

- (instancetype) initWithFormat:		(OFConstantString *)	format
arguments:		(va_list)	arguments

Initializes an already allocated OFString with a format string.

See printf for the format syntax. As an addition, %@ is available as format specifier for objects, C for OFUnichar and S for const OFUnichar *.

Parameters

format	A string used as format to initialize the OFString
arguments	The arguments used in the format string

Returns: An initialized OFString

Exceptions

OFInvalidFormatException	The specified format is invalid
OFInvalidEncodingException	The resulting string is not in not in UTF-8 encoding

◆ initWithString:

- (instancetype) initWithString: (OFString *) string

Initializes an already allocated OFString with another string.

Parameters

string A string to initialize the OFString with

Returns: An initialized OFString

◆ initWithUTF16String:

- (instancetype) initWithUTF16String: (const OFChar16 *) string

Initializes an already allocated OFString with a UTF-16 string.

Parameters

string A zero-terminated UTF-16 string

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-16-encoded

◆ initWithUTF16String:byteOrder:

- (instancetype) initWithUTF16String:		(const OFChar16 *)	string
byteOrder:		(OFByteOrder)	byteOrder

Initializes an already allocated OFString with a UTF-16 string, assuming the specified byte order if no byte order mark is found.

Parameters

string	A zero-terminated UTF-16 string
byteOrder	The byte order to assume if there is no byte order mark

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-16-encoded

◆ initWithUTF16String:length:

- (instancetype) initWithUTF16String:		(const OFChar16 *)	string
length:		(size_t)	length

Initializes an already allocated OFString with a UTF-16 string with the specified length.

Parameters

string	A zero-terminated UTF-16 string
length	The length of the UTF-16 string

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-16-encoded

◆ initWithUTF16String:length:byteOrder:

- (instancetype) initWithUTF16String:	(const OFChar16 *)	string
length:	(size_t)	length
byteOrder:	(OFByteOrder)	byteOrder

Initializes an already allocated OFString with a UTF-16 string with the specified length, assuming the specified byte order if no byte order mark is found.

Parameters

string	A zero-terminated UTF-16 string
length	The length of the UTF-16 string
byteOrder	The byte order to assume if there is no byte order mark

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-16-encoded

◆ initWithUTF32String:

- (instancetype) initWithUTF32String: (const OFChar32 *) string

Initializes an already allocated OFString with a UTF-32 string.

Parameters

string A zero-terminated UTF-32 string

Returns: An initialized OFString

◆ initWithUTF32String:byteOrder:

- (instancetype) initWithUTF32String:		(const OFChar32 *)	string
byteOrder:		(OFByteOrder)	byteOrder

Initializes an already allocated OFString with a UTF-32 string, assuming the specified byte order if no byte order mark is found.

Parameters

string	A zero-terminated UTF-32 string
byteOrder	The byte order to assume if there is no byte order mark

Returns: An initialized OFString

◆ initWithUTF32String:length:

- (instancetype) initWithUTF32String:		(const OFChar32 *)	string
length:		(size_t)	length

Initializes an already allocated OFString with a UTF-32 string with the specified length.

Parameters

string	A zero-terminated UTF-32 string
length	The length of the UTF-32 string

Returns: An initialized OFString

◆ initWithUTF32String:length:byteOrder:

- (instancetype) initWithUTF32String:	(const OFChar32 *)	string
length:	(size_t)	length
byteOrder:	(OFByteOrder)	byteOrder

Initializes an already allocated OFString with a UTF-32 string with the specified length, assuming the specified byte order if no byte order mark is found.

Parameters

string	A zero-terminated UTF-32 string
length	The length of the UTF-32 string
byteOrder	The byte order to assume if there is no byte order mark

Returns: An initialized OFString

◆ initWithUTF8String:

- (instancetype) initWithUTF8String: (const char *) UTF8String

Initializes an already allocated OFString from a UTF-8 encoded C string.

Parameters

UTF8String A UTF-8 encoded C string to initialize the OFString with

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ initWithUTF8String:length:

- (instancetype) initWithUTF8String:		(const char *)	UTF8String
length:		(size_t)	UTF8StringLength

Initializes an already allocated OFString from a UTF-8 encoded C string with the specified length.

Parameters

UTF8String	A UTF-8 encoded C string to initialize the OFString with
UTF8StringLength	The length of the UTF-8 encoded C string

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ initWithUTF8StringNoCopy:freeWhenDone:

- (instancetype) initWithUTF8StringNoCopy:		(char *)	UTF8String
freeWhenDone:		(bool)	freeWhenDone

Initializes an already allocated OFString from an UTF-8 encoded C string without copying the string, if possible.

If initialization fails for whatever reason, the passed C string is not freed if freeWhenDone is true.

Note: OFMutableString always creates a copy!

Parameters

UTF8String	A UTF-8 encoded C string to initialize the OFString with
freeWhenDone	Whether to free the C string when it is not needed anymore

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ initWithUTF8StringNoCopy:length:freeWhenDone:

- (instancetype) initWithUTF8StringNoCopy:	(char *)	UTF8String
length:	(size_t)	UTF8StringLength
freeWhenDone:	(bool)	freeWhenDone

Initializes an already allocated OFString from an UTF-8 encoded C string with the specified length without copying the string, if possible.

If initialization fails for whatever reason, the passed C string is not freed if freeWhenDone is true.

Note: OFMutableString always creates a copy!

Parameters

UTF8String	A UTF-8 encoded C string to initialize the OFString with
UTF8StringLength	The length of the UTF-8 encoded C string
freeWhenDone	Whether to free the C string when it is not needed anymore

Returns: An initialized OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ insecureCStringWithEncoding:

- (const char *) insecureCStringWithEncoding: (OFStringEncoding) encoding

Returns the OFString as an insecure C string (meaning it can contain \0) in the specified encoding.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

Parameters

encoding The encoding for the C string

Returns: The OFString as a C string in the specified encoding

◆ longLongValueWithBase:

- (long long) longLongValueWithBase: (unsigned char) base

The value of the string in the specified base as a long long.

Leading and trailing whitespaces are ignored.

If the string contains any non-number characters, an OFInvalidFormatException is thrown.

If the number is too big to fit into a long long, an OFOutOfRangeException is thrown.

Parameters

base	The base to use. If the base is 0, base 16 is assumed if the string starts with 0x (after stripping white spaces). If the string starts with 0, base 8 is assumed. Otherwise, base 10 is assumed.

Returns: The value of the string in the specified base

Exceptions

OFInvalidFormatException	The string cannot be parsed as a `long long`
OFOutOfRangeException	The value cannot be represented as a `long long`

◆ lossyCStringWithEncoding:

- (const char *) lossyCStringWithEncoding: (OFStringEncoding) encoding

Returns the OFString as a C string in the specified encoding, replacing characters that cannot be represented in the specified encoding with a question mark.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

Parameters

encoding The encoding for the C string

Returns: The OFString as a C string in the specified encoding

◆ objectByParsingJSONWithDepthLimit:

- (id) objectByParsingJSONWithDepthLimit: (size_t) depthLimit

Creates an object from the JSON value of the string.

Note: This also allows parsing JSON5, an extension of JSON. See http://json5.org/ for more details.

Warning: Although not specified by the JSON specification, this can also return primitives like strings and numbers. The rationale behind this is that most JSON parsers allow JSON data just consisting of a single primitive, leading to real world JSON files sometimes only consisting of a single primitive. Therefore, you should not make any assumptions about the object returned by this method if you don't want your program to terminate due to a message not understood, but instead check the returned object using isKindOfClass: (OFObject-p).

Parameters

depthLimit The maximum depth the parser should accept (defaults to 32 if not specified, 0 means no limit (insecure!))

Returns: An object

Exceptions

OFInvalidJSONException The string contained invalid JSON

◆ pathWithComponents:

+ (OFString *) pathWithComponents: (OFArray *) components

Creates a path from the specified path components.

Parameters

components An array of components for the path

Returns: A new autoreleased OFString

◆ rangeOfString:

- (OFRange) rangeOfString: (OFString *) string

Returns the range of the first occurrence of the string.

Parameters

string The string to search

Returns: The range of the first occurrence of the string or a range with OFNotFound as start position if it was not found

◆ rangeOfString:options:

- (OFRange) rangeOfString:		(OFString *)	string
options:		(OFStringSearchOptions)	options

Returns the range of the string.

Parameters

string	The string to search
options	Options modifying search behavior

Returns: The range of the first occurrence of the string or a range with OFNotFound as start position if it was not found

◆ rangeOfString:options:range:

- (OFRange) rangeOfString:	(OFString *)	string
options:	(OFStringSearchOptions)	options
range:	(OFRange)	range

Returns the range of the string in the specified range.

Parameters

string	The string to search
options	Options modifying search behaviour
range	The range in which to search

Returns: The range of the first occurrence of the string or a range with OFNotFound as start position if it was not found

◆ string

+ (instancetype) string

Creates a new OFString.

Returns: A new, autoreleased OFString

◆ stringByAddingPercentEncodingWithAllowedCharacters:

- (OFString *) stringByAddingPercentEncodingWithAllowedCharacters: (OFCharacterSet *) allowedCharacters

Percent-encodes a string for use in an IRI, but does not escape the specified allowed characters.

Parameters

allowedCharacters A character set of characters that should not be escaped

Returns: A new autoreleased string

◆ stringByAppendingFormat:

- (OFString *) stringByAppendingFormat:		(OFConstantString *)	format
,		(...)

Creates a new string by appending the specified format.

Parameters

format A format string which generates the string to append

Returns: A new, autoreleased OFString with the specified format appended

Exceptions

OFInvalidEncodingException	The string was not properly UTF-8-encoded after formatting it
OFInvalidFormatException	The specified format is invalid

◆ stringByAppendingFormat:arguments:

- (OFString *) stringByAppendingFormat:		(OFConstantString *)	format
arguments:		(va_list)	arguments

Creates a new string by appending the specified format.

Parameters

format	A format string which generates the string to append
arguments	The arguments used in the format string

Returns: A new, autoreleased OFString with the specified format appended

Exceptions

OFInvalidEncodingException	The string was not properly UTF-8-encoded after formatting it
OFInvalidFormatException	The specified format is invalid

◆ stringByAppendingPathComponent:

- (OFString *) stringByAppendingPathComponent: (OFString *) component

Creates a new string by appending a path component.

Parameters

component The path component to append

Returns: A new, autoreleased OFString with the path component appended

◆ stringByAppendingPathExtension:

- (OFString *) stringByAppendingPathExtension: (OFString *) extension

Creates a new string by appending a path extension.

Parameters

extension The extension to append

Returns: A new, autoreleased OFString with the path extension appended

◆ stringByAppendingString:

- (OFString *) stringByAppendingString: (OFString *) string

Creates a new string by appending another string.

Parameters

string The string to append

Returns: A new, autoreleased OFString with the specified string appended

◆ stringByReplacingOccurrencesOfString:withString:

- (OFString *) stringByReplacingOccurrencesOfString:		(OFString *)	string
withString:		(OFString *)	replacement

Creates a new string by replacing the occurrences of the specified string with the specified replacement.

Parameters

string	The string to replace
replacement	The string with which it should be replaced

Returns: A new string with the occurrences of the specified string replaced

◆ stringByReplacingOccurrencesOfString:withString:options:range:

- (OFString *) stringByReplacingOccurrencesOfString:	(OFString *)	string
withString:	(OFString *)	replacement
options:	(int)	options
range:	(OFRange)	range

Creates a new string by replacing the occurrences of the specified string in the specified range with the specified replacement.

Parameters

string	The string to replace
replacement	The string with which it should be replaced
options	Options modifying search behavior. Possible values are: None yet, pass 0
range	The range in which to replace the string

Returns: A new string with the occurrences of the specified string replaced

◆ stringByXMLUnescapingWithBlock:

- (OFString *) stringByXMLUnescapingWithBlock: (OFStringXMLUnescapingBlock) block

Unescapes XML in the string and uses the specified block for unknown entities.

Parameters

block A block which handles unknown entities

Exceptions

OFInvalidFormatException	The string is not a valid XML string
OFUnknownXMLEntityException	The string contains unknown XML entities

◆ stringByXMLUnescapingWithDelegate:

- (OFString *) stringByXMLUnescapingWithDelegate: (nullable id< OFStringXMLUnescapingDelegate >) delegate

Unescapes XML in the string and uses the specified delegate for unknown entities.

Parameters

delegate An OFXMLUnescapingDelegate as a handler for unknown entities

Exceptions

OFInvalidFormatException	The string is not a valid XML string
OFUnknownXMLEntityException	The string contains unknown XML entities

◆ stringWithCharacters:length:

+ (instancetype) stringWithCharacters:		(const OFUnichar *)	characters
length:		(size_t)	length

Creates a new OFString from a Unicode string with the specified length.

Parameters

characters	An array of Unicode characters
length	The length of the Unicode character array

Returns: A new autoreleased OFString

◆ stringWithContentsOfFile:

+ (instancetype) stringWithContentsOfFile: (OFString *) path

Creates a new OFString with the contents of the specified UTF-8 encoded file.

Parameters

path	The path to the file

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ stringWithContentsOfFile:encoding:

+ (instancetype) stringWithContentsOfFile:		(OFString *)	path
encoding:		(OFStringEncoding)	encoding

Creates a new OFString with the contents of the specified file in the specified encoding.

Parameters

path	The path to the file
encoding	The encoding of the file

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ stringWithContentsOfIRI:

+ (instancetype) stringWithContentsOfIRI: (OFIRI *) IRI

Creates a new OFString with the contents of the specified IRI.

If the IRI's scheme is file, it tries UTF-8 encoding.

If the IRI's scheme is http or https, it tries to detect the encoding from the HTTP headers. If it could not detect the encoding using the HTTP headers, it tries UTF-8.

Parameters

IRI	The IRI to the contents for the string

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not in the expected encoding

◆ stringWithContentsOfIRI:encoding:

+ (instancetype) stringWithContentsOfIRI:		(OFIRI *)	IRI
encoding:		(OFStringEncoding)	encoding

Creates a new OFString with the contents of the specified IRI in the specified encoding.

Parameters

IRI	The IRI to the contents for the string
encoding	The encoding to assume

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ stringWithCString:encoding:

+ (instancetype) stringWithCString:		(const char *)	cString
encoding:		(OFStringEncoding)	encoding

Creates a new OFString from a C string with the specified encoding.

Parameters

cString	A C string to initialize the OFString with
encoding	The encoding of the C string

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ stringWithCString:encoding:length:

+ (instancetype) stringWithCString:	(const char *)	cString
encoding:	(OFStringEncoding)	encoding
length:	(size_t)	cStringLength

Creates a new OFString from a C string with the specified encoding and length.

Parameters

cString	A C string to initialize the OFString with
encoding	The encoding of the C string
cStringLength	The length of the C string

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ stringWithData:encoding:

+ (instancetype) stringWithData:		(OFData *)	data
encoding:		(OFStringEncoding)	encoding

Creates a new OFString from OFData with the specified encoding.

Parameters

data	OFData with the contents of the string
encoding	The encoding in which the string is stored in the OFData

Returns: An new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not in the specified encoding

◆ stringWithFormat:

+ (instancetype) stringWithFormat:		(OFConstantString *)	format
,		(...)

Creates a new OFString from a format string.

See printf for the format syntax. As an addition, %@ is available as format specifier for objects, C for OFUnichar and S for const OFUnichar *.

Parameters

format A string used as format to initialize the OFString

Returns: A new autoreleased OFString

Exceptions

OFInvalidFormatException	The specified format is invalid
OFInvalidEncodingException	The resulting string is not in not in UTF-8 encoding

◆ stringWithString:

+ (instancetype) stringWithString: (OFString *) string

Creates a new OFString from another string.

Parameters

string A string to initialize the OFString with

Returns: A new autoreleased OFString

◆ stringWithUTF16String:

+ (instancetype) stringWithUTF16String: (const OFChar16 *) string

Creates a new OFString from a UTF-16 encoded string.

Parameters

string A zero-terminated UTF-16 string

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-16-encoded

◆ stringWithUTF16String:byteOrder:

+ (instancetype) stringWithUTF16String:		(const OFChar16 *)	string
byteOrder:		(OFByteOrder)	byteOrder

Creates a new OFString from a UTF-16 encoded string, assuming the specified byte order if no byte order mark is found.

Parameters

string	A zero-terminated UTF-16 string
byteOrder	The byte order to assume if there is no byte order mark

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-16-encoded

◆ stringWithUTF16String:length:

+ (instancetype) stringWithUTF16String:		(const OFChar16 *)	string
length:		(size_t)	length

Creates a new OFString from a UTF-16 encoded string with the specified length.

Parameters

string	A zero-terminated UTF-16 string
length	The length of the UTF-16 string

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-16-encoded

◆ stringWithUTF16String:length:byteOrder:

+ (instancetype) stringWithUTF16String:	(const OFChar16 *)	string
length:	(size_t)	length
byteOrder:	(OFByteOrder)	byteOrder

Creates a new OFString from a UTF-16 encoded string with the specified length, assuming the specified byte order if no byte order mark is found.

Parameters

string	A zero-terminated UTF-16 string
length	The length of the UTF-16 string
byteOrder	The byte order to assume if there is no byte order mark

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-16-encoded

◆ stringWithUTF32String:

+ (instancetype) stringWithUTF32String: (const OFChar32 *) string

Creates a new OFString from a UTF-32 encoded string.

Parameters

string A zero-terminated UTF-32 string

Returns: A new autoreleased OFString

◆ stringWithUTF32String:byteOrder:

+ (instancetype) stringWithUTF32String:		(const OFChar32 *)	string
byteOrder:		(OFByteOrder)	byteOrder

Creates a new OFString from a UTF-32 encoded string, assuming the specified byte order if no byte order mark is found.

Parameters

string	A zero-terminated UTF-32 string
byteOrder	The byte order to assume if there is no byte order mark

Returns: A new autoreleased OFString

◆ stringWithUTF32String:length:

+ (instancetype) stringWithUTF32String:		(const OFChar32 *)	string
length:		(size_t)	length

Creates a new OFString from a UTF-32 encoded string with the specified length.

Parameters

string	A zero-terminated UTF-32 string
length	The length of the UTF-32 string

Returns: A new autoreleased OFString

◆ stringWithUTF32String:length:byteOrder:

+ (instancetype) stringWithUTF32String:	(const OFChar32 *)	string
length:	(size_t)	length
byteOrder:	(OFByteOrder)	byteOrder

Creates a new OFString from a UTF-32 encoded string with the specified length, assuming the specified byte order if no byte order mark is found.

Parameters

string	A zero-terminated UTF-32 string
length	The length of the UTF-32 string
byteOrder	The byte order to assume if there is no byte order mark

Returns: A new autoreleased OFString

◆ stringWithUTF8String:

+ (instancetype) stringWithUTF8String: (const char *) UTF8String

Creates a new OFString from a UTF-8 encoded C string.

Parameters

UTF8String A UTF-8 encoded C string to initialize the OFString with

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ stringWithUTF8String:length:

+ (instancetype) stringWithUTF8String:		(const char *)	UTF8String
length:		(size_t)	UTF8StringLength

Creates a new OFString from a UTF-8 encoded C string with the specified length.

Parameters

UTF8String	A UTF-8 encoded C string to initialize the OFString with
UTF8StringLength	The length of the UTF-8 encoded C string

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ stringWithUTF8StringNoCopy:freeWhenDone:

+ (instancetype) stringWithUTF8StringNoCopy:		(char *)	UTF8String
freeWhenDone:		(bool)	freeWhenDone

Creates a new OFString from a UTF-8 encoded C string without copying the string, if possible.

If initialization fails for whatever reason, the passed C string is not freed if freeWhenDone is true.

Note: OFMutableString always creates a copy!

Parameters

UTF8String	A UTF-8 encoded C string to initialize the OFString with
freeWhenDone	Whether to free the C string when the OFString gets deallocated

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ stringWithUTF8StringNoCopy:length:freeWhenDone:

+ (instancetype) stringWithUTF8StringNoCopy:	(char *)	UTF8String
length:	(size_t)	UTF8StringLength
freeWhenDone:	(bool)	freeWhenDone

Creates a new OFString from a UTF-8 encoded C string with the specified length without copying the string, if possible.

If initialization fails for whatever reason, the passed C string is not freed if freeWhenDone is true.

Note: OFMutableString always creates a copy!

Parameters

UTF8String	A UTF-8 encoded C string to initialize the OFString with
UTF8StringLength	The length of the UTF-8 encoded C string
freeWhenDone	Whether to free the C string when the OFString gets deallocated

Returns: A new autoreleased OFString

Exceptions

OFInvalidEncodingException The string is not properly UTF-8-encoded

◆ substringFromIndex:

- (OFString *) substringFromIndex: (size_t) idx

Creates a substring from the specified index to the end.

Parameters

idx	The index from where the substring should start, inclusive

Returns: The substring from the specified index to the end

◆ substringToIndex:

- (OFString *) substringToIndex: (size_t) idx

Creates a substring from the beginning to the specified index.

Parameters

idx	The index at which the substring should end, exclusive

Returns: The substring from the beginning to the specified index

◆ substringWithRange:

- (OFString *) substringWithRange: (OFRange) range

Creates a substring with the specified range.

Parameters

range The range of the substring

Returns: The substring as a new autoreleased OFString

◆ unsignedLongLongValueWithBase:

- (unsigned long long) unsignedLongLongValueWithBase: (unsigned char) base

The value of the string in the specified base as an unsigned long long.

Leading and trailing whitespaces are ignored.

If the string contains any non-number characters, an OFInvalidFormatException is thrown.

If the number is too big to fit into an unsigned long long, an OFOutOfRangeException is thrown.

Parameters

base	The base to use. If the base is 0, base 16 is assumed if the string starts with 0x (after stripping white spaces). If the string starts with 0, base 8 is assumed. Otherwise, base 10 is assumed.

Returns: The value of the string in the specified base

Exceptions

OFInvalidFormatException	The string cannot be parsed as an `unsigned long long`
OFOutOfRangeException	The value cannot be represented as an `unsigned long long`

◆ UTF16StringWithByteOrder:

- (const OFChar16 *) UTF16StringWithByteOrder: (OFByteOrder) byteOrder

Returns the string in UTF-16 encoding with the specified byte order.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

The returned string is null-terminated.

Parameters

byteOrder The byte order for the UTF-16 encoding

Returns: The string in UTF-16 encoding with the specified byte order

Exceptions

OFInvalidEncodingException The string cannot be represented in UTF-16

◆ UTF32StringWithByteOrder:

- (const OFChar32 *) UTF32StringWithByteOrder: (OFByteOrder) byteOrder

Returns the string in UTF-32 encoding with the specified byte order.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

The returned string is null-terminated.

Parameters

byteOrder The byte order for the UTF-32 encoding

Returns: The string in UTF-32 encoding with the specified byte order

◆ writeToFile:

- (void) writeToFile: (OFString *) path

Writes the string into the specified file using UTF-8 encoding.

Parameters

path	The path of the file to write to

◆ writeToFile:encoding:

- (void) writeToFile:		(OFString *)	path
encoding:		(OFStringEncoding)	encoding

Writes the string into the specified file using the specified encoding.

Parameters

path	The path of the file to write to
encoding	The encoding to use to write the string into the file

Exceptions

OFInvalidEncodingException The string cannot be represented in the specified encoding

◆ writeToIRI:

- (void) writeToIRI: (OFIRI *) IRI

Writes the string to the specified IRI using UTF-8 encoding.

Parameters

IRI	The IRI to write to

◆ writeToIRI:encoding:

- (void) writeToIRI:		(OFIRI *)	IRI
encoding:		(OFStringEncoding)	encoding

Writes the string to the specified IRI using the specified encoding.

Parameters

IRI	The IRI to write to
encoding	The encoding to use to write the string to the IRI

Exceptions

OFInvalidEncodingException The string cannot be represented in the specified encoding

Property Documentation

◆ capitalizedString

- (OFString *) capitalizedString

readnonatomicassign

The string in capitalized form.

Note: This only considers spaces, tabs and newlines to be word delimiters! Also note that this might change in the future to all word delimiters specified by Unicode!

◆ characters

- (const OFUnichar *) characters

readnonatomicassign

The string as an array of Unicode characters.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

The returned string is not null-terminated.

◆ doubleValue

- (double) doubleValue

readnonatomicassign

The double value of the string as a double.

Exceptions

OFInvalidFormatException	The string cannot be parsed as a `double`
OFOutOfRangeException	The value cannot be represented as a `double`

◆ floatValue

- (float) floatValue

readnonatomicassign

The float value of the string as a float.

Exceptions

OFInvalidFormatException	The string cannot be parsed as a `float`
OFOutOfRangeException	The value cannot be represented as a `float`

◆ longLongValue

- (long long) longLongValue

readnonatomicassign

The decimal value of the string as a long long.

Leading and trailing whitespaces are ignored.

If the string contains any non-number characters, an OFInvalidFormatException is thrown.

If the number is too big to fit into a long long, an OFOutOfRangeException is thrown.

◆ objectByParsingJSON

- (id) objectByParsingJSON

readnonatomicassign

The string interpreted as JSON and parsed as an object.

Note: This also allows parsing JSON5, an extension of JSON. See http://json5.org/ for more details.

Warning: Although not specified by the JSON specification, this can also return primitives like strings and numbers. The rationale behind this is that most JSON parsers allow JSON data just consisting of a single primitive, leading to real world JSON files sometimes only consisting of a single primitive. Therefore, you should not make any assumptions about the object returned by this method if you don't want your program to terminate due to a message not understood, but instead check the returned object using isKindOfClass: (OFObject-p).

Exceptions

OFInvalidJSONException The string contained invalid JSON

◆ objectByParsingPropertyList

- (id) objectByParsingPropertyList

readnonatomicassign

The string interpreted as a property list and parsed as an object.

Note: This only supports XML property lists!

Exceptions

OFInvalidFormatException	The string is not in correct XML property list format
OFUnsupportedVersionException	The property list is using a version that is not supported

◆ stringByRemovingPercentEncoding

- (OFString *) stringByRemovingPercentEncoding

readnonatomicassign

The string with percent encoding removed.

Exceptions

OFInvalidFormatException The string is not in proper percent encoding

◆ unsignedLongLongValue

- (unsigned long long) unsignedLongLongValue

readnonatomicassign

The decimal value of the string as an unsigned long long.

Leading and trailing whitespaces are ignored.

If the string contains any non-number characters, an OFInvalidFormatException is thrown.

If the number is too big to fit into an unsigned long long, an OFOutOfRangeException is thrown.

◆ UTF16String

- (const OFChar16 *) UTF16String

readnonatomicassign

The string in UTF-16 encoding with native byte order.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

The returned string is null-terminated.

◆ UTF32String

- (const OFChar32 *) UTF32String

readnonatomicassign

The string in UTF-32 encoding with native byte order.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

The returned string is null-terminated.

◆ UTF8String

- (const char *) UTF8String

readnonatomicassign

The OFString as a UTF-8 encoded C string.

The result is valid until the autorelease pool is released. If you want to use the result outside the scope of the current autorelease pool, you have to copy it.

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

src/OFString.h
src/OFString.m

Instance Methods

Class Methods

Properties

Detailed Description

Method Documentation

◆ caseInsensitiveCompare:

◆ characterAtIndex:

◆ compare:

◆ componentsSeparatedByCharactersInSet:

◆ componentsSeparatedByCharactersInSet:options:

◆ componentsSeparatedByString:

◆ componentsSeparatedByString:options:

◆ containsString:

◆ cStringLengthWithEncoding:

◆ cStringWithEncoding:

◆ dataWithEncoding:

◆ enumerateLinesUsingBlock:

◆ getCharacters:inRange:

◆ getCString:maxLength:encoding:

◆ getLossyCString:maxLength:encoding:

◆ hasPrefix:

◆ hasSuffix:

◆ indexOfCharacterFromSet:

◆ indexOfCharacterFromSet:options:

◆ indexOfCharacterFromSet:options:range:

◆ init

◆ initWithCharacters:length:

◆ initWithContentsOfFile:

◆ initWithContentsOfFile:encoding:

◆ initWithContentsOfIRI:

◆ initWithContentsOfIRI:encoding:

◆ initWithCString:encoding:

◆ initWithCString:encoding:length:

◆ initWithData:encoding:

◆ initWithFormat:

◆ initWithFormat:arguments:

◆ initWithString:

◆ initWithUTF16String:

◆ initWithUTF16String:byteOrder:

◆ initWithUTF16String:length:

◆ initWithUTF16String:length:byteOrder:

◆ initWithUTF32String:

◆ initWithUTF32String:byteOrder:

◆ initWithUTF32String:length:

◆ initWithUTF32String:length:byteOrder:

◆ initWithUTF8String:

◆ initWithUTF8String:length:

◆ initWithUTF8StringNoCopy:freeWhenDone:

◆ initWithUTF8StringNoCopy:length:freeWhenDone:

◆ insecureCStringWithEncoding:

◆ longLongValueWithBase:

◆ lossyCStringWithEncoding:

◆ objectByParsingJSONWithDepthLimit:

◆ pathWithComponents:

◆ rangeOfString:

◆ rangeOfString:options:

◆ rangeOfString:options:range:

◆ string

◆ stringByAddingPercentEncodingWithAllowedCharacters:

◆ stringByAppendingFormat:

◆ stringByAppendingFormat:arguments:

◆ stringByAppendingPathComponent:

◆ stringByAppendingPathExtension:

◆ stringByAppendingString:

◆ stringByReplacingOccurrencesOfString:withString:

◆ stringByReplacingOccurrencesOfString:withString:options:range:

◆ stringByXMLUnescapingWithBlock:

◆ stringByXMLUnescapingWithDelegate:

◆ stringWithCharacters:length:

◆ stringWithContentsOfFile:

◆ stringWithContentsOfFile:encoding:

◆ stringWithContentsOfIRI:

◆ stringWithContentsOfIRI:encoding:

◆ stringWithCString:encoding:

◆ stringWithCString:encoding:length:

◆ stringWithData:encoding:

◆ stringWithFormat:

◆ stringWithString:

◆ stringWithUTF16String:

◆ stringWithUTF16String:byteOrder: