Havoc Pennington's implementation of convenient character set conversion
[platform/upstream/glib.git] / glib / glib.h
index 72ccbfb..0c4d9f5 100644 (file)
@@ -178,11 +178,11 @@ extern "C" {
  */
 #if !defined (G_VA_COPY)
 #  if defined (__GNUC__) && defined (__PPC__) && (defined (_CALL_SYSV) || defined (_WIN32))
-#  define G_VA_COPY(ap1, ap2)    (*(ap1) = *(ap2))
+#    define G_VA_COPY(ap1, ap2)          (*(ap1) = *(ap2))
 #  elif defined (G_VA_COPY_AS_ARRAY)
-#  define G_VA_COPY(ap1, ap2)    g_memmove ((ap1), (ap2), sizeof (va_list))
+#    define G_VA_COPY(ap1, ap2)          g_memmove ((ap1), (ap2), sizeof (va_list))
 #  else /* va_list is a pointer */
-#  define G_VA_COPY(ap1, ap2)    ((ap1) = (ap2))
+#    define G_VA_COPY(ap1, ap2)          ((ap1) = (ap2))
 #  endif /* va_list is a pointer */
 #endif /* !G_VA_COPY */
 
@@ -205,47 +205,42 @@ extern "C" {
  * *capable* to do function inlining, in which case inline function bodys
  * do make sense. we also define G_INLINE_FUNC to properly export the
  * function prototypes if no inlining can be performed.
- * we special case most of the stuff, so inline functions can have a normal
- * implementation by defining G_INLINE_FUNC to extern and G_CAN_INLINE to 1.
+ * inline function bodies have to be special cased with G_CAN_INLINE and a
+ * .c file specific macro to allow one compiled instance with extern linkage
+ * of the functions by defining G_IMPLEMENT_INLINES and the .c file macro.
  */
+#ifdef G_IMPLEMENT_INLINES
+#  define G_INLINE_FUNC extern
+#  undef  G_CAN_INLINE
+#endif
 #ifndef G_INLINE_FUNC
 #  define G_CAN_INLINE 1
 #endif
-#ifdef G_HAVE_INLINE
-#  if defined (__GNUC__) && defined (__STRICT_ANSI__)
-#    undef inline
-#    define inline __inline__
-#  endif
-#else /* !G_HAVE_INLINE */
+#if defined (G_HAVE_INLINE) && defined (__GNUC__) && defined (__STRICT_ANSI__)
+#  undef inline
+#  define inline __inline__
+#elif !defined (G_HAVE_INLINE)
 #  undef inline
 #  if defined (G_HAVE___INLINE__)
 #    define inline __inline__
-#  else /* !inline && !__inline__ */
-#    if defined (G_HAVE___INLINE)
-#      define inline __inline
-#    else /* !inline && !__inline__ && !__inline */
-#      define inline /* don't inline, then */
-#      ifndef G_INLINE_FUNC
-#       undef G_CAN_INLINE
-#      endif
+#  elif defined (G_HAVE___INLINE)
+#    define inline __inline
+#  else /* !inline && !__inline__ && !__inline */
+#    define inline  /* don't inline, then */
+#    ifndef G_INLINE_FUNC
+#      undef G_CAN_INLINE
 #    endif
 #  endif
 #endif
 #ifndef G_INLINE_FUNC
-#  ifdef __GNUC__
-#    ifdef __OPTIMIZE__
-#      define G_INLINE_FUNC extern inline
-#    else
-#      undef G_CAN_INLINE
-#      define G_INLINE_FUNC extern
-#    endif
-#  else /* !__GNUC__ */
-#    ifdef G_CAN_INLINE
-#      define G_INLINE_FUNC static inline
-#    else
-#      define G_INLINE_FUNC extern
-#    endif
-#  endif /* !__GNUC__ */
+#  if defined (__GNUC__) && (__OPTIMIZE__)
+#    define G_INLINE_FUNC extern inline
+#  elif defined (G_CAN_INLINE) && !defined (__GNUC__)
+#    define G_INLINE_FUNC static inline
+#  else /* can't inline */
+#    define G_INLINE_FUNC extern
+#    undef G_CAN_INLINE
+#  endif
 #endif /* !G_INLINE_FUNC */
 
 
@@ -323,11 +318,11 @@ extern "C" {
  * Actual use is strongly deprecated of course ;)
  */
 #if defined (__i386__) && defined (__GNUC__) && __GNUC__ >= 2
-#define        G_BREAKPOINT()          G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
+#  define G_BREAKPOINT()       G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
 #elif defined (__alpha__) && defined (__GNUC__) && __GNUC__ >= 2
-#define        G_BREAKPOINT()          G_STMT_START{ __asm__ __volatile__ ("bpt"); }G_STMT_END
+#  define G_BREAKPOINT()       G_STMT_START{ __asm__ __volatile__ ("bpt"); }G_STMT_END
 #else  /* !__i386__ && !__alpha__ */
-#define        G_BREAKPOINT()
+#  define G_BREAKPOINT()       G_STMT_START{ raise (5 /* SIGTRAP */); }G_STMT_END
 #endif /* __i386__ */
 
 
@@ -544,13 +539,6 @@ typedef unsigned short     gushort;
 typedef unsigned long  gulong;
 typedef unsigned int   guint;
 
-#define G_GSHORT_FORMAT  "hi"
-#define G_GUSHORT_FORMAT "hu"
-#define G_GINT_FORMAT    "i"
-#define G_GUINT_FORMAT   "u"
-#define G_GLONG_FORMAT   "li"
-#define G_GULONG_FORMAT  "lu"
-
 typedef float  gfloat;
 typedef double gdouble;
 
@@ -941,6 +929,15 @@ struct _GTuples
   guint len;
 };
 
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#include <gerror.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
 
 /* IEEE Standard 754 Single Precision Storage Format (gfloat):
  *
@@ -1470,19 +1467,32 @@ GLogLevelFlags  g_log_set_always_fatal  (GLogLevelFlags  fatal_mask);
 #ifndef        G_LOG_DOMAIN
 #define        G_LOG_DOMAIN    ((gchar*) 0)
 #endif /* G_LOG_DOMAIN */
-#ifdef __GNUC__
-#define        g_error(format, args...)        g_log (G_LOG_DOMAIN, \
-                                              G_LOG_LEVEL_ERROR, \
-                                              format, ##args)
-#define        g_message(format, args...)      g_log (G_LOG_DOMAIN, \
-                                              G_LOG_LEVEL_MESSAGE, \
-                                              format, ##args)
-#define        g_critical(format, args...)     g_log (G_LOG_DOMAIN, \
-                                              G_LOG_LEVEL_CRITICAL, \
-                                              format, ##args)
-#define        g_warning(format, args...)      g_log (G_LOG_DOMAIN, \
-                                              G_LOG_LEVEL_WARNING, \
-                                              format, ##args)
+#if defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
+#define        g_error(...)    g_log (G_LOG_DOMAIN,         \
+                              G_LOG_LEVEL_ERROR,    \
+                              __VA_ARGS__)
+#define        g_message(...)  g_log (G_LOG_DOMAIN,         \
+                              G_LOG_LEVEL_MESSAGE,  \
+                              __VA_ARGS__)
+#define        g_critical(...) g_log (G_LOG_DOMAIN,         \
+                              G_LOG_LEVEL_CRITICAL, \
+                              __VA_ARGS__)
+#define        g_warning(...)  g_log (G_LOG_DOMAIN,         \
+                              G_LOG_LEVEL_WARNING,  \
+                              __VA_ARGS__)
+#elif defined (__GNUC__)
+#define        g_error(format...)      g_log (G_LOG_DOMAIN,         \
+                                      G_LOG_LEVEL_ERROR,    \
+                                      format)
+#define        g_message(format...)    g_log (G_LOG_DOMAIN,         \
+                                      G_LOG_LEVEL_MESSAGE,  \
+                                      format)
+#define        g_critical(format...)   g_log (G_LOG_DOMAIN,         \
+                                      G_LOG_LEVEL_CRITICAL, \
+                                      format)
+#define        g_warning(format...)    g_log (G_LOG_DOMAIN,         \
+                                      G_LOG_LEVEL_WARNING,  \
+                                      format)
 #else  /* !__GNUC__ */
 static void
 g_error (const gchar *format,
@@ -1621,7 +1631,8 @@ void g_blow_chunks (void);
 /* Timer
  */
 
-#define G_MICROSEC 1000000
+/* microseconds per second */
+#define G_USEC_PER_SEC 1000000
 
 GTimer* g_timer_new    (void);
 void   g_timer_destroy (GTimer  *timer);
@@ -1790,7 +1801,24 @@ void     g_atexit                (GVoidFunc    func);
  */
 G_INLINE_FUNC gint     g_bit_nth_lsf (guint32 mask,
                                       gint    nth_bit);
-#ifdef G_CAN_INLINE
+G_INLINE_FUNC gint     g_bit_nth_msf (guint32 mask,
+                                      gint    nth_bit);
+G_INLINE_FUNC guint    g_bit_storage (guint number);
+
+
+/* Trash Stacks
+ * elements need to be >= sizeof (gpointer)
+ */
+G_INLINE_FUNC void     g_trash_stack_push      (GTrashStack **stack_p,
+                                                gpointer      data_p);
+G_INLINE_FUNC gpointer g_trash_stack_pop       (GTrashStack **stack_p);
+G_INLINE_FUNC gpointer g_trash_stack_peek      (GTrashStack **stack_p);
+G_INLINE_FUNC guint    g_trash_stack_height    (GTrashStack **stack_p);
+
+
+/* inline function implementations
+ */
+#if defined (G_CAN_INLINE) || defined (__G_UTILS_C__)
 G_INLINE_FUNC gint
 g_bit_nth_lsf (guint32 mask,
               gint    nth_bit)
@@ -1804,11 +1832,6 @@ g_bit_nth_lsf (guint32 mask,
   while (nth_bit < 32);
   return -1;
 }
-#endif /* G_CAN_INLINE */
-
-G_INLINE_FUNC gint     g_bit_nth_msf (guint32 mask,
-                                      gint    nth_bit);
-#ifdef G_CAN_INLINE
 G_INLINE_FUNC gint
 g_bit_nth_msf (guint32 mask,
               gint    nth_bit)
@@ -1824,10 +1847,6 @@ g_bit_nth_msf (guint32 mask,
   while (nth_bit > 0);
   return -1;
 }
-#endif /* G_CAN_INLINE */
-
-G_INLINE_FUNC guint    g_bit_storage (guint number);
-#ifdef G_CAN_INLINE
 G_INLINE_FUNC guint
 g_bit_storage (guint number)
 {
@@ -1841,15 +1860,6 @@ g_bit_storage (guint number)
   while (number);
   return n_bits;
 }
-#endif /* G_CAN_INLINE */
-
-
-/* Trash Stacks
- * elements need to be >= sizeof (gpointer)
- */
-G_INLINE_FUNC void     g_trash_stack_push      (GTrashStack **stack_p,
-                                                gpointer      data_p);
-#ifdef G_CAN_INLINE
 G_INLINE_FUNC void
 g_trash_stack_push (GTrashStack **stack_p,
                    gpointer      data_p)
@@ -1859,10 +1869,6 @@ g_trash_stack_push (GTrashStack **stack_p,
   data->next = *stack_p;
   *stack_p = data;
 }
-#endif /* G_CAN_INLINE */
-
-G_INLINE_FUNC gpointer g_trash_stack_pop       (GTrashStack **stack_p);
-#ifdef G_CAN_INLINE
 G_INLINE_FUNC gpointer
 g_trash_stack_pop (GTrashStack **stack_p)
 {
@@ -1880,10 +1886,6 @@ g_trash_stack_pop (GTrashStack **stack_p)
 
   return data;
 }
-#endif  /* G_CAN_INLINE */
-
-G_INLINE_FUNC gpointer g_trash_stack_peek      (GTrashStack **stack_p);
-#ifdef G_CAN_INLINE
 G_INLINE_FUNC gpointer
 g_trash_stack_peek (GTrashStack **stack_p)
 {
@@ -1893,10 +1895,6 @@ g_trash_stack_peek (GTrashStack **stack_p)
 
   return data;
 }
-#endif  /* G_CAN_INLINE */
-
-G_INLINE_FUNC guint    g_trash_stack_height    (GTrashStack **stack_p);
-#ifdef G_CAN_INLINE
 G_INLINE_FUNC guint
 g_trash_stack_height (GTrashStack **stack_p)
 {
@@ -1908,7 +1906,7 @@ g_trash_stack_height (GTrashStack **stack_p)
 
   return i;
 }
-#endif  /* G_CAN_INLINE */
+#endif  /* G_CAN_INLINE || __G_UTILS_C__ */
 
 
 /* String Chunks
@@ -2059,8 +2057,8 @@ gboolean g_str_equal (gconstpointer   v,
 guint   g_str_hash  (gconstpointer   v);
 
 gint    g_int_equal (gconstpointer   v,
-                     gconstpointer   v2);
-guint   g_int_hash  (gconstpointer   v);
+                     gconstpointer   v2) G_GNUC_CONST;
+guint   g_int_hash  (gconstpointer   v) G_GNUC_CONST;
 
 /* This "hash" function will just return the key's adress as an
  * unsigned integer. Useful for hashing on plain adresses or
@@ -2068,9 +2066,9 @@ guint      g_int_hash  (gconstpointer   v);
  * passing NULL into g_hash_table_new() as GHashFunc has the
  * same effect as passing g_direct_hash().
  */
-guint g_direct_hash  (gconstpointer v);
+guint g_direct_hash  (gconstpointer v) G_GNUC_CONST;
 gint  g_direct_equal (gconstpointer v,
-                     gconstpointer v2);
+                     gconstpointer v2) G_GNUC_CONST;
 
 
 /* Quarks (string<->id association)
@@ -2078,7 +2076,7 @@ gint  g_direct_equal (gconstpointer v,
 GQuark   g_quark_try_string            (const gchar    *string);
 GQuark   g_quark_from_static_string    (const gchar    *string);
 GQuark   g_quark_from_string           (const gchar    *string);
-gchar*   g_quark_to_string             (GQuark          quark);
+gchar*   g_quark_to_string             (GQuark          quark) G_GNUC_CONST;
 
 
 /* Keyed Data List
@@ -2555,11 +2553,11 @@ void         g_date_add_years             (GDate       *date,
                                            guint        n_years);
 void         g_date_subtract_years        (GDate       *date,
                                            guint        n_years);
-gboolean     g_date_is_leap_year          (GDateYear    year);
+gboolean     g_date_is_leap_year          (GDateYear    year) G_GNUC_CONST;
 guint8       g_date_days_in_month         (GDateMonth   month, 
-                                           GDateYear    year);
-guint8       g_date_monday_weeks_in_year  (GDateYear    year);
-guint8       g_date_sunday_weeks_in_year  (GDateYear    year);
+                                           GDateYear    year) G_GNUC_CONST;
+guint8       g_date_monday_weeks_in_year  (GDateYear    year) G_GNUC_CONST;
+guint8       g_date_sunday_weeks_in_year  (GDateYear    year) G_GNUC_CONST;
 
 /* qsort-friendly (with a cast...) */
 gint         g_date_compare               (GDate       *lhs,
@@ -2668,7 +2666,7 @@ gdouble g_random_double_range  (gdouble     min,
  * next largest prime, or the highest it knows about which is about
  * MAXINT/4.
  */
-guint     g_spaced_primes_closest (guint num);
+guint     g_spaced_primes_closest (guint num) G_GNUC_CONST;
 
 
 /* GIOChannel
@@ -2908,34 +2906,47 @@ gint        g_io_channel_unix_get_fd (GIOChannel *channel);
 
 #define G_WIN32_MSG_HANDLE 19981206
 
-/* This can be used to wait until a channel is readable.  On Unix you
- * would do a select() on the fd of the channel. This should probably
- * be replaced by something for all platforms?
+/* Use this to get a GPollFD from a GIOChannel, so that you can call
+ * g_io_channel_win32_poll(). After calling this you should only use
+ * g_io_channel_read() to read from the GIOChannel, i.e. never read()
+ * or recv() from the underlying file descriptor or SOCKET.
+ */
+void        g_io_channel_win32_make_pollfd (GIOChannel   *channel,
+                                           GIOCondition  condition,
+                                           GPollFD      *fd);
+
+/* This can be used to wait a until at least one of the channels is readable.
+ * On Unix you would do a select() on the file descriptors of the channels.
+ * This should probably be available for all platforms?
  */
-gint        g_io_channel_win32_wait_for_condition (GIOChannel  *channel,
-                                                  GIOCondition condition,
-                                                  gint         timeout);
+gint        g_io_channel_win32_poll   (GPollFD    *fds,
+                                      gint        n_fds,
+                                      gint        timeout);
 
 /* This is used to add polling for Windows messages. GDK (GTk+) programs
  * should *not* use this.
  */
-void        g_main_poll_win32_msg_add(gint        priority,
-                                     GPollFD    *fd,
-                                     guint       hwnd);
+void        g_main_poll_win32_msg_add (gint        priority,
+                                      GPollFD    *fd,
+                                      guint       hwnd);
 
 /* An IO channel for Windows messages for window handle hwnd. */
 GIOChannel *g_io_channel_win32_new_messages (guint hwnd);
 
 /* An IO channel for C runtime (emulated Unix-like) file
  * descriptors. Identical to g_io_channel_unix_new above.
+ * After calling g_io_add_watch() on a IO channel returned
+ * by this function, you shouldn't call read() on the file
+ * descriptor.
  */
 GIOChannel* g_io_channel_win32_new_fd (int         fd);
 
 /* Get the C runtime file descriptor of a channel. */
 gint        g_io_channel_win32_get_fd (GIOChannel *channel);
 
-/* An IO channel for a SOCK_STREAM winsock socket. The parameter should
- * be a SOCKET.
+/* An IO channel for a SOCK_STREAM winsock socket. The parameter
+ * should be a SOCKET. After calling g_io_add_watch() on a IO channel
+ * returned by this function, you shouldn't call recv() on the SOCKET.
  */
 GIOChannel *g_io_channel_win32_new_stream_socket (int socket);
 
@@ -3021,6 +3032,14 @@ gchar *         g_win32_error_message (gint error);
 /* GLib Thread support
  */
 
+extern GQuark g_thread_error_quark();
+#define G_THREAD_ERROR g_thread_error_quark()
+
+typedef enum
+{
+  G_THREAD_ERROR_AGAIN /* Resource temporarily unavailable */
+} GThreadError;
+
 typedef void           (*GThreadFunc)          (gpointer       value);
 
 typedef enum
@@ -3073,7 +3092,8 @@ struct _GThreadFunctions
                                   gboolean              joinable,
                                   gboolean              bound,
                                   GThreadPriority       priority,
-                                  gpointer              thread);
+                                  gpointer              thread,
+                                  GError              **error);
   void      (*thread_yield)       (void);
   void      (*thread_join)        (gpointer             thread);
   void      (*thread_exit)        (void);
