OFString.h

Go to the documentation of this file.

/*
 * Copyright (c) 2008-2026 Jonathan Schleifer <js@nil.im>
 *
 * All rights reserved.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 3.0 only,
 * as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * version 3.0 for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3.0 along with this program. If not, see
 * <https://www.gnu.org/licenses/>.
 */

#ifndef __STDC_LIMIT_MACROS
# define __STDC_LIMIT_MACROS
#endif
#ifndef __STDC_CONSTANT_MACROS
# define __STDC_CONSTANT_MACROS
#endif

#include "objfw-defs.h"

#ifdef OF_HAVE_SYS_TYPES_H
# include <sys/types.h>
#endif

#include <stdarg.h>
#include <stdint.h>
#ifdef OF_HAVE_INTTYPES_H
# include <inttypes.h>
#endif

#import "OFObject.h"
#import "OFJSONRepresentation.h"
#import "OFMessagePackRepresentation.h"

OF_ASSUME_NONNULL_BEGIN

@class OFArray OF_GENERIC(ObjectType);
@class OFCharacterSet;
@class OFConstantString;
@class OFIRI;
@class OFString;

#if defined(__cplusplus) && __cplusplus >= 201103L
typedef char16_t OFChar16;
typedef char32_t OFChar32;
#else
typedef uint_least16_t OFChar16;
typedef uint_least32_t OFChar32;
#endif
typedef OFChar32 OFUnichar;

typedef enum {
    /*
     * UTF-8 *has* to be 0, so that if the current @ref OFLocale is
     * `nil`, `[OFLocale encoding]` returns UTF-8.
     */
    OFStringEncodingUTF8,
    OFStringEncodingASCII,
    OFStringEncodingISO8859_1,
    OFStringEncodingISO8859_2,
    OFStringEncodingISO8859_3,
    OFStringEncodingISO8859_15,
    OFStringEncodingWindows1251,
    OFStringEncodingWindows1252,
    OFStringEncodingCodepage437,
    OFStringEncodingCodepage850,
    OFStringEncodingCodepage858,
    OFStringEncodingMacRoman,
    OFStringEncodingKOI8R,
    OFStringEncodingKOI8U,
    OFStringEncodingWindows1250,
    OFStringEncodingCodepage852,
    OFStringEncodingAutodetect = -1
} OFStringEncoding;

typedef enum {
    OFStringSearchBackwards = 1
} OFStringSearchOptions;

typedef enum {
    OFStringSkipEmptyComponents = 1
} OFStringSeparationOptions;

#ifdef OF_HAVE_BLOCKS

typedef void (^OFStringLineEnumerationBlock)(OFString *line, bool *stop);
#endif

@interface OFString: OFObject <OFCopying, OFMutableCopying, OFComparing,
    OFJSONRepresentation, OFMessagePackRepresentation>
@property (readonly, nonatomic) size_t length;

@property (readonly, nonatomic) const char *UTF8String OF_RETURNS_INNER_POINTER;

@property (readonly, nonatomic) size_t UTF8StringLength;

@property (readonly, nonatomic) OFString *uppercaseString;

@property (readonly, nonatomic) OFString *lowercaseString;

@property (readonly, nonatomic) OFString *capitalizedString;

@property (readonly, nonatomic) signed char charValue;

@property (readonly, nonatomic) short shortValue;

@property (readonly, nonatomic) int intValue;

@property (readonly, nonatomic) long longValue;

@property (readonly, nonatomic) long long longLongValue;

@property (readonly, nonatomic) unsigned char unsignedCharValue;

@property (readonly, nonatomic) unsigned short unsignedShortValue;

@property (readonly, nonatomic) unsigned int unsignedIntValue;

@property (readonly, nonatomic) unsigned long unsignedLongValue;

@property (readonly, nonatomic) unsigned long long unsignedLongLongValue;

@property (readonly, nonatomic) float floatValue;

@property (readonly, nonatomic) double doubleValue;

@property (readonly, nonatomic) const OFUnichar *characters
    OF_RETURNS_INNER_POINTER;

@property (readonly, nonatomic) const OFChar16 *UTF16String
    OF_RETURNS_INNER_POINTER;

@property (readonly, nonatomic) size_t UTF16StringLength;

@property (readonly, nonatomic) const OFChar32 *UTF32String
    OF_RETURNS_INNER_POINTER;

@property (readonly, nonatomic) OFString *stringByDeletingLeadingWhitespaces;

@property (readonly, nonatomic) OFString *stringByDeletingTrailingWhitespaces;

@property (readonly, nonatomic) OFString *stringByDeletingEnclosingWhitespaces;

@property (readonly, nonatomic) OFString *stringByReplacingControlCharacters;

#if defined(OF_WINDOWS) || defined(DOXYGEN)

@property (readonly, nonatomic)
    OFString *stringByExpandingWindowsEnvironmentStrings;
#endif

+ (instancetype)string;

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

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

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

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

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

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

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

+ (instancetype)stringWithString: (OFString *)string;

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

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

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

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

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

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

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

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

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

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

#ifdef OF_HAVE_FILES

+ (instancetype)stringWithContentsOfFile: (OFString *)path;

