ObjFW  Diff

/*!
 * @class OFString OFString.h ObjFW/OFString.h
 *
 * @brief A class for handling strings.
 */
@interface OFString: OFObject <OFCopying, OFMutableCopying, OFComparing,
    OFSerialization, OFJSONRepresentation, OFMessagePackRepresentation>



































































































































































































/*!
 * @brief Creates a new OFString.
 *
 * @return A new, autoreleased OFString
 */
+ (instancetype)string;

 *
 * @param encoding The encoding for the C string
 * @return The OFString as a C string in the specified encoding
 */
- (const char *)lossyCStringWithEncoding: (of_string_encoding_t)encoding
    OF_RETURNS_INNER_POINTER;

/*!
 * @brief Returns 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.
 *
 * @return The OFString as a UTF-8 encoded C string
 */
- (const char *)UTF8String OF_RETURNS_INNER_POINTER;

/*!
 * @brief Returns the length of the string in Unicode codepoints.
 *
 * @return The length of the string in Unicode codepoints
 */
- (size_t)length;

/*!
 * @brief Returns the number of bytes the string needs in the specified
 *	  encoding.
 *
 * @param encoding The encoding for the string
 * @return The number of bytes the string needs in the specified encoding.
 */
- (size_t)cStringLengthWithEncoding: (of_string_encoding_t)encoding;

/*!
 * @brief Returns the number of bytes the string needs in UTF-8 encoding.
 *
 * @return The number of bytes the string needs in UTF-8 encoding.
 */
- (size_t)UTF8StringLength;

/*!
 * @brief Compares the OFString to another OFString without caring about the
 *	  case.
 *
 * @param otherString A string to compare with
 * @return An of_comparison_result_t
 */

 * @return A new string with the occurrences of the specified string replaced
 */
