[errors] Introduce `FT_Error_String'.

* include/freetype/fterrors.h (FT_Error_String),
src/base/fterrors.c (FT_Error_String): Implement `FT_Error_String'.

* src/base/ftbase.c, src/base/Jamfile (_source),
src/base/rules.mk (BASE_SRC): Add `fterrors.c' to the build logic.

* src/base/ftdebug.c (FT_Throw): Use `FT_Error_String'.

ChangeLog

@@ -1,3 +1,15 @@
+2018-08-30  Armin Hasitzka  <prince.cherusker@gmail.com>
+
+	[errors] Introduce `FT_Error_String'.
+
+	* include/freetype/fterrors.h (FT_Error_String),
+	src/base/fterrors.c (FT_Error_String): Implement `FT_Error_String'.
+
+	* src/base/ftbase.c, src/base/Jamfile (_source),
+	src/base/rules.mk (BASE_SRC): Add `fterrors.c' to the build logic.
+
+	* src/base/ftdebug.c (FT_Throw): Use `FT_Error_String'.
+
 2018-08-30  Werner Lemberg  <wl@gnu.org>
 
 	[autofit] Trace `before' and `after' edges of strong points.

include/freetype/fterrors.h

@@ -166,6 +166,8 @@
   /*                                                           */
 #ifndef FT_ERRORDEF
 
+#define FT_INCLUDE_ERR_PROTOS
+
 #define FT_ERRORDEF( e, v, s )  e = v,
 #define FT_ERROR_START_LIST     enum {
 #define FT_ERROR_END_LIST       FT_ERR_CAT( FT_ERR_PREFIX, Max ) };
@@ -228,6 +230,42 @@
 #undef FT_ERR_PREFIX
 #endif
 
+#ifdef FT_INCLUDE_ERR_PROTOS
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Error_String
+   *
+   * @description:
+   *   Retrieve the description of a valid FreeType error code.
+   *
+   * @input:
+   *   error_code ::
+   *     A valid FreeType error code.
+   *
+   * @return:
+   *   A C~string or `NULL`, if any error occurred.
+   *
+   * @note:
+   *   FreeType has to be compiled with `FT_CONFIG_OPTION_ERROR_STRINGS` or
+   *   `FT_DEBUG_LEVEL_ERROR` to get meaningful descriptions.
+   *   'error_string' will be `NULL` otherwise.
+   *
+   *   Module identification will be ignored:
+   *
+   *   ```c
+   *     strcmp( FT_Error_String(  FT_Err_Unknown_File_Format ),
+   *             FT_Error_String( BDF_Err_Unknown_File_Format ) ) == 0;
+   *   ```
+   */
+  FT_EXPORT( const char* )
+  FT_Error_String( FT_Error  error_code );
+
+
+#endif /* FT_INCLUDE_ERR_PROTOS */
+
 #endif /* !(FTERRORS_H_ && __FTERRORS_H__) */
 
 

src/base/Jamfile

@@ -22,6 +22,7 @@ SubDir  FT2_TOP $(FT2_SRC_DIR) base ;
                ftcalc
                ftcolor
                ftdbgmem
+               fterrors
                ftfntfmt
                ftgloadr
                fthash

src/base/ftbase.c

@@ -23,6 +23,7 @@
 #include "ftcalc.c"
 #include "ftcolor.c"
 #include "ftdbgmem.c"
+#include "fterrors.c"
 #include "ftfntfmt.c"
 #include "ftgloadr.c"
 #include "fthash.c"

src/base/ftdebug.c

@@ -87,9 +87,12 @@
             int          line,
             const char*  file )
   {
-    FT_UNUSED( error );
-    FT_UNUSED( line );
-    FT_UNUSED( file );
+    fprintf( stderr,
+             "%s:%d: error 0x%02x: %s\n",
+             file,
+             line,
+             error,
+             FT_Error_String( error ) );
 
     return 0;
   }

src/base/fterrors.c

@@ -0,0 +1,45 @@
+/****************************************************************************
+ *
+ * fterrors.c
+ *
+ *   FreeType API for error code handling.
+ *
+ * Copyright 2018 by
+ * Armin Hasitzka, David Turner, Robert Wilhelm, and Werner Lemberg.
+ *
+ * This file is part of the FreeType project, and may only be used,
+ * modified, and distributed under the terms of the FreeType project
+ * license, LICENSE.TXT.  By continuing to use, modify, or distribute
+ * this file you indicate that you have read the license and
+ * understand and accept it fully.
+ *
+ */
+
+
+#include <ft2build.h>
+#include FT_ERRORS_H
+
+
+  /* documentation is in fterrors.h */
+
+  FT_EXPORT_DEF( const char* )
+  FT_Error_String( FT_Error  error_code )
+  {
+    if ( error_code <  0                                ||
+         error_code >= FT_ERR_CAT( FT_ERR_PREFIX, Max ) )
+      return NULL;
+
+#if defined( FT_CONFIG_OPTION_ERROR_STRINGS ) || \
+    defined( FT_DEBUG_LEVEL_ERROR )
+
+#undef FTERRORS_H_
+#define FT_ERROR_START_LIST     switch ( FT_ERROR_BASE( error_code ) ) {
+#define FT_ERRORDEF( e, v, s )    case v: return s;
+#define FT_ERROR_END_LIST       }
+
+#include FT_ERRORS_H
+
+#endif /* defined( FT_CONFIG_OPTION_ERROR_STRINGS ) || ... */
+
+    return NULL;
+  }

src/base/rules.mk

@@ -40,6 +40,7 @@ BASE_SRC := $(BASE_DIR)/ftadvanc.c \
             $(BASE_DIR)/ftcalc.c   \
             $(BASE_DIR)/ftcolor.c  \
             $(BASE_DIR)/ftdbgmem.c \
+            $(BASE_DIR)/fterrors.c \
             $(BASE_DIR)/ftfntfmt.c \
             $(BASE_DIR)/ftgloadr.c \
             $(BASE_DIR)/fthash.c   \