+ (instancetype)stringWithContentsOfFile: (OFString *)path
                encoding: (OFStringEncoding)encoding;
#endif

+ (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI;

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

- (instancetype)init OF_DESIGNATED_INITIALIZER;

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

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

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

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

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

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

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

- (instancetype)initWithString: (OFString *)string;

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

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

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

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

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

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

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

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

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

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

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

#ifdef OF_HAVE_FILES

- (instancetype)initWithContentsOfFile: (OFString *)path;

- (instancetype)initWithContentsOfFile: (OFString *)path
                  encoding: (OFStringEncoding)encoding;
#endif

- (instancetype)initWithContentsOfIRI: (OFIRI *)IRI;

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

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

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

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

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

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

- (size_t)cStringLengthWithEncoding: (OFStringEncoding)encoding;

- (OFComparisonResult)compare: (OFString *)string;

- (OFComparisonResult)caseInsensitiveCompare: (OFString *)string;

- (OFUnichar)characterAtIndex: (size_t)index;

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

- (OFRange)rangeOfString: (OFString *)string;

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

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

- (OFRange)rangeOfCharacterFromSet: (OFCharacterSet *)characterSet;

- (OFRange)rangeOfCharacterFromSet: (OFCharacterSet *)characterSet
               options: (OFStringSearchOptions)options;

- (OFRange)rangeOfCharacterFromSet: (OFCharacterSet *)characterSet
               options: (OFStringSearchOptions)options
                 range: (OFRange)range;

- (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
    OF_DEPRECATED(ObjFW, 1, 3, "Use -[rangeOfCharacterFromSet:] instead");

- (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
              options: (OFStringSearchOptions)options
    OF_DEPRECATED(ObjFW, 1, 3,
    "Use -[rangeOfCharacterFromSet:options:] instead");

- (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
              options: (OFStringSearchOptions)options
                range: (OFRange)range
    OF_DEPRECATED(ObjFW, 1, 3,
    "Use -[rangeOfCharacterFromSet:options:range:] instead");

- (bool)containsString: (OFString *)string;

- (OFString *)substringFromIndex: (size_t)idx;

- (OFString *)substringToIndex: (size_t)idx;

- (OFString *)substringWithRange: (OFRange)range;

- (signed char)charValueWithBase: (unsigned char)base;

- (short)shortValueWithBase: (unsigned char)base;

- (int)intValueWithBase: (unsigned char)base;

- (long)longValueWithBase: (unsigned char)base;

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

- (unsigned char)unsignedCharValueWithBase: (unsigned char)base;

- (unsigned short)unsignedShortValueWithBase: (unsigned char)base;

- (unsigned int)unsignedIntValueWithBase: (unsigned char)base;

- (unsigned long)unsignedLongValueWithBase: (unsigned char)base;

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

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

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

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

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

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

- (bool)hasPrefix: (OFString *)prefix;

- (bool)hasSuffix: (OFString *)suffix;

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

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

- (OFArray OF_GENERIC(OFString *) *)
    componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet;

- (OFArray OF_GENERIC(OFString *) *)
    componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet
                 options: (OFStringSeparationOptions)options;

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

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

- (OFData *)dataWithEncoding: (OFStringEncoding)encoding;

#ifdef OF_HAVE_FILES

- (void)writeToFile: (OFString *)path;

- (void)writeToFile: (OFString *)path encoding: (OFStringEncoding)encoding;
#endif

- (void)writeToIRI: (OFIRI *)IRI;

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

#ifdef OF_HAVE_BLOCKS

- (void)enumerateLinesUsingBlock: (OFStringLineEnumerationBlock)block;
#endif
@end

#ifdef __cplusplus
extern "C" {
#endif

extern OFStringEncoding OFStringEncodingParseName(OFString *name);

extern OFString *_Nullable OFStringEncodingName(OFStringEncoding encoding);

extern size_t OFUTF16StringLength(const OFChar16 *string);

extern size_t OFUTF32StringLength(const OFChar32 *string);
#ifdef __cplusplus
}
#endif

OF_ASSUME_NONNULL_END

#import "OFConstantString.h"
#import "OFMutableString.h"
#import "OFString+CryptographicHashing.h"
#import "OFString+JSONParsing.h"
#ifdef OF_HAVE_FILES
# import "OFString+PathAdditions.h"
#endif
#import "OFString+PercentEncoding.h"
#import "OFString+PropertyListParsing.h"
#import "OFString+XMLEscaping.h"
#import "OFString+XMLUnescaping.h"

#if !defined(NSINTEGER_DEFINED) && !__has_feature(objc_modules)
/*
 * Very *ugly* hack required for string boxing literals to work.
 *
 * This hack is needed in order to work with `@class NSString` from Apple's
 * objc/NSString.h - which is included when using modules - as
 * @compatibility_alias does not work if @class has been used before.
 * For some reason, this makes Clang refer to OFString for string box literals
 * and not to NSString (which would result in a linker error, but would be the
 * correct behavior).
 *
 * TODO: Submit a patch for Clang that makes the boxing classes configurable!
 */
@interface NSString: OFString
@end
#endif