- (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
					withString: (OFString *)replacement
					   options: (int)options
					     range: (of_range_t)range;

/*!
 * @brief Returns the string in uppercase.
 *
 * @return The string in uppercase
 */
- (OFString *)uppercaseString;

/*!
 * @brief Returns the string in lowercase.
 *
 * @return The string in lowercase
 */
- (OFString *)lowercaseString;

/*!
 * @brief Returns the string capitalized.
 *
 * @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!
 *
 * @return The capitalized string
 */
- (OFString *)capitalizedString;

/*!
 * @brief Creates a new string by deleting leading whitespaces.
 *
 * @return A new autoreleased OFString with leading whitespaces deleted
 */
- (OFString *)stringByDeletingLeadingWhitespaces;

/*!
 * @brief Creates a new string by deleting trailing whitespaces.
 *
 * @return A new autoreleased OFString with trailing whitespaces deleted
 */
- (OFString *)stringByDeletingTrailingWhitespaces;

/*!
 * @brief Creates a new string by deleting leading and trailing whitespaces.
 *
 * @return A new autoreleased OFString with leading and trailing whitespaces
 *	   deleted
 */
- (OFString *)stringByDeletingEnclosingWhitespaces;

/*!
 * @brief Checks whether the string has the specified prefix.
 *
 * @param prefix The prefix to check for
 * @return A boolean whether the string has the specified prefix
 */
- (bool)hasPrefix: (OFString *)prefix;

 * 		  `OF_STRING_SKIP_EMPTY` | Skip empty components
 * @return An autoreleased OFArray with the separated string
 */
- (OFArray OF_GENERIC(OFString *) *)
    componentsSeparatedByString: (OFString *)delimiter
			options: (int)options;

/*!
 * @brief Returns the components of the path.
 *
 * @return The components of the path
 */
- (OFArray OF_GENERIC(OFString *) *)pathComponents;

/*!
 * @brief Returns the last component of the path.
 *
 * @return The last component of the path
 */
- (OFString *)lastPathComponent;

/*!
 * @brief Returns the file extension of the path.
 *
 * @return The file extension of the path
 */
- (OFString *)pathExtension;

/*!
 * @brief Returns the directory name of the path.
 *
 * @return The directory name of the path
 */
- (OFString *)stringByDeletingLastPathComponent;

/*!
 * @brief Returns a new string with the file extension of the path removed.
 *
 * @return A new string with the file extension of the path removed
 */
- (OFString *)stringByDeletingPathExtension;

/*!
 * @brief Returns the path with relative sub paths resolved.
 *
 * @return The path with relative sub paths resolved
 */
- (OFString *)stringByStandardizingPath;

/*!
 * @brief Returns the URL path with relative sub paths resolved.
 *
 * This works similar to @ref stringByStandardizingPath, but is intended for
 * standardization of paths that are part of a URL.
 *
 * @return The URL path with relative sub paths resolved
 */
- (OFString *)stringByStandardizingURLPath;

/*!
 * @brief Returns the decimal value of the string as an `intmax_t`.
 *
 * Leading and trailing whitespaces are ignored.
 *
 * If the string contains any non-number characters, an
 * @ref OFInvalidEncodingException is thrown.
 *
 * If the number is too big to fit into an `intmax_t`, an
 * @ref OFOutOfRangeException is thrown.
 *
 * @return An `intmax_t` with the value of the string
 */
- (intmax_t)decimalValue;

/*!
 * @brief Returns the hexadecimal value of the string as an `uintmax_t`.
 *
 * Leading and trailing whitespaces are ignored.
 *
 * If the string contains any non-number characters, an
 * @ref OFInvalidEncodingException is thrown.
 *
 * If the number is too big to fit into an `uintmax_t`, an
 * @ref OFOutOfRangeException is thrown.
 *
 * @return A `uintmax_t` with the value of the string
 */
- (uintmax_t)hexadecimalValue;

/*!
 * @brief Returns the octal value of the string as an `uintmax_t`.
 *
 * Leading and trailing whitespaces are ignored.
 *
 * If the string contains any non-number characters, an
 * @ref OFInvalidEncodingException is thrown.
 *
 * If the number is too big to fit into an `uintmax_t`, an
 * @ref OFOutOfRangeException is thrown.
 *
 * @return A `uintmax_t` with the value of the string
 */
- (uintmax_t)octalValue;

/*!
 * @brief Returns the float value of the string as a float.
 *
 * If the string contains any non-number characters, an
 * OFInvalidEncodingException is thrown.
 *
 * @return A float with the value of the string
 */
- (float)floatValue;

/*!
 * @brief Returns the double value of the string as a double.
 *
 * If the string contains any non-number characters, an
 * OFInvalidEncodingException is thrown.
 *
 * @return A double with the value of the string
 */
- (double)doubleValue;

/*!
 * @brief Returns 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.
 *
 * @return The string as an array of Unicode characters
 */
- (const of_unichar_t *)characters OF_RETURNS_INNER_POINTER;

/*!
 * @brief Returns 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.
 *
 * @return The string in UTF-16 encoding with native byte order
 */
- (const char16_t *)UTF16String OF_RETURNS_INNER_POINTER;

/*!
 * @brief 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.
 *
 * @param byteOrder The byte order for the UTF-16 encoding
 * @return The string in UTF-16 encoding with the specified byte order
 */
- (const char16_t *)UTF16StringWithByteOrder: (of_byte_order_t)byteOrder
    OF_RETURNS_INNER_POINTER;

/*!
 * @brief Returns the length of the string in UTF-16 characters.
 *
 * @return The length of string in UTF-16 characters
 */
- (size_t)UTF16StringLength;

/*!
 * @brief Returns 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.
 *
 * @return The string in UTF-32 encoding with native byte order
 */
- (const char32_t *)UTF32String OF_RETURNS_INNER_POINTER;

/*!
 * @brief 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.
 *

 * @brief Returns the string as OFData with the specified encoding.
 *
 * @param encoding The encoding to use for the returned OFData
 * @return The string as OFData with the specified encoding
 */
- (OFData *)dataWithEncoding: (of_string_encoding_t)encoding;

#ifdef OF_HAVE_UNICODE_TABLES
/*!
 * @brief Returns the string in Unicode Normalization Form D (NFD).
 *
 * @return The string in Unicode Normalization Form D (NFD)
 */
- (OFString *)decomposedStringWithCanonicalMapping;

/*!
 * @brief Returns the string in Unicode Normalization Form KD (NFKD).
 *
 * @return The string in Unicode Normalization Form KD (NFKD)
 */
- (OFString *)decomposedStringWithCompatibilityMapping;
#endif

#ifdef OF_HAVE_FILES
/*!
 * @brief Writes the string into the specified file using UTF-8 encoding.
 *
 * @param path The path of the file to write to
 */
- (void)writeToFile: (OFString *)path;