icuSources/common/unicode/putil.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 ******************************************************************************
   5 *
   6 *   Copyright (C) 1997-2014, International Business Machines
   7 *   Corporation and others.  All Rights Reserved.
   8 *
   9 ******************************************************************************
  10 *
  11 *  FILE NAME : putil.h
  12 *
  13 *   Date        Name        Description
  14 *   05/14/98    nos         Creation (content moved here from utypes.h).
  15 *   06/17/99    erm         Added IEEE_754
  16 *   07/22/98    stephen     Added IEEEremainder, max, min, trunc
  17 *   08/13/98    stephen     Added isNegativeInfinity, isPositiveInfinity
  18 *   08/24/98    stephen     Added longBitsFromDouble
  19 *   03/02/99    stephen     Removed openFile().  Added AS400 support.
  20 *   04/15/99    stephen     Converted to C
  21 *   11/15/99    helena      Integrated S/390 changes for IEEE support.
  22 *   01/11/00    helena      Added u_getVersion.
  23 ******************************************************************************
  24 */
  25
  26 #ifndef PUTIL_H
  27 #define PUTIL_H
  28
  29 #include "unicode/utypes.h"
  30  /**
  31   * \file
  32   * \brief C API: Platform Utilities
  33   */
  34
  35 /*==========================================================================*/
  36 /* Platform utilities                                                       */
  37 /*==========================================================================*/
  38
  39 /**
  40  * Platform utilities isolates the platform dependencies of the
  41  * library.  For each platform which this code is ported to, these
  42  * functions may have to be re-implemented.
  43  */
  44
  45 /**
  46  * Return the ICU data directory.
  47  * The data directory is where common format ICU data files (.dat files)
  48  *   are loaded from.  Note that normal use of the built-in ICU
  49  *   facilities does not require loading of an external data file;
  50  *   unless you are adding custom data to ICU, the data directory
  51  *   does not need to be set.
  52  *
  53  * The data directory is determined as follows:
  54  *    If u_setDataDirectory() has been called, that is it, otherwise
  55  *    if the ICU_DATA environment variable is set, use that, otherwise
  56  *    If a data directory was specified at ICU build time
  57  *      <code>
  58  * \code
  59  *        #define ICU_DATA_DIR "path"
  60  * \endcode
  61  * </code> use that,
  62  *    otherwise no data directory is available.
  63  *
  64  * @return the data directory, or an empty string ("") if no data directory has
  65  *         been specified.
  66  *
  67  * @stable ICU 2.0
  68  */
  69 U_STABLE const char* U_EXPORT2 u_getDataDirectory(void);
  70
  71
  72 /**
  73  * Set the ICU data directory.
  74  * The data directory is where common format ICU data files (.dat files)
  75  *   are loaded from.  Note that normal use of the built-in ICU
  76  *   facilities does not require loading of an external data file;
  77  *   unless you are adding custom data to ICU, the data directory
  78  *   does not need to be set.
  79  *
  80  * This function should be called at most once in a process, before the
  81  * first ICU operation (e.g., u_init()) that will require the loading of an
  82  * ICU data file.
  83  * This function is not thread-safe. Use it before calling ICU APIs from
  84  * multiple threads.
  85  *
  86  * @param directory The directory to be set.
  87  *
  88  * @see u_init
  89  * @stable ICU 2.0
  90  */
  91 U_STABLE void U_EXPORT2 u_setDataDirectory(const char *directory);
  92
  93 #ifndef U_HIDE_INTERNAL_API
  94 /**
  95   * Return the time zone files override directory, or an empty string if
  96   * no directory was specified. Certain time zone resources will be preferentially
  97   * loaded from individual files in this directory.
  98   *
  99   * @return the time zone data override directory.
 100   * @internal
 101   */
 102 U_INTERNAL const char * U_EXPORT2 u_getTimeZoneFilesDirectory(UErrorCode *status);
 103
 104 /**
 105   * Set the time zone files override directory.
 106   * This function is not thread safe; it must not be called concurrently with
 107   *   u_getTimeZoneFilesDirectory() or any other use of ICU time zone functions.
 108   * This function should only be called before using any ICU service that
 109   *   will access the time zone data.
 110   * @internal
 111   */
 112 U_INTERNAL void U_EXPORT2 u_setTimeZoneFilesDirectory(const char *path, UErrorCode *status);
 113 #endif  /* U_HIDE_INTERNAL_API */
 114
 115
 116 /**
 117  * @{
 118  * Filesystem file and path separator characters.
 119  * Example: '/' and ':' on Unix, '\\' and ';' on Windows.
 120  * @stable ICU 2.0
 121  */
 122 #if U_PLATFORM_USES_ONLY_WIN32_API
 123 #   define U_FILE_SEP_CHAR '\\'
 124 #   define U_FILE_ALT_SEP_CHAR '/'
 125 #   define U_PATH_SEP_CHAR ';'
 126 #   define U_FILE_SEP_STRING "\\"
 127 #   define U_FILE_ALT_SEP_STRING "/"
 128 #   define U_PATH_SEP_STRING ";"
 129 #else
 130 #   define U_FILE_SEP_CHAR '/'
 131 #   define U_FILE_ALT_SEP_CHAR '/'
 132 #   define U_PATH_SEP_CHAR ':'
 133 #   define U_FILE_SEP_STRING "/"
 134 #   define U_FILE_ALT_SEP_STRING "/"
 135 #   define U_PATH_SEP_STRING ":"
 136 #endif
 137
 138 /** @} */
 139
 140 /**
 141  * Convert char characters to UChar characters.
 142  * This utility function is useful only for "invariant characters"
 143  * that are encoded in the platform default encoding.
 144  * They are a small, constant subset of the encoding and include
 145  * just the latin letters, digits, and some punctuation.
 146  * For details, see U_CHARSET_FAMILY.
 147  *
 148  * @param cs Input string, points to <code>length</code>
 149  *           character bytes from a subset of the platform encoding.
 150  * @param us Output string, points to memory for <code>length</code>
 151  *           Unicode characters.
 152  * @param length The number of characters to convert; this may
 153  *               include the terminating <code>NUL</code>.
 154  *
 155  * @see U_CHARSET_FAMILY
 156  * @stable ICU 2.0
 157  */
 158 U_STABLE void U_EXPORT2
 159 u_charsToUChars(const char *cs, UChar *us, int32_t length);
 160
 161 /**
 162  * Convert UChar characters to char characters.
 163  * This utility function is useful only for "invariant characters"
 164  * that can be encoded in the platform default encoding.
 165  * They are a small, constant subset of the encoding and include
 166  * just the latin letters, digits, and some punctuation.
 167  * For details, see U_CHARSET_FAMILY.
 168  *
 169  * @param us Input string, points to <code>length</code>
 170  *           Unicode characters that can be encoded with the
 171  *           codepage-invariant subset of the platform encoding.
 172  * @param cs Output string, points to memory for <code>length</code>
 173  *           character bytes.
 174  * @param length The number of characters to convert; this may
 175  *               include the terminating <code>NUL</code>.
 176  *
 177  * @see U_CHARSET_FAMILY
 178  * @stable ICU 2.0
 179  */
 180 U_STABLE void U_EXPORT2
 181 u_UCharsToChars(const UChar *us, char *cs, int32_t length);
 182
 183 #endif