jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ****************************************************************************** jpayne@69: * jpayne@69: * Copyright (C) 1998-2015, International Business Machines jpayne@69: * Corporation and others. All Rights Reserved. jpayne@69: * jpayne@69: ****************************************************************************** jpayne@69: * jpayne@69: * File ustdio.h jpayne@69: * jpayne@69: * Modification History: jpayne@69: * jpayne@69: * Date Name Description jpayne@69: * 10/16/98 stephen Creation. jpayne@69: * 11/06/98 stephen Modified per code review. jpayne@69: * 03/12/99 stephen Modified for new C API. jpayne@69: * 07/19/99 stephen Minor doc update. jpayne@69: * 02/01/01 george Added sprintf & sscanf with all of its variants jpayne@69: ****************************************************************************** jpayne@69: */ jpayne@69: jpayne@69: #ifndef USTDIO_H jpayne@69: #define USTDIO_H jpayne@69: jpayne@69: #include jpayne@69: #include jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: #include "unicode/ucnv.h" jpayne@69: #include "unicode/utrans.h" jpayne@69: #include "unicode/localpointer.h" jpayne@69: #include "unicode/unum.h" jpayne@69: jpayne@69: #if !UCONFIG_NO_CONVERSION jpayne@69: jpayne@69: /* jpayne@69: TODO jpayne@69: The following is a small list as to what is currently wrong/suggestions for jpayne@69: ustdio. jpayne@69: jpayne@69: * Make sure that * in the scanf format specification works for all formats. jpayne@69: * Each UFILE takes up at least 2KB. jpayne@69: Look into adding setvbuf() for configurable buffers. jpayne@69: * This library does buffering. The OS should do this for us already. Check on jpayne@69: this, and remove it from this library, if this is the case. Double buffering jpayne@69: wastes a lot of time and space. jpayne@69: * Test stdin and stdout with the u_f* functions jpayne@69: * Testing should be done for reading and writing multi-byte encodings, jpayne@69: and make sure that a character that is contained across buffer boundries jpayne@69: works even for incomplete characters. jpayne@69: * Make sure that the last character is flushed when the file/string is closed. jpayne@69: * snprintf should follow the C99 standard for the return value, which is jpayne@69: return the number of characters (excluding the trailing '\0') jpayne@69: which would have been written to the destination string regardless jpayne@69: of available space. This is like pre-flighting. jpayne@69: * Everything that uses %s should do what operator>> does for UnicodeString. jpayne@69: It should convert one byte at a time, and once a character is jpayne@69: converted then check to see if it's whitespace or in the scanset. jpayne@69: If it's whitespace or in the scanset, put all the bytes back (do nothing jpayne@69: for sprintf/sscanf). jpayne@69: * If bad string data is encountered, make sure that the function fails jpayne@69: without memory leaks and the unconvertable characters are valid jpayne@69: substitution or are escaped characters. jpayne@69: * u_fungetc() can't unget a character when it's at the beginning of the jpayne@69: internal conversion buffer. For example, read the buffer size # of jpayne@69: characters, and then ungetc to get the previous character that was jpayne@69: at the end of the last buffer. jpayne@69: * u_fflush() and u_fclose should return an int32_t like C99 functions. jpayne@69: 0 is returned if the operation was successful and EOF otherwise. jpayne@69: * u_fsettransliterator does not support U_READ side of transliteration. jpayne@69: * The format specifier should limit the size of a format or honor it in jpayne@69: order to prevent buffer overruns. (e.g. %256.256d). jpayne@69: * u_fread and u_fwrite don't exist. They're needed for reading and writing jpayne@69: data structures without any conversion. jpayne@69: * u_file_read and u_file_write are used for writing strings. u_fgets and jpayne@69: u_fputs or u_fread and u_fwrite should be used to do this. jpayne@69: * The width parameter for all scanf formats, including scanset, needs jpayne@69: better testing. This prevents buffer overflows. jpayne@69: * Figure out what is suppose to happen when a codepage is changed midstream. jpayne@69: Maybe a flush or a rewind are good enough. jpayne@69: * Make sure that a UFile opened with "rw" can be used after using jpayne@69: u_fflush with a u_frewind. jpayne@69: * scanf(%i) should detect what type of number to use. jpayne@69: * Add more testing of the alternate format, %# jpayne@69: * Look at newline handling of fputs/puts jpayne@69: * Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[] jpayne@69: * Complete the file documentation with proper doxygen formatting. jpayne@69: See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C API: Unicode stdio-like API jpayne@69: * jpayne@69: *

