Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ustdio.h @ 69:33d812a61356

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