1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ****************************************************************************** 5 * 6 * Copyright (C) 1998-2015, International Business Machines 7 * Corporation and others. All Rights Reserved. 8 * 9 ****************************************************************************** 10 * 11 * File ustdio.h 12 * 13 * Modification History: 14 * 15 * Date Name Description 16 * 10/16/98 stephen Creation. 17 * 11/06/98 stephen Modified per code review. 18 * 03/12/99 stephen Modified for new C API. 19 * 07/19/99 stephen Minor doc update. 20 * 02/01/01 george Added sprintf & sscanf with all of its variants 21 ****************************************************************************** 22 */ 23 24 #ifndef USTDIO_H 25 #define USTDIO_H 26 27 #include <stdio.h> 28 #include <stdarg.h> 29 30 #include "unicode/utypes.h" 31 #include "unicode/ucnv.h" 32 #include "unicode/utrans.h" 33 #include "unicode/unum.h" 34 35 #if U_SHOW_CPLUSPLUS_API 36 #include "unicode/localpointer.h" 37 #endif // U_SHOW_CPLUSPLUS_API 38 39 #if !UCONFIG_NO_CONVERSION 40 41 /* 42 TODO 43 The following is a small list as to what is currently wrong/suggestions for 44 ustdio. 45 46 * Make sure that * in the scanf format specification works for all formats. 47 * Each UFILE takes up at least 2KB. 48 Look into adding setvbuf() for configurable buffers. 49 * This library does buffering. The OS should do this for us already. Check on 50 this, and remove it from this library, if this is the case. Double buffering 51 wastes a lot of time and space. 52 * Test stdin and stdout with the u_f* functions 53 * Testing should be done for reading and writing multi-byte encodings, 54 and make sure that a character that is contained across buffer boundaries 55 works even for incomplete characters. 56 * Make sure that the last character is flushed when the file/string is closed. 57 * snprintf should follow the C99 standard for the return value, which is 58 return the number of characters (excluding the trailing '\0') 59 which would have been written to the destination string regardless 60 of available space. This is like pre-flighting. 61 * Everything that uses %s should do what operator>> does for UnicodeString. 62 It should convert one byte at a time, and once a character is 63 converted then check to see if it's whitespace or in the scanset. 64 If it's whitespace or in the scanset, put all the bytes back (do nothing 65 for sprintf/sscanf). 66 * If bad string data is encountered, make sure that the function fails 67 without memory leaks and the unconvertable characters are valid 68 substitution or are escaped characters. 69 * u_fungetc() can't unget a character when it's at the beginning of the 70 internal conversion buffer. For example, read the buffer size # of 71 characters, and then ungetc to get the previous character that was 72 at the end of the last buffer. 73 * u_fflush() and u_fclose should return an int32_t like C99 functions. 74 0 is returned if the operation was successful and EOF otherwise. 75 * u_fsettransliterator does not support U_READ side of transliteration. 76 * The format specifier should limit the size of a format or honor it in 77 order to prevent buffer overruns. (e.g. %256.256d). 78 * u_fread and u_fwrite don't exist. They're needed for reading and writing 79 data structures without any conversion. 80 * u_file_read and u_file_write are used for writing strings. u_fgets and 81 u_fputs or u_fread and u_fwrite should be used to do this. 82 * The width parameter for all scanf formats, including scanset, needs 83 better testing. This prevents buffer overflows. 84 * Figure out what is suppose to happen when a codepage is changed midstream. 85 Maybe a flush or a rewind are good enough. 86 * Make sure that a UFile opened with "rw" can be used after using 87 u_fflush with a u_frewind. 88 * scanf(%i) should detect what type of number to use. 89 * Add more testing of the alternate format, %# 90 * Look at newline handling of fputs/puts 91 * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[] 92 * Complete the file documentation with proper doxygen formatting. 93 See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html 94 */ 95 96 /** 97 * \file 98 * \brief C API: Unicode stdio-like API 99 * 100 * <h2>Unicode stdio-like C API</h2> 101 * 102 * <p>This API provides an stdio-like API wrapper around ICU's other 103 * formatting and parsing APIs. It is meant to ease the transition of adding 104 * Unicode support to a preexisting applications using stdio. The following 105 * is a small list of noticeable differences between stdio and ICU I/O's 106 * ustdio implementation.</p> 107 * 108 * <ul> 109 * <li>Locale specific formatting and parsing is only done with file IO.</li> 110 * <li>u_fstropen can be used to simulate file IO with strings. 111 * This is similar to the iostream API, and it allows locale specific 112 * formatting and parsing to be used.</li> 113 * <li>This API provides uniform formatting and parsing behavior between 114 * platforms (unlike the standard stdio implementations found on various 115 * platforms).</li> 116 * <li>This API is better suited for text data handling than binary data 117 * handling when compared to the typical stdio implementation.</li> 118 * <li>You can specify a Transliterator while using the file IO.</li> 119 * <li>You can specify a file's codepage separately from the default 120 * system codepage.</li> 121 * </ul> 122 * 123 * <h2>Formatting and Parsing Specification</h2> 124 * 125 * General printf format:<br> 126 * %[format modifier][width][.precision][type modifier][format] 127 * 128 * General scanf format:<br> 129 * %[*][format modifier][width][type modifier][format] 130 * 131 <table cellspacing="3"> 132 <tr><td>format</td><td>default<br>printf<br>type</td><td>default<br>scanf<br>type</td><td>description</td></tr> 133 <tr><td>%E</td><td>double</td><td>float</td><td>Scientific with an uppercase exponent</td></tr> 134 <tr><td>%e</td><td>double</td><td>float</td><td>Scientific with a lowercase exponent</td></tr> 135 <tr><td>%G</td><td>double</td><td>float</td><td>Use %E or %f for best format</td></tr> 136 <tr><td>%g</td><td>double</td><td>float</td><td>Use %e or %f for best format</td></tr> 137 <tr><td>%f</td><td>double</td><td>float</td><td>Simple floating point without the exponent</td></tr> 138 <tr><td>%X</td><td>int32_t</td><td>int32_t</td><td>ustdio special uppercase hex radix formatting</td></tr> 139 <tr><td>%x</td><td>int32_t</td><td>int32_t</td><td>ustdio special lowercase hex radix formatting</td></tr> 140 <tr><td>%d</td><td>int32_t</td><td>int32_t</td><td>Decimal format</td></tr> 141 <tr><td>%i</td><td>int32_t</td><td>int32_t</td><td>Same as %d</td></tr> 142 <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> 143 <tr><td>%o</td><td>int32_t</td><td>int32_t</td><td>ustdio special octal radix formatting</td></tr> 144 <tr><td>%u</td><td>uint32_t</td><td>uint32_t</td><td>Decimal format</td></tr> 145 <tr><td>%p</td><td>void *</td><td>void *</td><td>Prints the pointer value</td></tr> 146 <tr><td>%s</td><td>char *</td><td>char *</td><td>Use default converter or specified converter from fopen</td></tr> 147 <tr><td>%c</td><td>char</td><td>char</td><td>Use default converter or specified converter from fopen<br> 148 When width is specified for scanf, this acts like a non-NULL-terminated char * string.<br> 149 By default, only one char is written.</td></tr> 150 <tr><td>%S</td><td>UChar *</td><td>UChar *</td><td>Null terminated UTF-16 string</td></tr> 151 <tr><td>%C</td><td>UChar</td><td>UChar</td><td>16-bit Unicode code unit<br> 152 When width is specified for scanf, this acts like a non-NULL-terminated UChar * string<br> 153 By default, only one codepoint is written.</td></tr> 154 <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> 155 <tr><td>%%</td><td> </td><td> </td><td>Show a percent sign</td></tr> 156 </table> 157 158 Format modifiers 159 <table> 160 <tr><td>modifier</td><td>formats</td><td>type</td><td>comments</td></tr> 161 <tr><td>%h</td><td>%d, %i, %o, %x</td><td>int16_t</td><td>short format</td></tr> 162 <tr><td>%h</td><td>%u</td><td>uint16_t</td><td>short format</td></tr> 163 <tr><td>%h</td><td>c</td><td>char</td><td><b>(Unimplemented)</b> Use invariant converter</td></tr> 164 <tr><td>%h</td><td>s</td><td>char *</td><td><b>(Unimplemented)</b> Use invariant converter</td></tr> 165 <tr><td>%h</td><td>C</td><td>char</td><td><b>(Unimplemented)</b> 8-bit Unicode code unit</td></tr> 166 <tr><td>%h</td><td>S</td><td>char *</td><td><b>(Unimplemented)</b> Null terminated UTF-8 string</td></tr> 167 <tr><td>%l</td><td>%d, %i, %o, %x</td><td>int32_t</td><td>long format (no effect)</td></tr> 168 <tr><td>%l</td><td>%u</td><td>uint32_t</td><td>long format (no effect)</td></tr> 169 <tr><td>%l</td><td>c</td><td>N/A</td><td><b>(Unimplemented)</b> Reserved for future implementation</td></tr> 170 <tr><td>%l</td><td>s</td><td>N/A</td><td><b>(Unimplemented)</b> Reserved for future implementation</td></tr> 171 <tr><td>%l</td><td>C</td><td>UChar32</td><td><b>(Unimplemented)</b> 32-bit Unicode code unit</td></tr> 172 <tr><td>%l</td><td>S</td><td>UChar32 *</td><td><b>(Unimplemented)</b> Null terminated UTF-32 string</td></tr> 173 <tr><td>%ll</td><td>%d, %i, %o, %x</td><td>int64_t</td><td>long long format</td></tr> 174 <tr><td>%ll</td><td>%u</td><td>uint64_t</td><td><b>(Unimplemented)</b> long long format</td></tr> 175 <tr><td>%-</td><td><i>all</i></td><td>N/A</td><td>Left justify</td></tr> 176 <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> 177 <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> 178 <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 179 decimal point for floats.</td></tr> 180 <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 181 some large number.</td></tr> 182 <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 183 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> 184 </table> 185 186 printf modifier 187 %* int32_t Next argument after this one specifies the width 188 189 scanf modifier 190 %* N/A This field is scanned, but not stored 191 192 <p>If you are using this C API instead of the ustream.h API for C++, 193 you can use one of the following u_fprintf examples to display a UnicodeString.</p> 194 195 <pre><code> 196 UFILE *out = u_finit(stdout, NULL, NULL); 197 UnicodeString string1("string 1"); 198 UnicodeString string2("string 2"); 199 u_fprintf(out, "%S\n", string1.getTerminatedBuffer()); 200 u_fprintf(out, "%.*S\n", string2.length(), string2.getBuffer()); 201 u_fclose(out); 202 </code></pre> 203 204 */ 205 206 207 /** 208 * When an end of file is encountered, this value can be returned. 209 * @see u_fgetc 210 * @stable 3.0 211 */ 212 #define U_EOF 0xFFFF 213 214 /** Forward declaration of a Unicode-aware file @stable 3.0 */ 215 typedef struct UFILE UFILE; 216 217 /** 218 * Enum for which direction of stream a transliterator applies to. 219 * @see u_fsettransliterator 220 * @stable ICU 3.0 221 */ 222 typedef enum { 223 U_READ = 1, 224 U_WRITE = 2, 225 U_READWRITE =3 /* == (U_READ | U_WRITE) */ 226 } UFileDirection; 227 228 /** 229 * Open a UFILE. 230 * A UFILE is a wrapper around a FILE* that is locale and codepage aware. 231 * That is, data written to a UFILE will be formatted using the conventions 232 * specified by that UFILE's Locale; this data will be in the character set 233 * specified by that UFILE's codepage. 234 * @param filename The name of the file to open. Must be 0-terminated. 235 * @param perm The read/write permission for the UFILE; one of "r", "w", "rw" 236 * @param locale The locale whose conventions will be used to format 237 * and parse output. If this parameter is NULL, the default locale will 238 * be used. 239 * @param codepage The codepage in which data will be written to and 240 * read from the file. If this parameter is NULL the system default codepage 241 * will be used. 242 * @return A new UFILE, or NULL if an error occurred. 243 * @stable ICU 3.0 244 */ 245 U_CAPI UFILE* U_EXPORT2 246 u_fopen(const char *filename, 247 const char *perm, 248 const char *locale, 249 const char *codepage); 250 251 /** 252 * Open a UFILE with a UChar* filename 253 * A UFILE is a wrapper around a FILE* that is locale and codepage aware. 254 * That is, data written to a UFILE will be formatted using the conventions 255 * specified by that UFILE's Locale; this data will be in the character set 256 * specified by that UFILE's codepage. 257 * @param filename The name of the file to open. Must be 0-terminated. 258 * @param perm The read/write permission for the UFILE; one of "r", "w", "rw" 259 * @param locale The locale whose conventions will be used to format 260 * and parse output. If this parameter is NULL, the default locale will 261 * be used. 262 * @param codepage The codepage in which data will be written to and 263 * read from the file. If this parameter is NULL the system default codepage 264 * will be used. 265 * @return A new UFILE, or NULL if an error occurred. 266 * @stable ICU 54 267 */ 268 U_CAPI UFILE* U_EXPORT2 269 u_fopen_u(const UChar *filename, 270 const char *perm, 271 const char *locale, 272 const char *codepage); 273 274 /** 275 * Open a UFILE on top of an existing FILE* stream. The FILE* stream 276 * ownership remains with the caller. To have the UFILE take over 277 * ownership and responsibility for the FILE* stream, use the 278 * function u_fadopt. 279 * @param f The FILE* to which this UFILE will attach and use. 280 * @param locale The locale whose conventions will be used to format 281 * and parse output. If this parameter is NULL, the default locale will 282 * be used. 283 * @param codepage The codepage in which data will be written to and 284 * read from the file. If this parameter is NULL, data will be written and 285 * read using the default codepage for <TT>locale</TT>, unless <TT>locale</TT> 286 * is NULL, in which case the system default codepage will be used. 287 * @return A new UFILE, or NULL if an error occurred. 288 * @stable ICU 3.0 289 */ 290 U_CAPI UFILE* U_EXPORT2 291 u_finit(FILE *f, 292 const char *locale, 293 const char *codepage); 294 295 /** 296 * Open a UFILE on top of an existing FILE* stream. The FILE* stream 297 * ownership is transferred to the new UFILE. It will be closed when the 298 * UFILE is closed. 299 * @param f The FILE* which this UFILE will take ownership of. 300 * @param locale The locale whose conventions will be used to format 301 * and parse output. If this parameter is NULL, the default locale will 302 * be used. 303 * @param codepage The codepage in which data will be written to and 304 * read from the file. If this parameter is NULL, data will be written and 305 * read using the default codepage for <TT>locale</TT>, unless <TT>locale</TT> 306 * is NULL, in which case the system default codepage will be used. 307 * @return A new UFILE, or NULL if an error occurred. If an error occurs 308 * the ownership of the FILE* stream remains with the caller. 309 * @stable ICU 4.4 310 */ 311 U_CAPI UFILE* U_EXPORT2 312 u_fadopt(FILE *f, 313 const char *locale, 314 const char *codepage); 315 316 /** 317 * Create a UFILE that can be used for localized formatting or parsing. 318 * The u_sprintf and u_sscanf functions do not read or write numbers for a 319 * specific locale. The ustdio.h file functions can be used on this UFILE. 320 * The string is usable once u_fclose or u_fflush has been called on the 321 * returned UFILE. 322 * @param stringBuf The string used for reading or writing. 323 * @param capacity The number of code units available for use in stringBuf 324 * @param locale The locale whose conventions will be used to format 325 * and parse output. If this parameter is NULL, the default locale will 326 * be used. 327 * @return A new UFILE, or NULL if an error occurred. 328 * @stable ICU 3.0 329 */ 330 U_CAPI UFILE* U_EXPORT2 331 u_fstropen(UChar *stringBuf, 332 int32_t capacity, 333 const char *locale); 334 335 /** 336 * Close a UFILE. Implies u_fflush first. 337 * @param file The UFILE to close. 338 * @stable ICU 3.0 339 * @see u_fflush 340 */ 341 U_CAPI void U_EXPORT2 342 u_fclose(UFILE *file); 343 344 #if U_SHOW_CPLUSPLUS_API 345 346 U_NAMESPACE_BEGIN 347 348 /** 349 * \class LocalUFILEPointer 350 * "Smart pointer" class, closes a UFILE via u_fclose(). 351 * For most methods see the LocalPointerBase base class. 352 * 353 * @see LocalPointerBase 354 * @see LocalPointer 355 * @stable ICU 4.4 356 */ 357 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose); 358 359 U_NAMESPACE_END 360 361 #endif 362 363 /** 364 * Tests if the UFILE is at the end of the file stream. 365 * @param f The UFILE from which to read. 366 * @return Returns true after the first read operation that attempts to 367 * read past the end of the file. It returns false if the current position is 368 * not end of file. 369 * @stable ICU 3.0 370 */ 371 U_CAPI UBool U_EXPORT2 372 u_feof(UFILE *f); 373 374 /** 375 * Flush output of a UFILE. Implies a flush of 376 * converter/transliterator state. (That is, a logical break is 377 * made in the output stream - for example if a different type of 378 * output is desired.) The underlying OS level file is also flushed. 379 * Note that for a stateful encoding, the converter may write additional 380 * bytes to return the stream to default state. 381 * @param file The UFILE to flush. 382 * @stable ICU 3.0 383 */ 384 U_CAPI void U_EXPORT2 385 u_fflush(UFILE *file); 386 387 /** 388 * Rewind the file pointer to the beginning of the file. 389 * @param file The UFILE to rewind. 390 * @stable ICU 3.0 391 */ 392 U_CAPI void 393 u_frewind(UFILE *file); 394 395 /** 396 * Get the FILE* associated with a UFILE. 397 * @param f The UFILE 398 * @return A FILE*, owned by the UFILE. (The FILE <EM>must not</EM> be modified or closed) 399 * @stable ICU 3.0 400 */ 401 U_CAPI FILE* U_EXPORT2 402 u_fgetfile(UFILE *f); 403 404 #if !UCONFIG_NO_FORMATTING 405 406 /** 407 * Get the locale whose conventions are used to format and parse output. 408 * This is the same locale passed in the preceding call to<TT>u_fsetlocale</TT> 409 * or <TT>u_fopen</TT>. 410 * @param file The UFILE to set. 411 * @return The locale whose conventions are used to format and parse output. 412 * @stable ICU 3.0 413 */ 414 U_CAPI const char* U_EXPORT2 415 u_fgetlocale(UFILE *file); 416 417 /** 418 * Set the locale whose conventions will be used to format and parse output. 419 * @param locale The locale whose conventions will be used to format 420 * and parse output. 421 * @param file The UFILE to query. 422 * @return NULL if successful, otherwise a negative number. 423 * @stable ICU 3.0 424 */ 425 U_CAPI int32_t U_EXPORT2 426 u_fsetlocale(UFILE *file, 427 const char *locale); 428 429 #endif 430 431 /** 432 * Get the codepage in which data is written to and read from the UFILE. 433 * This is the same codepage passed in the preceding call to 434 * <TT>u_fsetcodepage</TT> or <TT>u_fopen</TT>. 435 * @param file The UFILE to query. 436 * @return The codepage in which data is written to and read from the UFILE, 437 * or NULL if an error occurred. 438 * @stable ICU 3.0 439 */ 440 U_CAPI const char* U_EXPORT2 441 u_fgetcodepage(UFILE *file); 442 443 /** 444 * Set the codepage in which data will be written to and read from the UFILE. 445 * All Unicode data written to the UFILE will be converted to this codepage 446 * before it is written to the underlying FILE*. It it generally a bad idea to 447 * mix codepages within a file. This should only be called right 448 * after opening the <TT>UFile</TT>, or after calling <TT>u_frewind</TT>. 449 * @param codepage The codepage in which data will be written to 450 * and read from the file. For example <TT>"latin-1"</TT> or <TT>"ibm-943"</TT>. 451 * A value of NULL means the default codepage for the UFILE's current 452 * locale will be used. 453 * @param file The UFILE to set. 454 * @return 0 if successful, otherwise a negative number. 455 * @see u_frewind 456 * @stable ICU 3.0 457 */ 458 U_CAPI int32_t U_EXPORT2 459 u_fsetcodepage(const char *codepage, 460 UFILE *file); 461 462 463 /** 464 * Returns an alias to the converter being used for this file. 465 * @param f The UFILE to get the value from 466 * @return alias to the converter (The converter <EM>must not</EM> be modified or closed) 467 * @stable ICU 3.0 468 */ 469 U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f); 470 471 #if !UCONFIG_NO_FORMATTING 472 /** 473 * Returns an alias to the number formatter being used for this file. 474 * @param f The UFILE to get the value from 475 * @return alias to the number formatter (The formatter <EM>must not</EM> be modified or closed) 476 * @stable ICU 51 477 */ 478 U_CAPI const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f); 479 480 /* Output functions */ 481 482 /** 483 * Write formatted data to <TT>stdout</TT>. 484 * @param patternSpecification A pattern specifying how <TT>u_printf</TT> will 485 * interpret the variable arguments received and format the data. 486 * @return The number of Unicode characters written to <TT>stdout</TT> 487 * @stable ICU 49 488 */ 489 U_CAPI int32_t U_EXPORT2 490 u_printf(const char *patternSpecification, 491 ... ); 492 493 /** 494 * Write formatted data to a UFILE. 495 * @param f The UFILE to which to write. 496 * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will 497 * interpret the variable arguments received and format the data. 498 * @return The number of Unicode characters written to <TT>f</TT>. 499 * @stable ICU 3.0 500 */ 501 U_CAPI int32_t U_EXPORT2 502 u_fprintf(UFILE *f, 503 const char *patternSpecification, 504 ... ); 505 506 /** 507 * Write formatted data to a UFILE. 508 * This is identical to <TT>u_fprintf</TT>, except that it will 509 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 510 * @param f The UFILE to which to write. 511 * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will 512 * interpret the variable arguments received and format the data. 513 * @param ap The argument list to use. 514 * @return The number of Unicode characters written to <TT>f</TT>. 515 * @see u_fprintf 516 * @stable ICU 3.0 517 */ 518 U_CAPI int32_t U_EXPORT2 519 u_vfprintf(UFILE *f, 520 const char *patternSpecification, 521 va_list ap); 522 523 /** 524 * Write formatted data to <TT>stdout</TT>. 525 * @param patternSpecification A pattern specifying how <TT>u_printf_u</TT> will 526 * interpret the variable arguments received and format the data. 527 * @return The number of Unicode characters written to <TT>stdout</TT> 528 * @stable ICU 49 529 */ 530 U_CAPI int32_t U_EXPORT2 531 u_printf_u(const UChar *patternSpecification, 532 ... ); 533 534 /** 535 * Get a UFILE for <TT>stdout</TT>. 536 * @return UFILE that writes to <TT>stdout</TT> 537 * @stable ICU 49 538 */ 539 U_CAPI UFILE * U_EXPORT2 540 u_get_stdout(void); 541 542 /** 543 * Write formatted data to a UFILE. 544 * @param f The UFILE to which to write. 545 * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will 546 * interpret the variable arguments received and format the data. 547 * @return The number of Unicode characters written to <TT>f</TT>. 548 * @stable ICU 3.0 549 */ 550 U_CAPI int32_t U_EXPORT2 551 u_fprintf_u(UFILE *f, 552 const UChar *patternSpecification, 553 ... ); 554 555 /** 556 * Write formatted data to a UFILE. 557 * This is identical to <TT>u_fprintf_u</TT>, except that it will 558 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 559 * @param f The UFILE to which to write. 560 * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will 561 * interpret the variable arguments received and format the data. 562 * @param ap The argument list to use. 563 * @return The number of Unicode characters written to <TT>f</TT>. 564 * @see u_fprintf_u 565 * @stable ICU 3.0 566 */ 567 U_CAPI int32_t U_EXPORT2 568 u_vfprintf_u(UFILE *f, 569 const UChar *patternSpecification, 570 va_list ap); 571 #endif 572 /** 573 * Write a Unicode to a UFILE. The null (U+0000) terminated UChar* 574 * <TT>s</TT> will be written to <TT>f</TT>, excluding the NULL terminator. 575 * A newline will be added to <TT>f</TT>. 576 * @param s The UChar* to write. 577 * @param f The UFILE to which to write. 578 * @return A non-negative number if successful, EOF otherwise. 579 * @see u_file_write 580 * @stable ICU 3.0 581 */ 582 U_CAPI int32_t U_EXPORT2 583 u_fputs(const UChar *s, 584 UFILE *f); 585 586 /** 587 * Write a UChar to a UFILE. 588 * @param uc The UChar to write. 589 * @param f The UFILE to which to write. 590 * @return The character written if successful, EOF otherwise. 591 * @stable ICU 3.0 592 */ 593 U_CAPI UChar32 U_EXPORT2 594 u_fputc(UChar32 uc, 595 UFILE *f); 596 597 /** 598 * Write Unicode to a UFILE. 599 * The ustring passed in will be converted to the UFILE's underlying 600 * codepage before it is written. 601 * @param ustring A pointer to the Unicode data to write. 602 * @param count The number of Unicode characters to write 603 * @param f The UFILE to which to write. 604 * @return The number of Unicode characters written. 605 * @see u_fputs 606 * @stable ICU 3.0 607 */ 608 U_CAPI int32_t U_EXPORT2 609 u_file_write(const UChar *ustring, 610 int32_t count, 611 UFILE *f); 612 613 614 /* Input functions */ 615 #if !UCONFIG_NO_FORMATTING 616 617 /** 618 * Read formatted data from a UFILE. 619 * @param f The UFILE from which to read. 620 * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will 621 * interpret the variable arguments received and parse the data. 622 * @return The number of items successfully converted and assigned, or EOF 623 * if an error occurred. 624 * @stable ICU 3.0 625 */ 626 U_CAPI int32_t U_EXPORT2 627 u_fscanf(UFILE *f, 628 const char *patternSpecification, 629 ... ); 630 631 /** 632 * Read formatted data from a UFILE. 633 * This is identical to <TT>u_fscanf</TT>, except that it will 634 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 635 * @param f The UFILE from which to read. 636 * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will 637 * interpret the variable arguments received and parse the data. 638 * @param ap The argument list to use. 639 * @return The number of items successfully converted and assigned, or EOF 640 * if an error occurred. 641 * @see u_fscanf 642 * @stable ICU 3.0 643 */ 644 U_CAPI int32_t U_EXPORT2 645 u_vfscanf(UFILE *f, 646 const char *patternSpecification, 647 va_list ap); 648 649 /** 650 * Read formatted data from a UFILE. 651 * @param f The UFILE from which to read. 652 * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will 653 * interpret the variable arguments received and parse the data. 654 * @return The number of items successfully converted and assigned, or EOF 655 * if an error occurred. 656 * @stable ICU 3.0 657 */ 658 U_CAPI int32_t U_EXPORT2 659 u_fscanf_u(UFILE *f, 660 const UChar *patternSpecification, 661 ... ); 662 663 /** 664 * Read formatted data from a UFILE. 665 * This is identical to <TT>u_fscanf_u</TT>, except that it will 666 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 667 * @param f The UFILE from which to read. 668 * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will 669 * interpret the variable arguments received and parse the data. 670 * @param ap The argument list to use. 671 * @return The number of items successfully converted and assigned, or EOF 672 * if an error occurred. 673 * @see u_fscanf_u 674 * @stable ICU 3.0 675 */ 676 U_CAPI int32_t U_EXPORT2 677 u_vfscanf_u(UFILE *f, 678 const UChar *patternSpecification, 679 va_list ap); 680 #endif 681 682 /** 683 * Read one line of text into a UChar* string from a UFILE. The newline 684 * at the end of the line is read into the string. The string is always 685 * null terminated 686 * @param f The UFILE from which to read. 687 * @param n The maximum number of characters - 1 to read. 688 * @param s The UChar* to receive the read data. Characters will be 689 * stored successively in <TT>s</TT> until a newline or EOF is 690 * reached. A null character (U+0000) will be appended to <TT>s</TT>. 691 * @return A pointer to <TT>s</TT>, or NULL if no characters were available. 692 * @stable ICU 3.0 693 */ 694 U_CAPI UChar* U_EXPORT2 695 u_fgets(UChar *s, 696 int32_t n, 697 UFILE *f); 698 699 /** 700 * Read a UChar from a UFILE. It is recommended that <TT>u_fgetcx</TT> 701 * used instead for proper parsing functions, but sometimes reading 702 * code units is needed instead of codepoints. 703 * 704 * @param f The UFILE from which to read. 705 * @return The UChar value read, or U+FFFF if no character was available. 706 * @stable ICU 3.0 707 */ 708 U_CAPI UChar U_EXPORT2 709 u_fgetc(UFILE *f); 710 711 /** 712 * Read a UChar32 from a UFILE. 713 * 714 * @param f The UFILE from which to read. 715 * @return The UChar32 value read, or U_EOF if no character was 716 * available, or U+FFFFFFFF if an ill-formed character was 717 * encountered. 718 * @see u_unescape() 719 * @stable ICU 3.0 720 */ 721 U_CAPI UChar32 U_EXPORT2 722 u_fgetcx(UFILE *f); 723 724 /** 725 * Unget a UChar from a UFILE. 726 * If this function is not the first to operate on <TT>f</TT> after a call 727 * to <TT>u_fgetc</TT>, the results are undefined. 728 * If this function is passed a character that was not received from the 729 * previous <TT>u_fgetc</TT> or <TT>u_fgetcx</TT> call, the results are undefined. 730 * @param c The UChar to put back on the stream. 731 * @param f The UFILE to receive <TT>c</TT>. 732 * @return The UChar32 value put back if successful, U_EOF otherwise. 733 * @stable ICU 3.0 734 */ 735 U_CAPI UChar32 U_EXPORT2 736 u_fungetc(UChar32 c, 737 UFILE *f); 738 739 /** 740 * Read Unicode from a UFILE. 741 * Bytes will be converted from the UFILE's underlying codepage, with 742 * subsequent conversion to Unicode. The data will not be NULL terminated. 743 * @param chars A pointer to receive the Unicode data. 744 * @param count The number of Unicode characters to read. 745 * @param f The UFILE from which to read. 746 * @return The number of Unicode characters read. 747 * @stable ICU 3.0 748 */ 749 U_CAPI int32_t U_EXPORT2 750 u_file_read(UChar *chars, 751 int32_t count, 752 UFILE *f); 753 754 #if !UCONFIG_NO_TRANSLITERATION 755 756 /** 757 * Set a transliterator on the UFILE. The transliterator will be owned by the 758 * UFILE. 759 * @param file The UFILE to set transliteration on 760 * @param adopt The UTransliterator to set. Can be NULL, which will 761 * mean that no transliteration is used. 762 * @param direction either U_READ, U_WRITE, or U_READWRITE - sets 763 * which direction the transliterator is to be applied to. If 764 * U_READWRITE, the "Read" transliteration will be in the inverse 765 * direction. 766 * @param status ICU error code. 767 * @return The previously set transliterator, owned by the 768 * caller. If U_READWRITE is specified, only the WRITE transliterator 769 * is returned. In most cases, the caller should call utrans_close() 770 * on the result of this function. 771 * @stable ICU 3.0 772 */ 773 U_CAPI UTransliterator* U_EXPORT2 774 u_fsettransliterator(UFILE *file, UFileDirection direction, 775 UTransliterator *adopt, UErrorCode *status); 776 777 #endif 778 779 780 /* Output string functions */ 781 #if !UCONFIG_NO_FORMATTING 782 783 784 /** 785 * Write formatted data to a Unicode string. 786 * 787 * @param buffer The Unicode String to which to write. 788 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will 789 * interpret the variable arguments received and format the data. 790 * @return The number of Unicode code units written to <TT>buffer</TT>. This 791 * does not include the terminating null character. 792 * @stable ICU 3.0 793 */ 794 U_CAPI int32_t U_EXPORT2 795 u_sprintf(UChar *buffer, 796 const char *patternSpecification, 797 ... ); 798 799 /** 800 * Write formatted data to a Unicode string. When the number of code units 801 * required to store the data exceeds <TT>count</TT>, then <TT>count</TT> code 802 * units of data are stored in <TT>buffer</TT> and a negative value is 803 * returned. When the number of code units required to store the data equals 804 * <TT>count</TT>, the string is not null terminated and <TT>count</TT> is 805 * returned. 806 * 807 * @param buffer The Unicode String to which to write. 808 * @param count The number of code units to read. 809 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will 810 * interpret the variable arguments received and format the data. 811 * @return The number of Unicode characters that would have been written to 812 * <TT>buffer</TT> had count been sufficiently large. This does not include 813 * the terminating null character. 814 * @stable ICU 3.0 815 */ 816 U_CAPI int32_t U_EXPORT2 817 u_snprintf(UChar *buffer, 818 int32_t count, 819 const char *patternSpecification, 820 ... ); 821 822 /** 823 * Write formatted data to a Unicode string. 824 * This is identical to <TT>u_sprintf</TT>, except that it will 825 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 826 * 827 * @param buffer The Unicode string to which to write. 828 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will 829 * interpret the variable arguments received and format the data. 830 * @param ap The argument list to use. 831 * @return The number of Unicode characters written to <TT>buffer</TT>. 832 * @see u_sprintf 833 * @stable ICU 3.0 834 */ 835 U_CAPI int32_t U_EXPORT2 836 u_vsprintf(UChar *buffer, 837 const char *patternSpecification, 838 va_list ap); 839 840 /** 841 * Write formatted data to a Unicode string. 842 * This is identical to <TT>u_snprintf</TT>, except that it will 843 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>.<br><br> 844 * When the number of code units required to store the data exceeds 845 * <TT>count</TT>, then <TT>count</TT> code units of data are stored in 846 * <TT>buffer</TT> and a negative value is returned. When the number of code 847 * units required to store the data equals <TT>count</TT>, the string is not 848 * null terminated and <TT>count</TT> is returned. 849 * 850 * @param buffer The Unicode string to which to write. 851 * @param count The number of code units to read. 852 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will 853 * interpret the variable arguments received and format the data. 854 * @param ap The argument list to use. 855 * @return The number of Unicode characters that would have been written to 856 * <TT>buffer</TT> had count been sufficiently large. 857 * @see u_sprintf 858 * @stable ICU 3.0 859 */ 860 U_CAPI int32_t U_EXPORT2 861 u_vsnprintf(UChar *buffer, 862 int32_t count, 863 const char *patternSpecification, 864 va_list ap); 865 866 /** 867 * Write formatted data to a Unicode string. 868 * 869 * @param buffer The Unicode string to which to write. 870 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will 871 * interpret the variable arguments received and format the data. 872 * @return The number of Unicode characters written to <TT>buffer</TT>. 873 * @stable ICU 3.0 874 */ 875 U_CAPI int32_t U_EXPORT2 876 u_sprintf_u(UChar *buffer, 877 const UChar *patternSpecification, 878 ... ); 879 880 /** 881 * Write formatted data to a Unicode string. When the number of code units 882 * required to store the data exceeds <TT>count</TT>, then <TT>count</TT> code 883 * units of data are stored in <TT>buffer</TT> and a negative value is 884 * returned. When the number of code units required to store the data equals 885 * <TT>count</TT>, the string is not null terminated and <TT>count</TT> is 886 * returned. 887 * 888 * @param buffer The Unicode string to which to write. 889 * @param count The number of code units to read. 890 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will 891 * interpret the variable arguments received and format the data. 892 * @return The number of Unicode characters that would have been written to 893 * <TT>buffer</TT> had count been sufficiently large. 894 * @stable ICU 3.0 895 */ 896 U_CAPI int32_t U_EXPORT2 897 u_snprintf_u(UChar *buffer, 898 int32_t count, 899 const UChar *patternSpecification, 900 ... ); 901 902 /** 903 * Write formatted data to a Unicode string. 904 * This is identical to <TT>u_sprintf_u</TT>, except that it will 905 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 906 * 907 * @param buffer The Unicode string to which to write. 908 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will 909 * interpret the variable arguments received and format the data. 910 * @param ap The argument list to use. 911 * @return The number of Unicode characters written to <TT>f</TT>. 912 * @see u_sprintf_u 913 * @stable ICU 3.0 914 */ 915 U_CAPI int32_t U_EXPORT2 916 u_vsprintf_u(UChar *buffer, 917 const UChar *patternSpecification, 918 va_list ap); 919 920 /** 921 * Write formatted data to a Unicode string. 922 * This is identical to <TT>u_snprintf_u</TT>, except that it will 923 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 924 * When the number of code units required to store the data exceeds 925 * <TT>count</TT>, then <TT>count</TT> code units of data are stored in 926 * <TT>buffer</TT> and a negative value is returned. When the number of code 927 * units required to store the data equals <TT>count</TT>, the string is not 928 * null terminated and <TT>count</TT> is returned. 929 * 930 * @param buffer The Unicode string to which to write. 931 * @param count The number of code units to read. 932 * @param patternSpecification A pattern specifying how <TT>u_sprintf</TT> will 933 * interpret the variable arguments received and format the data. 934 * @param ap The argument list to use. 935 * @return The number of Unicode characters that would have been written to 936 * <TT>f</TT> had count been sufficiently large. 937 * @see u_sprintf_u 938 * @stable ICU 3.0 939 */ 940 U_CAPI int32_t U_EXPORT2 941 u_vsnprintf_u(UChar *buffer, 942 int32_t count, 943 const UChar *patternSpecification, 944 va_list ap); 945 946 /* Input string functions */ 947 948 /** 949 * Read formatted data from a Unicode string. 950 * 951 * @param buffer The Unicode string from which to read. 952 * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will 953 * interpret the variable arguments received and parse the data. 954 * @return The number of items successfully converted and assigned, or EOF 955 * if an error occurred. 956 * @stable ICU 3.0 957 */ 958 U_CAPI int32_t U_EXPORT2 959 u_sscanf(const UChar *buffer, 960 const char *patternSpecification, 961 ... ); 962 963 /** 964 * Read formatted data from a Unicode string. 965 * This is identical to <TT>u_sscanf</TT>, except that it will 966 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 967 * 968 * @param buffer The Unicode string from which to read. 969 * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will 970 * interpret the variable arguments received and parse the data. 971 * @param ap The argument list to use. 972 * @return The number of items successfully converted and assigned, or EOF 973 * if an error occurred. 974 * @see u_sscanf 975 * @stable ICU 3.0 976 */ 977 U_CAPI int32_t U_EXPORT2 978 u_vsscanf(const UChar *buffer, 979 const char *patternSpecification, 980 va_list ap); 981 982 /** 983 * Read formatted data from a Unicode string. 984 * 985 * @param buffer The Unicode string from which to read. 986 * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will 987 * interpret the variable arguments received and parse the data. 988 * @return The number of items successfully converted and assigned, or EOF 989 * if an error occurred. 990 * @stable ICU 3.0 991 */ 992 U_CAPI int32_t U_EXPORT2 993 u_sscanf_u(const UChar *buffer, 994 const UChar *patternSpecification, 995 ... ); 996 997 /** 998 * Read formatted data from a Unicode string. 999 * This is identical to <TT>u_sscanf_u</TT>, except that it will 1000 * <EM>not</EM> call <TT>va_start</TT> and <TT>va_end</TT>. 1001 * 1002 * @param buffer The Unicode string from which to read. 1003 * @param patternSpecification A pattern specifying how <TT>u_sscanf</TT> will 1004 * interpret the variable arguments received and parse the data. 1005 * @param ap The argument list to use. 1006 * @return The number of items successfully converted and assigned, or EOF 1007 * if an error occurred. 1008 * @see u_sscanf_u 1009 * @stable ICU 3.0 1010 */ 1011 U_CAPI int32_t U_EXPORT2 1012 u_vsscanf_u(const UChar *buffer, 1013 const UChar *patternSpecification, 1014 va_list ap); 1015 1016 1017 #endif 1018 #endif 1019 #endif 1020 1021 1022