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