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