Unicode stdio-like C API

jpayne@69: * jpayne@69: *

This API provides an stdio-like API wrapper around ICU's other jpayne@69: * formatting and parsing APIs. It is meant to ease the transition of adding jpayne@69: * Unicode support to a preexisting applications using stdio. The following jpayne@69: * is a small list of noticable differences between stdio and ICU I/O's jpayne@69: * ustdio implementation.

jpayne@69: * jpayne@69: * jpayne@69: * jpayne@69: *

Formatting and Parsing Specification

jpayne@69: * jpayne@69: * General printf format:
jpayne@69: * %[format modifier][width][.precision][type modifier][format] jpayne@69: * jpayne@69: * General scanf format:
jpayne@69: * %[*][format modifier][width][type modifier][format] jpayne@69: * jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69:
formatdefault
printf
type		default
scanf
type		description
%EdoublefloatScientific with an uppercase exponent
%edoublefloatScientific with a lowercase exponent
%GdoublefloatUse %E or %f for best format
%gdoublefloatUse %e or %f for best format
%fdoublefloatSimple floating point without the exponent
%Xint32_tint32_tustdio special uppercase hex radix formatting
%xint32_tint32_tustdio special lowercase hex radix formatting
%dint32_tint32_tDecimal format
%iint32_tint32_tSame as %d
%nint32_tint32_tcount (write the number of UTF-16 codeunits read/written)
%oint32_tint32_tustdio special octal radix formatting
%uuint32_tuint32_tDecimal format
%pvoid *void *Prints the pointer value
%schar *char *Use default converter or specified converter from fopen
%ccharcharUse default converter or specified converter from fopen
jpayne@69: When width is specified for scanf, this acts like a non-NULL-terminated char * string.
jpayne@69: By default, only one char is written.
%SUChar *UChar *Null terminated UTF-16 string
%CUCharUChar16-bit Unicode code unit
jpayne@69: When width is specified for scanf, this acts like a non-NULL-terminated UChar * string
jpayne@69: By default, only one codepoint is written.
%[] UChar *Null terminated UTF-16 string which contains the filtered set of characters specified by the UnicodeSet
%%  Show a percent sign
jpayne@69: jpayne@69: Format modifiers jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69: jpayne@69:
modifierformatstypecomments
%h%d, %i, %o, %xint16_tshort format
%h%uuint16_tshort format
%hcchar(Unimplemented) Use invariant converter
%hschar *(Unimplemented) Use invariant converter
%hCchar(Unimplemented) 8-bit Unicode code unit
%hSchar *(Unimplemented) Null terminated UTF-8 string
%l%d, %i, %o, %xint32_tlong format (no effect)
%l%uuint32_tlong format (no effect)
%lcN/A(Unimplemented) Reserved for future implementation
%lsN/A(Unimplemented) Reserved for future implementation
%lCUChar32(Unimplemented) 32-bit Unicode code unit
%lSUChar32 *(Unimplemented) Null terminated UTF-32 string
%ll%d, %i, %o, %xint64_tlong long format
%ll%uuint64_t(Unimplemented) long long format
%-allN/ALeft justify
%+%d, %i, %o, %x, %e, %f, %g, %E, %GN/AAlways show the plus or minus sign. Needs data for plus sign.
% %d, %i, %o, %x, %e, %f, %g, %E, %GN/AInstead of a "+" output a blank character for positive numbers.
%#%d, %i, %o, %x, %e, %f, %g, %E, %GN/APrecede octal value with 0, hex with 0x and show the jpayne@69: decimal point for floats.
%nallN/AWidth of input/output. num is an actual number from 0 to jpayne@69: some large number.
%.n%e, %f, %g, %E, %F, %GN/ASignificant digits precision. num is an actual number from jpayne@69: 0 to some large number.
If * is used in printf, then the precision is passed in as an argument before the number to be formatted.
jpayne@69: jpayne@69: printf modifier jpayne@69: %* int32_t Next argument after this one specifies the width jpayne@69: jpayne@69: scanf modifier jpayne@69: %* N/A This field is scanned, but not stored jpayne@69: jpayne@69:

If you are using this C API instead of the ustream.h API for C++, jpayne@69: you can use one of the following u_fprintf examples to display a UnicodeString.

jpayne@69: jpayne@69: 

