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