← Back to branch summary

~alinuxninja/nginx-edge/trunk

« back to all changes in this revision

Viewing changes to debian/modules/ngx_pagespeed/psol/include/third_party/icu/source/io/unicode/ustdio.h

  • Committer: Vivian
  • Date: 2015-12-04 18:20:11 UTC
  • Revision ID: git-v1:a36f2bc32e884f7473b3a47040e5411306144d7d
* Do not extract psol.tar.gz

Show diffs side-by-side

added added

removed removed

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