jpayne@69:     UFILE *out = u_finit(stdout, NULL, NULL);
jpayne@69:     UnicodeString string1("string 1");
jpayne@69:     UnicodeString string2("string 2");
jpayne@69:     u_fprintf(out, "%S\n", string1.getTerminatedBuffer());
jpayne@69:     u_fprintf(out, "%.*S\n", string2.length(), string2.getBuffer());
jpayne@69:     u_fclose(out);
jpayne@69:
jpayne@69: jpayne@69: */ jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * When an end of file is encountered, this value can be returned. jpayne@69: * @see u_fgetc jpayne@69: * @stable 3.0 jpayne@69: */ jpayne@69: #define U_EOF 0xFFFF jpayne@69: jpayne@69: /** Forward declaration of a Unicode-aware file @stable 3.0 */ jpayne@69: typedef struct UFILE UFILE; jpayne@69: jpayne@69: /** jpayne@69: * Enum for which direction of stream a transliterator applies to. jpayne@69: * @see u_fsettransliterator jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: typedef enum { jpayne@69: U_READ = 1, jpayne@69: U_WRITE = 2, jpayne@69: U_READWRITE =3 /* == (U_READ | U_WRITE) */ jpayne@69: } UFileDirection; jpayne@69: jpayne@69: /** jpayne@69: * Open a UFILE. jpayne@69: * A UFILE is a wrapper around a FILE* that is locale and codepage aware. jpayne@69: * That is, data written to a UFILE will be formatted using the conventions jpayne@69: * specified by that UFILE's Locale; this data will be in the character set jpayne@69: * specified by that UFILE's codepage. jpayne@69: * @param filename The name of the file to open. jpayne@69: * @param perm The read/write permission for the UFILE; one of "r", "w", "rw" jpayne@69: * @param locale The locale whose conventions will be used to format jpayne@69: * and parse output. If this parameter is NULL, the default locale will jpayne@69: * be used. jpayne@69: * @param codepage The codepage in which data will be written to and jpayne@69: * read from the file. If this paramter is NULL the system default codepage jpayne@69: * will be used. jpayne@69: * @return A new UFILE, or NULL if an error occurred. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UFILE* U_EXPORT2 jpayne@69: u_fopen(const char *filename, jpayne@69: const char *perm, jpayne@69: const char *locale, jpayne@69: const char *codepage); jpayne@69: jpayne@69: /** jpayne@69: * Open a UFILE with a UChar* filename jpayne@69: * A UFILE is a wrapper around a FILE* that is locale and codepage aware. jpayne@69: * That is, data written to a UFILE will be formatted using the conventions jpayne@69: * specified by that UFILE's Locale; this data will be in the character set jpayne@69: * specified by that UFILE's codepage. jpayne@69: * @param filename The name of the file to open. jpayne@69: * @param perm The read/write permission for the UFILE; one of "r", "w", "rw" jpayne@69: * @param locale The locale whose conventions will be used to format jpayne@69: * and parse output. If this parameter is NULL, the default locale will jpayne@69: * be used. jpayne@69: * @param codepage The codepage in which data will be written to and jpayne@69: * read from the file. If this paramter is NULL the system default codepage jpayne@69: * will be used. jpayne@69: * @return A new UFILE, or NULL if an error occurred. jpayne@69: * @stable ICU 54 jpayne@69: */ jpayne@69: U_STABLE UFILE* U_EXPORT2 jpayne@69: u_fopen_u(const UChar *filename, jpayne@69: const char *perm, jpayne@69: const char *locale, jpayne@69: const char *codepage); jpayne@69: jpayne@69: /** jpayne@69: * Open a UFILE on top of an existing FILE* stream. The FILE* stream jpayne@69: * ownership remains with the caller. To have the UFILE take over jpayne@69: * ownership and responsibility for the FILE* stream, use the jpayne@69: * function u_fadopt. jpayne@69: * @param f The FILE* to which this UFILE will attach and use. jpayne@69: * @param locale The locale whose conventions will be used to format jpayne@69: * and parse output. If this parameter is NULL, the default locale will jpayne@69: * be used. jpayne@69: * @param codepage The codepage in which data will be written to and jpayne@69: * read from the file. If this paramter is NULL, data will be written and jpayne@69: * read using the default codepage for locale, unless locale jpayne@69: * is NULL, in which case the system default codepage will be used. jpayne@69: * @return A new UFILE, or NULL if an error occurred. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UFILE* U_EXPORT2 jpayne@69: u_finit(FILE *f, jpayne@69: const char *locale, jpayne@69: const char *codepage); jpayne@69: jpayne@69: /** jpayne@69: * Open a UFILE on top of an existing FILE* stream. The FILE* stream jpayne@69: * ownership is transferred to the new UFILE. It will be closed when the jpayne@69: * UFILE is closed. jpayne@69: * @param f The FILE* which this UFILE will take ownership of. jpayne@69: * @param locale The locale whose conventions will be used to format jpayne@69: * and parse output. If this parameter is NULL, the default locale will jpayne@69: * be used. jpayne@69: * @param codepage The codepage in which data will be written to and jpayne@69: * read from the file. If this paramter is NULL, data will be written and jpayne@69: * read using the default codepage for locale, unless locale jpayne@69: * is NULL, in which case the system default codepage will be used. jpayne@69: * @return A new UFILE, or NULL if an error occurred. If an error occurs jpayne@69: * the ownership of the FILE* stream remains with the caller. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE UFILE* U_EXPORT2 jpayne@69: u_fadopt(FILE *f, jpayne@69: const char *locale, jpayne@69: const char *codepage); jpayne@69: jpayne@69: /** jpayne@69: * Create a UFILE that can be used for localized formatting or parsing. jpayne@69: * The u_sprintf and u_sscanf functions do not read or write numbers for a jpayne@69: * specific locale. The ustdio.h file functions can be used on this UFILE. jpayne@69: * The string is usable once u_fclose or u_fflush has been called on the jpayne@69: * returned UFILE. jpayne@69: * @param stringBuf The string used for reading or writing. jpayne@69: * @param capacity The number of code units available for use in stringBuf jpayne@69: * @param locale The locale whose conventions will be used to format jpayne@69: * and parse output. If this parameter is NULL, the default locale will jpayne@69: * be used. jpayne@69: * @return A new UFILE, or NULL if an error occurred. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UFILE* U_EXPORT2 jpayne@69: u_fstropen(UChar *stringBuf, jpayne@69: int32_t capacity, jpayne@69: const char *locale); jpayne@69: jpayne@69: /** jpayne@69: * Close a UFILE. Implies u_fflush first. jpayne@69: * @param file The UFILE to close. jpayne@69: * @stable ICU 3.0 jpayne@69: * @see u_fflush jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: u_fclose(UFILE *file); jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUFILEPointer jpayne@69: * "Smart pointer" class, closes a UFILE via u_fclose(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose); jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Tests if the UFILE is at the end of the file stream. jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @return Returns TRUE after the first read operation that attempts to jpayne@69: * read past the end of the file. It returns FALSE if the current position is jpayne@69: * not end of file. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: u_feof(UFILE *f); jpayne@69: jpayne@69: /** jpayne@69: * Flush output of a UFILE. Implies a flush of jpayne@69: * converter/transliterator state. (That is, a logical break is jpayne@69: * made in the output stream - for example if a different type of jpayne@69: * output is desired.) The underlying OS level file is also flushed. jpayne@69: * Note that for a stateful encoding, the converter may write additional jpayne@69: * bytes to return the stream to default state. jpayne@69: * @param file The UFILE to flush. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: u_fflush(UFILE *file); jpayne@69: jpayne@69: /** jpayne@69: * Rewind the file pointer to the beginning of the file. jpayne@69: * @param file The UFILE to rewind. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE void jpayne@69: u_frewind(UFILE *file); jpayne@69: jpayne@69: /** jpayne@69: * Get the FILE* associated with a UFILE. jpayne@69: * @param f The UFILE jpayne@69: * @return A FILE*, owned by the UFILE. (The FILE must not be modified or closed) jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE FILE* U_EXPORT2 jpayne@69: u_fgetfile(UFILE *f); jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: /** jpayne@69: * Get the locale whose conventions are used to format and parse output. jpayne@69: * This is the same locale passed in the preceding call tou_fsetlocale jpayne@69: * or u_fopen. jpayne@69: * @param file The UFILE to set. jpayne@69: * @return The locale whose conventions are used to format and parse output. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE const char* U_EXPORT2 jpayne@69: u_fgetlocale(UFILE *file); jpayne@69: jpayne@69: /** jpayne@69: * Set the locale whose conventions will be used to format and parse output. jpayne@69: * @param locale The locale whose conventions will be used to format jpayne@69: * and parse output. jpayne@69: * @param file The UFILE to query. jpayne@69: * @return NULL if successful, otherwise a negative number. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_fsetlocale(UFILE *file, jpayne@69: const char *locale); jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Get the codepage in which data is written to and read from the UFILE. jpayne@69: * This is the same codepage passed in the preceding call to jpayne@69: * u_fsetcodepage or u_fopen. jpayne@69: * @param file The UFILE to query. jpayne@69: * @return The codepage in which data is written to and read from the UFILE, jpayne@69: * or NULL if an error occurred. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE const char* U_EXPORT2 jpayne@69: u_fgetcodepage(UFILE *file); jpayne@69: jpayne@69: /** jpayne@69: * Set the codepage in which data will be written to and read from the UFILE. jpayne@69: * All Unicode data written to the UFILE will be converted to this codepage jpayne@69: * before it is written to the underlying FILE*. It it generally a bad idea to jpayne@69: * mix codepages within a file. This should only be called right jpayne@69: * after opening the UFile, or after calling u_frewind. jpayne@69: * @param codepage The codepage in which data will be written to jpayne@69: * and read from the file. For example "latin-1" or "ibm-943". jpayne@69: * A value of NULL means the default codepage for the UFILE's current jpayne@69: * locale will be used. jpayne@69: * @param file The UFILE to set. jpayne@69: * @return 0 if successful, otherwise a negative number. jpayne@69: * @see u_frewind jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_fsetcodepage(const char *codepage, jpayne@69: UFILE *file); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Returns an alias to the converter being used for this file. jpayne@69: * @param f The UFILE to get the value from jpayne@69: * @return alias to the converter (The converter must not be modified or closed) jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UConverter* U_EXPORT2 u_fgetConverter(UFILE *f); jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: /** jpayne@69: * Returns an alias to the number formatter being used for this file. jpayne@69: * @param f The UFILE to get the value from jpayne@69: * @return alias to the number formatter (The formatter must not be modified or closed) jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f); jpayne@69: jpayne@69: /* Output functions */ jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to stdout. jpayne@69: * @param patternSpecification A pattern specifying how u_printf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @return The number of Unicode characters written to stdout jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_printf(const char *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a UFILE. jpayne@69: * @param f The UFILE to which to write. jpayne@69: * @param patternSpecification A pattern specifying how u_fprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @return The number of Unicode characters written to f. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_fprintf(UFILE *f, jpayne@69: const char *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a UFILE. jpayne@69: * This is identical to u_fprintf, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * @param f The UFILE to which to write. jpayne@69: * @param patternSpecification A pattern specifying how u_fprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of Unicode characters written to f. jpayne@69: * @see u_fprintf jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vfprintf(UFILE *f, jpayne@69: const char *patternSpecification, jpayne@69: va_list ap); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to stdout. jpayne@69: * @param patternSpecification A pattern specifying how u_printf_u will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @return The number of Unicode characters written to stdout jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_printf_u(const UChar *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Get a UFILE for stdout. jpayne@69: * @return UFILE that writes to stdout jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: U_STABLE UFILE * U_EXPORT2 jpayne@69: u_get_stdout(void); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a UFILE. jpayne@69: * @param f The UFILE to which to write. jpayne@69: * @param patternSpecification A pattern specifying how u_fprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @return The number of Unicode characters written to f. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_fprintf_u(UFILE *f, jpayne@69: const UChar *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a UFILE. jpayne@69: * This is identical to u_fprintf_u, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * @param f The UFILE to which to write. jpayne@69: * @param patternSpecification A pattern specifying how u_fprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of Unicode characters written to f. jpayne@69: * @see u_fprintf_u jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vfprintf_u(UFILE *f, jpayne@69: const UChar *patternSpecification, jpayne@69: va_list ap); jpayne@69: #endif jpayne@69: /** jpayne@69: * Write a Unicode to a UFILE. The null (U+0000) terminated UChar* jpayne@69: * s will be written to f, excluding the NULL terminator. jpayne@69: * A newline will be added to f. jpayne@69: * @param s The UChar* to write. jpayne@69: * @param f The UFILE to which to write. jpayne@69: * @return A non-negative number if successful, EOF otherwise. jpayne@69: * @see u_file_write jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_fputs(const UChar *s, jpayne@69: UFILE *f); jpayne@69: jpayne@69: /** jpayne@69: * Write a UChar to a UFILE. jpayne@69: * @param uc The UChar to write. jpayne@69: * @param f The UFILE to which to write. jpayne@69: * @return The character written if successful, EOF otherwise. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UChar32 U_EXPORT2 jpayne@69: u_fputc(UChar32 uc, jpayne@69: UFILE *f); jpayne@69: jpayne@69: /** jpayne@69: * Write Unicode to a UFILE. jpayne@69: * The ustring passed in will be converted to the UFILE's underlying jpayne@69: * codepage before it is written. jpayne@69: * @param ustring A pointer to the Unicode data to write. jpayne@69: * @param count The number of Unicode characters to write jpayne@69: * @param f The UFILE to which to write. jpayne@69: * @return The number of Unicode characters written. jpayne@69: * @see u_fputs jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_file_write(const UChar *ustring, jpayne@69: int32_t count, jpayne@69: UFILE *f); jpayne@69: jpayne@69: jpayne@69: /* Input functions */ jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: /** jpayne@69: * Read formatted data from a UFILE. jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @param patternSpecification A pattern specifying how u_fscanf will jpayne@69: * interpret the variable arguments received and parse the data. jpayne@69: * @return The number of items successfully converted and assigned, or EOF jpayne@69: * if an error occurred. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_fscanf(UFILE *f, jpayne@69: const char *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Read formatted data from a UFILE. jpayne@69: * This is identical to u_fscanf, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @param patternSpecification A pattern specifying how u_fscanf will jpayne@69: * interpret the variable arguments received and parse the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of items successfully converted and assigned, or EOF jpayne@69: * if an error occurred. jpayne@69: * @see u_fscanf jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vfscanf(UFILE *f, jpayne@69: const char *patternSpecification, jpayne@69: va_list ap); jpayne@69: jpayne@69: /** jpayne@69: * Read formatted data from a UFILE. jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @param patternSpecification A pattern specifying how u_fscanf will jpayne@69: * interpret the variable arguments received and parse the data. jpayne@69: * @return The number of items successfully converted and assigned, or EOF jpayne@69: * if an error occurred. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_fscanf_u(UFILE *f, jpayne@69: const UChar *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Read formatted data from a UFILE. jpayne@69: * This is identical to u_fscanf_u, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @param patternSpecification A pattern specifying how u_fscanf will jpayne@69: * interpret the variable arguments received and parse the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of items successfully converted and assigned, or EOF jpayne@69: * if an error occurred. jpayne@69: * @see u_fscanf_u jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vfscanf_u(UFILE *f, jpayne@69: const UChar *patternSpecification, jpayne@69: va_list ap); jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Read one line of text into a UChar* string from a UFILE. The newline jpayne@69: * at the end of the line is read into the string. The string is always jpayne@69: * null terminated jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @param n The maximum number of characters - 1 to read. jpayne@69: * @param s The UChar* to receive the read data. Characters will be jpayne@69: * stored successively in s until a newline or EOF is jpayne@69: * reached. A null character (U+0000) will be appended to s. jpayne@69: * @return A pointer to s, or NULL if no characters were available. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UChar* U_EXPORT2 jpayne@69: u_fgets(UChar *s, jpayne@69: int32_t n, jpayne@69: UFILE *f); jpayne@69: jpayne@69: /** jpayne@69: * Read a UChar from a UFILE. It is recommended that u_fgetcx jpayne@69: * used instead for proper parsing functions, but sometimes reading jpayne@69: * code units is needed instead of codepoints. jpayne@69: * jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @return The UChar value read, or U+FFFF if no character was available. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UChar U_EXPORT2 jpayne@69: u_fgetc(UFILE *f); jpayne@69: jpayne@69: /** jpayne@69: * Read a UChar32 from a UFILE. jpayne@69: * jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @return The UChar32 value read, or U_EOF if no character was jpayne@69: * available, or U+FFFFFFFF if an ill-formed character was jpayne@69: * encountered. jpayne@69: * @see u_unescape() jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UChar32 U_EXPORT2 jpayne@69: u_fgetcx(UFILE *f); jpayne@69: jpayne@69: /** jpayne@69: * Unget a UChar from a UFILE. jpayne@69: * If this function is not the first to operate on f after a call jpayne@69: * to u_fgetc, the results are undefined. jpayne@69: * If this function is passed a character that was not recieved from the jpayne@69: * previous u_fgetc or u_fgetcx call, the results are undefined. jpayne@69: * @param c The UChar to put back on the stream. jpayne@69: * @param f The UFILE to receive c. jpayne@69: * @return The UChar32 value put back if successful, U_EOF otherwise. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UChar32 U_EXPORT2 jpayne@69: u_fungetc(UChar32 c, jpayne@69: UFILE *f); jpayne@69: jpayne@69: /** jpayne@69: * Read Unicode from a UFILE. jpayne@69: * Bytes will be converted from the UFILE's underlying codepage, with jpayne@69: * subsequent conversion to Unicode. The data will not be NULL terminated. jpayne@69: * @param chars A pointer to receive the Unicode data. jpayne@69: * @param count The number of Unicode characters to read. jpayne@69: * @param f The UFILE from which to read. jpayne@69: * @return The number of Unicode characters read. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_file_read(UChar *chars, jpayne@69: int32_t count, jpayne@69: UFILE *f); jpayne@69: jpayne@69: #if !UCONFIG_NO_TRANSLITERATION jpayne@69: jpayne@69: /** jpayne@69: * Set a transliterator on the UFILE. The transliterator will be owned by the jpayne@69: * UFILE. jpayne@69: * @param file The UFILE to set transliteration on jpayne@69: * @param adopt The UTransliterator to set. Can be NULL, which will jpayne@69: * mean that no transliteration is used. jpayne@69: * @param direction either U_READ, U_WRITE, or U_READWRITE - sets jpayne@69: * which direction the transliterator is to be applied to. If jpayne@69: * U_READWRITE, the "Read" transliteration will be in the inverse jpayne@69: * direction. jpayne@69: * @param status ICU error code. jpayne@69: * @return The previously set transliterator, owned by the jpayne@69: * caller. If U_READWRITE is specified, only the WRITE transliterator jpayne@69: * is returned. In most cases, the caller should call utrans_close() jpayne@69: * on the result of this function. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE UTransliterator* U_EXPORT2 jpayne@69: u_fsettransliterator(UFILE *file, UFileDirection direction, jpayne@69: UTransliterator *adopt, UErrorCode *status); jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: jpayne@69: /* Output string functions */ jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a Unicode string. jpayne@69: * jpayne@69: * @param buffer The Unicode String to which to write. jpayne@69: * @param patternSpecification A pattern specifying how u_sprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @return The number of Unicode code units written to buffer. This jpayne@69: * does not include the terminating null character. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_sprintf(UChar *buffer, jpayne@69: const char *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a Unicode string. When the number of code units jpayne@69: * required to store the data exceeds count, then count code jpayne@69: * units of data are stored in buffer and a negative value is jpayne@69: * returned. When the number of code units required to store the data equals jpayne@69: * count, the string is not null terminated and count is jpayne@69: * returned. jpayne@69: * jpayne@69: * @param buffer The Unicode String to which to write. jpayne@69: * @param count The number of code units to read. jpayne@69: * @param patternSpecification A pattern specifying how u_sprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @return The number of Unicode characters that would have been written to jpayne@69: * buffer had count been sufficiently large. This does not include jpayne@69: * the terminating null character. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_snprintf(UChar *buffer, jpayne@69: int32_t count, jpayne@69: const char *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a Unicode string. jpayne@69: * This is identical to u_sprintf, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * jpayne@69: * @param buffer The Unicode string to which to write. jpayne@69: * @param patternSpecification A pattern specifying how u_sprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of Unicode characters written to buffer. jpayne@69: * @see u_sprintf jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vsprintf(UChar *buffer, jpayne@69: const char *patternSpecification, jpayne@69: va_list ap); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a Unicode string. jpayne@69: * This is identical to u_snprintf, except that it will jpayne@69: * not call va_start and va_end.

