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  */
105 
111 typedef enum {
115 
121 typedef enum {
125 
126 #ifdef OF_HAVE_BLOCKS
127 
134 typedef void (^OFStringLineEnumerationBlock)(OFString *line, bool *stop);
135 #endif
136 
147 @property (readonly, nonatomic) size_t length;
148 
156 @property (readonly, nonatomic) const char *UTF8String;
157 
161 @property (readonly, nonatomic) size_t UTF8StringLength;
162 
166 @property (readonly, nonatomic) OFString *uppercaseString;
167 
171 @property (readonly, nonatomic) OFString *lowercaseString;
172 
180 @property (readonly, nonatomic) OFString *capitalizedString;
181 
193 @property (readonly, nonatomic) long long longLongValue;
194 
206 @property (readonly, nonatomic) unsigned long long unsignedLongLongValue;
207 
214 @property (readonly, nonatomic) float floatValue;
215 
222 @property (readonly, nonatomic) double doubleValue;
223 
233 @property (readonly, nonatomic) const OFUnichar *characters;
234 
244 @property (readonly, nonatomic) const OFChar16 *UTF16String;
245 
249 @property (readonly, nonatomic) size_t UTF16StringLength;
250 
260 @property (readonly, nonatomic) const OFChar32 *UTF32String;
261 
265 @property (readonly, nonatomic) OFString *stringByDeletingLeadingWhitespaces;
266 
270 @property (readonly, nonatomic) OFString *stringByDeletingTrailingWhitespaces;
271 
275 @property (readonly, nonatomic) OFString *stringByDeletingEnclosingWhitespaces;
276 
277 #if defined(OF_WINDOWS) || defined(DOXYGEN)
278 
281 @property (readonly, nonatomic)
283 #endif
284 
290 + (instancetype)string;
291 
299 + (instancetype)stringWithUTF8String: (const char *)UTF8String;
300 
310 + (instancetype)stringWithUTF8String: (const char *)UTF8String
311  length: (size_t)UTF8StringLength;
312 
328 + (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
329  freeWhenDone: (bool)freeWhenDone;
330 
347 + (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
348  length: (size_t)UTF8StringLength
349  freeWhenDone: (bool)freeWhenDone;
350 
359 + (instancetype)stringWithCString: (const char *)cString
360  encoding: (OFStringEncoding)encoding;
361 
372 + (instancetype)stringWithCString: (const char *)cString
373  encoding: (OFStringEncoding)encoding
374  length: (size_t)cStringLength;
375 
384 + (instancetype)stringWithData: (OFData *)data
385  encoding: (OFStringEncoding)encoding;
386 
393 + (instancetype)stringWithString: (OFString *)string;
394 
403 + (instancetype)stringWithCharacters: (const OFUnichar *)characters
404  length: (size_t)length;
405 
413 + (instancetype)stringWithUTF16String: (const OFChar16 *)string;
414 
424 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
425  length: (size_t)length;
426 
436 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
437  byteOrder: (OFByteOrder)byteOrder;
438 
450 + (instancetype)stringWithUTF16String: (const OFChar16 *)string
451  length: (size_t)length
452  byteOrder: (OFByteOrder)byteOrder;
453 
460 + (instancetype)stringWithUTF32String: (const OFChar32 *)string;
461 
470 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
471  length: (size_t)length;
472 
481 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
482  byteOrder: (OFByteOrder)byteOrder;
483 
494 + (instancetype)stringWithUTF32String: (const OFChar32 *)string
495  length: (size_t)length
496  byteOrder: (OFByteOrder)byteOrder;
497 
511 + (instancetype)stringWithFormat: (OFConstantString *)format, ...;
512 
513 #ifdef OF_HAVE_FILES
514 
522 + (instancetype)stringWithContentsOfFile: (OFString *)path;
523 
533 + (instancetype)stringWithContentsOfFile: (OFString *)path
534  encoding: (OFStringEncoding)encoding;
535 #endif
536 
550 + (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI;
551 
561 + (instancetype)stringWithContentsOfIRI: (OFIRI *)IRI
562  encoding: (OFStringEncoding)encoding;
563 
569 - (instancetype)init OF_DESIGNATED_INITIALIZER;
570 
579 - (instancetype)initWithUTF8String: (const char *)UTF8String;
580 
590 - (instancetype)initWithUTF8String: (const char *)UTF8String
591  length: (size_t)UTF8StringLength;
592 
608 - (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
609  freeWhenDone: (bool)freeWhenDone;
610 
628 - (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
629  length: (size_t)UTF8StringLength
630  freeWhenDone: (bool)freeWhenDone;
631 
641 - (instancetype)initWithCString: (const char *)cString
642  encoding: (OFStringEncoding)encoding;
643 
654 - (instancetype)initWithCString: (const char *)cString
655  encoding: (OFStringEncoding)encoding
656  length: (size_t)cStringLength;
657 
667 - (instancetype)initWithData: (OFData *)data
668  encoding: (OFStringEncoding)encoding;
669 
676 - (instancetype)initWithString: (OFString *)string;
677 
686 - (instancetype)initWithCharacters: (const OFUnichar *)characters
687  length: (size_t)length;
688 
696 - (instancetype)initWithUTF16String: (const OFChar16 *)string;
697 
707 - (instancetype)initWithUTF16String: (const OFChar16 *)string
708  length: (size_t)length;
709 
719 - (instancetype)initWithUTF16String: (const OFChar16 *)string
720  byteOrder: (OFByteOrder)byteOrder;
721 
733 - (instancetype)initWithUTF16String: (const OFChar16 *)string
734  length: (size_t)length
735  byteOrder: (OFByteOrder)byteOrder;
736 
743 - (instancetype)initWithUTF32String: (const OFChar32 *)string;
744 
753 - (instancetype)initWithUTF32String: (const OFChar32 *)string
754  length: (size_t)length;
755 
764 - (instancetype)initWithUTF32String: (const OFChar32 *)string
765  byteOrder: (OFByteOrder)byteOrder;
766 
777 - (instancetype)initWithUTF32String: (const OFChar32 *)string
778  length: (size_t)length
779  byteOrder: (OFByteOrder)byteOrder;
780 
794 - (instancetype)initWithFormat: (OFConstantString *)format, ...;
795 
810 - (instancetype)initWithFormat: (OFConstantString *)format
811  arguments: (va_list)arguments;
812 
813 #ifdef OF_HAVE_FILES
814 
822 - (instancetype)initWithContentsOfFile: (OFString *)path;
823 
833 - (instancetype)initWithContentsOfFile: (OFString *)path
834  encoding: (OFStringEncoding)encoding;
835 #endif
836 
851 - (instancetype)initWithContentsOfIRI: (OFIRI *)IRI;
852 
862 - (instancetype)initWithContentsOfIRI: (OFIRI *)IRI
863  encoding: (OFStringEncoding)encoding;
864 
878 - (size_t)getCString: (char *)cString
879  maxLength: (size_t)maxLength
880  encoding: (OFStringEncoding)encoding;
881 
894 - (size_t)getLossyCString: (char *)cString
895  maxLength: (size_t)maxLength
896  encoding: (OFStringEncoding)encoding;
897 
910 - (const char *)cStringWithEncoding: (OFStringEncoding)encoding;
911 
924 - (const char *)lossyCStringWithEncoding: (OFStringEncoding)encoding;
925 
937 - (const char *)insecureCStringWithEncoding: (OFStringEncoding)encoding;
938 
948 - (size_t)cStringLengthWithEncoding: (OFStringEncoding)encoding;
949 
956 - (OFComparisonResult)compare: (OFString *)string;
957 
964 - (OFComparisonResult)caseInsensitiveCompare: (OFString *)string;
965 
972 - (OFUnichar)characterAtIndex: (size_t)index;
973 
981 - (void)getCharacters: (OFUnichar *)buffer inRange: (OFRange)range;
982 
990 - (OFRange)rangeOfString: (OFString *)string;
991 
1000 - (OFRange)rangeOfString: (OFString *)string
1001  options: (OFStringSearchOptions)options;
1002 
1012 - (OFRange)rangeOfString: (OFString *)string
1013  options: (OFStringSearchOptions)options
1014  range: (OFRange)range;
1015 
1023 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet;
1024 
1033 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1034  options: (OFStringSearchOptions)options;
1035 
1045 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
1046  options: (OFStringSearchOptions)options
1047  range: (OFRange)range;
1048 
1055 - (bool)containsString: (OFString *)string;
1056 
1063 - (OFString *)substringFromIndex: (size_t)idx;
1064 
1071 - (OFString *)substringToIndex: (size_t)idx;
1072 
1079 - (OFString *)substringWithRange: (OFRange)range;
1080 
1100 - (long long)longLongValueWithBase: (unsigned char)base;
1101 
1124 - (unsigned long long)unsignedLongLongValueWithBase: (unsigned char)base;
1125 
1132 - (OFString *)stringByAppendingString: (OFString *)string;
1133 
1143 - (OFString *)stringByAppendingFormat: (OFConstantString *)format, ...;
1144 
1155 - (OFString *)stringByAppendingFormat: (OFConstantString *)format
1156  arguments: (va_list)arguments;
1157 
1166 - (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1167  withString: (OFString *)replacement;
1168 
1181 - (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1182  withString: (OFString *)replacement
1183  options: (int)options
1184  range: (OFRange)range;
1185 
1192 - (bool)hasPrefix: (OFString *)prefix;
1193 
1200 - (bool)hasSuffix: (OFString *)suffix;
1201 
1209 - (OFArray OF_GENERIC(OFString *) *)
1210  componentsSeparatedByString: (OFString *)delimiter;
1211 
1220 - (OFArray OF_GENERIC(OFString *) *)
1221  componentsSeparatedByString: (OFString *)delimiter
1222  options: (OFStringSeparationOptions)options;
1223 
1231 - (OFArray OF_GENERIC(OFString *) *)
1232  componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet;
1233 
1242 - (OFArray OF_GENERIC(OFString *) *)
1243  componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet
1244  options: (OFStringSeparationOptions)options;
1245 
1259 - (const OFChar16 *)UTF16StringWithByteOrder: (OFByteOrder)byteOrder;
1260 
1273 - (const OFChar32 *)UTF32StringWithByteOrder: (OFByteOrder)byteOrder;
1274 
1283 - (OFData *)dataWithEncoding: (OFStringEncoding)encoding;
1284 
1285 #ifdef OF_HAVE_FILES
1286 
1291 - (void)writeToFile: (OFString *)path;
1292 
1302 - (void)writeToFile: (OFString *)path encoding: (OFStringEncoding)encoding;
1303 #endif
1304 
1310 - (void)writeToIRI: (OFIRI *)IRI;
1311 
1320 - (void)writeToIRI: (OFIRI *)IRI encoding: (OFStringEncoding)encoding;
1321 
1322 #ifdef OF_HAVE_BLOCKS
1323 
1328 - (void)enumerateLinesUsingBlock: (OFStringLineEnumerationBlock)block;
1329 #endif
1330 @end
1331 
1332 #ifdef __cplusplus
1333 extern "C" {
1334 #endif
1335 
1346 
1353 extern OFString *_Nullable OFStringEncodingName(OFStringEncoding encoding);
1354 
1361 extern size_t OFUTF16StringLength(const OFChar16 *string);
1362 
1369 extern size_t OFUTF32StringLength(const OFChar32 *string);
1370 #ifdef __cplusplus
1371 }
1372 #endif
1373 
1374 OF_ASSUME_NONNULL_END
1375 
1376 #import "OFConstantString.h"
1377 #import "OFMutableString.h"
1378 #import "OFString+CryptographicHashing.h"
1379 #import "OFString+JSONParsing.h"
1380 #ifdef OF_HAVE_FILES
1381 # import "OFString+PathAdditions.h"
1382 #endif
1383 #import "OFString+PercentEncoding.h"
1384 #import "OFString+PropertyListParsing.h"
1385 #import "OFString+XMLEscaping.h"
1386 #import "OFString+XMLUnescaping.h"
1387 
1388 #if !defined(NSINTEGER_DEFINED) && !__has_feature(modules)
1389 /*
1390  * Very *ugly* hack required for string boxing literals to work.
1391  *
1392  * This hack is needed in order to work with `@class NSString` from Apple's
1393  * objc/NSString.h - which is included when using modules - as
1394  * @compatibility_alias does not work if @class has been used before.
1395  * For some reason, this makes Clang refer to OFString for string box literals
1396  * and not to NSString (which would result in a linker error, but would be the
1397  * correct behavior).
1398  *
1399  * TODO: Submit a patch for Clang that makes the boxing classes configurable!
1400  */
1401 @interface NSString: OFString
1402 @end
1403 #endif
OFStringSeparationOptions
Options for separating strings.
Definition: OFString.h:121
Definition: OFString.h:103
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:902
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:282
OFString * capitalizedString
The string in capitalized form.
Definition: OFString.h:180
OFString * stringByDeletingEnclosingWhitespaces
The string with leading and trailing whitespaces deleted.
Definition: OFString.h:275
size_t OFUTF32StringLength(const OFChar32 *string)
Returns the length of the specified UTF-32 string.
Definition: OFString.m:360
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:166
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:168
OFString * stringByDeletingTrailingWhitespaces
The string with trailing whitespaces deleted.
Definition: OFString.h:270
Definition: OFString.h:123
Definition: OFString.h:113
const OFUnichar * characters
The string as an array of Unicode characters.
Definition: OFString.h:233
A protocol implemented by classes that support encoding to a JSON representation. ...
Definition: OFJSONRepresentation.h:49
A class for handling strings.
Definition: OFString.h:142
Definition: OFString.h:87
const OFChar32 * UTF32String
The string in UTF-32 encoding with native byte order.
Definition: OFString.h:260
OFString * lowercaseString
The string in lowercase.
Definition: OFString.h:171
size_t OFUTF16StringLength(const OFChar16 *string)
Returns the length of the specified UTF-16 string.
Definition: OFString.m:349
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:244
Definition: OFString.h:71
Definition: OFString.h:101
OFByteOrder
An enum for representing endianness.
Definition: OFObject.h:92
Definition: OFString.h:77
Definition: OFString.h:99
size_t UTF16StringLength
The length of the string in UTF-16 characters.
Definition: OFString.h:249
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:265
size_t UTF8StringLength
The number of bytes the string needs in UTF-8 encoding.
Definition: OFString.h:161
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:193
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:147
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:134
const char * UTF8String
The OFString as a UTF-8 encoded C string.
Definition: OFString.h:156
double doubleValue
The double value of the string as a double.
Definition: OFString.h:222
float floatValue
The float value of the string as a float.
Definition: OFString.h:214
instancetype string()
Creates a new OFString.
Definition: OFString.m:736
unsigned long long unsignedLongLongValue
The decimal value of the string as an unsigned long long.
Definition: OFString.h:206
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:111
OFString * OFStringEncodingName(OFStringEncoding encoding)
Returns the name of the specified OFStringEncoding.
Definition: OFString.m:230