ObjFW
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 program is free software: you can redistribute it and/or modify it
7  * under the terms of the GNU Lesser General Public License version 3.0 only,
8  * as published by the Free Software Foundation.
9  *
10  * This program is distributed in the hope that it will be useful, but WITHOUT
11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
13  * version 3.0 for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * version 3.0 along with this program. If not, see
17  * <https://www.gnu.org/licenses/>.
18  */
19 
20 #ifndef __STDC_LIMIT_MACROS
21 # define __STDC_LIMIT_MACROS
22 #endif
23 #ifndef __STDC_CONSTANT_MACROS
24 # define __STDC_CONSTANT_MACROS
25 #endif
26 
27 #include "objfw-defs.h"
28 
29 #ifdef OF_HAVE_SYS_TYPES_H
30 # include <sys/types.h>
31 #endif
32 
33 #include <stdarg.h>
34 #include <stdint.h>
35 #ifdef OF_HAVE_INTTYPES_H
36 # include <inttypes.h>
37 #endif
38 
39 #import "OFObject.h"
40 #import "OFJSONRepresentation.h"
41 #import "OFMessagePackRepresentation.h"
42 
43 OF_ASSUME_NONNULL_BEGIN
44 
47 @class OFArray OF_GENERIC(ObjectType);
48 @class OFCharacterSet;
49 @class OFConstantString;
50 @class OFIRI;
51 @class OFString;
52 
53 #if defined(__cplusplus) && __cplusplus >= 201103L
54 typedef char16_t OFChar16;
55 typedef char32_t OFChar32;
56 #else
57 typedef uint_least16_t OFChar16;
58 typedef uint_least32_t OFChar32;
59 #endif
60 typedef OFChar32 OFUnichar;
61 
65 typedef enum {
66  /*
67  * UTF-8 *has* to be 0, so that if the current @ref OFLocale is
68  * `nil`, `[OFLocale encoding]` returns UTF-8.
69  */
101 
107 typedef enum {
111 
117 typedef enum {
121 
122 #ifdef OF_HAVE_BLOCKS
123 
130 typedef void (^OFStringLineEnumerationBlock)(OFString *line, bool *stop);
131 #endif
132 
143 @property (readonly, nonatomic) size_t length;
144 
152 @property (readonly, nonatomic) const char *UTF8String;
153 
157 @property (readonly, nonatomic) size_t UTF8StringLength;
158 
162 @property (readonly, nonatomic) OFString *uppercaseString;
163 
167 @property (readonly, nonatomic) OFString *lowercaseString;
168 
176 @property (readonly, nonatomic) OFString *capitalizedString;
177 
189 @property (readonly, nonatomic) long long longLongValue;
190 
202 @property (readonly, nonatomic) unsigned long long unsignedLongLongValue;
203 
210 @property (readonly, nonatomic) float floatValue;
211 
218 @property (readonly, nonatomic) double doubleValue;
219 
229 @property (readonly, nonatomic) const OFUnichar *characters;
230 
240 @property (readonly, nonatomic) const OFChar16 *UTF16String;
241 
245 @property (readonly, nonatomic) size_t UTF16StringLength;
246 
256 @property (readonly, nonatomic) const OFChar32 *UTF32String;
257 
261 @property (readonly, nonatomic) OFString *stringByDeletingLeadingWhitespaces;
262 
266 @property (readonly, nonatomic) OFString *stringByDeletingTrailingWhitespaces;
267 
271 @property (readonly, nonatomic) OFString *stringByDeletingEnclosingWhitespaces;
272 
273 #if defined(OF_WINDOWS) || defined(DOXYGEN)
274 
277 @property (readonly, nonatomic)
279 #endif
280 
286 + (instancetype)string;
287 
295 + (instancetype)stringWithUTF8String: (const char *)UTF8String;
296 
306 + (instancetype)stringWithUTF8String: (const char *)UTF8String
307  length: (size_t)UTF8StringLength;
308 
324 + (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
325  freeWhenDone: (bool)freeWhenDone;
326 
343 + (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
344  length: (size_t)UTF8StringLength
345  freeWhenDone: (bool)freeWhenDone;
346 
355 + (instancetype)stringWithCString: (const char *)cString
356  encoding: (OFStringEncoding)encoding;
357 
368 + (instancetype)stringWithCString: (const char *)cString
369  encoding: (OFStringEncoding)encoding
370  length: (size_t)cStringLength;
371 
380 + (instancetype)stringWithData: (OFData *)data
381  encoding: (OFStringEncoding)encoding;
382 
389 + (instancetype)stringWithString: (OFString *)string;
390 
399 + (instancetype)stringWithCharacters: (const OFUnichar *)characters
400  length: (size_t)length;
401 
409 + (instancetype)stringWithUTF16String: (const OFChar16 *)string;
410 
420 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
421  length: (size_t)length;
422 
432 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
433  byteOrder: (OFByteOrder)byteOrder;
434 
446 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
447  length: (size_t)length
448  byteOrder: (OFByteOrder)byteOrder;
449 
456 + (instancetype)stringWithUTF32String: (const OFChar32 *)string;
457 
466 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
467  length: (size_t)length;
468 
477 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
478  byteOrder: (OFByteOrder)byteOrder;
479 
490 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
491  length: (size_t)length
492  byteOrder: (OFByteOrder)byteOrder;
493 
507 + (instancetype)stringWithFormat: (OFConstantString *)format, ...;
508 
509 #ifdef OF_HAVE_FILES
510 
518 + (instancetype)stringWithContentsOfFile: (OFString *)path;
519 
529 + (instancetype)stringWithContentsOfFile: (OFString *)path
530  encoding: (OFStringEncoding)encoding;
531 #endif
532 
546 + (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI;
547 
557 + (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI
558  encoding: (OFStringEncoding)encoding;
559 
565 - (instancetype)init OF_DESIGNATED_INITIALIZER;
566 
575 - (instancetype)initWithUTF8String: (const char *)UTF8String;
576 
586 - (instancetype)initWithUTF8String: (const char *)UTF8String
587  length: (size_t)UTF8StringLength;
588 
604 - (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
605  freeWhenDone: (bool)freeWhenDone;
606 
624 - (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
625  length: (size_t)UTF8StringLength
626  freeWhenDone: (bool)freeWhenDone;
627 
637 - (instancetype)initWithCString: (const char *)cString
638  encoding: (OFStringEncoding)encoding;
639 
650 - (instancetype)initWithCString: (const char *)cString
651  encoding: (OFStringEncoding)encoding
652  length: (size_t)cStringLength;
653 
663 - (instancetype)initWithData: (OFData *)data
664  encoding: (OFStringEncoding)encoding;
665 
672 - (instancetype)initWithString: (OFString *)string;
673 
682 - (instancetype)initWithCharacters: (const OFUnichar *)characters
683  length: (size_t)length;
684 
692 - (instancetype)initWithUTF16String: (const OFChar16 *)string;
693 
703 - (instancetype)initWithUTF16String: (const OFChar16 *)string
704  length: (size_t)length;
705 
715 - (instancetype)initWithUTF16String: (const OFChar16 *)string
716  byteOrder: (OFByteOrder)byteOrder;
717 
729 - (instancetype)initWithUTF16String: (const OFChar16 *)string
730  length: (size_t)length
731  byteOrder: (OFByteOrder)byteOrder;
732 
739 - (instancetype)initWithUTF32String: (const OFChar32 *)string;
740 
749 - (instancetype)initWithUTF32String: (const OFChar32 *)string
750  length: (size_t)length;
751 
760 - (instancetype)initWithUTF32String: (const OFChar32 *)string
761  byteOrder: (OFByteOrder)byteOrder;
762 
773 - (instancetype)initWithUTF32String: (const OFChar32 *)string
774  length: (size_t)length
775  byteOrder: (OFByteOrder)byteOrder;
776 
790 - (instancetype)initWithFormat: (OFConstantString *)format, ...;
791 
806 - (instancetype)initWithFormat: (OFConstantString *)format
807  arguments: (va_list)arguments;
808 
809 #ifdef OF_HAVE_FILES
810 
818 - (instancetype)initWithContentsOfFile: (OFString *)path;
819 
829 - (instancetype)initWithContentsOfFile: (OFString *)path
830  encoding: (OFStringEncoding)encoding;
831 #endif
832 
847 - (instancetype)initWithContentsOfIRI: (OFIRI *)IRI;
848 
858 - (instancetype)initWithContentsOfIRI: (OFIRI *)IRI
859  encoding: (OFStringEncoding)encoding;
860 
874 - (size_t)getCString: (char *)cString
875  maxLength: (size_t)maxLength
876  encoding: (OFStringEncoding)encoding;
877 
890 - (size_t)getLossyCString: (char *)cString
891  maxLength: (size_t)maxLength
892  encoding: (OFStringEncoding)encoding;
893 
906 - (const char *)cStringWithEncoding: (OFStringEncoding)encoding;
907 
920 - (const char *)lossyCStringWithEncoding: (OFStringEncoding)encoding;
921 
931 - (size_t)cStringLengthWithEncoding: (OFStringEncoding)encoding;
932 
939 - (OFComparisonResult)compare: (OFString *)string;
940 
947 - (OFComparisonResult)caseInsensitiveCompare: (OFString *)string;
948 
955 - (OFUnichar)characterAtIndex: (size_t)index;
956 
964 - (void)getCharacters: (OFUnichar *)buffer inRange: (OFRange)range;
965 
973 - (OFRange)rangeOfString: (OFString *)string;
974 
983 - (OFRange)rangeOfString: (OFString *)string
984  options: (OFStringSearchOptions)options;
985 
995 - (OFRange)rangeOfString: (OFString *)string
996  options: (OFStringSearchOptions)options
997  range: (OFRange)range;
998 
1006 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet;
1007 
1016 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1017  options: (OFStringSearchOptions)options;
1018 
1028 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1029  options: (OFStringSearchOptions)options
1030  range: (OFRange)range;
1031 
1038 - (bool)containsString: (OFString *)string;
1039 
1046 - (OFString *)substringFromIndex: (size_t)idx;
1047 
1054 - (OFString *)substringToIndex: (size_t)idx;
1055 
1062 - (OFString *)substringWithRange: (OFRange)range;
1063 
1083 - (long long)longLongValueWithBase: (unsigned char)base;
1084 
1107 - (unsigned long long)unsignedLongLongValueWithBase: (unsigned char)base;
1108 
1115 - (OFString *)stringByAppendingString: (OFString *)string;
1116 
1126 - (OFString *)stringByAppendingFormat: (OFConstantString *)format, ...;
1127 
1138 - (OFString *)stringByAppendingFormat: (OFConstantString *)format
1139  arguments: (va_list)arguments;
1140 
1149 - (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1150  withString: (OFString *)replacement;
1151 
1164 - (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1165  withString: (OFString *)replacement
1166  options: (int)options
1167  range: (OFRange)range;
1168 
1175 - (bool)hasPrefix: (OFString *)prefix;
1176 
1183 - (bool)hasSuffix: (OFString *)suffix;
1184 
1192 - (OFArray OF_GENERIC(OFString *) *)
1193  componentsSeparatedByString: (OFString *)delimiter;
1194 
1203 - (OFArray OF_GENERIC(OFString *) *)
1204  componentsSeparatedByString: (OFString *)delimiter
1205  options: (OFStringSeparationOptions)options;
1206 
1214 - (OFArray OF_GENERIC(OFString *) *)
1215  componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet;
1216 
1225 - (OFArray OF_GENERIC(OFString *) *)
1226  componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet
1227  options: (OFStringSeparationOptions)options;
1228 
1242 - (const OFChar16 *)UTF16StringWithByteOrder: (OFByteOrder)byteOrder;
1243 
1256 - (const OFChar32 *)UTF32StringWithByteOrder: (OFByteOrder)byteOrder;
1257 
1266 - (OFData *)dataWithEncoding: (OFStringEncoding)encoding;
1267 
1268 #ifdef OF_HAVE_FILES
1269 
1274 - (void)writeToFile: (OFString *)path;
1275 
1285 - (void)writeToFile: (OFString *)path encoding: (OFStringEncoding)encoding;
1286 #endif
1287 
1293 - (void)writeToIRI: (OFIRI *)IRI;
1294 
1303 - (void)writeToIRI: (OFIRI *)IRI encoding: (OFStringEncoding)encoding;
1304 
1305 #ifdef OF_HAVE_BLOCKS
1306 
1311 - (void)enumerateLinesUsingBlock: (OFStringLineEnumerationBlock)block;
1312 #endif
1313 @end
1314 
1315 #ifdef __cplusplus
1316 extern "C" {
1317 #endif
1318 
1329 
1336 extern OFString *_Nullable OFStringEncodingName(OFStringEncoding encoding);
1337 
1338 extern char *_Nullable OFStrDup(const char *_Nonnull);
1339 extern size_t OFUTF8StringEncode(OFUnichar, char *);
1340 extern ssize_t OFUTF8StringDecode(const char *, size_t, OFUnichar *);
1341 extern size_t OFUTF16StringLength(const OFChar16 *);
1342 extern size_t OFUTF32StringLength(const OFChar32 *);
1343 #ifdef __cplusplus
1344 }
1345 #endif
1346 
1347 OF_ASSUME_NONNULL_END
1348 
1349 #import "OFConstantString.h"
1350 #import "OFMutableString.h"
1351 #import "OFString+CryptographicHashing.h"
1352 #import "OFString+JSONParsing.h"
1353 #ifdef OF_HAVE_FILES
1354 # import "OFString+PathAdditions.h"
1355 #endif
1356 #import "OFString+PercentEncoding.h"
1357 #import "OFString+PropertyListParsing.h"
1358 #import "OFString+XMLEscaping.h"
1359 #import "OFString+XMLUnescaping.h"
1360 
1361 #if !defined(NSINTEGER_DEFINED) && !__has_feature(modules)
1362 /*
1363  * Very *ugly* hack required for string boxing literals to work.
1364  *
1365  * This hack is needed in order to work with `@class NSString` from Apple's
1366  * objc/NSString.h - which is included when using modules - as
1367  * @compatibility_alias does not work if @class has been used before.
1368  * For some reason, this makes Clang refer to OFString for string box literals
1369  * and not to NSString (which would result in a linker error, but would be the
1370  * correct behavior).
1371  *
1372  * TODO: Submit a patch for Clang that makes the boxing classes configurable!
1373  */
1374 @interface NSString: OFString
1375 @end
1376 #endif
OFStringSeparationOptions
Options for separating strings.
Definition: OFString.h:117
Definition: OFString.h:99
An abstract class for storing objects in an array.
Definition: OFArray.h:107
instancetype init()
Initializes an already allocated OFString to be empty.
Definition: OFString.m:769
A protocol for comparing objects.
Definition: OFObject.h:1388
OFStringEncoding
The encoding of a string.
Definition: OFString.h:65
Definition: OFString.h:81
OFString * stringByExpandingWindowsEnvironmentStrings
The string with the Windows Environment Strings expanded.
Definition: OFString.h:278
OFString * capitalizedString
The string in capitalized form.
Definition: OFString.h:176
OFString * stringByDeletingEnclosingWhitespaces
The string with leading and trailing whitespaces deleted.
Definition: OFString.h:271
Definition: OFString.h:89
A class for storing constant strings using the @"" literal.
Definition: OFConstantString.h:41
The root class for all other classes inside ObjFW.
Definition: OFObject.h:690
OFString * uppercaseString
The string in uppercase.
Definition: OFString.h:162
Definition: OFString.h:93
A class cluster representing a character set.
Definition: OFCharacterSet.h:32
OFStringEncoding OFStringEncodingParseName(OFString *name)
Parses the specified string encoding name and returns the OFStringEncoding for it.
Definition: OFString.m:152
OFString * stringByDeletingTrailingWhitespaces
The string with trailing whitespaces deleted.
Definition: OFString.h:266
Definition: OFString.h:119
Definition: OFString.h:109
const OFUnichar * characters
The string as an array of Unicode characters.
Definition: OFString.h:229
A protocol implemented by classes that support encoding to a JSON representation. ...
Definition: OFJSONRepresentation.h:48
A class for handling strings.
Definition: OFString.h:138
Definition: OFString.h:87
const OFChar32 * UTF32String
The string in UTF-32 encoding with native byte order.
Definition: OFString.h:256
OFString * lowercaseString
The string in lowercase.
Definition: OFString.h:167
OFComparisonResult
A result of a comparison.
Definition: OFObject.h:58
Definition: OFString.h:79
const OFChar16 * UTF16String
The string in UTF-16 encoding with native byte order.
Definition: OFString.h:240
Definition: OFString.h:71
OFByteOrder
An enum for representing endianness.
Definition: OFObject.h:92
Definition: OFString.h:77
size_t UTF16StringLength
The length of the string in UTF-16 characters.
Definition: OFString.h:245
A protocol implemented by classes that support encoding to a MessagePack representation.
Definition: OFMessagePackRepresentation.h:33
OFString * stringByDeletingLeadingWhitespaces
The string with leading whitespaces deleted.
Definition: OFString.h:261
size_t UTF8StringLength
The number of bytes the string needs in UTF-8 encoding.
Definition: OFString.h:157
Definition: OFString.h:91
A class for representing IRIs, URIs, URLs and URNs, for parsing them as well as accessing parts of th...
Definition: OFIRI.h:39
long long longLongValue
The decimal value of the string as a long long.
Definition: OFString.h:189
Definition: OFString.h:97
A protocol for the creation of mutable copies.
Definition: OFObject.h:1371
A protocol for the creation of copies.
Definition: OFObject.h:1350
A class for storing arbitrary data in an array.
Definition: OFData.h:45
size_t length
The length of the string in Unicode code points.
Definition: OFString.h:143
Definition: OFString.h:75
Definition: OFString.h:83
void(^ OFStringLineEnumerationBlock)(OFString *line, bool *stop)
A block for enumerating the lines of a string.
Definition: OFString.h:130
const char * UTF8String
The OFString as a UTF-8 encoded C string.
Definition: OFString.h:152
double doubleValue
The double value of the string as a double.
Definition: OFString.h:218
float floatValue
The float value of the string as a float.
Definition: OFString.h:210
instancetype string()
Creates a new OFString.
Definition: OFString.m:603
unsigned long long unsignedLongLongValue
The decimal value of the string as an unsigned long long.
Definition: OFString.h:202
Definition: OFString.h:95
A range.
Definition: OFObject.h:110
Definition: OFString.h:85
Definition: OFString.h:73
OFStringSearchOptions
Options for searching in strings.
Definition: OFString.h:107
OFString * OFStringEncodingName(OFStringEncoding encoding)
Returns the name of the specified OFStringEncoding.
Definition: OFString.m:207