jpayne@69: * When the number of code units required to store the data exceeds jpayne@69: * count, then count code units of data are stored in jpayne@69: * buffer and a negative value is returned. When the number of code jpayne@69: * units required to store the data equals count, the string is not jpayne@69: * null terminated and count is returned. jpayne@69: * jpayne@69: * @param buffer The Unicode string to which to write. jpayne@69: * @param count The number of code units to read. jpayne@69: * @param patternSpecification A pattern specifying how u_sprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of Unicode characters that would have been written to jpayne@69: * buffer had count been sufficiently large. jpayne@69: * @see u_sprintf jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vsnprintf(UChar *buffer, jpayne@69: int32_t count, jpayne@69: const char *patternSpecification, jpayne@69: va_list ap); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a Unicode string. jpayne@69: * jpayne@69: * @param buffer The Unicode string to which to write. jpayne@69: * @param patternSpecification A pattern specifying how u_sprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @return The number of Unicode characters written to buffer. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_sprintf_u(UChar *buffer, jpayne@69: const UChar *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a Unicode string. When the number of code units jpayne@69: * required to store the data exceeds count, then count code jpayne@69: * units of data are stored in buffer and a negative value is jpayne@69: * returned. When the number of code units required to store the data equals jpayne@69: * count, the string is not null terminated and count is jpayne@69: * returned. jpayne@69: * jpayne@69: * @param buffer The Unicode string to which to write. jpayne@69: * @param count The number of code units to read. jpayne@69: * @param patternSpecification A pattern specifying how u_sprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @return The number of Unicode characters that would have been written to jpayne@69: * buffer had count been sufficiently large. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_snprintf_u(UChar *buffer, jpayne@69: int32_t count, jpayne@69: const UChar *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a Unicode string. jpayne@69: * This is identical to u_sprintf_u, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * jpayne@69: * @param buffer The Unicode string to which to write. jpayne@69: * @param patternSpecification A pattern specifying how u_sprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of Unicode characters written to f. jpayne@69: * @see u_sprintf_u jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vsprintf_u(UChar *buffer, jpayne@69: const UChar *patternSpecification, jpayne@69: va_list ap); jpayne@69: jpayne@69: /** jpayne@69: * Write formatted data to a Unicode string. jpayne@69: * This is identical to u_snprintf_u, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * When the number of code units required to store the data exceeds jpayne@69: * count, then count code units of data are stored in jpayne@69: * buffer and a negative value is returned. When the number of code jpayne@69: * units required to store the data equals count, the string is not jpayne@69: * null terminated and count is returned. jpayne@69: * jpayne@69: * @param buffer The Unicode string to which to write. jpayne@69: * @param count The number of code units to read. jpayne@69: * @param patternSpecification A pattern specifying how u_sprintf will jpayne@69: * interpret the variable arguments received and format the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of Unicode characters that would have been written to jpayne@69: * f had count been sufficiently large. jpayne@69: * @see u_sprintf_u jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vsnprintf_u(UChar *buffer, jpayne@69: int32_t count, jpayne@69: const UChar *patternSpecification, jpayne@69: va_list ap); jpayne@69: jpayne@69: /* Input string functions */ jpayne@69: jpayne@69: /** jpayne@69: * Read formatted data from a Unicode string. jpayne@69: * jpayne@69: * @param buffer The Unicode string from which to read. jpayne@69: * @param patternSpecification A pattern specifying how u_sscanf will jpayne@69: * interpret the variable arguments received and parse the data. jpayne@69: * @return The number of items successfully converted and assigned, or EOF jpayne@69: * if an error occurred. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_sscanf(const UChar *buffer, jpayne@69: const char *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Read formatted data from a Unicode string. jpayne@69: * This is identical to u_sscanf, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * jpayne@69: * @param buffer The Unicode string from which to read. jpayne@69: * @param patternSpecification A pattern specifying how u_sscanf will jpayne@69: * interpret the variable arguments received and parse the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of items successfully converted and assigned, or EOF jpayne@69: * if an error occurred. jpayne@69: * @see u_sscanf jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vsscanf(const UChar *buffer, jpayne@69: const char *patternSpecification, jpayne@69: va_list ap); jpayne@69: jpayne@69: /** jpayne@69: * Read formatted data from a Unicode string. jpayne@69: * jpayne@69: * @param buffer The Unicode string from which to read. jpayne@69: * @param patternSpecification A pattern specifying how u_sscanf will jpayne@69: * interpret the variable arguments received and parse the data. jpayne@69: * @return The number of items successfully converted and assigned, or EOF jpayne@69: * if an error occurred. jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_sscanf_u(const UChar *buffer, jpayne@69: const UChar *patternSpecification, jpayne@69: ... ); jpayne@69: jpayne@69: /** jpayne@69: * Read formatted data from a Unicode string. jpayne@69: * This is identical to u_sscanf_u, except that it will jpayne@69: * not call va_start and va_end. jpayne@69: * jpayne@69: * @param buffer The Unicode string from which to read. jpayne@69: * @param patternSpecification A pattern specifying how u_sscanf will jpayne@69: * interpret the variable arguments received and parse the data. jpayne@69: * @param ap The argument list to use. jpayne@69: * @return The number of items successfully converted and assigned, or EOF jpayne@69: * if an error occurred. jpayne@69: * @see u_sscanf_u jpayne@69: * @stable ICU 3.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: u_vsscanf_u(const UChar *buffer, jpayne@69: const UChar *patternSpecification, jpayne@69: va_list ap); jpayne@69: jpayne@69: jpayne@69: #endif jpayne@69: #endif jpayne@69: #endif jpayne@69: jpayne@69: