ObjFW
Loading...
Searching...
No Matches
OFString.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008-2024 Jonathan Schleifer <js@nil.im>
3 *
4 * All rights reserved.
5 *
6 * This file is part of ObjFW. It may be distributed under the terms of the
7 * Q Public License 1.0, which can be found in the file LICENSE.QPL included in
8 * the packaging of this file.
9 *
10 * Alternatively, it may be distributed under the terms of the GNU General
11 * Public License, either version 2 or 3, which can be found in the file
12 * LICENSE.GPLv2 or LICENSE.GPLv3 respectively included in the packaging of this
13 * file.
14 */
15
16#ifndef __STDC_LIMIT_MACROS
17# define __STDC_LIMIT_MACROS
18#endif
19#ifndef __STDC_CONSTANT_MACROS
20# define __STDC_CONSTANT_MACROS
21#endif
22
23#include "objfw-defs.h"
24
25#ifdef OF_HAVE_SYS_TYPES_H
26# include <sys/types.h>
27#endif
28
29#include <stdarg.h>
30#include <stdint.h>
31#ifdef OF_HAVE_INTTYPES_H
32# include <inttypes.h>
33#endif
34
35#import "OFObject.h"
36#import "OFJSONRepresentation.h"
37#import "OFMessagePackRepresentation.h"
38
39OF_ASSUME_NONNULL_BEGIN
40
43@class OFArray OF_GENERIC(ObjectType);
44@class OFCharacterSet;
45@class OFConstantString;
46@class OFIRI;
47@class OFString;
48
49#if defined(__cplusplus) && __cplusplus >= 201103L
50typedef char16_t OFChar16;
51typedef char32_t OFChar32;
52#else
53typedef uint_least16_t OFChar16;
54typedef uint_least32_t OFChar32;
55#endif
56typedef OFChar32 OFUnichar;
57
97
107
117
118#ifdef OF_HAVE_BLOCKS
126typedef void (^OFStringLineEnumerationBlock)(OFString *line, bool *stop);
127#endif
128
139@property (readonly, nonatomic) size_t length;
140
148@property (readonly, nonatomic) const char *UTF8String;
149
153@property (readonly, nonatomic) size_t UTF8StringLength;
154
158@property (readonly, nonatomic) OFString *uppercaseString;
159
163@property (readonly, nonatomic) OFString *lowercaseString;
164
172@property (readonly, nonatomic) OFString *capitalizedString;
173
185@property (readonly, nonatomic) long long longLongValue;
186
198@property (readonly, nonatomic) unsigned long long unsignedLongLongValue;
199
206@property (readonly, nonatomic) float floatValue;
207
214@property (readonly, nonatomic) double doubleValue;
215
225@property (readonly, nonatomic) const OFUnichar *characters;
226
236@property (readonly, nonatomic) const OFChar16 *UTF16String;
237
241@property (readonly, nonatomic) size_t UTF16StringLength;
242
252@property (readonly, nonatomic) const OFChar32 *UTF32String;
253
257@property (readonly, nonatomic) OFString *stringByDeletingLeadingWhitespaces;
258
262@property (readonly, nonatomic) OFString *stringByDeletingTrailingWhitespaces;
263
267@property (readonly, nonatomic) OFString *stringByDeletingEnclosingWhitespaces;
268
269#if defined(OF_WINDOWS) || defined(DOXYGEN)
273@property (readonly, nonatomic)
275#endif
276
282+ (instancetype)string;
283
291+ (instancetype)stringWithUTF8String: (const char *)UTF8String;
292
302+ (instancetype)stringWithUTF8String: (const char *)UTF8String
303 length: (size_t)UTF8StringLength;
304
320+ (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
321 freeWhenDone: (bool)freeWhenDone;
322
339+ (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
340 length: (size_t)UTF8StringLength
341 freeWhenDone: (bool)freeWhenDone;
342
351+ (instancetype)stringWithCString: (const char *)cString
352 encoding: (OFStringEncoding)encoding;
353
364+ (instancetype)stringWithCString: (const char *)cString
365 encoding: (OFStringEncoding)encoding
366 length: (size_t)cStringLength;
367
376+ (instancetype)stringWithData: (OFData *)data
377 encoding: (OFStringEncoding)encoding;
378
385+ (instancetype)stringWithString: (OFString *)string;
386
395+ (instancetype)stringWithCharacters: (const OFUnichar *)characters
396 length: (size_t)length;
397
405+ (instancetype)stringWithUTF16String: (const OFChar16 *)string;
406
416+ (instancetype)stringWithUTF16String: (const OFChar16 *)string
417 length: (size_t)length;
418
428+ (instancetype)stringWithUTF16String: (const OFChar16 *)string
429 byteOrder: (OFByteOrder)byteOrder;
430
442+ (instancetype)stringWithUTF16String: (const OFChar16 *)string
443 length: (size_t)length
444 byteOrder: (OFByteOrder)byteOrder;
445
452+ (instancetype)stringWithUTF32String: (const OFChar32 *)string;
453
462+ (instancetype)stringWithUTF32String: (const OFChar32 *)string
463 length: (size_t)length;
464
473+ (instancetype)stringWithUTF32String: (const OFChar32 *)string
474 byteOrder: (OFByteOrder)byteOrder;
475
486+ (instancetype)stringWithUTF32String: (const OFChar32 *)string
487 length: (size_t)length
488 byteOrder: (OFByteOrder)byteOrder;
489
503+ (instancetype)stringWithFormat: (OFConstantString *)format, ...;
504
505#ifdef OF_HAVE_FILES
514+ (instancetype)stringWithContentsOfFile: (OFString *)path;
515
525+ (instancetype)stringWithContentsOfFile: (OFString *)path
526 encoding: (OFStringEncoding)encoding;
527#endif
528
542+ (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI;
543
553+ (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI
554 encoding: (OFStringEncoding)encoding;
555
561- (instancetype)init OF_DESIGNATED_INITIALIZER;
562
571- (instancetype)initWithUTF8String: (const char *)UTF8String;
572
582- (instancetype)initWithUTF8String: (const char *)UTF8String
583 length: (size_t)UTF8StringLength;
584
600- (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
601 freeWhenDone: (bool)freeWhenDone;
602
620- (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
621 length: (size_t)UTF8StringLength
622 freeWhenDone: (bool)freeWhenDone;
623
633- (instancetype)initWithCString: (const char *)cString
634 encoding: (OFStringEncoding)encoding;
635
646- (instancetype)initWithCString: (const char *)cString
647 encoding: (OFStringEncoding)encoding
648 length: (size_t)cStringLength;
649
659- (instancetype)initWithData: (OFData *)data
660 encoding: (OFStringEncoding)encoding;
661
668- (instancetype)initWithString: (OFString *)string;
669
678- (instancetype)initWithCharacters: (const OFUnichar *)characters
679 length: (size_t)length;
680
688- (instancetype)initWithUTF16String: (const OFChar16 *)string;
689
699- (instancetype)initWithUTF16String: (const OFChar16 *)string
700 length: (size_t)length;
701
711- (instancetype)initWithUTF16String: (const OFChar16 *)string
712 byteOrder: (OFByteOrder)byteOrder;
713
725- (instancetype)initWithUTF16String: (const OFChar16 *)string
726 length: (size_t)length
727 byteOrder: (OFByteOrder)byteOrder;
728
735- (instancetype)initWithUTF32String: (const OFChar32 *)string;
736
745- (instancetype)initWithUTF32String: (const OFChar32 *)string
746 length: (size_t)length;
747
756- (instancetype)initWithUTF32String: (const OFChar32 *)string
757 byteOrder: (OFByteOrder)byteOrder;
758
769- (instancetype)initWithUTF32String: (const OFChar32 *)string
770 length: (size_t)length
771 byteOrder: (OFByteOrder)byteOrder;
772
786- (instancetype)initWithFormat: (OFConstantString *)format, ...;
787
802- (instancetype)initWithFormat: (OFConstantString *)format
803 arguments: (va_list)arguments;
804
805#ifdef OF_HAVE_FILES
814- (instancetype)initWithContentsOfFile: (OFString *)path;
815
825- (instancetype)initWithContentsOfFile: (OFString *)path
826 encoding: (OFStringEncoding)encoding;
827#endif
828
843- (instancetype)initWithContentsOfIRI: (OFIRI *)IRI;
844
854- (instancetype)initWithContentsOfIRI: (OFIRI *)IRI
855 encoding: (OFStringEncoding)encoding;
856
870- (size_t)getCString: (char *)cString
871 maxLength: (size_t)maxLength
872 encoding: (OFStringEncoding)encoding;
873
886- (size_t)getLossyCString: (char *)cString
887 maxLength: (size_t)maxLength
888 encoding: (OFStringEncoding)encoding;
889
902- (const char *)cStringWithEncoding: (OFStringEncoding)encoding;
903
916- (const char *)lossyCStringWithEncoding: (OFStringEncoding)encoding;
917
927- (size_t)cStringLengthWithEncoding: (OFStringEncoding)encoding;
928
935- (OFComparisonResult)compare: (OFString *)string;
936
943- (OFComparisonResult)caseInsensitiveCompare: (OFString *)string;
944
951- (OFUnichar)characterAtIndex: (size_t)index;
952
960- (void)getCharacters: (OFUnichar *)buffer inRange: (OFRange)range;
961
969- (OFRange)rangeOfString: (OFString *)string;
970
979- (OFRange)rangeOfString: (OFString *)string
980 options: (OFStringSearchOptions)options;
981
991- (OFRange)rangeOfString: (OFString *)string
992 options: (OFStringSearchOptions)options
993 range: (OFRange)range;
994
1002- (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet;
1003
1012- (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1013 options: (OFStringSearchOptions)options;
1014
1024- (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1025 options: (OFStringSearchOptions)options
1026 range: (OFRange)range;
1027
1034- (bool)containsString: (OFString *)string;
1035
1042- (OFString *)substringFromIndex: (size_t)idx;
1043
1050- (OFString *)substringToIndex: (size_t)idx;
1051
1058- (OFString *)substringWithRange: (OFRange)range;
1059
1079- (long long)longLongValueWithBase: (unsigned char)base;
1080
1103- (unsigned long long)unsignedLongLongValueWithBase: (unsigned char)base;
1104
1111- (OFString *)stringByAppendingString: (OFString *)string;
1112
1122- (OFString *)stringByAppendingFormat: (OFConstantString *)format, ...;
1123
1134- (OFString *)stringByAppendingFormat: (OFConstantString *)format
1135 arguments: (va_list)arguments;
1136
1145- (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1146 withString: (OFString *)replacement;
1147
1160- (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1161 withString: (OFString *)replacement
1162 options: (int)options
1163 range: (OFRange)range;
1164
1171- (bool)hasPrefix: (OFString *)prefix;
1172
1179- (bool)hasSuffix: (OFString *)suffix;
1180
1188- (OFArray OF_GENERIC(OFString *) *)
1189 componentsSeparatedByString: (OFString *)delimiter;
1190
1199- (OFArray OF_GENERIC(OFString *) *)
1200 componentsSeparatedByString: (OFString *)delimiter
1201 options: (OFStringSeparationOptions)options;
1202
1210- (OFArray OF_GENERIC(OFString *) *)
1211 componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet;
1212
1221- (OFArray OF_GENERIC(OFString *) *)
1222 componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet
1223 options: (OFStringSeparationOptions)options;
1224
1238- (const OFChar16 *)UTF16StringWithByteOrder: (OFByteOrder)byteOrder;
1239
1252- (const OFChar32 *)UTF32StringWithByteOrder: (OFByteOrder)byteOrder;
1253
1262- (OFData *)dataWithEncoding: (OFStringEncoding)encoding;
1263
1264#ifdef OF_HAVE_FILES
1270- (void)writeToFile: (OFString *)path;
1271
1281- (void)writeToFile: (OFString *)path encoding: (OFStringEncoding)encoding;
1282#endif
1283
1289- (void)writeToIRI: (OFIRI *)IRI;
1290
1299- (void)writeToIRI: (OFIRI *)IRI encoding: (OFStringEncoding)encoding;
1300
1301#ifdef OF_HAVE_BLOCKS
1307- (void)enumerateLinesUsingBlock: (OFStringLineEnumerationBlock)block;
1308#endif
1309@end
1310
1311#ifdef __cplusplus
1312extern "C" {
1313#endif
1325
1332extern OFString *_Nullable OFStringEncodingName(OFStringEncoding encoding);
1333
1334extern char *_Nullable OFStrDup(const char *_Nonnull);
1335extern size_t OFUTF8StringEncode(OFUnichar, char *);
1336extern ssize_t OFUTF8StringDecode(const char *, size_t, OFUnichar *);
1337extern size_t OFUTF16StringLength(const OFChar16 *);
1338extern size_t OFUTF32StringLength(const OFChar32 *);
1339#ifdef __cplusplus
1340}
1341#endif
1342
1343OF_ASSUME_NONNULL_END
1344
1345#import "OFConstantString.h"
1346#import "OFMutableString.h"
1347#import "OFString+CryptographicHashing.h"
1348#import "OFString+JSONParsing.h"
1349#ifdef OF_HAVE_FILES
1350# import "OFString+PathAdditions.h"
1351#endif
1352#import "OFString+PercentEncoding.h"
1353#import "OFString+PropertyListParsing.h"
1354#import "OFString+XMLEscaping.h"
1356
1357#if !defined(NSINTEGER_DEFINED) && !__has_feature(modules)
1358/*
1359 * Very *ugly* hack required for string boxing literals to work.
1360 *
1361 * This hack is needed in order to work with `@class NSString` from Apple's
1362 * objc/NSString.h - which is included when using modules - as
1363 * @compatibility_alias does not work if @class has been used before.
1364 * For some reason, this makes Clang refer to OFString for string box literals
1365 * and not to NSString (which would result in a linker error, but would be the
1366 * correct behavior).
1367 *
1368 * TODO: Submit a patch for Clang that makes the boxing classes configurable!
1369 */
1370@interface NSString: OFString
1371@end
1372#endif
OFComparisonResult
A result of a comparison.
Definition OFObject.h:54
OFByteOrder
An enum for representing endianness.
Definition OFObject.h:88
OFStringEncoding OFStringEncodingParseName(OFString *name)
Parses the specified string encoding name and returns the OFStringEncoding for it.
Definition OFString.m:148
OFStringSeparationOptions
Options for separating strings.
Definition OFString.h:113
@ OFStringSkipEmptyComponents
Definition OFString.h:115
OFStringSearchOptions
Options for searching in strings.
Definition OFString.h:103
@ OFStringSearchBackwards
Definition OFString.h:105
OFString * OFStringEncodingName(OFStringEncoding encoding)
Returns the name of the specified OFStringEncoding.
Definition OFString.m:203
OFStringEncoding
The encoding of a string.
Definition OFString.h:61
@ OFStringEncodingWindows1251
Definition OFString.h:79
@ OFStringEncodingKOI8R
Definition OFString.h:91
@ OFStringEncodingISO8859_2
Definition OFString.h:73
@ OFStringEncodingISO8859_3
Definition OFString.h:75
@ OFStringEncodingASCII
Definition OFString.h:69
@ OFStringEncodingISO8859_1
Definition OFString.h:71
@ OFStringEncodingWindows1252
Definition OFString.h:81
@ OFStringEncodingMacRoman
Definition OFString.h:89
@ OFStringEncodingCodepage437
Definition OFString.h:83
@ OFStringEncodingCodepage850
Definition OFString.h:85
@ OFStringEncodingAutodetect
Definition OFString.h:95
@ OFStringEncodingCodepage858
Definition OFString.h:87
@ OFStringEncodingUTF8
Definition OFString.h:67
@ OFStringEncodingISO8859_15
Definition OFString.h:77
@ OFStringEncodingKOI8U
Definition OFString.h:93
void(^ OFStringLineEnumerationBlock)(OFString *line, bool *stop)
A block for enumerating the lines of a string.
Definition OFString.h:126
An abstract class for storing objects in an array.
Definition OFArray.h:105
A class cluster representing a character set.
Definition OFCharacterSet.h:29
A class for storing constant strings using the @"" literal.
Definition OFConstantString.h:38
A class for storing arbitrary data in an array.
Definition OFData.h:42
A class for representing IRIs, URIs, URLs and URNs, for parsing them as well as accessing parts of th...
Definition OFIRI.h:37
The root class for all other classes inside ObjFW.
Definition OFObject.h:688
A class for handling strings.
Definition OFString.h:135
instancetype init()
Initializes an already allocated OFString to be empty.
Definition OFString.m:765
const OFUnichar * characters
The string as an array of Unicode characters.
Definition OFString.h:225
OFString * stringByDeletingEnclosingWhitespaces
The string with leading and trailing whitespaces deleted.
Definition OFString.h:267
const char * UTF8String
The OFString as a UTF-8 encoded C string.
Definition OFString.h:148
const OFChar16 * UTF16String
The string in UTF-16 encoding with native byte order.
Definition OFString.h:236
OFString * lowercaseString
The string in lowercase.
Definition OFString.h:163
unsigned long long unsignedLongLongValue
The decimal value of the string as an unsigned long long.
Definition OFString.h:198
size_t UTF16StringLength
The length of the string in UTF-16 characters.
Definition OFString.h:241
double doubleValue
The double value of the string as a double.
Definition OFString.h:214
OFString * uppercaseString
The string in uppercase.
Definition OFString.h:158
float floatValue
The float value of the string as a float.
Definition OFString.h:206
OFString * stringByDeletingTrailingWhitespaces
The string with trailing whitespaces deleted.
Definition OFString.h:262
size_t UTF8StringLength
The number of bytes the string needs in UTF-8 encoding.
Definition OFString.h:153
const OFChar32 * UTF32String
The string in UTF-32 encoding with native byte order.
Definition OFString.h:252
size_t length
The length of the string in Unicode code points.
Definition OFString.h:139
OFString * stringByExpandingWindowsEnvironmentStrings
The string with the Windows Environment Strings expanded.
Definition OFString.h:274
long long longLongValue
The decimal value of the string as a long long.
Definition OFString.h:185
OFString * capitalizedString
The string in capitalized form.
Definition OFString.h:172
instancetype string()
Creates a new OFString.
Definition OFString.m:599
OFString * stringByDeletingLeadingWhitespaces
The string with leading whitespaces deleted.
Definition OFString.h:257
A protocol for comparing objects.
Definition OFObject.h:1384
A protocol for the creation of copies.
Definition OFObject.h:1346
A protocol implemented by classes that support encoding to a JSON representation.
Definition OFJSONRepresentation.h:44
A protocol implemented by classes that support encoding to a MessagePack representation.
Definition OFMessagePackRepresentation.h:29
A protocol for the creation of mutable copies.
Definition OFObject.h:1367
A range.
Definition OFObject.h:106