Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

ustdio.h

Go to the documentation of this file.
00001 /*
00002 ******************************************************************************
00003 *
00004 *   Copyright (C) 1998-2001, International Business Machines
00005 *   Corporation and others.  All Rights Reserved.
00006 *
00007 ******************************************************************************
00008 *
00009 * File ustdio.h
00010 *
00011 * Modification History:
00012 *
00013 *   Date        Name        Description
00014 *   10/16/98    stephen     Creation.
00015 *   11/06/98    stephen     Modified per code review.
00016 *   03/12/99    stephen     Modified for new C API.
00017 *   07/19/99    stephen     Minor doc update.
00018 *   02/01/01    george      Added sprintf & sscanf with all of its variants
00019 ******************************************************************************
00020 */
00021 
00022 #ifndef USTDIO_H
00023 #define USTDIO_H
00024 
00025 #include <stdio.h>
00026 #include <stdarg.h>
00027 
00028 #include "unicode/utypes.h"
00029 #include "unicode/ucnv.h"
00030 #include "unicode/utrans.h"
00031 
00032 /*
00033     TODO
00034  The following is a small list as to what is currently wrong/suggestions for
00035  ustdio.
00036 
00037  * %D and %T printf uses the current timezone, but the scanf version uses GMT.
00038  * %p should be deprecated. Pointers are 2-16 bytes big and scanf should
00039     really read them.
00040  * The format specification should use int32_t and ICU type variants instead of
00041     the compiler dependent int.
00042  * We should consider using Microsoft's wprintf and wscanf format
00043     specification.
00044  * %C and %S are aliases of %lc and %ls, which are used for wchar_t.
00045     We should consider using this for UChar and replace %K and %U,
00046     or we should make them use wchar_t.
00047  * + in printf format specification is incomplete.
00048  * Make sure that #, blank and precision in the printf format specification
00049     works.
00050  * Make sure that * in the scanf format specification works.
00051  * Each UFILE takes up at least 2KB. This should be really reduced.
00052  * This library does buffering. The OS should do this for us already. Check on
00053     this, and remove it from this library, if this is the case. Double buffering
00054     wastes a lot of time and space.
00055  * Make sure that surrogates are supported.
00056  * The ustream header should also include operator<< and
00057     operator>> for UDate (not double). This may not work on some compilers
00058     that use these operators on a double.
00059  * Testing should be done for reading and writing multi-byte encodings,
00060     and make sure that a character that is contained across buffer boundries
00061     works even for incomplete characters.
00062  * Make sure that the last character is flushed when the file/string is closed.
00063  * snprintf should follow the C99 standard for the return value, which is
00064     return the number of characters (excluding the trailing '\0')
00065     which would have been written to the destination string regardless
00066     of available space. This is like pre-flighting.
00067  * Everything that uses %s should do what operator>> does for UnicodeString.
00068     It should convert one byte at a time, and once a character is
00069     converted then check to see if it's whitespace or in the scanset.
00070     If it's whitespace or in the scanset, put all the bytes back (do nothing
00071     for sprintf/sscanf).
00072  * If bad string data is encountered, make sure that the function fails
00073     without memory leaks and the unconvertable characters are valid
00074     substitution or are escaped characters.
00075  * u_fungetc() can't unget a character when it's at the beginning of the
00076     internal conversion buffer, and it shouldn't be writing new
00077     characters to this buffer because they might be different characters.
00078     This can be tested by writing a file, and reading it backwards by
00079     using u_fgetc and two u_fungetc() calls with incorrect data.
00080     FYI The behavior is undefined for ungetc() when an incorrect character
00081     is put back, when its called multiple times in a row, or when
00082     a its called without a read operation.
00083  * u_fflush() and u_fclose should return an int32_t like C99 functions.
00084    0 is returned if the operation was successful and EOF otherwise.
00085  * u_fsettransliterator does not support U_READ side of transliteration.
00086  * The format specifier should limit the size of a format or honor it in
00087    order to prevent buffer overruns.  (e.g. %1000.1000d).
00088  * More testing is needed.
00089 */
00090 
00091 
00092 #define U_EOF 0xFFFF
00093 
00095 typedef struct UFILE UFILE;
00096 
00098 typedef enum { 
00099    U_READ = 1, U_WRITE = 2, 
00100    U_READWRITE =3  /* == (U_READ | U_WRITE) */ 
00101 } UFileDirection;
00102 
00121 U_CAPI UFILE* U_EXPORT2
00122 u_fopen(const char    *filename,
00123     const char    *perm,
00124     const char    *locale,
00125     const char    *codepage);
00126 
00140 U_CAPI UFILE* U_EXPORT2
00141 u_finit(FILE        *f,
00142     const char    *locale,
00143     const char    *codepage);
00144 
00150 U_CAPI void U_EXPORT2
00151 u_fclose(UFILE *file);
00152 
00161 U_CAPI void U_EXPORT2
00162 u_fflush(UFILE *file);
00163 
00170 U_CAPI FILE* U_EXPORT2
00171 u_fgetfile(UFILE *f);
00172 
00181 U_CAPI const char* U_EXPORT2
00182 u_fgetlocale(UFILE *file);
00183 
00192 U_CAPI int32_t U_EXPORT2
00193 u_fsetlocale(const char        *locale,
00194          UFILE        *file);
00195 
00205 U_CAPI const char* U_EXPORT2
00206 u_fgetcodepage(UFILE *file);
00207 
00220 U_CAPI int32_t U_EXPORT2
00221 u_fsetcodepage(const char    *codepage,
00222            UFILE        *file);
00223 
00224 
00231 U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
00232 
00233 /* Output functions */
00234 
00243 U_CAPI int32_t U_EXPORT2
00244 u_fprintf(    UFILE        *f,
00245         const char    *patternSpecification,
00246         ... );
00247 
00260 U_CAPI int32_t U_EXPORT2
00261 u_vfprintf(    UFILE        *f,
00262         const char    *patternSpecification,
00263         va_list        ap);
00264 
00273 U_CAPI int32_t U_EXPORT2
00274 u_fprintf_u(    UFILE        *f,
00275         const UChar    *patternSpecification,
00276         ... );
00277 
00290 U_CAPI int32_t U_EXPORT2
00291 u_vfprintf_u(    UFILE        *f,
00292         const UChar    *patternSpecification,
00293         va_list        ap);
00294 
00304 U_CAPI int32_t U_EXPORT2
00305 u_fputs(const UChar    *s,
00306     UFILE        *f);
00307 
00315 U_CAPI int32_t U_EXPORT2
00316 u_fputc(UChar        uc,
00317     UFILE        *f);
00318 
00329 U_CAPI int32_t U_EXPORT2
00330 u_file_write(const UChar     *chars, 
00331          int32_t        count, 
00332          UFILE         *f);
00333 
00334 
00335 /* Input functions */
00336 
00346 U_CAPI int32_t U_EXPORT2
00347 u_fscanf(    UFILE        *f,
00348         const char     *patternSpecification,
00349         ... );
00350 
00364 U_CAPI int32_t U_EXPORT2
00365 u_vfscanf(    UFILE        *f,
00366         const char     *patternSpecification,
00367         va_list        ap);
00368 
00378 U_CAPI int32_t U_EXPORT2
00379 u_fscanf_u(    UFILE        *f,
00380         const UChar     *patternSpecification,
00381         ... );
00382 
00396 U_CAPI int32_t U_EXPORT2
00397 u_vfscanf_u(    UFILE        *f,
00398         const UChar     *patternSpecification,
00399         va_list        ap);
00400 
00413 U_CAPI UChar* U_EXPORT2
00414 u_fgets(UFILE        *f,
00415     int32_t        n,
00416     UChar        *s);
00417 
00424 U_CAPI UChar U_EXPORT2
00425 u_fgetc(UFILE        *f);
00426 
00441 U_CAPI UChar32 U_EXPORT2
00442 u_fgetcx(UFILE        *f);
00443 
00453 U_CAPI UChar U_EXPORT2
00454 u_fungetc(UChar        c,
00455       UFILE        *f);
00456 
00467 U_CAPI int32_t U_EXPORT2
00468 u_file_read(UChar        *chars, 
00469         int32_t        count, 
00470         UFILE         *f);
00471 
00489 U_CAPI UTransliterator* U_EXPORT2
00490 u_fsettransliterator(UFILE *file, UFileDirection direction,
00491                      UTransliterator *adopt, UErrorCode *status);
00492 
00493 
00494 
00495 
00496 
00497 
00498 
00499 
00500 
00501 
00502 /* Output string functions */
00503 
00504 
00517 U_CAPI int32_t U_EXPORT2
00518 u_sprintf(UChar       *buffer,
00519         const char    *locale,
00520         const char    *patternSpecification,
00521         ... );
00522 
00541 U_CAPI int32_t U_EXPORT2
00542 u_snprintf(UChar      *buffer,
00543         int32_t       count,
00544         const char    *locale,
00545         const char    *patternSpecification,
00546         ... );
00547 
00563 U_CAPI int32_t U_EXPORT2
00564 u_vsprintf(UChar      *buffer,
00565         const char    *locale,
00566         const char    *patternSpecification,
00567         va_list        ap);
00568 
00590 U_CAPI int32_t U_EXPORT2
00591 u_vsnprintf(UChar     *buffer,
00592         int32_t       count,
00593         const char    *locale,
00594         const char    *patternSpecification,
00595         va_list        ap);
00596 
00608 U_CAPI int32_t U_EXPORT2
00609 u_sprintf_u(UChar      *buffer,
00610         const char     *locale,
00611         const UChar    *patternSpecification,
00612         ... );
00613 
00631 U_CAPI int32_t U_EXPORT2
00632 u_snprintf_u(UChar     *buffer,
00633         int32_t        count,
00634         const char     *locale,
00635         const UChar    *patternSpecification,
00636         ... );
00637 
00654 U_CAPI int32_t U_EXPORT2
00655 u_vsprintf_u(UChar     *buffer,
00656         const char    *locale,
00657         const UChar    *patternSpecification,
00658         va_list        ap);
00659 
00680 U_CAPI int32_t U_EXPORT2
00681 u_vsnprintf_u(UChar *buffer,
00682         int32_t         count,
00683         const char     *locale,
00684         const UChar     *patternSpecification,
00685         va_list         ap);
00686 
00687 /* Input string functions */
00688 
00701 U_CAPI int32_t U_EXPORT2
00702 u_sscanf(const UChar   *buffer,
00703         const char     *locale,
00704         const char     *patternSpecification,
00705         ... );
00706 
00723 U_CAPI int32_t U_EXPORT2
00724 u_vsscanf(const UChar  *buffer,
00725         const char     *locale,
00726         const char     *patternSpecification,
00727         va_list        ap);
00728 
00741 U_CAPI int32_t U_EXPORT2
00742 u_sscanf_u(const UChar  *buffer,
00743         const char      *locale,
00744         const UChar     *patternSpecification,
00745         ... );
00746 
00763 U_CAPI int32_t U_EXPORT2
00764 u_vsscanf_u(const UChar *buffer,
00765         const char      *locale,
00766         const UChar     *patternSpecification,
00767         va_list         ap);
00768 
00769 
00770 #endif
00771 
00772 
00773 

Generated on Thu Aug 15 14:13:34 2002 for ICU 2.2 by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001