1 /* CFString.h
2
3 Copyright (C) 2010 Free Software Foundation, Inc.
4
5 Written by: Stefan Bidigaray
6 Date: January, 2010
7
8 This file is part of CoreBase.
9
10 This library is free software; you can redistribute it and/or
11 modify it under the terms of the GNU Lesser General Public
12 License as published by the Free Software Foundation; either
13 version 2.1 of the License, or (at your option) any later version.
14
15 This library is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public
21 License along with this library; see the file COPYING.LIB.
22 If not, see <http://www.gnu.org/licenses/> or write to the
23 Free Software Foundation, 51 Franklin Street, Fifth Floor,
24 Boston, MA 02110-1301, USA.
25 */
26
27 #ifndef __COREFOUNDATION_CFSTRING_H__
28 #define __COREFOUNDATION_CFSTRING_H__
29
30 #include "CFBase.h"
31 #include "CFArray.h"
32 #include "CFCharacterSet.h"
33 #include "CFData.h"
34 #include "CFDictionary.h"
35 #include "CFLocale.h"
36
37 #include <stdarg.h>
38
39 CF_EXTERN_C_BEGIN
40
41 /** \defgroup CFStringRef CFString Reference
42 \brief The CFString type defines opaque objects representing strings.
43
44 CFString is "toll-free bridged" to NSString.
45
46 \{
47 */
48
49 /*
50 * Data Types
51 */
52 typedef UInt32 CFStringEncoding;
53
54 /*
55 * Constants
56 */
57 typedef enum
58 {
59 kCFCompareCaseInsensitive = 1,
60 kCFCompareBackwards = 4,
61 kCFCompareAnchored = 8,
62 kCFCompareNonliteral = 16,
63 kCFCompareLocalized = 32,
64 kCFCompareNumerically = 64,
65 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
66 kCFCompareDiacriticInsensitive = 128,
67 kCFCompareWidthInsensitive = 256,
68 kCFCompareForcedOrdering = 512
69 #endif
70 } CFStringCompareFlags;
71
72 enum CFStringBuiltInEncodings
73 {
74 kCFStringEncodingMacRoman = 0,
75 kCFStringEncodingWindowsLatin1 = 0x0500,
76 kCFStringEncodingISOLatin1 = 0x0201,
77 kCFStringEncodingNextStepLatin = 0x0B01,
78 kCFStringEncodingASCII = 0x0600,
79 kCFStringEncodingUnicode = 0x0100,
80 kCFStringEncodingUTF8 = 0x08000100,
81 kCFStringEncodingNonLossyASCII = 0x0BFF,
82 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST)
83 kCFStringEncodingUTF16 = 0x0100,
84 kCFStringEncodingUTF16BE = 0x10000100,
85 kCFStringEncodingUTF16LE = 0x14000100,
86 kCFStringEncodingUTF32 = 0x0c000100,
87 kCFStringEncodingUTF32BE = 0x18000100,
88 kCFStringEncodingUTF32LE = 0x1c000100
89 #endif
90 };
91
92 #if OS_API_VERSION(MAC_OS_X_VERSION_10_2, GS_API_LATEST)
93 # define kCFStringEncodingInvalidId (0xffffffffU)
94 #endif
95
96 /** \def CFSTR(x)
97 \brief Creates a constant string object.
98
99 \note This macro will create the constant string at runtime.
100 */
101 /* The 'pure' attribute tells the compiler that this function will always
102 return the same result with the same input. If it has any skill, then
103 constant propagation passes will magically make sure that this function is
104 called as few times as possible. */
105 CF_EXPORT CFStringRef
106 __CFStringMakeConstantString (const char *str) GS_PURE_FUNCTION;
107 //#define CFSTR(x) __CFStringMakeConstantString("" x "")
108
109 #ifdef __CONSTANT_CFSTRINGS__
110 #define CFSTR(x) ((CFStringRef) __builtin___CFStringMakeConstantString ("" x ""))
111 #else
112 #define CFSTR(x) __CFStringMakeConstantString("" x "")
113 #endif
114
115 /** \name Creating a CFString
116 \{
117 */
118 CF_EXPORT CFArrayRef
119 CFStringCreateArrayBySeparatingStrings (CFAllocatorRef alloc,
120 CFStringRef theString, CFStringRef separatorString);
121
122 CF_EXPORT CFStringRef
123 CFStringCreateByCombiningStrings (CFAllocatorRef alloc, CFArrayRef theArray,
124 CFStringRef separatorString);
125
126 CF_EXPORT CFStringRef
127 CFStringCreateCopy (CFAllocatorRef alloc, CFStringRef theString);
128
129 CF_EXPORT CFStringRef
130 CFStringCreateFromExternalRepresentation (CFAllocatorRef alloc, CFDataRef data,
131 CFStringEncoding encoding);
132
133 CF_EXPORT CFStringRef
134 CFStringCreateWithBytes (CFAllocatorRef alloc, const UInt8 *bytes,
135 CFIndex numBytes, CFStringEncoding encoding, Boolean isExternalRepresentation);
136
137 CF_EXPORT CFStringRef
138 CFStringCreateWithCharacters (CFAllocatorRef alloc, const UniChar *chars,
139 CFIndex numChars);
140
141 CF_EXPORT CFStringRef
142 CFStringCreateWithCharactersNoCopy (CFAllocatorRef alloc, const UniChar *chars,
143 CFIndex numChars, CFAllocatorRef contentsDeallocator);
144
145 CF_EXPORT CFStringRef
146 CFStringCreateWithCString (CFAllocatorRef alloc, const char *cStr,
147 CFStringEncoding encoding);
148
149 CF_EXPORT CFStringRef
150 CFStringCreateWithCStringNoCopy (CFAllocatorRef alloc, const char *cStr,
151 CFStringEncoding encoding, CFAllocatorRef contentsDeallocator);
152
153 CF_EXPORT CFStringRef
154 CFStringCreateWithFormat (CFAllocatorRef alloc, CFDictionaryRef formatOptions,
155 CFStringRef format, ...);
156
157 CF_EXPORT CFStringRef
158 CFStringCreateWithFormatAndArguments (CFAllocatorRef alloc,
159 CFDictionaryRef formatOptions, CFStringRef format, va_list arguments);
160
161 CF_EXPORT CFStringRef
162 CFStringCreateWithSubstring (CFAllocatorRef alloc, CFStringRef str,
163 CFRange range);
164
165 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST)
166 CF_EXPORT CFStringRef
167 CFStringCreateWithFileSystemRepresentation (CFAllocatorRef alloc,
168 const char *buffer);
169 #endif
170
171 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
172 CF_EXPORT CFStringRef
173 CFStringCreateWithBytesNoCopy (CFAllocatorRef alloc, const UInt8 *bytes,
174 CFIndex numBytes, CFStringEncoding encoding, Boolean isExternalReprentation,
175 CFAllocatorRef contentsDeallocator);
176 #endif
177 /** \} */
178
179 /** \name Searching CFStrings
180 \{
181 */
182 CF_EXPORT CFArrayRef
183 CFStringCreateArrayWithFindResults (CFAllocatorRef alloc, CFStringRef theString,
184 CFStringRef stringToFind, CFRange rangeToSearch,
185 CFStringCompareFlags compareOptions);
186
187 CF_EXPORT CFRange
188 CFStringFind (CFStringRef theString, CFStringRef stringToFind,
189 CFStringCompareFlags compareOptions);
190
191 CF_EXPORT Boolean
192 CFStringFindWithOptions (CFStringRef theString, CFStringRef stringToFind,
193 CFRange rangeToSearch, CFStringCompareFlags searchOptions, CFRange *result);
194
195 CF_EXPORT Boolean
196 CFStringFindWithOptionsAndLocale (CFStringRef theString,CFStringRef stringToFind,
197 CFRange rangeToSearch, CFStringCompareFlags searchOptions,
198 CFLocaleRef locale, CFRange *result);
199
200 CF_EXPORT void
201 CFStringGetLineBounds (CFStringRef theString, CFRange range,
202 CFIndex *lineBeginIndex, CFIndex *lineEndIndex, CFIndex *contentsEndIndex);
203
204 #if OS_API_VERSION(MAC_OS_X_VERSION_10_2, GS_API_LATEST)
205 CF_EXPORT Boolean
206 CFStringFindCharacterFromSet (CFStringRef theString, CFCharacterSetRef theSet,
207 CFRange rangeToSearch, CFStringCompareFlags searchOptions, CFRange *result);
208 #endif
209
210 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
211 CF_EXPORT void
212 CFStringGetParagraphBounds (CFStringRef string, CFRange range,
213 CFIndex *parBeginIndex, CFIndex *parEndIndex, CFIndex *contentsEndIndex);
214 #endif
215 /** \} */
216
217 /** \name Comparing String
218 \{
219 */
220 CF_EXPORT CFComparisonResult
221 CFStringCompare (CFStringRef theString1, CFStringRef theString2,
222 CFStringCompareFlags compareOptions);
223
224 CF_EXPORT CFComparisonResult
225 CFStringCompareWithOptions (CFStringRef theString1, CFStringRef theString2,
226 CFRange rangeToCOmpare, CFStringCompareFlags compareOptions);
227
228 CF_EXPORT Boolean
229 CFStringHasPrefix (CFStringRef theString, CFStringRef prefix);
230
231 CF_EXPORT Boolean
232 CFStringHasSuffix (CFStringRef theString, CFStringRef suffix);
233
234 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
235 CF_EXPORT CFComparisonResult
236 CFStringCompareWithOptionsAndLocale (CFStringRef theString1,
237 CFStringRef theString2, CFRange rangeToCOmpare,
238 CFStringCompareFlags compareOptions, CFLocaleRef locale);
239 #endif
240 /** \} */
241
242 /** \name Accessing Characters
243 \{
244 */
245 CF_EXPORT CFDataRef
246 CFStringCreateExternalRepresentation (CFAllocatorRef alloc,
247 CFStringRef theString, CFStringEncoding encoding, UInt8 lossByte);
248
249 CF_EXPORT CFIndex
250 CFStringGetBytes (CFStringRef theString, CFRange range,
251 CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation,
252 UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen);
253
254 CF_EXPORT UniChar
255 CFStringGetCharacterAtIndex (CFStringRef theString, CFIndex idx);
256
257 CF_EXPORT void
258 CFStringGetCharacters (CFStringRef theString, CFRange range, UniChar *buffer);
259
260 CF_EXPORT const UniChar *
261 CFStringGetCharactersPtr (CFStringRef theString);
262
263 CF_EXPORT Boolean
264 CFStringGetCString (CFStringRef theString, char *buffer, CFIndex bufferSize,
265 CFStringEncoding encoding);
266
267 CF_EXPORT const char *
268 CFStringGetCStringPtr (CFStringRef theString, CFStringEncoding encoding);
269
270 CF_EXPORT CFIndex
271 CFStringGetLength (CFStringRef str);
272
273 CF_EXPORT CFRange
274 CFStringGetRangeOfComposedCharactersAtIndex (CFStringRef theString,
275 CFIndex theIndex);
276
277 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST)
278 CF_EXPORT UTF32Char
279 CFStringGetLongCharacterForSurrogatePair (UniChar surrogateHigh,
280 UniChar surrogateLow);
281
282 CF_EXPORT Boolean
283 CFStringGetSurrogatePairForLongCharacter (UTF32Char character,
284 UniChar *surrogates);
285
286 CF_EXPORT Boolean
287 CFStringIsSurrogateHighCharacter (UniChar character);
288
289 CF_EXPORT Boolean
290 CFStringIsSurrogateLowCharacter (UniChar character);
291 #endif
292 /** \} */
293
294 /** \name Working with Encodings
295 \{
296 */
297 CF_EXPORT CFStringRef
298 CFStringConvertEncodingToIANACharSetName (CFStringEncoding encoding);
299
300 CF_EXPORT unsigned long
301 CFStringConvertEncodingToNSStringEncoding (CFStringEncoding encoding);
302
303 UInt32
304 CFStringConvertEncodingToWindowsCodepage (CFStringEncoding encoding);
305
306 CF_EXPORT CFStringEncoding
307 CFStringConvertIANACharSetNameToEncoding (CFStringRef theString);
308
309 CF_EXPORT CFStringEncoding
310 CFStringConvertNSStringEncodingToEncoding (unsigned long encoding);
311
312 CF_EXPORT CFStringEncoding
313 CFStringConvertWindowsCodepageToEncoding (UInt32 codepage);
314
315 CF_EXPORT CFStringEncoding
316 CFStringGetFastestEncoding (CFStringRef theString);
317
318 CF_EXPORT const CFStringEncoding *
319 CFStringGetListOfAvailableEncodings (void);
320
321 CF_EXPORT CFIndex
322 CFStringGetMaximumSizeForEncoding (CFIndex length, CFStringEncoding encoding);
323
324 CF_EXPORT CFStringEncoding
325 CFStringGetMostCompatibleMacStringEncoding (CFStringEncoding encoding);
326
327 CF_EXPORT CFStringRef
328 CFStringGetNameOfEncoding (CFStringEncoding encoding);
329
330 CF_EXPORT CFStringEncoding
331 CFStringGetSmallestEncoding (CFStringRef theString);
332
333 CF_EXPORT CFStringEncoding
334 CFStringGetSystemEncoding (void);
335
336 CF_EXPORT Boolean
337 CFStringIsEncodingAvailable (CFStringEncoding encoding);
338
339 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST)
340 CF_EXPORT Boolean
341 CFStringGetFileSystemRepresentation (CFStringRef string, char *buffer,
342 CFIndex maxBufLen);
343
344 CF_EXPORT CFIndex
345 CFStringGetMaximumSizeOfFileSystemRepresentation (CFStringRef string);
346 #endif
347 /** \} */
348
349 /** \name Getting Numeric Values
350 \{
351 */
352 CF_EXPORT double
353 CFStringGetDoubleValue (CFStringRef str);
354
355 CF_EXPORT SInt32
356 CFStringGetIntValue (CFStringRef str);
357 /** \} */
358
359 /** \name Getting String Properties
360 \{
361 */
362 CF_EXPORT void
363 CFShow (CFTypeRef obj);
364
365 CF_EXPORT void
366 CFShowStr (CFStringRef str);
367
368 CF_EXPORT CFTypeID
369 CFStringGetTypeID (void);
370 /** \} */
371
372
373
374 /** \name Pascal Strings
375 \{
376 */
377 CF_EXPORT CFStringRef
378 CFStringCreateWithPascalString (CFAllocatorRef alloc, ConstStr255Param pStr,
379 CFStringEncoding encoding);
380
381 CF_EXPORT CFStringRef
382 CFStringCreateWithPascalStringNoCopy (CFAllocatorRef alloc,
383 ConstStr255Param pStr, CFStringEncoding encoding,
384 CFAllocatorRef contentsDeallocate);
385
386 CF_EXPORT Boolean
387 CFStringGetPascalString (CFStringRef theString, StringPtr buffer,
388 CFIndex bufferSize, CFStringEncoding encoding);
389
390 CF_EXPORT ConstStringPtr
391 CFStringGetPascalStringPtr (CFStringRef theString, CFStringEncoding encoding);
392 /** \} */
393 /** \} */
394
395
396
397 /** \defgroup CFMutableStringRef CFMutableString Reference
398 * \{
399 */
400 #if OS_API_VERSION(MAC_OS_X_VERSION_10_2, GS_API_LATEST)
401 typedef enum
402 {
403 kCFStringNormalizationFormD = 0,
404 kCFStringNormalizationFormKD = 1,
405 kCFStringNormalizationFormC = 2,
406 kCFStringNormalizationFormKC = 3
407 } CFStringNormalizationForm;
408 #endif
409
410 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST)
411 CF_EXPORT const CFStringRef kCFStringTransformStripCombiningMarks;
412 CF_EXPORT const CFStringRef kCFStringTransformToLatin;
413 CF_EXPORT const CFStringRef kCFStringTransformFullwidthHalfwidth;
414 CF_EXPORT const CFStringRef kCFStringTransformLatinKatakana;
415 CF_EXPORT const CFStringRef kCFStringTransformLatinHiragana;
416 CF_EXPORT const CFStringRef kCFStringTransformHiraganaKatakana;
417 CF_EXPORT const CFStringRef kCFStringTransformMandarinLatin;
418 CF_EXPORT const CFStringRef kCFStringTransformLatinHangul;
419 CF_EXPORT const CFStringRef kCFStringTransformLatinArabic;
420 CF_EXPORT const CFStringRef kCFStringTransformLatinHebrew;
421 CF_EXPORT const CFStringRef kCFStringTransformLatinThai;
422 CF_EXPORT const CFStringRef kCFStringTransformLatinCyrillic;
423 CF_EXPORT const CFStringRef kCFStringTransformLatinGreek;
424 CF_EXPORT const CFStringRef kCFStringTransformToXMLHex;
425 CF_EXPORT const CFStringRef kCFStringTransformToUnicodeName;
426 #endif
427 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
428 CF_EXPORT const CFStringRef kCFStringTransformStripDiacritics;
429 #endif
430
431 CF_EXPORT void
432 CFStringAppend (CFMutableStringRef theString, CFStringRef appendedString);
433
434 CF_EXPORT void
435 CFStringAppendCharacters (CFMutableStringRef theString,
436 const UniChar *chars, CFIndex numChars);
437
438 CF_EXPORT void
439 CFStringAppendCString (CFMutableStringRef theString, const char *cStr,
440 CFStringEncoding encoding);
441
442 CF_EXPORT void
443 CFStringAppendFormat (CFMutableStringRef theString,
444 CFDictionaryRef formatOptions, CFStringRef format, ...);
445
446 CF_EXPORT void
447 CFStringAppendFormatAndArguments (CFMutableStringRef theString,
448 CFDictionaryRef formatOptions, CFStringRef format, va_list arguments);
449
450 CF_EXPORT void
451 CFStringAppendPascalString (CFMutableStringRef theString,
452 ConstStr255Param pStr, CFStringEncoding encoding);
453
454 CF_EXPORT void
455 CFStringCapitalize (CFMutableStringRef theString, CFLocaleRef locale);
456
457 CF_EXPORT CFMutableStringRef
458 CFStringCreateMutable (CFAllocatorRef alloc, CFIndex maxLength);
459
460 CF_EXPORT CFMutableStringRef
461 CFStringCreateMutableCopy (CFAllocatorRef alloc, CFIndex maxLength,
462 CFStringRef theString);
463
464 CF_EXPORT CFMutableStringRef
465 CFStringCreateMutableWithExternalCharactersNoCopy (CFAllocatorRef alloc,
466 UniChar *chars, CFIndex numChars, CFIndex capacity,
467 CFAllocatorRef externalCharactersAllocator);
468
469 CF_EXPORT void
470 CFStringDelete (CFMutableStringRef theString, CFRange range);
471
472 CF_EXPORT void
473 CFStringInsert (CFMutableStringRef str, CFIndex idx, CFStringRef insertedStr);
474
475 CF_EXPORT void
476 CFStringLowercase (CFMutableStringRef theString, CFLocaleRef locale);
477
478 CF_EXPORT void
479 CFStringPad (CFMutableStringRef theString, CFStringRef padString,
480 CFIndex length, CFIndex indexIntoPad);
481
482 CF_EXPORT void
483 CFStringReplace (CFMutableStringRef theString, CFRange range,
484 CFStringRef replacement);
485
486 CF_EXPORT void
487 CFStringReplaceAll (CFMutableStringRef theString, CFStringRef replacement);
488
489 CF_EXPORT void
490 CFStringSetExternalCharactersNoCopy (CFMutableStringRef theString,
491 UniChar *chars, CFIndex length, CFIndex capacity);
492
493 CF_EXPORT void
494 CFStringTrim (CFMutableStringRef theString, CFStringRef trimString);
495
496 CF_EXPORT void
497 CFStringTrimWhitespace (CFMutableStringRef theString);
498
499 CF_EXPORT void
500 CFStringUppercase (CFMutableStringRef theString, CFLocaleRef locale);
501
502 #if OS_API_VERSION(MAC_OS_X_VERSION_10_2, GS_API_LATEST)
503 CF_EXPORT CFIndex
504 CFStringFindAndReplace (CFMutableStringRef theString,
505 CFStringRef stringToFind, CFStringRef replacementString,
506 CFRange rangeToSearch, CFOptionFlags compareOptions);
507
508 CF_EXPORT void
509 CFStringNormalize (CFMutableStringRef theString,
510 CFStringNormalizationForm theForm);
511 #endif
512
513 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST)
514 CF_EXPORT Boolean
515 CFStringTransform (CFMutableStringRef string, CFRange *range,
516 CFStringRef transform, Boolean reverse);
517 #endif
518
519 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
520 CF_EXPORT void
521 CFStringFold (CFMutableStringRef theString, CFOptionFlags theFlags,
522 CFLocaleRef theLocale);
523 #endif
524 /** \} */
525
526
527
528 /** \ingroup CFStringRef
529 \name CFStringInlineBuffer
530 \{
531 */
532 #define __kCFStringInlineBufferLength 64
533 struct CFStringInlineBuffer
534 {
535 UniChar buffer[__kCFStringInlineBufferLength];
536 CFStringRef theString;
537 const UniChar *directBuffer;
538 CFRange rangeToBuffer;
539 CFIndex bufferedRangeStart;
540 CFIndex bufferedRangeEnd;
541 };
542 typedef struct CFStringInlineBuffer CFStringInlineBuffer;
543
544 CF_INLINE void
545 CFStringInitInlineBuffer (CFStringRef str, CFStringInlineBuffer *buf,
546 CFRange range)
547 {
548 buf->theString = str;
549 buf->rangeToBuffer = range;
550 buf->directBuffer = CFStringGetCharactersPtr (str);
551 buf->bufferedRangeStart = 0;
552 buf->bufferedRangeEnd = 0;
553 }
554
555 CF_INLINE UniChar
556 CFStringGetCharacterFromInlineBuffer (CFStringInlineBuffer *buf, CFIndex idx)
557 {
558 if (buf->directBuffer)
559 {
560 if (idx < 0 || idx >= buf->rangeToBuffer.length)
561 return 0;
562 return buf->directBuffer[idx + buf->rangeToBuffer.location];
563 }
564 else if (idx >= buf->bufferedRangeEnd || idx < buf->bufferedRangeStart)
565 {
566 CFRange range;
567
568 if (idx < 0 || idx >= buf->rangeToBuffer.length)
569 return 0;
570
571 /* Use 16 here so it's efficient to go backwards, too */
572 buf->bufferedRangeStart = idx - 16;
573 if (buf->bufferedRangeStart < 0)
574 buf->bufferedRangeStart = 0;
575 buf->bufferedRangeEnd =
576 buf->bufferedRangeStart + __kCFStringInlineBufferLength;
577 if (buf->bufferedRangeEnd > buf->rangeToBuffer.length)
578 buf->bufferedRangeEnd = buf->rangeToBuffer.length;
579
580 range = CFRangeMake (buf->rangeToBuffer.location + buf->bufferedRangeStart,
581 buf->bufferedRangeEnd - buf->bufferedRangeStart);
582
583 CFStringGetCharacters (buf->theString, range, buf->buffer);
584 }
585
586 return buf->buffer[(idx - buf->bufferedRangeStart)];
587 }
588 /** \} */
589
590 CF_EXTERN_C_END
591
592 #endif /* __COREFOUNDATION_CFSTRING_H__ */
593