Repository navigation
Expand file tree
/
Copy pathustring.h
More file actions
1696 lines (1624 loc) · 72.7 KB
/
Copy pathustring.h
File metadata and controls
1696 lines (1624 loc) · 72.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
**********************************************************************
* Copyright (C) 1998-2010, International Business Machines
* Corporation and others. All Rights Reserved.
**********************************************************************
*
* File ustring.h
*
* Modification History:
*
* Date Name Description
* 12/07/98 bertrand Creation.
******************************************************************************
*/
#ifndef USTRING_H
#define USTRING_H
#include "unicode/utypes.h"
#include "unicode/putil.h"
#include "unicode/uiter.h"
/** Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. @stable ICU 2.1*/
#ifndef UBRK_TYPEDEF_UBREAK_ITERATOR
# define UBRK_TYPEDEF_UBREAK_ITERATOR
typedef struct UBreakIterator UBreakIterator;
#endif
/**
* \file
* \brief C API: Unicode string handling functions
*
* These C API functions provide general Unicode string handling.
*
* Some functions are equivalent in name, signature, and behavior to the ANSI C <string.h>
* functions. (For example, they do not check for bad arguments like NULL string pointers.)
* In some cases, only the thread-safe variant of such a function is implemented here
* (see u_strtok_r()).
*
* Other functions provide more Unicode-specific functionality like locale-specific
* upper/lower-casing and string comparison in code point order.
*
* ICU uses 16-bit Unicode (UTF-16) in the form of arrays of UChar code units.
* UTF-16 encodes each Unicode code point with either one or two UChar code units.
* (This is the default form of Unicode, and a forward-compatible extension of the original,
* fixed-width form that was known as UCS-2. UTF-16 superseded UCS-2 with Unicode 2.0
* in 1996.)
*
* Some APIs accept a 32-bit UChar32 value for a single code point.
*
* ICU also handles 16-bit Unicode text with unpaired surrogates.
* Such text is not well-formed UTF-16.
* Code-point-related functions treat unpaired surrogates as surrogate code points,
* i.e., as separate units.
*
* Although UTF-16 is a variable-width encoding form (like some legacy multi-byte encodings),
* it is much more efficient even for random access because the code unit values
* for single-unit characters vs. lead units vs. trail units are completely disjoint.
* This means that it is easy to determine character (code point) boundaries from
* random offsets in the string.
*
* Unicode (UTF-16) string processing is optimized for the single-unit case.
* Although it is important to support supplementary characters
* (which use pairs of lead/trail code units called "surrogates"),
* their occurrence is rare. Almost all characters in modern use require only
* a single UChar code unit (i.e., their code point values are <=0xffff).
*
* For more details see the User Guide Strings chapter (http://icu-project.org/userguide/strings.html).
* For a discussion of the handling of unpaired surrogates see also
* Jitterbug 2145 and its icu mailing list proposal on 2002-sep-18.
*/
/**
* \defgroup ustring_ustrlen String Length
* \ingroup ustring_strlen
*/
/*@{*/
/**
* Determine the length of an array of UChar.
*
* @param s The array of UChars, NULL (U+0000) terminated.
* @return The number of UChars in <code>chars</code>, minus the terminator.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strlen(const UChar *s);
/*@}*/
/**
* Count Unicode code points in the length UChar code units of the string.
* A code point may occupy either one or two UChar code units.
* Counting code points involves reading all code units.
*
* This functions is basically the inverse of the U16_FWD_N() macro (see utf.h).
*
* @param s The input string.
* @param length The number of UChar code units to be checked, or -1 to count all
* code points before the first NUL (U+0000).
* @return The number of code points in the specified code units.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_countChar32(const UChar *s, int32_t length);
/**
* Check if the string contains more Unicode code points than a certain number.
* This is more efficient than counting all code points in the entire string
* and comparing that number with a threshold.
* This function may not need to scan the string at all if the length is known
* (not -1 for NUL-termination) and falls within a certain range, and
* never needs to count more than 'number+1' code points.
* Logically equivalent to (u_countChar32(s, length)>number).
* A Unicode code point may occupy either one or two UChar code units.
*
* @param s The input string.
* @param length The length of the string, or -1 if it is NUL-terminated.
* @param number The number of code points in the string is compared against
* the 'number' parameter.
* @return Boolean value for whether the string contains more Unicode code points
* than 'number'. Same as (u_countChar32(s, length)>number).
* @stable ICU 2.4
*/
U_STABLE UBool U_EXPORT2
u_strHasMoreChar32Than(const UChar *s, int32_t length, int32_t number);
/**
* Concatenate two ustrings. Appends a copy of <code>src</code>,
* including the null terminator, to <code>dst</code>. The initial copied
* character from <code>src</code> overwrites the null terminator in <code>dst</code>.
*
* @param dst The destination string.
* @param src The source string.
* @return A pointer to <code>dst</code>.
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2
u_strcat(UChar *dst,
const UChar *src);
/**
* Concatenate two ustrings.
* Appends at most <code>n</code> characters from <code>src</code> to <code>dst</code>.
* Adds a terminating NUL.
* If src is too long, then only <code>n-1</code> characters will be copied
* before the terminating NUL.
* If <code>n<=0</code> then dst is not modified.
*
* @param dst The destination string.
* @param src The source string.
* @param n The maximum number of characters to append.
* @return A pointer to <code>dst</code>.
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2
u_strncat(UChar *dst,
const UChar *src,
int32_t n);
/**
* Find the first occurrence of a substring in a string.
* The substring is found at code point boundaries.
* That means that if the substring begins with
* a trail surrogate or ends with a lead surrogate,
* then it is found only if these surrogates stand alone in the text.
* Otherwise, the substring edge units would be matched against
* halves of surrogate pairs.
*
* @param s The string to search (NUL-terminated).
* @param substring The substring to find (NUL-terminated).
* @return A pointer to the first occurrence of <code>substring</code> in <code>s</code>,
* or <code>s</code> itself if the <code>substring</code> is empty,
* or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.
* @stable ICU 2.0
*
* @see u_strrstr
* @see u_strFindFirst
* @see u_strFindLast
*/
U_STABLE UChar * U_EXPORT2
u_strstr(const UChar *s, const UChar *substring);
/**
* Find the first occurrence of a substring in a string.
* The substring is found at code point boundaries.
* That means that if the substring begins with
* a trail surrogate or ends with a lead surrogate,
* then it is found only if these surrogates stand alone in the text.
* Otherwise, the substring edge units would be matched against
* halves of surrogate pairs.
*
* @param s The string to search.
* @param length The length of s (number of UChars), or -1 if it is NUL-terminated.
* @param substring The substring to find (NUL-terminated).
* @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated.
* @return A pointer to the first occurrence of <code>substring</code> in <code>s</code>,
* or <code>s</code> itself if the <code>substring</code> is empty,
* or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.
* @stable ICU 2.4
*
* @see u_strstr
* @see u_strFindLast
*/
U_STABLE UChar * U_EXPORT2
u_strFindFirst(const UChar *s, int32_t length, const UChar *substring, int32_t subLength);
/**
* Find the first occurrence of a BMP code point in a string.
* A surrogate code point is found only if its match in the text is not
* part of a surrogate pair.
* A NUL character is found at the string terminator.
*
* @param s The string to search (NUL-terminated).
* @param c The BMP code point to find.
* @return A pointer to the first occurrence of <code>c</code> in <code>s</code>
* or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
* @stable ICU 2.0
*
* @see u_strchr32
* @see u_memchr
* @see u_strstr
* @see u_strFindFirst
*/
U_STABLE UChar * U_EXPORT2
u_strchr(const UChar *s, UChar c);
/**
* Find the first occurrence of a code point in a string.
* A surrogate code point is found only if its match in the text is not
* part of a surrogate pair.
* A NUL character is found at the string terminator.
*
* @param s The string to search (NUL-terminated).
* @param c The code point to find.
* @return A pointer to the first occurrence of <code>c</code> in <code>s</code>
* or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
* @stable ICU 2.0
*
* @see u_strchr
* @see u_memchr32
* @see u_strstr
* @see u_strFindFirst
*/
U_STABLE UChar * U_EXPORT2
u_strchr32(const UChar *s, UChar32 c);
/**
* Find the last occurrence of a substring in a string.
* The substring is found at code point boundaries.
* That means that if the substring begins with
* a trail surrogate or ends with a lead surrogate,
* then it is found only if these surrogates stand alone in the text.
* Otherwise, the substring edge units would be matched against
* halves of surrogate pairs.
*
* @param s The string to search (NUL-terminated).
* @param substring The substring to find (NUL-terminated).
* @return A pointer to the last occurrence of <code>substring</code> in <code>s</code>,
* or <code>s</code> itself if the <code>substring</code> is empty,
* or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.
* @stable ICU 2.4
*
* @see u_strstr
* @see u_strFindFirst
* @see u_strFindLast
*/
U_STABLE UChar * U_EXPORT2
u_strrstr(const UChar *s, const UChar *substring);
/**
* Find the last occurrence of a substring in a string.
* The substring is found at code point boundaries.
* That means that if the substring begins with
* a trail surrogate or ends with a lead surrogate,
* then it is found only if these surrogates stand alone in the text.
* Otherwise, the substring edge units would be matched against
* halves of surrogate pairs.
*
* @param s The string to search.
* @param length The length of s (number of UChars), or -1 if it is NUL-terminated.
* @param substring The substring to find (NUL-terminated).
* @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated.
* @return A pointer to the last occurrence of <code>substring</code> in <code>s</code>,
* or <code>s</code> itself if the <code>substring</code> is empty,
* or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.
* @stable ICU 2.4
*
* @see u_strstr
* @see u_strFindLast
*/
U_STABLE UChar * U_EXPORT2
u_strFindLast(const UChar *s, int32_t length, const UChar *substring, int32_t subLength);
/**
* Find the last occurrence of a BMP code point in a string.
* A surrogate code point is found only if its match in the text is not
* part of a surrogate pair.
* A NUL character is found at the string terminator.
*
* @param s The string to search (NUL-terminated).
* @param c The BMP code point to find.
* @return A pointer to the last occurrence of <code>c</code> in <code>s</code>
* or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
* @stable ICU 2.4
*
* @see u_strrchr32
* @see u_memrchr
* @see u_strrstr
* @see u_strFindLast
*/
U_STABLE UChar * U_EXPORT2
u_strrchr(const UChar *s, UChar c);
/**
* Find the last occurrence of a code point in a string.
* A surrogate code point is found only if its match in the text is not
* part of a surrogate pair.
* A NUL character is found at the string terminator.
*
* @param s The string to search (NUL-terminated).
* @param c The code point to find.
* @return A pointer to the last occurrence of <code>c</code> in <code>s</code>
* or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
* @stable ICU 2.4
*
* @see u_strrchr
* @see u_memchr32
* @see u_strrstr
* @see u_strFindLast
*/
U_STABLE UChar * U_EXPORT2
u_strrchr32(const UChar *s, UChar32 c);
/**
* Locates the first occurrence in the string <code>string</code> of any of the characters
* in the string <code>matchSet</code>.
* Works just like C's strpbrk but with Unicode.
*
* @param string The string in which to search, NUL-terminated.
* @param matchSet A NUL-terminated string defining a set of code points
* for which to search in the text string.
* @return A pointer to the character in <code>string</code> that matches one of the
* characters in <code>matchSet</code>, or NULL if no such character is found.
* @stable ICU 2.0
*/
U_STABLE UChar * U_EXPORT2
u_strpbrk(const UChar *string, const UChar *matchSet);
/**
* Returns the number of consecutive characters in <code>string</code>,
* beginning with the first, that do not occur somewhere in <code>matchSet</code>.
* Works just like C's strcspn but with Unicode.
*
* @param string The string in which to search, NUL-terminated.
* @param matchSet A NUL-terminated string defining a set of code points
* for which to search in the text string.
* @return The number of initial characters in <code>string</code> that do not
* occur in <code>matchSet</code>.
* @see u_strspn
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strcspn(const UChar *string, const UChar *matchSet);
/**
* Returns the number of consecutive characters in <code>string</code>,
* beginning with the first, that occur somewhere in <code>matchSet</code>.
* Works just like C's strspn but with Unicode.
*
* @param string The string in which to search, NUL-terminated.
* @param matchSet A NUL-terminated string defining a set of code points
* for which to search in the text string.
* @return The number of initial characters in <code>string</code> that do
* occur in <code>matchSet</code>.
* @see u_strcspn
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strspn(const UChar *string, const UChar *matchSet);
/**
* The string tokenizer API allows an application to break a string into
* tokens. Unlike strtok(), the saveState (the current pointer within the
* original string) is maintained in saveState. In the first call, the
* argument src is a pointer to the string. In subsequent calls to
* return successive tokens of that string, src must be specified as
* NULL. The value saveState is set by this function to maintain the
* function's position within the string, and on each subsequent call
* you must give this argument the same variable. This function does
* handle surrogate pairs. This function is similar to the strtok_r()
* the POSIX Threads Extension (1003.1c-1995) version.
*
* @param src String containing token(s). This string will be modified.
* After the first call to u_strtok_r(), this argument must
* be NULL to get to the next token.
* @param delim Set of delimiter characters (Unicode code points).
* @param saveState The current pointer within the original string,
* which is set by this function. The saveState
* parameter should the address of a local variable of type
* UChar *. (i.e. defined "Uhar *myLocalSaveState" and use
* &myLocalSaveState for this parameter).
* @return A pointer to the next token found in src, or NULL
* when there are no more tokens.
* @stable ICU 2.0
*/
U_STABLE UChar * U_EXPORT2
u_strtok_r(UChar *src,
const UChar *delim,
UChar **saveState);
/**
* Compare two Unicode strings for bitwise equality (code unit order).
*
* @param s1 A string to compare.
* @param s2 A string to compare.
* @return 0 if <code>s1</code> and <code>s2</code> are bitwise equal; a negative
* value if <code>s1</code> is bitwise less than <code>s2,</code>; a positive
* value if <code>s1</code> is bitwise greater than <code>s2</code>.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strcmp(const UChar *s1,
const UChar *s2);
/**
* Compare two Unicode strings in code point order.
* See u_strCompare for details.
*
* @param s1 A string to compare.
* @param s2 A string to compare.
* @return a negative/zero/positive integer corresponding to whether
* the first string is less than/equal to/greater than the second one
* in code point order
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strcmpCodePointOrder(const UChar *s1, const UChar *s2);
/**
* Compare two Unicode strings (binary order).
*
* The comparison can be done in code unit order or in code point order.
* They differ only in UTF-16 when
* comparing supplementary code points (U+10000..U+10ffff)
* to BMP code points near the end of the BMP (i.e., U+e000..U+ffff).
* In code unit order, high BMP code points sort after supplementary code points
* because they are stored as pairs of surrogates which are at U+d800..U+dfff.
*
* This functions works with strings of different explicitly specified lengths
* unlike the ANSI C-like u_strcmp() and u_memcmp() etc.
* NUL-terminated strings are possible with length arguments of -1.
*
* @param s1 First source string.
* @param length1 Length of first source string, or -1 if NUL-terminated.
*
* @param s2 Second source string.
* @param length2 Length of second source string, or -1 if NUL-terminated.
*
* @param codePointOrder Choose between code unit order (FALSE)
* and code point order (TRUE).
*
* @return <0 or 0 or >0 as usual for string comparisons
*
* @stable ICU 2.2
*/
U_STABLE int32_t U_EXPORT2
u_strCompare(const UChar *s1, int32_t length1,
const UChar *s2, int32_t length2,
UBool codePointOrder);
/**
* Compare two Unicode strings (binary order)
* as presented by UCharIterator objects.
* Works otherwise just like u_strCompare().
*
* Both iterators are reset to their start positions.
* When the function returns, it is undefined where the iterators
* have stopped.
*
* @param iter1 First source string iterator.
* @param iter2 Second source string iterator.
* @param codePointOrder Choose between code unit order (FALSE)
* and code point order (TRUE).
*
* @return <0 or 0 or >0 as usual for string comparisons
*
* @see u_strCompare
*
* @stable ICU 2.6
*/
U_STABLE int32_t U_EXPORT2
u_strCompareIter(UCharIterator *iter1, UCharIterator *iter2, UBool codePointOrder);
#ifndef U_COMPARE_CODE_POINT_ORDER
/* see also unistr.h and unorm.h */
/**
* Option bit for u_strCaseCompare, u_strcasecmp, unorm_compare, etc:
* Compare strings in code point order instead of code unit order.
* @stable ICU 2.2
*/
#define U_COMPARE_CODE_POINT_ORDER 0x8000
#endif
/**
* Compare two strings case-insensitively using full case folding.
* This is equivalent to
* u_strCompare(u_strFoldCase(s1, options),
* u_strFoldCase(s2, options),
* (options&U_COMPARE_CODE_POINT_ORDER)!=0).
*
* The comparison can be done in UTF-16 code unit order or in code point order.
* They differ only when comparing supplementary code points (U+10000..U+10ffff)
* to BMP code points near the end of the BMP (i.e., U+e000..U+ffff).
* In code unit order, high BMP code points sort after supplementary code points
* because they are stored as pairs of surrogates which are at U+d800..U+dfff.
*
* This functions works with strings of different explicitly specified lengths
* unlike the ANSI C-like u_strcmp() and u_memcmp() etc.
* NUL-terminated strings are possible with length arguments of -1.
*
* @param s1 First source string.
* @param length1 Length of first source string, or -1 if NUL-terminated.
*
* @param s2 Second source string.
* @param length2 Length of second source string, or -1 if NUL-terminated.
*
* @param options A bit set of options:
* - U_FOLD_CASE_DEFAULT or 0 is used for default options:
* Comparison in code unit order with default case folding.
*
* - U_COMPARE_CODE_POINT_ORDER
* Set to choose code point order instead of code unit order
* (see u_strCompare for details).
*
* - U_FOLD_CASE_EXCLUDE_SPECIAL_I
*
* @param pErrorCode Must be a valid pointer to an error code value,
* which must not indicate a failure before the function call.
*
* @return <0 or 0 or >0 as usual for string comparisons
*
* @stable ICU 2.2
*/
U_STABLE int32_t U_EXPORT2
u_strCaseCompare(const UChar *s1, int32_t length1,
const UChar *s2, int32_t length2,
uint32_t options,
UErrorCode *pErrorCode);
/**
* Compare two ustrings for bitwise equality.
* Compares at most <code>n</code> characters.
*
* @param ucs1 A string to compare.
* @param ucs2 A string to compare.
* @param n The maximum number of characters to compare.
* @return 0 if <code>s1</code> and <code>s2</code> are bitwise equal; a negative
* value if <code>s1</code> is bitwise less than <code>s2</code>; a positive
* value if <code>s1</code> is bitwise greater than <code>s2</code>.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strncmp(const UChar *ucs1,
const UChar *ucs2,
int32_t n);
/**
* Compare two Unicode strings in code point order.
* This is different in UTF-16 from u_strncmp() if supplementary characters are present.
* For details, see u_strCompare().
*
* @param s1 A string to compare.
* @param s2 A string to compare.
* @param n The maximum number of characters to compare.
* @return a negative/zero/positive integer corresponding to whether
* the first string is less than/equal to/greater than the second one
* in code point order
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strncmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t n);
/**
* Compare two strings case-insensitively using full case folding.
* This is equivalent to u_strcmp(u_strFoldCase(s1, options), u_strFoldCase(s2, options)).
*
* @param s1 A string to compare.
* @param s2 A string to compare.
* @param options A bit set of options:
* - U_FOLD_CASE_DEFAULT or 0 is used for default options:
* Comparison in code unit order with default case folding.
*
* - U_COMPARE_CODE_POINT_ORDER
* Set to choose code point order instead of code unit order
* (see u_strCompare for details).
*
* - U_FOLD_CASE_EXCLUDE_SPECIAL_I
*
* @return A negative, zero, or positive integer indicating the comparison result.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strcasecmp(const UChar *s1, const UChar *s2, uint32_t options);
/**
* Compare two strings case-insensitively using full case folding.
* This is equivalent to u_strcmp(u_strFoldCase(s1, at most n, options),
* u_strFoldCase(s2, at most n, options)).
*
* @param s1 A string to compare.
* @param s2 A string to compare.
* @param n The maximum number of characters each string to case-fold and then compare.
* @param options A bit set of options:
* - U_FOLD_CASE_DEFAULT or 0 is used for default options:
* Comparison in code unit order with default case folding.
*
* - U_COMPARE_CODE_POINT_ORDER
* Set to choose code point order instead of code unit order
* (see u_strCompare for details).
*
* - U_FOLD_CASE_EXCLUDE_SPECIAL_I
*
* @return A negative, zero, or positive integer indicating the comparison result.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_strncasecmp(const UChar *s1, const UChar *s2, int32_t n, uint32_t options);
/**
* Compare two strings case-insensitively using full case folding.
* This is equivalent to u_strcmp(u_strFoldCase(s1, n, options),
* u_strFoldCase(s2, n, options)).
*
* @param s1 A string to compare.
* @param s2 A string to compare.
* @param length The number of characters in each string to case-fold and then compare.
* @param options A bit set of options:
* - U_FOLD_CASE_DEFAULT or 0 is used for default options:
* Comparison in code unit order with default case folding.
*
* - U_COMPARE_CODE_POINT_ORDER
* Set to choose code point order instead of code unit order
* (see u_strCompare for details).
*
* - U_FOLD_CASE_EXCLUDE_SPECIAL_I
*
* @return A negative, zero, or positive integer indicating the comparison result.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_memcasecmp(const UChar *s1, const UChar *s2, int32_t length, uint32_t options);
/**
* Copy a ustring. Adds a null terminator.
*
* @param dst The destination string.
* @param src The source string.
* @return A pointer to <code>dst</code>.
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2
u_strcpy(UChar *dst,
const UChar *src);
/**
* Copy a ustring.
* Copies at most <code>n</code> characters. The result will be null terminated
* if the length of <code>src</code> is less than <code>n</code>.
*
* @param dst The destination string.
* @param src The source string.
* @param n The maximum number of characters to copy.
* @return A pointer to <code>dst</code>.
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2
u_strncpy(UChar *dst,
const UChar *src,
int32_t n);
#if !UCONFIG_NO_CONVERSION
/**
* Copy a byte string encoded in the default codepage to a ustring.
* Adds a null terminator.
* Performs a host byte to UChar conversion
*
* @param dst The destination string.
* @param src The source string.
* @return A pointer to <code>dst</code>.
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2 u_uastrcpy(UChar *dst,
const char *src );
/**
* Copy a byte string encoded in the default codepage to a ustring.
* Copies at most <code>n</code> characters. The result will be null terminated
* if the length of <code>src</code> is less than <code>n</code>.
* Performs a host byte to UChar conversion
*
* @param dst The destination string.
* @param src The source string.
* @param n The maximum number of characters to copy.
* @return A pointer to <code>dst</code>.
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2 u_uastrncpy(UChar *dst,
const char *src,
int32_t n);
/**
* Copy ustring to a byte string encoded in the default codepage.
* Adds a null terminator.
* Performs a UChar to host byte conversion
*
* @param dst The destination string.
* @param src The source string.
* @return A pointer to <code>dst</code>.
* @stable ICU 2.0
*/
U_STABLE char* U_EXPORT2 u_austrcpy(char *dst,
const UChar *src );
/**
* Copy ustring to a byte string encoded in the default codepage.
* Copies at most <code>n</code> characters. The result will be null terminated
* if the length of <code>src</code> is less than <code>n</code>.
* Performs a UChar to host byte conversion
*
* @param dst The destination string.
* @param src The source string.
* @param n The maximum number of characters to copy.
* @return A pointer to <code>dst</code>.
* @stable ICU 2.0
*/
U_STABLE char* U_EXPORT2 u_austrncpy(char *dst,
const UChar *src,
int32_t n );
#endif
/**
* Synonym for memcpy(), but with UChars only.
* @param dest The destination string
* @param src The source string
* @param count The number of characters to copy
* @return A pointer to <code>dest</code>
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2
u_memcpy(UChar *dest, const UChar *src, int32_t count);
/**
* Synonym for memmove(), but with UChars only.
* @param dest The destination string
* @param src The source string
* @param count The number of characters to move
* @return A pointer to <code>dest</code>
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2
u_memmove(UChar *dest, const UChar *src, int32_t count);
/**
* Initialize <code>count</code> characters of <code>dest</code> to <code>c</code>.
*
* @param dest The destination string.
* @param c The character to initialize the string.
* @param count The maximum number of characters to set.
* @return A pointer to <code>dest</code>.
* @stable ICU 2.0
*/
U_STABLE UChar* U_EXPORT2
u_memset(UChar *dest, UChar c, int32_t count);
/**
* Compare the first <code>count</code> UChars of each buffer.
*
* @param buf1 The first string to compare.
* @param buf2 The second string to compare.
* @param count The maximum number of UChars to compare.
* @return When buf1 < buf2, a negative number is returned.
* When buf1 == buf2, 0 is returned.
* When buf1 > buf2, a positive number is returned.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_memcmp(const UChar *buf1, const UChar *buf2, int32_t count);
/**
* Compare two Unicode strings in code point order.
* This is different in UTF-16 from u_memcmp() if supplementary characters are present.
* For details, see u_strCompare().
*
* @param s1 A string to compare.
* @param s2 A string to compare.
* @param count The maximum number of characters to compare.
* @return a negative/zero/positive integer corresponding to whether
* the first string is less than/equal to/greater than the second one
* in code point order
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
u_memcmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t count);
/**
* Find the first occurrence of a BMP code point in a string.
* A surrogate code point is found only if its match in the text is not
* part of a surrogate pair.
* A NUL character is found at the string terminator.
*
* @param s The string to search (contains <code>count</code> UChars).
* @param c The BMP code point to find.
* @param count The length of the string.
* @return A pointer to the first occurrence of <code>c</code> in <code>s</code>
* or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
* @stable ICU 2.0
*
* @see u_strchr
* @see u_memchr32
* @see u_strFindFirst
*/
U_STABLE UChar* U_EXPORT2
u_memchr(const UChar *s, UChar c, int32_t count);
/**
* Find the first occurrence of a code point in a string.
* A surrogate code point is found only if its match in the text is not
* part of a surrogate pair.
* A NUL character is found at the string terminator.
*
* @param s The string to search (contains <code>count</code> UChars).
* @param c The code point to find.
* @param count The length of the string.
* @return A pointer to the first occurrence of <code>c</code> in <code>s</code>
* or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
* @stable ICU 2.0
*
* @see u_strchr32
* @see u_memchr
* @see u_strFindFirst
*/
U_STABLE UChar* U_EXPORT2
u_memchr32(const UChar *s, UChar32 c, int32_t count);
/**
* Find the last occurrence of a BMP code point in a string.
* A surrogate code point is found only if its match in the text is not
* part of a surrogate pair.
* A NUL character is found at the string terminator.
*
* @param s The string to search (contains <code>count</code> UChars).
* @param c The BMP code point to find.
* @param count The length of the string.
* @return A pointer to the last occurrence of <code>c</code> in <code>s</code>
* or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
* @stable ICU 2.4
*
* @see u_strrchr
* @see u_memrchr32
* @see u_strFindLast
*/
U_STABLE UChar* U_EXPORT2
u_memrchr(const UChar *s, UChar c, int32_t count);
/**
* Find the last occurrence of a code point in a string.
* A surrogate code point is found only if its match in the text is not
* part of a surrogate pair.
* A NUL character is found at the string terminator.
*
* @param s The string to search (contains <code>count</code> UChars).
* @param c The code point to find.
* @param count The length of the string.
* @return A pointer to the last occurrence of <code>c</code> in <code>s</code>
* or <code>NULL</code> if <code>c</code> is not in <code>s</code>.
* @stable ICU 2.4
*
* @see u_strrchr32
* @see u_memrchr
* @see u_strFindLast
*/
U_STABLE UChar* U_EXPORT2
u_memrchr32(const UChar *s, UChar32 c, int32_t count);
/**
* Unicode String literals in C.
* We need one macro to declare a variable for the string
* and to statically preinitialize it if possible,
* and a second macro to dynamically intialize such a string variable if necessary.
*
* The macros are defined for maximum performance.
* They work only for strings that contain "invariant characters", i.e.,
* only latin letters, digits, and some punctuation.
* See utypes.h for details.
*
* A pair of macros for a single string must be used with the same
* parameters.
* The string parameter must be a C string literal.
* The length of the string, not including the terminating
* <code>NUL</code>, must be specified as a constant.
* The U_STRING_DECL macro should be invoked exactly once for one
* such string variable before it is used.
*
* Usage:
* <pre>
* U_STRING_DECL(ustringVar1, "Quick-Fox 2", 11);
* U_STRING_DECL(ustringVar2, "jumps 5%", 8);
* static UBool didInit=FALSE;
*
* int32_t function() {
* if(!didInit) {
* U_STRING_INIT(ustringVar1, "Quick-Fox 2", 11);
* U_STRING_INIT(ustringVar2, "jumps 5%", 8);
* didInit=TRUE;
* }
* return u_strcmp(ustringVar1, ustringVar2);
* }
* </pre>
*
* Note that the macros will NOT consistently work if their argument is another #define.
* The following will not work on all platforms, don't use it.
*
* <pre>
* #define GLUCK "Mr. Gluck"
* U_STRING_DECL(var, GLUCK, 9)
* U_STRING_INIT(var, GLUCK, 9)
* </pre>
*
* Instead, use the string literal "Mr. Gluck" as the argument to both macro
* calls.
*
*
* @stable ICU 2.0
*/
#if defined(U_DECLARE_UTF16)
# define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]=U_DECLARE_UTF16(cs)
/**@stable ICU 2.0 */
# define U_STRING_INIT(var, cs, length)
#elif U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || (U_SIZEOF_UCHAR == 2 && defined(U_WCHAR_IS_UTF16)))
# define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]=L ## cs
/**@stable ICU 2.0 */
# define U_STRING_INIT(var, cs, length)
#elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY
# define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]={ (const UChar *)cs }
/**@stable ICU 2.0 */
# define U_STRING_INIT(var, cs, length)
#else
# define U_STRING_DECL(var, cs, length) static UChar var[(length)+1]
/**@stable ICU 2.0 */
# define U_STRING_INIT(var, cs, length) u_charsToUChars(cs, var, length+1)
#endif
/**
* Unescape a string of characters and write the resulting
* Unicode characters to the destination buffer. The following escape
* sequences are recognized:
*
* \\uhhhh 4 hex digits; h in [0-9A-Fa-f]
* \\Uhhhhhhhh 8 hex digits
* \\xhh 1-2 hex digits
* \\x{h...} 1-8 hex digits
* \\ooo 1-3 octal digits; o in [0-7]
* \\cX control-X; X is masked with 0x1F
*
* as well as the standard ANSI C escapes:
*
* \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A,
* \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B,
* \\" => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C
*
* Anything else following a backslash is generically escaped. For
* example, "[a\\-z]" returns "[a-z]".
*
* If an escape sequence is ill-formed, this method returns an empty
* string. An example of an ill-formed sequence is "\\u" followed by
* fewer than 4 hex digits.
*
* The above characters are recognized in the compiler's codepage,
* that is, they are coded as 'u', '\\', etc. Characters that are
* not parts of escape sequences are converted using u_charsToUChars().
*
* This function is similar to UnicodeString::unescape() but not
* identical to it. The latter takes a source UnicodeString, so it
* does escape recognition but no conversion.
*
* @param src a zero-terminated string of invariant characters
* @param dest pointer to buffer to receive converted and unescaped
* text and, if there is room, a zero terminator. May be NULL for
* preflighting, in which case no UChars will be written, but the
* return value will still be valid. On error, an empty string is
* stored here (if possible).
* @param destCapacity the number of UChars that may be written at
* dest. Ignored if dest == NULL.
* @return the length of unescaped string.
* @see u_unescapeAt
* @see UnicodeString#unescape()
* @see UnicodeString#unescapeAt()
* @stable ICU 2.0
*/