2 ******************************************************************************
4 * Copyright (C) 1998-2013, International Business Machines
5 * Corporation and others. All Rights Reserved.
7 ******************************************************************************
11 * Modification History:
13 * Date Name Description
14 * 10/16/98 stephen Creation.
15 * 11/06/98 stephen Modified per code review.
16 * 03/12/99 stephen Modified for new C API.
17 * 07/19/99 stephen Minor doc update.
18 * 02/01/01 george Added sprintf & sscanf with all of its variants
19 ******************************************************************************
28 #include "unicode/utypes.h"
29 #include "unicode/ucnv.h"
30 #include "unicode/utrans.h"
31 #include "unicode/localpointer.h"
32 #include "unicode/unum.h"
36 The following is a small list as to what is currently wrong/suggestions for
39 * Make sure that * in the scanf format specification works for all formats.
40 * Each UFILE takes up at least 2KB.
41 Look into adding setvbuf() for configurable buffers.
42 * This library does buffering. The OS should do this for us already. Check on
43 this, and remove it from this library, if this is the case. Double buffering
44 wastes a lot of time and space.
45 * Test stdin and stdout with the u_f* functions
46 * Testing should be done for reading and writing multi-byte encodings,
47 and make sure that a character that is contained across buffer boundries
48 works even for incomplete characters.
49 * Make sure that the last character is flushed when the file/string is closed.
50 * snprintf should follow the C99 standard for the return value, which is
51 return the number of characters (excluding the trailing '\0')
52 which would have been written to the destination string regardless
53 of available space. This is like pre-flighting.
54 * Everything that uses %s should do what operator>> does for UnicodeString.
55 It should convert one byte at a time, and once a character is
56 converted then check to see if it's whitespace or in the scanset.
57 If it's whitespace or in the scanset, put all the bytes back (do nothing
59 * If bad string data is encountered, make sure that the function fails
60 without memory leaks and the unconvertable characters are valid
61 substitution or are escaped characters.
62 * u_fungetc() can't unget a character when it's at the beginning of the
63 internal conversion buffer. For example, read the buffer size # of
64 characters, and then ungetc to get the previous character that was
65 at the end of the last buffer.
66 * u_fflush() and u_fclose should return an int32_t like C99 functions.
67 0 is returned if the operation was successful and EOF otherwise.
68 * u_fsettransliterator does not support U_READ side of transliteration.
69 * The format specifier should limit the size of a format or honor it in
70 order to prevent buffer overruns. (e.g. %256.256d).
71 * u_fread and u_fwrite don't exist. They're needed for reading and writing
72 data structures without any conversion.
73 * u_file_read and u_file_write are used for writing strings. u_fgets and
74 u_fputs or u_fread and u_fwrite should be used to do this.
75 * The width parameter for all scanf formats, including scanset, needs
76 better testing. This prevents buffer overflows.
77 * Figure out what is suppose to happen when a codepage is changed midstream.
78 Maybe a flush or a rewind are good enough.
79 * Make sure that a UFile opened with "rw" can be used after using
80 u_fflush with a u_frewind.
81 * scanf(%i) should detect what type of number to use.
82 * Add more testing of the alternate format, %#
83 * Look at newline handling of fputs/puts
84 * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
85 * Complete the file documentation with proper doxygen formatting.
86 See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
91 * \brief C API: Unicode stdio-like API
93 * <h2>Unicode stdio-like C API</h2>
95 * <p>This API provides an stdio-like API wrapper around ICU's other
96 * formatting and parsing APIs. It is meant to ease the transition of adding
97 * Unicode support to a preexisting applications using stdio. The following
98 * is a small list of noticable differences between stdio and ICU I/O's
99 * ustdio implementation.</p>
102 * <li>Locale specific formatting and parsing is only done with file IO.</li>
103 * <li>u_fstropen can be used to simulate file IO with strings.
104 * This is similar to the iostream API, and it allows locale specific
105 * formatting and parsing to be used.</li>
106 * <li>This API provides uniform formatting and parsing behavior between
107 * platforms (unlike the standard stdio implementations found on various
109 * <li>This API is better suited for text data handling than binary data
110 * handling when compared to the typical stdio implementation.</li>
111 * <li>You can specify a Transliterator while using the file IO.</li>
112 * <li>You can specify a file's codepage separately from the default
113 * system codepage.</li>
116 * <h2>Formatting and Parsing Specification</h2>
118 * General printf format:<br>
119 * %[format modifier][width][.precision][type modifier][format]
121 * General scanf format:<br>
122 * %[*][format modifier][width][type modifier][format]
124 <table cellspacing="3">
125 <tr><td>format</td><td>default<br>printf<br>type</td><td>default<br>scanf<br>type</td><td>description</td></tr>
126 <tr><td>%E</td><td>double</td><td>float</td><td>Scientific with an uppercase exponent</td></tr>
127 <tr><td>%e</td><td>double</td><td>float</td><td>Scientific with a lowercase exponent</td></tr>
128 <tr><td>%G</td><td>double</td><td>float</td><td>Use %E or %f for best format</td></tr>
129 <tr><td>%g</td><td>double</td><td>float</td><td>Use %e or %f for best format</td></tr>
130 <tr><td>%f</td><td>double</td><td>float</td><td>Simple floating point without the exponent</td></tr>
131 <tr><td>%X</td><td>int32_t</td><td>int32_t</td><td>ustdio special uppercase hex radix formatting</td></tr>
132 <tr><td>%x</td><td>int32_t</td><td>int32_t</td><td>ustdio special lowercase hex radix formatting</td></tr>
133 <tr><td>%d</td><td>int32_t</td><td>int32_t</td><td>Decimal format</td></tr>
134 <tr><td>%i</td><td>int32_t</td><td>int32_t</td><td>Same as %d</td></tr>
135 <tr><td>%n</td><td>int32_t</td><td>int32_t</td><td>count (write the number of UTF-16 codeunits read/written)</td></tr>
136 <tr><td>%o</td><td>int32_t</td><td>int32_t</td><td>ustdio special octal radix formatting</td></tr>
137 <tr><td>%u</td><td>uint32_t</td><td>uint32_t</td><td>Decimal format</td></tr>
138 <tr><td>%p</td><td>void *</td><td>void *</td><td>Prints the pointer value</td></tr>
139 <tr><td>%s</td><td>char *</td><td>char *</td><td>Use default converter or specified converter from fopen</td></tr>
140 <tr><td>%c</td><td>char</td><td>char</td><td>Use default converter or specified converter from fopen<br>
141 When width is specified for scanf, this acts like a non-NULL-terminated char * string.<br>
142 By default, only one char is written.</td></tr>
143 <tr><td>%S</td><td>UChar *</td><td>UChar *</td><td>Null terminated UTF-16 string</td></tr>
144 <tr><td>%C</td><td>UChar</td><td>UChar</td><td>16-bit Unicode code unit<br>
145 When width is specified for scanf, this acts like a non-NULL-terminated UChar * string<br>
146 By default, only one codepoint is written.</td></tr>
147 <tr><td>%[]</td><td> </td><td>UChar *</td><td>Null terminated UTF-16 string which contains the filtered set of characters specified by the UnicodeSet</td></tr>
148 <tr><td>%%</td><td> </td><td> </td><td>Show a percent sign</td></tr>
153 <tr><td>modifier</td><td>formats</td><td>type</td><td>comments</td></tr>
154 <tr><td>%h</td><td>%d, %i, %o, %x</td><td>int16_t</td><td>short format</td></tr>
155 <tr><td>%h</td><td>%u</td><td>uint16_t</td><td>short format</td></tr>
156 <tr><td>%h</td><td>c</td><td>char</td><td><b>(Unimplemented)</b> Use invariant converter</td></tr>
157 <tr><td>%h</td><td>s</td><td>char *</td><td><b>(Unimplemented)</b> Use invariant converter</td></tr>
158 <tr><td>%h</td><td>C</td><td>char</td><td><b>(Unimplemented)</b> 8-bit Unicode code unit</td></tr>
159 <tr><td>%h</td><td>S</td><td>char *</td><td><b>(Unimplemented)</b> Null terminated UTF-8 string</td></tr>
160 <tr><td>%l</td><td>%d, %i, %o, %x</td><td>int32_t</td><td>long format (no effect)</td></tr>
161 <tr><td>%l</td><td>%u</td><td>uint32_t</td><td>long format (no effect)</td></tr>
162 <tr><td>%l</td><td>c</td><td>N/A</td><td><b>(Unimplemented)</b> Reserved for future implementation</td></tr>
163 <tr><td>%l</td><td>s</td><td>N/A</td><td><b>(Unimplemented)</b> Reserved for future implementation</td></tr>
164 <tr><td>%l</td><td>C</td><td>UChar32</td><td><b>(Unimplemented)</b> 32-bit Unicode code unit</td></tr>
165 <tr><td>%l</td><td>S</td><td>UChar32 *</td><td><b>(Unimplemented)</b> Null terminated UTF-32 string</td></tr>
166 <tr><td>%ll</td><td>%d, %i, %o, %x</td><td>int64_t</td><td>long long format</td></tr>
167 <tr><td>%ll</td><td>%u</td><td>uint64_t</td><td><b>(Unimplemented)</b> long long format</td></tr>
168 <tr><td>%-</td><td><i>all</i></td><td>N/A</td><td>Left justify</td></tr>
169 <tr><td>%+</td><td>%d, %i, %o, %x, %e, %f, %g, %E, %G</td><td>N/A</td><td>Always show the plus or minus sign. Needs data for plus sign.</td></tr>
170 <tr><td>% </td><td>%d, %i, %o, %x, %e, %f, %g, %E, %G</td><td>N/A</td><td>Instead of a "+" output a blank character for positive numbers.</td></tr>
171 <tr><td>%#</td><td>%d, %i, %o, %x, %e, %f, %g, %E, %G</td><td>N/A</td><td>Precede octal value with 0, hex with 0x and show the
172 decimal point for floats.</td></tr>
173 <tr><td>%<i>n</i></td><td><i>all</i></td><td>N/A</td><td>Width of input/output. num is an actual number from 0 to
174 some large number.</td></tr>
175 <tr><td>%.<i>n</i></td><td>%e, %f, %g, %E, %F, %G</td><td>N/A</td><td>Significant digits precision. num is an actual number from
176 0 to some large number.<br>If * is used in printf, then the precision is passed in as an argument before the number to be formatted.</td></tr>
180 %* int32_t Next argument after this one specifies the width
183 %* N/A This field is scanned, but not stored
185 <p>If you are using this C API instead of the ustream.h API for C++,
186 you can use one of the following u_fprintf examples to display a UnicodeString.</p>
189 UFILE *out = u_finit(stdout, NULL, NULL);
190 UnicodeString string1("string 1");
191 UnicodeString string2("string 2");
192 u_fprintf(out, "%S\n", string1.getTerminatedBuffer());
193 u_fprintf(out, "%.*S\n", string2.length(), string2.getBuffer());
201 * When an end of file is encountered, this value can be returned.
207 /** Forward declaration of a Unicode-aware file @stable 3.0 */
208 typedef struct UFILE UFILE;
211 * Enum for which direction of stream a transliterator applies to.
212 * @see u_fsettransliterator
218 U_READWRITE =3 /* == (U_READ | U_WRITE) */
223 * A UFILE is a wrapper around a FILE* that is locale and codepage aware.
224 * That is, data written to a UFILE will be formatted using the conventions
225 * specified by that UFILE's Locale; this data will be in the character set
226 * specified by that UFILE's codepage.
227 * @param filename The name of the file to open.
228 * @param perm The read/write permission for the UFILE; one of "r", "w", "rw"
229 * @param locale The locale whose conventions will be used to format
230 * and parse output. If this parameter is NULL, the default locale will
232 * @param codepage The codepage in which data will be written to and
233 * read from the file. If this paramter is NULL the system default codepage
235 * @return A new UFILE, or NULL if an error occurred.
238 U_STABLE UFILE* U_EXPORT2
239 u_fopen(const char *filename,
242 const char *codepage);
245 * Open a UFILE on top of an existing FILE* stream. The FILE* stream
246 * ownership remains with the caller. To have the UFILE take over
247 * ownership and responsibility for the FILE* stream, use the
249 * @param f The FILE* to which this UFILE will attach and use.
250 * @param locale The locale whose conventions will be used to format
251 * and parse output. If this parameter is NULL, the default locale will
253 * @param codepage The codepage in which data will be written to and
254 * read from the file. If this paramter is NULL, data will be written and
255 * read using the default codepage for <TT>locale</TT>, unless <TT>locale</TT>
256 * is NULL, in which case the system default codepage will be used.
257 * @return A new UFILE, or NULL if an error occurred.
260 U_STABLE UFILE* U_EXPORT2
263 const char *codepage);
266 * Open a UFILE on top of an existing FILE* stream. The FILE* stream
267 * ownership is transferred to the new UFILE. It will be closed when the
269 * @param f The FILE* which this UFILE will take ownership of.
270 * @param locale The locale whose conventions will be used to format
271 * and parse output. If this parameter is NULL, the default locale will
273 * @param codepage The codepage in which data will be written to and
274 * read from the file. If this paramter is NULL, data will be written and
275 * read using the default codepage for <TT>locale</TT>, unless <TT>locale</TT>
276 * is NULL, in which case the system default codepage will be used.
277 * @return A new UFILE, or NULL if an error occurred. If an error occurs
278 * the ownership of the FILE* stream remains with the caller.
281 U_STABLE UFILE* U_EXPORT2
284 const char *codepage);
287 * Create a UFILE that can be used for localized formatting or parsing.
288 * The u_sprintf and u_sscanf functions do not read or write numbers for a
289 * specific locale. The ustdio.h file functions can be used on this UFILE.
290 * The string is usable once u_fclose or u_fflush has been called on the
292 * @param stringBuf The string used for reading or writing.
293 * @param capacity The number of code units available for use in stringBuf
294 * @param locale The locale whose conventions will be used to format
295 * and parse output. If this parameter is NULL, the default locale will
297 * @return A new UFILE, or NULL if an error occurred.
300 U_STABLE UFILE* U_EXPORT2
301 u_fstropen(UChar *stringBuf,
306 * Close a UFILE. Implies u_fflush first.
307 * @param file The UFILE to close.
311 U_STABLE void U_EXPORT2
312 u_fclose(UFILE *file);
314 #if U_SHOW_CPLUSPLUS_API
319 * \class LocalUFILEPointer
320 * "Smart pointer" class, closes a UFILE via u_fclose().
321 * For most methods see the LocalPointerBase base class.
323 * @see LocalPointerBase
327 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose);
334 * Tests if the UFILE is at the end of the file stream.
335 * @param f The UFILE from which to read.
336 * @return Returns TRUE after the first read operation that attempts to
337 * read past the end of the file. It returns FALSE if the current position is
341 U_STABLE UBool U_EXPORT2
345 * Flush output of a UFILE. Implies a flush of
346 * converter/transliterator state. (That is, a logical break is
347 * made in the output stream - for example if a different type of
348 * output is desired.) The underlying OS level file is also flushed.
349 * Note that for a stateful encoding, the converter may write additional
350 * bytes to return the stream to default state.
351 * @param file The UFILE to flush.
354 U_STABLE void U_EXPORT2
355 u_fflush(UFILE *file);
358 * Rewind the file pointer to the beginning of the file.
359 * @param file The UFILE to rewind.
363 u_frewind(UFILE *file);
366 * Get the FILE* associated with a UFILE.
368 * @return A FILE*, owned by the UFILE. (The FILE <EM>must not</EM> be modified or closed)
371 U_STABLE FILE* U_EXPORT2
372 u_fgetfile(UFILE *f);
374 #if !UCONFIG_NO_FORMATTING
377 * Get the locale whose conventions are used to format and parse output.
378 * This is the same locale passed in the preceding call to<TT>u_fsetlocale</TT>
379 * or <TT>u_fopen</TT>.
380 * @param file The UFILE to set.
381 * @return The locale whose conventions are used to format and parse output.
384 U_STABLE const char* U_EXPORT2
385 u_fgetlocale(UFILE *file);
388 * Set the locale whose conventions will be used to format and parse output.
389 * @param locale The locale whose conventions will be used to format
391 * @param file The UFILE to query.
392 * @return NULL if successful, otherwise a negative number.
395 U_STABLE int32_t U_EXPORT2
396 u_fsetlocale(UFILE *file,
402 * Get the codepage in which data is written to and read from the UFILE.
403 * This is the same codepage passed in the preceding call to
404 * <TT>u_fsetcodepage</TT> or <TT>u_fopen</TT>.
405 * @param file The UFILE to query.
406 * @return The codepage in which data is written to and read from the UFILE,
407 * or NULL if an error occurred.
410 U_STABLE const char* U_EXPORT2
411 u_fgetcodepage(UFILE *file);
414 * Set the codepage in which data will be written to and read from the UFILE.
415 * All Unicode data written to the UFILE will be converted to this codepage
416 * before it is written to the underlying FILE*. It it generally a bad idea to
417 * mix codepages within a file. This should only be called right
418 * after opening the <TT>UFile</TT>, or after calling <TT>u_frewind</TT>.
419 * @param codepage The codepage in which data will be written to
420 * and read from the file. For example <TT>"latin-1"</TT> or <TT>"ibm-943"</TT>.
421 * A value of NULL means the default codepage for the UFILE's current
422 * locale will be used.
423 * @param file The UFILE to set.
424 * @return 0 if successful, otherwise a negative number.
428 U_STABLE int32_t U_EXPORT2
429 u_fsetcodepage(const char *codepage,
434 * Returns an alias to the converter being used for this file.
435 * @param f The UFILE to get the value from
436 * @return alias to the converter (The converter <EM>must not</EM> be modified or closed)
439 U_STABLE UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
441 #if !UCONFIG_NO_FORMATTING
442 #ifndef U_HIDE_DRAFT_API
444 * Returns an alias to the number formatter being used for this file.
445 * @param f The UFILE to get the value from
446 * @return alias to the number formatter (The formatter <EM>must not</EM> be modified or closed)
449 U_DRAFT const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);
450 #endif /* U_HIDE_DRAFT_API */
452 /* Output functions */
455 * Write formatted data to <TT>stdout</TT>.
456 * @param patternSpecification A pattern specifying how <TT>u_printf</TT> will
457 * interpret the variable arguments received and format the data.
458 * @return The number of Unicode characters written to <TT>stdout</TT>
461 U_STABLE int32_t U_EXPORT2
462 u_printf(const char *patternSpecification,
466 * Write formatted data to a UFILE.
467 * @param f The UFILE to which to write.
468 * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
469 * interpret the variable arguments received and format the data.
470 * @return The number of Unicode characters written to <TT>f</TT>.
473 U_STABLE int32_t U_EXPORT2
475 const char *patternSpecification,
479 * Write formatted data to a UFILE.
480 * This is identical to <TT>u_fprintf</TT>, except that it will
481 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
482 * @param f The UFILE to which to write.
483 * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
484 * interpret the variable arguments received and format the data.
485 * @param ap The argument list to use.
486 * @return The number of Unicode characters written to <TT>f</TT>.
490 U_STABLE int32_t U_EXPORT2
492 const char *patternSpecification,
496 * Write formatted data to <TT>stdout</TT>.
497 * @param patternSpecification A pattern specifying how <TT>u_printf_u</TT> will
498 * interpret the variable arguments received and format the data.
499 * @return The number of Unicode characters written to <TT>stdout</TT>
502 U_STABLE int32_t U_EXPORT2
503 u_printf_u(const UChar *patternSpecification,
507 * Get a UFILE for <TT>stdout</TT>.
508 * @return UFILE that writes to <TT>stdout</TT>
511 U_STABLE UFILE * U_EXPORT2
515 * Write formatted data to a UFILE.
516 * @param f The UFILE to which to write.
517 * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
518 * interpret the variable arguments received and format the data.
519 * @return The number of Unicode characters written to <TT>f</TT>.
522 U_STABLE int32_t U_EXPORT2
523 u_fprintf_u(UFILE *f,
524 const UChar *patternSpecification,
528 * Write formatted data to a UFILE.
529 * This is identical to <TT>u_fprintf_u</TT>, except that it will
530 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
531 * @param f The UFILE to which to write.
532 * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
533 * interpret the variable arguments received and format the data.
534 * @param ap The argument list to use.
535 * @return The number of Unicode characters written to <TT>f</TT>.
539 U_STABLE int32_t U_EXPORT2
540 u_vfprintf_u(UFILE *f,
541 const UChar *patternSpecification,
545 * Write a Unicode to a UFILE. The null (U+0000) terminated UChar*
546 * <TT>s</TT> will be written to <TT>f</TT>, excluding the NULL terminator.
547 * A newline will be added to <TT>f</TT>.
548 * @param s The UChar* to write.
549 * @param f The UFILE to which to write.
550 * @return A non-negative number if successful, EOF otherwise.
554 U_STABLE int32_t U_EXPORT2
555 u_fputs(const UChar *s,
559 * Write a UChar to a UFILE.
560 * @param uc The UChar to write.
561 * @param f The UFILE to which to write.
562 * @return The character written if successful, EOF otherwise.
565 U_STABLE UChar32 U_EXPORT2
570 * Write Unicode to a UFILE.
571 * The ustring passed in will be converted to the UFILE's underlying
572 * codepage before it is written.
573 * @param ustring A pointer to the Unicode data to write.
574 * @param count The number of Unicode characters to write
575 * @param f The UFILE to which to write.
576 * @return The number of Unicode characters written.
580 U_STABLE int32_t U_EXPORT2
581 u_file_write(const UChar *ustring,
586 /* Input functions */
587 #if !UCONFIG_NO_FORMATTING
590 * Read formatted data from a UFILE.
591 * @param f The UFILE from which to read.
592 * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
593 * interpret the variable arguments received and parse the data.
594 * @return The number of items successfully converted and assigned, or EOF
595 * if an error occurred.
598 U_STABLE int32_t U_EXPORT2
600 const char *patternSpecification,
604 * Read formatted data from a UFILE.
605 * This is identical to <TT>u_fscanf</TT>, except that it will
606 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
607 * @param f The UFILE from which to read.
608 * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
609 * interpret the variable arguments received and parse the data.
610 * @param ap The argument list to use.
611 * @return The number of items successfully converted and assigned, or EOF
612 * if an error occurred.
616 U_STABLE int32_t U_EXPORT2
618 const char *patternSpecification,
622 * Read formatted data from a UFILE.
623 * @param f The UFILE from which to read.
624 * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
625 * interpret the variable arguments received and parse the data.
626 * @return The number of items successfully converted and assigned, or EOF
627 * if an error occurred.
630 U_STABLE int32_t U_EXPORT2
632 const UChar *patternSpecification,
636 * Read formatted data from a UFILE.
637 * This is identical to <TT>u_fscanf_u</TT>, except that it will
638 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
639 * @param f The UFILE from which to read.
640 * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
641 * interpret the variable arguments received and parse the data.
642 * @param ap The argument list to use.
643 * @return The number of items successfully converted and assigned, or EOF
644 * if an error occurred.
648 U_STABLE int32_t U_EXPORT2
649 u_vfscanf_u(UFILE *f,
650 const UChar *patternSpecification,
655 * Read one line of text into a UChar* string from a UFILE. The newline
656 * at the end of the line is read into the string. The string is always
658 * @param f The UFILE from which to read.
659 * @param n The maximum number of characters - 1 to read.
660 * @param s The UChar* to receive the read data. Characters will be
661 * stored successively in <TT>s</TT> until a newline or EOF is
662 * reached. A null character (U+0000) will be appended to <TT>s</TT>.
663 * @return A pointer to <TT>s</TT>, or NULL if no characters were available.
666 U_STABLE UChar* U_EXPORT2
672 * Read a UChar from a UFILE. It is recommended that <TT>u_fgetcx</TT>
673 * used instead for proper parsing functions, but sometimes reading
674 * code units is needed instead of codepoints.
676 * @param f The UFILE from which to read.
677 * @return The UChar value read, or U+FFFF if no character was available.
680 U_STABLE UChar U_EXPORT2
684 * Read a UChar32 from a UFILE.
686 * @param f The UFILE from which to read.
687 * @return The UChar32 value read, or U_EOF if no character was
688 * available, or U+FFFFFFFF if an ill-formed character was
693 U_STABLE UChar32 U_EXPORT2
697 * Unget a UChar from a UFILE.
698 * If this function is not the first to operate on <TT>f</TT> after a call
699 * to <TT>u_fgetc</TT>, the results are undefined.
700 * If this function is passed a character that was not recieved from the
701 * previous <TT>u_fgetc</TT> or <TT>u_fgetcx</TT> call, the results are undefined.
702 * @param c The UChar to put back on the stream.
703 * @param f The UFILE to receive <TT>c</TT>.
704 * @return The UChar32 value put back if successful, U_EOF otherwise.
707 U_STABLE UChar32 U_EXPORT2
712 * Read Unicode from a UFILE.
713 * Bytes will be converted from the UFILE's underlying codepage, with
714 * subsequent conversion to Unicode. The data will not be NULL terminated.
715 * @param chars A pointer to receive the Unicode data.
716 * @param count The number of Unicode characters to read.
717 * @param f The UFILE from which to read.
718 * @return The number of Unicode characters read.
721 U_STABLE int32_t U_EXPORT2
722 u_file_read(UChar *chars,
726 #if !UCONFIG_NO_TRANSLITERATION
729 * Set a transliterator on the UFILE. The transliterator will be owned by the
731 * @param file The UFILE to set transliteration on
732 * @param adopt The UTransliterator to set. Can be NULL, which will
733 * mean that no transliteration is used.
734 * @param direction either U_READ, U_WRITE, or U_READWRITE - sets
735 * which direction the transliterator is to be applied to. If
736 * U_READWRITE, the "Read" transliteration will be in the inverse
738 * @param status ICU error code.
739 * @return The previously set transliterator, owned by the
740 * caller. If U_READWRITE is specified, only the WRITE transliterator
741 * is returned. In most cases, the caller should call utrans_close()
742 * on the result of this function.
745 U_STABLE UTransliterator* U_EXPORT2
746 u_fsettransliterator(UFILE *file, UFileDirection direction,
747 UTransliterator *adopt, UErrorCode *status);
752 /* Output string functions */
753 #if !UCONFIG_NO_FORMATTING
757 * Write formatted data to a Unicode string.
759 * @param buffer The Unicode String to which to write.
760 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
761 * interpret the variable arguments received and format the data.
762 * @return The number of Unicode code units written to <TT>buffer</TT>. This
763 * does not include the terminating null character.
766 U_STABLE int32_t U_EXPORT2
767 u_sprintf(UChar *buffer,
768 const char *patternSpecification,
772 * Write formatted data to a Unicode string. When the number of code units
773 * required to store the data exceeds <TT>count</TT>, then <TT>count</TT> code
774 * units of data are stored in <TT>buffer</TT> and a negative value is
775 * returned. When the number of code units required to store the data equals
776 * <TT>count</TT>, the string is not null terminated and <TT>count</TT> is
779 * @param buffer The Unicode String to which to write.
780 * @param count The number of code units to read.
781 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
782 * interpret the variable arguments received and format the data.
783 * @return The number of Unicode characters that would have been written to
784 * <TT>buffer</TT> had count been sufficiently large. This does not include
785 * the terminating null character.
788 U_STABLE int32_t U_EXPORT2
789 u_snprintf(UChar *buffer,
791 const char *patternSpecification,
795 * Write formatted data to a Unicode string.
796 * This is identical to <TT>u_sprintf</TT>, except that it will
797 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
799 * @param buffer The Unicode string to which to write.
800 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
801 * interpret the variable arguments received and format the data.
802 * @param ap The argument list to use.
803 * @return The number of Unicode characters written to <TT>buffer</TT>.
807 U_STABLE int32_t U_EXPORT2
808 u_vsprintf(UChar *buffer,
809 const char *patternSpecification,
813 * Write formatted data to a Unicode string.
814 * This is identical to <TT>u_snprintf</TT>, except that it will
815 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.<br><br>
816 * When the number of code units required to store the data exceeds
817 * <TT>count</TT>, then <TT>count</TT> code units of data are stored in
818 * <TT>buffer</TT> and a negative value is returned. When the number of code
819 * units required to store the data equals <TT>count</TT>, the string is not
820 * null terminated and <TT>count</TT> is returned.
822 * @param buffer The Unicode string to which to write.
823 * @param count The number of code units to read.
824 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
825 * interpret the variable arguments received and format the data.
826 * @param ap The argument list to use.
827 * @return The number of Unicode characters that would have been written to
828 * <TT>buffer</TT> had count been sufficiently large.
832 U_STABLE int32_t U_EXPORT2
833 u_vsnprintf(UChar *buffer,
835 const char *patternSpecification,
839 * Write formatted data to a Unicode string.
841 * @param buffer The Unicode string to which to write.
842 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
843 * interpret the variable arguments received and format the data.
844 * @return The number of Unicode characters written to <TT>buffer</TT>.
847 U_STABLE int32_t U_EXPORT2
848 u_sprintf_u(UChar *buffer,
849 const UChar *patternSpecification,
853 * Write formatted data to a Unicode string. When the number of code units
854 * required to store the data exceeds <TT>count</TT>, then <TT>count</TT> code
855 * units of data are stored in <TT>buffer</TT> and a negative value is
856 * returned. When the number of code units required to store the data equals
857 * <TT>count</TT>, the string is not null terminated and <TT>count</TT> is
860 * @param buffer The Unicode string to which to write.
861 * @param count The number of code units to read.
862 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
863 * interpret the variable arguments received and format the data.
864 * @return The number of Unicode characters that would have been written to
865 * <TT>buffer</TT> had count been sufficiently large.
868 U_STABLE int32_t U_EXPORT2
869 u_snprintf_u(UChar *buffer,
871 const UChar *patternSpecification,
875 * Write formatted data to a Unicode string.
876 * This is identical to <TT>u_sprintf_u</TT>, except that it will
877 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
879 * @param buffer The Unicode string to which to write.
880 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
881 * interpret the variable arguments received and format the data.
882 * @param ap The argument list to use.
883 * @return The number of Unicode characters written to <TT>f</TT>.
887 U_STABLE int32_t U_EXPORT2
888 u_vsprintf_u(UChar *buffer,
889 const UChar *patternSpecification,
893 * Write formatted data to a Unicode string.
894 * This is identical to <TT>u_snprintf_u</TT>, except that it will
895 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
896 * When the number of code units required to store the data exceeds
897 * <TT>count</TT>, then <TT>count</TT> code units of data are stored in
898 * <TT>buffer</TT> and a negative value is returned. When the number of code
899 * units required to store the data equals <TT>count</TT>, the string is not
900 * null terminated and <TT>count</TT> is returned.
902 * @param buffer The Unicode string to which to write.
903 * @param count The number of code units to read.
904 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will
905 * interpret the variable arguments received and format the data.
906 * @param ap The argument list to use.
907 * @return The number of Unicode characters that would have been written to
908 * <TT>f</TT> had count been sufficiently large.
912 U_STABLE int32_t U_EXPORT2
913 u_vsnprintf_u(UChar *buffer,
915 const UChar *patternSpecification,
918 /* Input string functions */
921 * Read formatted data from a Unicode string.
923 * @param buffer The Unicode string from which to read.
924 * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will
925 * interpret the variable arguments received and parse the data.
926 * @return The number of items successfully converted and assigned, or EOF
927 * if an error occurred.
930 U_STABLE int32_t U_EXPORT2
931 u_sscanf(const UChar *buffer,
932 const char *patternSpecification,
936 * Read formatted data from a Unicode string.
937 * This is identical to <TT>u_sscanf</TT>, except that it will
938 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
940 * @param buffer The Unicode string from which to read.
941 * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will
942 * interpret the variable arguments received and parse the data.
943 * @param ap The argument list to use.
944 * @return The number of items successfully converted and assigned, or EOF
945 * if an error occurred.
949 U_STABLE int32_t U_EXPORT2
950 u_vsscanf(const UChar *buffer,
951 const char *patternSpecification,
955 * Read formatted data from a Unicode string.
957 * @param buffer The Unicode string from which to read.
958 * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will
959 * interpret the variable arguments received and parse the data.
960 * @return The number of items successfully converted and assigned, or EOF
961 * if an error occurred.
964 U_STABLE int32_t U_EXPORT2
965 u_sscanf_u(const UChar *buffer,
966 const UChar *patternSpecification,
970 * Read formatted data from a Unicode string.
971 * This is identical to <TT>u_sscanf_u</TT>, except that it will
972 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.
974 * @param buffer The Unicode string from which to read.
975 * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will
976 * interpret the variable arguments received and parse the data.
977 * @param ap The argument list to use.
978 * @return The number of items successfully converted and assigned, or EOF
979 * if an error occurred.
983 U_STABLE int32_t U_EXPORT2
984 u_vsscanf_u(const UChar *buffer,
985 const UChar *patternSpecification,