ObjFW
OFString.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2008-2021 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 OBJFW_OF_STRING_H
17 #define OBJFW_OF_STRING_H
18 
19 #ifndef __STDC_LIMIT_MACROS
20 # define __STDC_LIMIT_MACROS
21 #endif
22 #ifndef __STDC_CONSTANT_MACROS
23 # define __STDC_CONSTANT_MACROS
24 #endif
25 
26 #include "objfw-defs.h"
27 
28 #ifdef OF_HAVE_SYS_TYPES_H
29 # include <sys/types.h>
30 #endif
31 
32 #include <stdarg.h>
33 #include <stdint.h>
34 #ifdef OF_HAVE_INTTYPES_H
35 # include <inttypes.h>
36 #endif
37 
38 #include "OFObject.h"
39 #ifdef __OBJC__
40 # import "OFSerialization.h"
41 # import "OFJSONRepresentation.h"
42 # import "OFMessagePackRepresentation.h"
43 #endif
44 
45 OF_ASSUME_NONNULL_BEGIN
46 
49 #ifdef __OBJC__
50 @class OFConstantString;
51 @class OFString;
52 #else
53 typedef void OFString;
54 #endif
55 
56 #if defined(__cplusplus) && __cplusplus >= 201103L
57 typedef char16_t of_char16_t;
58 typedef char32_t of_char32_t;
59 #else
60 typedef uint_least16_t of_char16_t;
61 typedef uint_least32_t of_char32_t;
62 #endif
63 typedef of_char32_t of_unichar_t;
64 
68 typedef enum of_string_encoding_t {
69  /*
70  * UTF-8 *has* to be 0, so that if the current @ref OFLocale is
71  * `nil`, `[OFLocale encoding]` returns UTF-8.
72  */
104 
105 enum {
106  OF_STRING_SEARCH_BACKWARDS = 1,
107  OF_STRING_SKIP_EMPTY = 2
108 };
109 
110 #ifdef OF_HAVE_BLOCKS
118 typedef void (^of_string_line_enumeration_block_t)(OFString *line, bool *stop);
119 #endif
120 
121 #ifdef __OBJC__
122 @class OFArray OF_GENERIC(ObjectType);
123 @class OFCharacterSet;
124 @class OFURL;
125 
136 @property (readonly, nonatomic) size_t length;
137 
145 @property (readonly, nonatomic) const char *UTF8String OF_RETURNS_INNER_POINTER;
146 
150 @property (readonly, nonatomic) size_t UTF8StringLength;
151 
155 @property (readonly, nonatomic) OFString *uppercaseString;
156 
160 @property (readonly, nonatomic) OFString *lowercaseString;
161 
169 @property (readonly, nonatomic) OFString *capitalizedString;
170 
182 @property (readonly, nonatomic) long long longLongValue;
183 
195 @property (readonly, nonatomic) unsigned long long unsignedLongLongValue;
196 
203 @property (readonly, nonatomic) float floatValue;
204 
211 @property (readonly, nonatomic) double doubleValue;
212 
220 @property (readonly, nonatomic) const of_unichar_t *characters
221  OF_RETURNS_INNER_POINTER;
222 
230 @property (readonly, nonatomic) const of_char16_t *UTF16String
231  OF_RETURNS_INNER_POINTER;
232 
236 @property (readonly, nonatomic) size_t UTF16StringLength;
237 
245 @property (readonly, nonatomic) const of_char32_t *UTF32String
246  OF_RETURNS_INNER_POINTER;
247 
251 @property (readonly, nonatomic) OFString *stringByDeletingLeadingWhitespaces;
252 
256 @property (readonly, nonatomic) OFString *stringByDeletingTrailingWhitespaces;
257 
261 @property (readonly, nonatomic) OFString *stringByDeletingEnclosingWhitespaces;
262 
263 # ifdef OF_HAVE_UNICODE_TABLES
267 @property (readonly, nonatomic) OFString *decomposedStringWithCanonicalMapping;
268 
272 @property (readonly, nonatomic)
274 # endif
275 
276 # ifdef OF_WINDOWS
280 @property (readonly, nonatomic)
281  OFString *stringByExpandingWindowsEnvironmentStrings;
282 # endif
283 
289 + (instancetype)string;
290 
297 + (instancetype)stringWithUTF8String: (const char *)UTF8String;
298 
307 + (instancetype)stringWithUTF8String: (const char *)UTF8String
308  length: (size_t)UTF8StringLength;
309 
324 + (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
325  freeWhenDone: (bool)freeWhenDone;
326 
342 + (instancetype)stringWithUTF8StringNoCopy: (char *)UTF8String
343  length: (size_t)UTF8StringLength
344  freeWhenDone: (bool)freeWhenDone;
345 
353 + (instancetype)stringWithCString: (const char *)cString
354  encoding: (of_string_encoding_t)encoding;
355 
365 + (instancetype)stringWithCString: (const char *)cString
366  encoding: (of_string_encoding_t)encoding
367  length: (size_t)cStringLength;
368 
376 + (instancetype)stringWithData: (OFData *)data
377  encoding: (of_string_encoding_t)encoding;
378 
385 + (instancetype)stringWithString: (OFString *)string;
386 
395 + (instancetype)stringWithCharacters: (const of_unichar_t *)characters
396  length: (size_t)length;
397 
404 + (instancetype)stringWithUTF16String: (const of_char16_t *)string;
405 
414 + (instancetype)stringWithUTF16String: (const of_char16_t *)string
415  length: (size_t)length;
416 
425 + (instancetype)stringWithUTF16String: (const of_char16_t *)string
426  byteOrder: (of_byte_order_t)byteOrder;
427 
438 + (instancetype)stringWithUTF16String: (const of_char16_t *)string
439  length: (size_t)length
440  byteOrder: (of_byte_order_t)byteOrder;
441 
448 + (instancetype)stringWithUTF32String: (const of_char32_t *)string;
449 
458 + (instancetype)stringWithUTF32String: (const of_char32_t *)string
459  length: (size_t)length;
460 
469 + (instancetype)stringWithUTF32String: (const of_char32_t *)string
470  byteOrder: (of_byte_order_t)byteOrder;
471 
482 + (instancetype)stringWithUTF32String: (const of_char32_t *)string
483  length: (size_t)length
484  byteOrder: (of_byte_order_t)byteOrder;
485 
496 + (instancetype)stringWithFormat: (OFConstantString *)format, ...;
497 
498 # ifdef OF_HAVE_FILES
506 + (instancetype)stringWithContentsOfFile: (OFString *)path;
507 
516 + (instancetype)stringWithContentsOfFile: (OFString *)path
517  encoding: (of_string_encoding_t)encoding;
518 # endif
519 
532 + (instancetype)stringWithContentsOfURL: (OFURL *)URL;
533 
542 + (instancetype)stringWithContentsOfURL: (OFURL *)URL
543  encoding: (of_string_encoding_t)encoding;
544 
552 - (instancetype)initWithUTF8String: (const char *)UTF8String;
553 
562 - (instancetype)initWithUTF8String: (const char *)UTF8String
563  length: (size_t)UTF8StringLength;
564 
579 - (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
580  freeWhenDone: (bool)freeWhenDone;
581 
598 - (instancetype)initWithUTF8StringNoCopy: (char *)UTF8String
599  length: (size_t)UTF8StringLength
600  freeWhenDone: (bool)freeWhenDone;
601 
610 - (instancetype)initWithCString: (const char *)cString
611  encoding: (of_string_encoding_t)encoding;
612 
622 - (instancetype)initWithCString: (const char *)cString
623  encoding: (of_string_encoding_t)encoding
624  length: (size_t)cStringLength;
625 
634 - (instancetype)initWithData: (OFData *)data
635  encoding: (of_string_encoding_t)encoding;
636 
643 - (instancetype)initWithString: (OFString *)string;
644 
653 - (instancetype)initWithCharacters: (const of_unichar_t *)characters
654  length: (size_t)length;
655 
662 - (instancetype)initWithUTF16String: (const of_char16_t *)string;
663 
672 - (instancetype)initWithUTF16String: (const of_char16_t *)string
673  length: (size_t)length;
674 
683 - (instancetype)initWithUTF16String: (const of_char16_t *)string
684  byteOrder: (of_byte_order_t)byteOrder;
685 
696 - (instancetype)initWithUTF16String: (const of_char16_t *)string
697  length: (size_t)length
698  byteOrder: (of_byte_order_t)byteOrder;
699 
706 - (instancetype)initWithUTF32String: (const of_char32_t *)string;
707 
716 - (instancetype)initWithUTF32String: (const of_char32_t *)string
717  length: (size_t)length;
718 
727 - (instancetype)initWithUTF32String: (const of_char32_t *)string
728  byteOrder: (of_byte_order_t)byteOrder;
729 
740 - (instancetype)initWithUTF32String: (const of_char32_t *)string
741  length: (size_t)length
742  byteOrder: (of_byte_order_t)byteOrder;
743 
754 - (instancetype)initWithFormat: (OFConstantString *)format, ...;
755 
767 - (instancetype)initWithFormat: (OFConstantString *)format
768  arguments: (va_list)arguments;
769 
770 # ifdef OF_HAVE_FILES
778 - (instancetype)initWithContentsOfFile: (OFString *)path;
779 
788 - (instancetype)initWithContentsOfFile: (OFString *)path
789  encoding: (of_string_encoding_t)encoding;
790 # endif
791 
805 - (instancetype)initWithContentsOfURL: (OFURL *)URL;
806 
815 - (instancetype)initWithContentsOfURL: (OFURL *)URL
816  encoding: (of_string_encoding_t)encoding;
817 
829 - (size_t)getCString: (char *)cString
830  maxLength: (size_t)maxLength
831  encoding: (of_string_encoding_t)encoding;
832 
845 - (size_t)getLossyCString: (char *)cString
846  maxLength: (size_t)maxLength
847  encoding: (of_string_encoding_t)encoding;
848 
859 - (const char *)cStringWithEncoding: (of_string_encoding_t)encoding
860  OF_RETURNS_INNER_POINTER;
861 
874 - (const char *)lossyCStringWithEncoding: (of_string_encoding_t)encoding
875  OF_RETURNS_INNER_POINTER;
876 
884 - (size_t)cStringLengthWithEncoding: (of_string_encoding_t)encoding;
885 
893 - (of_comparison_result_t)caseInsensitiveCompare: (OFString *)otherString;
894 
901 - (of_unichar_t)characterAtIndex: (size_t)index;
902 
910 - (void)getCharacters: (of_unichar_t *)buffer inRange: (of_range_t)range;
911 
919 - (of_range_t)rangeOfString: (OFString *)string;
920 
933 - (of_range_t)rangeOfString: (OFString *)string options: (int)options;
934 
948 - (of_range_t)rangeOfString: (OFString *)string
949  options: (int)options
950  range: (of_range_t)range;
951 
959 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet;
960 
973 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
974  options: (int)options;
975 
989 - (size_t)indexOfCharacterFromSet: (OFCharacterSet *)characterSet
990  options: (int)options
991  range: (of_range_t)range;
992 
999 - (bool)containsString: (OFString *)string;
1000 
1007 - (OFString *)substringFromIndex: (size_t)idx;
1008 
1015 - (OFString *)substringToIndex: (size_t)idx;
1016 
1023 - (OFString *)substringWithRange: (of_range_t)range;
1024 
1042 - (long long)longLongValueWithBase: (int)base;
1043 
1062 - (unsigned long long)unsignedLongLongValueWithBase: (int)base;
1063 
1070 - (OFString *)stringByAppendingString: (OFString *)string;
1071 
1078 - (OFString *)stringByAppendingFormat: (OFConstantString *)format, ...;
1079 
1087 - (OFString *)stringByAppendingFormat: (OFConstantString *)format
1088  arguments: (va_list)arguments;
1089 
1096 - (OFString *)stringByPrependingString: (OFString *)string;
1097 
1106 - (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1107  withString: (OFString *)replacement;
1108 
1121 - (OFString *)stringByReplacingOccurrencesOfString: (OFString *)string
1122  withString: (OFString *)replacement
1123  options: (int)options
1124  range: (of_range_t)range;
1125 
1132 - (bool)hasPrefix: (OFString *)prefix;
1133 
1140 - (bool)hasSuffix: (OFString *)suffix;
1141 
1149 - (OFArray OF_GENERIC(OFString *) *)
1150  componentsSeparatedByString: (OFString *)delimiter;
1151 
1164 - (OFArray OF_GENERIC(OFString *) *)
1165  componentsSeparatedByString: (OFString *)delimiter
1166  options: (int)options;
1167 
1175 - (OFArray OF_GENERIC(OFString *) *)
1176  componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet;
1177 
1190 - (OFArray OF_GENERIC(OFString *) *)
1191  componentsSeparatedByCharactersInSet: (OFCharacterSet *)characterSet
1192  options: (int)options;
1193 
1204 - (const of_char16_t *)UTF16StringWithByteOrder: (of_byte_order_t)byteOrder
1205  OF_RETURNS_INNER_POINTER;
1206 
1217 - (const of_char32_t *)UTF32StringWithByteOrder: (of_byte_order_t)byteOrder
1218  OF_RETURNS_INNER_POINTER;
1219 
1226 - (OFData *)dataWithEncoding: (of_string_encoding_t)encoding;
1227 
1228 # ifdef OF_HAVE_FILES
1234 - (void)writeToFile: (OFString *)path;
1235 
1243 - (void)writeToFile: (OFString *)path encoding: (of_string_encoding_t)encoding;
1244 # endif
1245 
1251 - (void)writeToURL: (OFURL *)URL;
1252 
1259 - (void)writeToURL: (OFURL *)URL encoding: (of_string_encoding_t)encoding;
1260 
1261 # ifdef OF_HAVE_BLOCKS
1267 - (void)enumerateLinesUsingBlock: (of_string_line_enumeration_block_t)block;
1268 # endif
1269 @end
1270 #endif
1271 
1272 #ifdef __cplusplus
1273 extern "C" {
1274 #endif
1275 extern of_string_encoding_t of_string_parse_encoding(OFString *);
1276 extern OFString *_Nullable of_string_name_of_encoding(of_string_encoding_t);
1277 extern size_t of_string_utf8_encode(of_unichar_t, char *);
1278 extern ssize_t of_string_utf8_decode(const char *, size_t, of_unichar_t *);
1279 extern size_t of_string_utf16_length(const of_char16_t *);
1280 extern size_t of_string_utf32_length(const of_char32_t *);
1281 #ifdef __cplusplus
1282 }
1283 #endif
1284 
1285 OF_ASSUME_NONNULL_END
1286 
1287 #include "OFConstantString.h"
1288 #include "OFMutableString.h"
1289 #ifdef __OBJC__
1290 # import "OFString+CryptoHashing.h"
1291 # import "OFString+JSONParsing.h"
1292 # ifdef OF_HAVE_FILES
1293 # import "OFString+PathAdditions.h"
1294 # endif
1295 # import "OFString+PropertyListParsing.h"
1296 # import "OFString+Serialization.h"
1297 # import "OFString+URLEncoding.h"
1298 # import "OFString+XMLEscaping.h"
1299 # import "OFString+XMLUnescaping.h"
1300 #endif
1301 
1302 #if defined(__OBJC__) && !defined(NSINTEGER_DEFINED) && !__has_feature(modules)
1303 /*
1304  * Very *ugly* hack required for string boxing literals to work.
1305  *
1306  * This hack is needed in order to work with `@class NSString` from Apple's
1307  * objc/NSString.h - which is included when using modules - as
1308  * @compatibility_alias does not work if @class has been used before.
1309  * For some reason, this makes Clang refer to OFString for string box literals
1310  * and not to NSString (which would result in a linker error, but would be the
1311  * correct behavior).
1312  *
1313  * TODO: Submit a patch for Clang that makes the boxing classes configurable!
1314  */
1315 @interface NSString: OFString
1316 @end
1317 #endif
1318 
1319 #endif
of_byte_order_t
An enum for storing endianess.
Definition: OFObject.h:81
of_comparison_result_t
A result of a comparison.
Definition: OFObject.h:57
void(^ of_string_line_enumeration_block_t)(OFString *line, bool *stop)
A block for enumerating the lines of a string.
Definition: OFString.h:118
of_string_encoding_t
The encoding of a string.
Definition: OFString.h:68
@ OF_STRING_ENCODING_KOI8_R
Definition: OFString.h:98
@ OF_STRING_ENCODING_UTF_8
Definition: OFString.h:74
@ OF_STRING_ENCODING_ISO_8859_3
Definition: OFString.h:82
@ OF_STRING_ENCODING_MAC_ROMAN
Definition: OFString.h:96
@ OF_STRING_ENCODING_ISO_8859_15
Definition: OFString.h:84
@ OF_STRING_ENCODING_WINDOWS_1252
Definition: OFString.h:88
@ OF_STRING_ENCODING_KOI8_U
Definition: OFString.h:100
@ OF_STRING_ENCODING_ISO_8859_1
Definition: OFString.h:78
@ OF_STRING_ENCODING_ISO_8859_2
Definition: OFString.h:80
@ OF_STRING_ENCODING_ASCII
Definition: OFString.h:76
@ OF_STRING_ENCODING_CODEPAGE_858
Definition: OFString.h:94
@ OF_STRING_ENCODING_CODEPAGE_850
Definition: OFString.h:92
@ OF_STRING_ENCODING_CODEPAGE_437
Definition: OFString.h:90
@ OF_STRING_ENCODING_AUTODETECT
Definition: OFString.h:102
@ OF_STRING_ENCODING_WINDOWS_1251
Definition: OFString.h:86
An abstract class for storing objects in an array.
Definition: OFArray.h:92
A class cluster representing a character set.
Definition: OFCharacterSet.h:29
A class for storing constant strings using the @"" literal.
Definition: OFConstantString.h:42
A class for storing arbitrary data in an array.
Definition: OFData.h:40
The root class for all other classes inside ObjFW.
Definition: OFObject.h:520
A class for handling strings.
Definition: OFString.h:132
const of_unichar_t * characters
The string as an array of Unicode characters.
Definition: OFString.h:221
OFString * stringByDeletingEnclosingWhitespaces
The string with leading and trailing whitespaces deleted.
Definition: OFString.h:261
const char * UTF8String
The OFString as a UTF-8 encoded C string.
Definition: OFString.h:145
OFString * lowercaseString
The string in lowercase.
Definition: OFString.h:160
unsigned long long unsignedLongLongValue
The decimal value of the string as an unsigned long long.
Definition: OFString.h:195
size_t UTF16StringLength
The length of the string in UTF-16 characters.
Definition: OFString.h:236
double doubleValue
The double value of the string as a double.
Definition: OFString.h:211
OFString * decomposedStringWithCanonicalMapping
The string in Unicode Normalization Form D (NFD).
Definition: OFString.h:267
OFString * uppercaseString
The string in uppercase.
Definition: OFString.h:155
float floatValue
The float value of the string as a float.
Definition: OFString.h:203
OFString * stringByDeletingTrailingWhitespaces
The string with trailing whitespaces deleted.
Definition: OFString.h:256
size_t UTF8StringLength
The number of bytes the string needs in UTF-8 encoding.
Definition: OFString.h:150
const of_char16_t * UTF16String
The string in UTF-16 encoding with native byte order.
Definition: OFString.h:231
size_t length
The length of the string in Unicode codepoints.
Definition: OFString.h:136
const of_char32_t * UTF32String
The string in UTF-32 encoding with native byte order.
Definition: OFString.h:246
long long longLongValue
The decimal value of the string as a long long.
Definition: OFString.h:182
OFString * capitalizedString
The string in capitalized form.
Definition: OFString.h:169
OFString * decomposedStringWithCompatibilityMapping
The string in Unicode Normalization Form KD (NFKD).
Definition: OFString.h:273
instancetype string()
Creates a new OFString.
Definition: OFString.m:634
OFString * stringByDeletingLeadingWhitespaces
The string with leading whitespaces deleted.
Definition: OFString.h:251
A class for parsing URLs and accessing parts of it.
Definition: OFURL.h:34
A protocol for comparing objects.
Definition: OFObject.h:1224
A protocol for the creation of copies.
Definition: OFObject.h:1187
A protocol implemented by classes that support encoding to a JSON representation.
Definition: OFJSONRepresentation.h:39
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:1208
A protocol for serializing objects.
Definition: OFSerialization.h:29
A range.
Definition: OFObject.h:93