@@ -3135,11 +3155,12 @@ GThread* g_thread_create (GThreadFunc            thread_func,
                          gulong                 stack_size,
                          gboolean               joinable,
                          gboolean               bound,
-                         GThreadPriority        priority);
+                         GThreadPriority        priority,
+                         GError               **error);
 GThread* g_thread_self ();
-void g_thread_join (GThreadthread);
-void g_thread_set_priority (GThreadthread, 
-                           GThreadPriority priority);
+void g_thread_join (GThread *thread);
+void g_thread_set_priority (GThread         *thread, 
+                           GThreadPriority  priority);
 
 /* GStaticMutexes can be statically initialized with the value
  * G_STATIC_MUTEX_INIT, and then they can directly be used, that is
@@ -3339,20 +3360,23 @@ GThreadPool*    g_thread_pool_new             (GFunc            thread_func,
                                               gboolean         bound,
                                               GThreadPriority  priority,
                                               gboolean         exclusive,
-                                              gpointer         user_data);
+                                              gpointer         user_data,
+                                              GError         **error);
 
 /* Push new data into the thread pool. This task is assigned to a thread later
  * (when the maximal number of threads is reached for that pool) or now
  * (otherwise). If necessary a new thread will be started. The function
  * returns immediatly */
 void            g_thread_pool_push            (GThreadPool     *pool,
-                                              gpointer         data);
+                                              gpointer         data,
+                                              GError         **error);
 
 /* Set the number of threads, which can run concurrently for that pool, -1
  * means no limit. 0 means has the effect, that the pool won't process
  * requests until the limit is set higher again */
 void            g_thread_pool_set_max_threads (GThreadPool     *pool,
-                                              gint             max_threads);
+                                              gint             max_threads,
+                                              GError         **error);
 gint            g_thread_pool_get_max_threads (GThreadPool     *pool);
 
 /* Get the number of threads assigned to that pool. This number doesn't
@@ -3379,11 +3403,36 @@ guint           g_thread_pool_get_num_unused_threads (void);
 /* Stop all currently unused threads, but leave the limit untouched */
 void            g_thread_pool_stop_unused_threads    (void);
 
+typedef enum 
+{
+  G_CONVERT_ERROR_NO_CONVERSION,
+  G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
+  G_CONVERT_ERROR_OTHER
+} GConvertError;
+
+#define G_CONVERT_ERROR g_convert_error_quark()
+GQuark g_convert_error_quark();
+
+gchar* g_convert               (const gchar  *str,
+                               gint          len,
+                               const gchar  *to_codeset,
+                               const gchar  *from_codeset,
+                               gint         *bytes_read,
+                               gint         *bytes_written,
+                               GError      **error);
+gchar* g_convert_with_fallback (const gchar  *str,
+                               gint          len,
+                               const gchar  *to_codeset,
+                               const gchar  *from_codeset,
+                               gchar        *fallback,
+                               gint         *bytes_read,
+                               gint         *bytes_written,
+                               GError      **error);
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
 
 #include <gunicode.h>
-#include <gerror.h>
 
 #endif /* __G_LIB_H__ */