source/io/unicode/ustdio.h

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