ObjFW
OFString.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2008-2023 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 
39 OF_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
50 typedef char16_t OFChar16;
51 typedef char32_t OFChar32;
52 #else
53 typedef uint_least16_t OFChar16;
54 typedef uint_least32_t OFChar32;
55 #endif
56 typedef OFChar32 OFUnichar;
57 
61 typedef enum {
62  /*
63  * UTF-8 *has* to be 0, so that if the current @ref OFLocale is
64  * `nil`, `[OFLocale encoding]` returns UTF-8.
65  */
97 
103 typedef enum {
107 
113 typedef enum {
117 
118 #ifdef OF_HAVE_BLOCKS
119 
126 typedef 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)
270 
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
506 
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
806 
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
1265 
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
1302 
1307 - (void)enumerateLinesUsingBlock: (OFStringLineEnumerationBlock)block;
1308 #endif
1309 @end
1310 
1311 #ifdef __cplusplus
1312 extern "C" {
1313 #endif
1314 
1325 
1332 extern OFString *_Nullable OFStringEncodingName(OFStringEncoding encoding);
1333 
1334 extern char *_Nullable OFStrDup(const char *_Nonnull);
1335 extern size_t OFUTF8StringEncode(OFUnichar, char *);
1336 extern ssize_t OFUTF8StringDecode(const char *, size_t, OFUnichar *);
1337 extern size_t OFUTF16StringLength(const OFChar16 *);
1338 extern size_t OFUTF32StringLength(const OFChar32 *);
1339 #ifdef __cplusplus
1340 }
1341 #endif
1342 
1343 OF_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"
1355 #import "OFString+XMLUnescaping.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
OFStringSeparationOptions
Options for separating strings.
Definition: OFString.h:113
Definition: OFString.h:95
An abstract class for storing objects in an array.
Definition: OFArray.h:103
instancetype init()
Initializes an already allocated OFString to be empty.
Definition: OFString.m:765
A protocol for comparing objects.
Definition: OFObject.h:1383
OFStringEncoding
The encoding of a string.
Definition: OFString.h:61
Definition: OFString.h:77
OFString * stringByExpandingWindowsEnvironmentStrings
The string with the Windows Environment Strings expanded.
Definition: OFString.h:274
OFString * capitalizedString
The string in capitalized form.
Definition: OFString.h:172
OFString * stringByDeletingEnclosingWhitespaces
The string with leading and trailing whitespaces deleted.
Definition: OFString.h:267
Definition: OFString.h:85
A class for storing constant strings using the @"" literal.
Definition: OFConstantString.h:37
The root class for all other classes inside ObjFW.
Definition: OFObject.h:686
OFString * uppercaseString
The string in uppercase.
Definition: OFString.h:158
Definition: OFString.h:89
A class cluster representing a character set.
Definition: OFCharacterSet.h:28
OFStringEncoding OFStringEncodingParseName(OFString *name)
Parses the specified string encoding name and returns the OFStringEncoding for it.
Definition: OFString.m:148
OFString * stringByDeletingTrailingWhitespaces
The string with trailing whitespaces deleted.
Definition: OFString.h:262
Definition: OFString.h:115
Definition: OFString.h:105
const OFUnichar * characters
The string as an array of Unicode characters.
Definition: OFString.h:225
A protocol implemented by classes that support encoding to a JSON representation. ...
Definition: OFJSONRepresentation.h:44
A class for handling strings.
Definition: OFString.h:134
Definition: OFString.h:83
const OFChar32 * UTF32String
The string in UTF-32 encoding with native byte order.
Definition: OFString.h:252
OFString * lowercaseString
The string in lowercase.
Definition: OFString.h:163
OFComparisonResult
A result of a comparison.
Definition: OFObject.h:54
Definition: OFString.h:75
const OFChar16 * UTF16String
The string in UTF-16 encoding with native byte order.
Definition: OFString.h:236
Definition: OFString.h:67
OFByteOrder
An enum for representing endianess.
Definition: OFObject.h:88
Definition: OFString.h:73
size_t UTF16StringLength
The length of the string in UTF-16 characters.
Definition: OFString.h:241
A protocol implemented by classes that support encoding to a MessagePack representation.
Definition: OFMessagePackRepresentation.h:29
OFString * stringByDeletingLeadingWhitespaces
The string with leading whitespaces deleted.
Definition: OFString.h:257
size_t UTF8StringLength
The number of bytes the string needs in UTF-8 encoding.
Definition: OFString.h:153
Definition: OFString.h:87
A class for representing IRIs, URIs, URLs and URNs, for parsing them as well as accessing parts of th...
Definition: OFIRI.h:35
long long longLongValue
The decimal value of the string as a long long.
Definition: OFString.h:185
Definition: OFString.h:93
A protocol for the creation of mutable copies.
Definition: OFObject.h:1367
A protocol for the creation of copies.
Definition: OFObject.h:1346
A class for storing arbitrary data in an array.
Definition: OFData.h:41
size_t length
The length of the string in Unicode codepoints.
Definition: OFString.h:139
Definition: OFString.h:71
Definition: OFString.h:79
void(^ OFStringLineEnumerationBlock)(OFString *line, bool *stop)
A block for enumerating the lines of a string.
Definition: OFString.h:126
const char * UTF8String
The OFString as a UTF-8 encoded C string.
Definition: OFString.h:148
double doubleValue
The double value of the string as a double.
Definition: OFString.h:214
float floatValue
The float value of the string as a float.
Definition: OFString.h:206
instancetype string()
Creates a new OFString.
Definition: OFString.m:599
unsigned long long unsignedLongLongValue
The decimal value of the string as an unsigned long long.
Definition: OFString.h:198
Definition: OFString.h:91
A range.
Definition: OFObject.h:106
Definition: OFString.h:81
Definition: OFString.h:69
OFStringSearchOptions
Options for searching in strings.
Definition: OFString.h:103
OFString * OFStringEncodingName(OFStringEncoding encoding)
Returns the name of the specified OFStringEncoding.
Definition: OFString.m:203