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