icuSources/io/unicode/ustdio.h

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