[C] Added utf-8 example to README

README.md

@@ -83,7 +83,7 @@ int main(void)
 #include "fort.hpp"
 int main(void)
 {
-    fort::table table;
+    fort::char_table table;
     table << fort::header
         << "N" << "Driver" << "Time" << "Avg Speed" << fort::endr
         << "1" << "Ricciardo" << "1:25.945" << "47.362" << fort::endr
@@ -140,7 +140,7 @@ int main(void)
 #include "fort.hpp"
 int main(void)
 {
-    fort::table table;
+    fort::char_table table;
     /* Change border style */
     table.set_border_style(FT_DOUBLE2_STYLE);
 
@@ -205,7 +205,7 @@ int main(void)
 #include "fort.hpp"
 int main(void)
 {
-    fort::table table;
+    fort::char_table table;
     table << fort::header;
     /* Fill each cell with operator[] */
     table [0][0] = "N";
@@ -239,6 +239,76 @@ Output:
 +---+---------+-------------+----------------+
 ```
 
+### Working with multibyte-character-strings
+`libfort` supports `wchar_t` and utf-8 strings. Here are simple examples of working with utf-8 strings:
+
+
+```C
+/* C API */
+#include <stdio.h>
+#include "fort.h"
+int main(void)
+{
+    ft_table_t *table = ft_create_table();
+    ft_set_border_style(table, FT_NICE_STYLE);
+    ft_set_cell_prop(table, FT_ANY_ROW, 0, FT_CPROP_TEXT_ALIGN, FT_ALIGNED_CENTER);
+    ft_set_cell_prop(table, FT_ANY_ROW, 1, FT_CPROP_TEXT_ALIGN, FT_ALIGNED_LEFT);
+    ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
+
+    ft_u8write_ln(table, "Ранг", "Название", "Год", "Рейтинг");
+    ft_u8write_ln(table, "1", "Побег из Шоушенка", "1994", "9.5");
+    ft_u8write_ln(table, "2", "12 разгневанных мужчин", "1957", "8.8");
+    ft_u8write_ln(table, "3", "Космическая одиссея 2001 года", "1968", "8.5");
+    ft_u8write_ln(table, "4", "Бегущий по лезвию", "1982", "8.1");
+
+    printf("%s\n", (const char *)ft_to_u8string(table));
+    ft_destroy_table(table);
+}
+```
+
+```C++
+/* C++ API */
+#include <iostream>
+#include "fort.hpp"
+int main(void)
+{
+    fort::utf8_table table;
+    table.set_border_style(FT_NICE_STYLE);
+    table.column(0).set_cell_text_align(fort::text_align::center);
+    table.column(1).set_cell_text_align(fort::text_align::center);
+
+    table << fort::header
+          << "Ранг" << "Название" << "Год" << "Рейтинг" << fort::endr
+          << "1" << "Побег из Шоушенка" << "1994" << "9.5"<< fort::endr
+          << "2" << "12 разгневанных мужчин" << "1957" << "8.8" << fort::endr
+          << "3" << "Космическая одиссея 2001 года" << "1968" << "8.5" << fort::endr
+          << "4" << "Бегущий по лезвию" << "1982" << "8.1" << fort::endr;
+    std::cout << table.to_string() << std::endl;
+}
+```
+
+Output:
+```text
+╔══════╦═══════════════════════════════╦══════╦═════════╗
+║ Ранг ║           Название            ║ Год  ║ Рейтинг ║
+╠══════╬═══════════════════════════════╬══════╬═════════╣
+║  1   ║       Побег из Шоушенка       ║ 1994 ║ 9.5     ║
+║  2   ║    12 разгневанных мужчин     ║ 1957 ║ 8.8     ║
+║  3   ║ Космическая одиссея 2001 года ║ 1968 ║ 8.5     ║
+║  4   ║       Бегущий по лезвию       ║ 1982 ║ 8.1     ║
+╚══════╩═══════════════════════════════╩══════╩═════════╝
+```
+
+Please note:
+-  `libfort` internally has a very simple logic to compute visible width of utf-8
+strings. It considers that each codepoint will occupy one position on the
+terminal in case of monowidth font (some east asians wide and fullwidth
+characters (see http://www.unicode.org/reports/tr11/tr11-33.html) will occupy
+2 positions). This logic is very simple and covers wide range of cases. But
+obviously there a lot of cases when it is not sufficient. In such cases user
+should use some external libraries and provide an appropriate function to
+`libfort` via `ft_set_u8strwid_func` function.
+
 ## Supported platforms and compilers
 
 The following compilers are currently used in continuous integration at [Travis](https://travis-ci.org/seleznevae/libfort), [AppVeyor](https://ci.appveyor.com/project/seleznevae/libfort) and [Cirrus](https://cirrus-ci.com/github/seleznevae/libfort):

lib/fort.h

@@ -56,7 +56,7 @@ SOFTWARE.
 
 /**
  * libfort configuration macros
- * (to disable wchar_t/utf-8 support this macros should be defined)
+ * (to disable wchar_t/UTF-8 support this macros should be defined)
  */
 /** #define FT_CONGIG_DISABLE_WCHAR */
 /** #define FT_CONGIG_DISABLE_UTF8 */
@@ -916,9 +916,9 @@ int ft_u8printf_ln(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_
 const void *ft_to_u8string(const ft_table_t *table);
 
 /**
- * Set custom function to compute visible width of utf8 string.
+ * Set custom function to compute visible width of UTF-8 string.
  *
- * libfort internally has a very simple logic to compute visible width of utf8
+ * libfort internally has a very simple logic to compute visible width of UTF-8
  * strings. It considers that each codepoint will occupy one position on the
  * terminal in case of monowidth font (some east asians wide and fullwidth
  * characters (see http://www.unicode.org/reports/tr11/tr11-33.html) will occupy
@@ -928,8 +928,8 @@ const void *ft_to_u8string(const ft_table_t *table);
  * libfort.
  *
  * @param u8strwid
- *   User provided function to evaluate width of utf8 string ( beg - start of
+ *   User provided function to evaluate width of UTF-8 string ( beg - start of
- *   utf8 string, end - end of utf8 string (not included), width - pointer to
+ *   UTF-8 string, end - end of UTF-8 string (not included), width - pointer to
  *   the result). If function succeed it should return 0, otherwise some non-
  *   zero value. If function returns nonzero value libfort fallbacks to default
  *   internal algorithm.

src/fort.h

@@ -56,7 +56,7 @@ SOFTWARE.
 
 /**
  * libfort configuration macros
- * (to disable wchar_t/utf-8 support this macros should be defined)
+ * (to disable wchar_t/UTF-8 support this macros should be defined)
  */
 /** #define FT_CONGIG_DISABLE_WCHAR */
 /** #define FT_CONGIG_DISABLE_UTF8 */
@@ -916,9 +916,9 @@ int ft_u8printf_ln(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_
 const void *ft_to_u8string(const ft_table_t *table);
 
 /**
- * Set custom function to compute visible width of utf8 string.
+ * Set custom function to compute visible width of UTF-8 string.
  *
- * libfort internally has a very simple logic to compute visible width of utf8
+ * libfort internally has a very simple logic to compute visible width of UTF-8
  * strings. It considers that each codepoint will occupy one position on the
  * terminal in case of monowidth font (some east asians wide and fullwidth
  * characters (see http://www.unicode.org/reports/tr11/tr11-33.html) will occupy
@@ -928,8 +928,8 @@ const void *ft_to_u8string(const ft_table_t *table);
  * libfort.
  *
  * @param u8strwid
- *   User provided function to evaluate width of utf8 string ( beg - start of
+ *   User provided function to evaluate width of UTF-8 string ( beg - start of
- *   utf8 string, end - end of utf8 string (not included), width - pointer to
+ *   UTF-8 string, end - end of UTF-8 string (not included), width - pointer to
  *   the result). If function succeed it should return 0, otherwise some non-
  *   zero value. If function returns nonzero value libfort fallbacks to default
  *   internal algorithm.