💾 Archived View for gmi.noulin.net › gitRepositories › md › file › fort.h.gmi captured on 2023-01-29 at 13:22:40. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
fort.h (34283B)
1 /*
2 libfort
3
4 MIT License
5
6 Copyright (c) 2017 - 2020 Seleznev Anton
7
8 Permission is hereby granted, free of charge, to any person obtaining a copy
9 of this software and associated documentation files (the "Software"), to deal
10 in the Software without restriction, including without limitation the rights
11 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12 copies of the Software, and to permit persons to whom the Software is
13 furnished to do so, subject to the following conditions:
14
15 The above copyright notice and this permission notice shall be included in all
16 copies or substantial portions of the Software.
17
18 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24 SOFTWARE.
25 */
26
27 /**
28 * @file fort.h
29 * @brief Main header file describing libfort API.
30 *
31 * This file contains declarations of all libfort functions and macro
32 * definitions.
33 */
34
35 #ifndef LIBFORT_H
36 #define LIBFORT_H
37
38 #include <stddef.h>
39 #include <stdlib.h>
40 #include <stdint.h>
41 #include <limits.h>
42
43 /*****************************************************************************
44 * VERSION
45 *****************************************************************************/
46
47 #define LIBFORT_MAJOR_VERSION 0
48 #define LIBFORT_MINOR_VERSION 5
49 #define LIBFORT_REVISION 0
50 #define LIBFORT_VERSION_STR "0.5.0"
51
52
53 /*****************************************************************************
54 * Configuration
55 *****************************************************************************/
56
57 /**
58 * libfort configuration macros
59 * (to disable wchar_t/UTF-8 support this macros should be defined)
60 */
61 /** #define FT_CONGIG_DISABLE_WCHAR */
62 /** #define FT_CONGIG_DISABLE_UTF8 */
63
64 #if !defined(FT_CONGIG_DISABLE_WCHAR)
65 #define FT_HAVE_WCHAR
66 #endif
67
68 #if !defined(FT_CONGIG_DISABLE_UTF8)
69 #define FT_HAVE_UTF8
70 #endif
71
72
73 /*****************************************************************************
74 * RETURN CODES
75 *****************************************************************************/
76
77 /**
78 * Operation successfully ended.
79 */
80 #define FT_SUCCESS 0
81
82 /**
83 * Memory allocation failed.
84 */
85 #define FT_MEMORY_ERROR -1
86
87 /**
88 * Invalid argument.
89 */
90 #define FT_EINVAL -2
91
92 /**
93 * Libfort internal logic error.
94 *
95 * Usually such errors mean that something is wrong in
96 * libfort internal logic and in most of cases cause of
97 * these errors is a library bug.
98 */
99 #define FT_INTERN_ERROR -3
100
101 /**
102 * General error.
103 *
104 * Different errors that do not belong to the group of errors
105 * mentioned above.
106 */
107 #define FT_GEN_ERROR -4
108
109
110 #define FT_IS_SUCCESS(arg) ((arg) >= 0)
111 #define FT_IS_ERROR(arg) ((arg) < 0)
112
113
114
115
116 /**
117 * @cond HELPER_MACROS
118 */
119
120 /*****************************************************************************
121 * Determine compiler
122 *****************************************************************************/
123
124 #if defined(__clang__)
125 #define FT_CLANG_COMPILER
126 #elif defined(__GNUC__)
127 #define FT_GCC_COMPILER
128 #elif defined(_MSC_VER)
129 #define FT_MICROSOFT_COMPILER
130 #else
131 #define FT_UNDEFINED_COMPILER
132 #endif
133
134
135 /*****************************************************************************
136 * Declare inline
137 *****************************************************************************/
138
139 #if defined(__cplusplus)
140 #define FT_INLINE inline
141 #else
142 #define FT_INLINE __inline
143 #endif /* if defined(__cplusplus) */
144
145
146 /*****************************************************************************
147 * C++ needs to know that types and declarations are C, not C++.
148 *****************************************************************************/
149
150 #ifdef __cplusplus
151 # define FT_BEGIN_DECLS extern "C" {
152 # define FT_END_DECLS }
153 #else
154 # define FT_BEGIN_DECLS
155 # define FT_END_DECLS
156 #endif
157
158
159 /*****************************************************************************
160 * Helper macros
161 *****************************************************************************/
162
163 #define FT_STR_2_CAT_(arg1, arg2) \
164 arg1##arg2
165 #define FT_STR_2_CAT(arg1, arg2) \
166 FT_STR_2_CAT_(arg1, arg2)
167
168 /**
169 * @interanl
170 */
171 static FT_INLINE int ft_check_if_string_helper(const char *str)
172 {
173 (void)str;
174 return 0;
175 }
176
177 /**
178 * @interanl
179 */
180 static FT_INLINE int ft_check_if_wstring_helper(const wchar_t *str)
181 {
182 (void)str;
183 return 0;
184 }
185
186 #define FT_NARGS_IMPL_(x1,x2,x3,x4,x5,x6,x7,x8,x9,x10,x11,x12,x13,x14,x15,N,...) N
187 #define FT_EXPAND_(x) x
188 #define FT_PP_NARG_(...) \
189 FT_EXPAND_(FT_NARGS_IMPL_(__VA_ARGS__,15,14,13,12,11,10,9,8,7,6,5,4,3,2,1,0))
190
191 #define FT_CHECK_IF_STR_32(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_31(checker,__VA_ARGS__)))
192 #define FT_CHECK_IF_STR_31(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_30(checker,__VA_ARGS__)))
193 #define FT_CHECK_IF_STR_30(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_29(checker,__VA_ARGS__)))
194 #define FT_CHECK_IF_STR_29(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_28(checker,__VA_ARGS__)))
195 #define FT_CHECK_IF_STR_28(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_27(checker,__VA_ARGS__)))
196 #define FT_CHECK_IF_STR_27(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_26(checker,__VA_ARGS__)))
197 #define FT_CHECK_IF_STR_26(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_25(checker,__VA_ARGS__)))
198 #define FT_CHECK_IF_STR_25(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_24(checker,__VA_ARGS__)))
199 #define FT_CHECK_IF_STR_24(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_23(checker,__VA_ARGS__)))
200 #define FT_CHECK_IF_STR_23(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_22(checker,__VA_ARGS__)))
201 #define FT_CHECK_IF_STR_22(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_21(checker,__VA_ARGS__)))
202 #define FT_CHECK_IF_STR_21(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_20(checker,__VA_ARGS__)))
203 #define FT_CHECK_IF_STR_20(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_19(checker,__VA_ARGS__)))
204 #define FT_CHECK_IF_STR_19(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_18(checker,__VA_ARGS__)))
205 #define FT_CHECK_IF_STR_18(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_17(checker,__VA_ARGS__)))
206 #define FT_CHECK_IF_STR_17(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_16(checker,__VA_ARGS__)))
207 #define FT_CHECK_IF_STR_16(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_15(checker,__VA_ARGS__)))
208 #define FT_CHECK_IF_STR_15(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_14(checker,__VA_ARGS__)))
209 #define FT_CHECK_IF_STR_14(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_13(checker,__VA_ARGS__)))
210 #define FT_CHECK_IF_STR_13(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_12(checker,__VA_ARGS__)))
211 #define FT_CHECK_IF_STR_12(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_11(checker,__VA_ARGS__)))
212 #define FT_CHECK_IF_STR_11(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_10(checker,__VA_ARGS__)))
213 #define FT_CHECK_IF_STR_10(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_9(checker,__VA_ARGS__)))
214 #define FT_CHECK_IF_STR_9(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_8(checker,__VA_ARGS__)))
215 #define FT_CHECK_IF_STR_8(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_7(checker,__VA_ARGS__)))
216 #define FT_CHECK_IF_STR_7(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_6(checker,__VA_ARGS__)))
217 #define FT_CHECK_IF_STR_6(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_5(checker,__VA_ARGS__)))
218 #define FT_CHECK_IF_STR_5(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_4(checker,__VA_ARGS__)))
219 #define FT_CHECK_IF_STR_4(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_3(checker,__VA_ARGS__)))
220 #define FT_CHECK_IF_STR_3(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_2(checker,__VA_ARGS__)))
221 #define FT_CHECK_IF_STR_2(checker,arg,...) (checker(arg),FT_EXPAND_(FT_CHECK_IF_STR_1(checker,__VA_ARGS__)))
222 #define FT_CHECK_IF_STR_1(checker,arg) (checker(arg))
223
224 #define FT_CHECK_IF_ARGS_ARE_STRINGS__(checker,func, ...) \
225 FT_EXPAND_(func(checker,__VA_ARGS__))
226 #define FT_CHECK_IF_ARGS_ARE_STRINGS_(checker,basis, n, ...) \
227 FT_CHECK_IF_ARGS_ARE_STRINGS__(checker,FT_STR_2_CAT_(basis, n), __VA_ARGS__)
228 #define FT_CHECK_IF_ARGS_ARE_STRINGS(...) \
229 FT_CHECK_IF_ARGS_ARE_STRINGS_(ft_check_if_string_helper,FT_CHECK_IF_STR_,FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__)
230
231 #ifdef FT_HAVE_WCHAR
232 #define CHECK_IF_ARGS_ARE_WSTRINGS(...) \
233 FT_CHECK_IF_ARGS_ARE_STRINGS_(ft_check_if_wstring_helper,FT_CHECK_IF_STR_,FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__)
234 #endif
235
236 /**
237 * @endcond
238 */
239
240
241 /*****************************************************************************
242 * Attribute format for argument checking
243 *****************************************************************************/
244
245 #if defined(FT_CLANG_COMPILER) || defined(FT_GCC_COMPILER)
246 #define FT_PRINTF_ATTRIBUTE_FORMAT(string_index, first_to_check) \
247 __attribute__ ((format (printf, string_index, first_to_check)))
248 #else
249 #define FT_PRINTF_ATTRIBUTE_FORMAT(string_index, first_to_check)
250 #endif /* defined(FT_CLANG_COMPILER) || defined(FT_GCC_COMPILER) */
251
252
253 /*****************************************************************************
254 * libfort API
255 *****************************************************************************/
256
257 FT_BEGIN_DECLS
258
259 /**
260 * The main structure of libfort containing information about formatted table.
261 */
262 struct ft_table;
263
264 /**
265 * The main structure of libfort containing information about formatted table.
266 *
267 * ft_table_t objects should be created by a call to ft_create_table and
268 * destroyed with ft_destroy_table.
269 */
270 typedef struct ft_table ft_table_t;
271
272 /**
273 * Create formatted table.
274 *
275 * @return
276 * The pointer to the new allocated ft_table_t, on success. NULL on error.
277 */
278 ft_table_t *ft_create_table(void);
279
280 /**
281 * Destroy formatted table.
282 *
283 * Destroy formatted table and free all resources allocated during table creation
284 * and work with it.
285 *
286 * @param table
287 * Pointer to formatted table previousley created with ft_create_table. If
288 * table is a null pointer, the function does nothing.
289 */
290 void ft_destroy_table(ft_table_t *table);
291
292 /**
293 * Copy formatted table.
294 *
295 * @param table
296 * Pointer to formatted table previousley created with ft_create_table. If
297 * table is a null pointer, the function returns null.
298 * @return
299 * The pointer to the new allocated ft_table_t, on success. NULL on error.
300 */
301 ft_table_t *ft_copy_table(ft_table_t *table);
302
303 /**
304 * Move current position to the first cell of the next line(row).
305 *
306 * @param table
307 * Pointer to formatted table.
308 * @return
309 * - 0: Success; data were written
310 * - (<0): In case of error.
311 * @note
312 * This function can fail only in case FT_STRATEGY_INSERT adding strategy
313 * was set for the table.
314 */
315 int ft_ln(ft_table_t *table);
316
317 /**
318 * Get row number of the current cell.
319 *
320 * @param table
321 * Pointer to formatted table.
322 * @return
323 * Row number of the current cell.
324 */
325 size_t ft_cur_row(const ft_table_t *table);
326
327 /**
328 * Get column number of the current cell.
329 *
330 * @param table
331 * Pointer to formatted table.
332 * @return
333 * Column number of the current cell.
334 */
335 size_t ft_cur_col(const ft_table_t *table);
336
337 /**
338 * Set current cell position.
339 *
340 * Current cell - cell that will be edited with all modifiing functions
341 * (ft_printf, ft_write ...).
342 *
343 * @param table
344 * Pointer to formatted table.
345 * @param row
346 * New row number for the current cell.
347 * @param col
348 * New row number for the current cell.
349 */
350 void ft_set_cur_cell(ft_table_t *table, size_t row, size_t col);
351
352 /**
353 * Check if table is empty.
354 *
355 * @param table
356 * Pointer to the table.
357 * @return
358 * 1 - table is empty
359 * 0 - some data has been inserted
360 */
361 int ft_is_empty(const ft_table_t *table);
362
363 /**
364 * Get number of rows in the table.
365 *
366 * @param table
367 * Pointer to formatted table.
368 * @return
369 * Number of rows in the table.
370 */
371 size_t ft_row_count(const ft_table_t *table);
372
373 /**
374 * Get number of columns in the table.
375 *
376 * @param table
377 * Pointer to formatted table.
378 * @return
379 * Number of columns in the table.
380 */
381 size_t ft_col_count(const ft_table_t *table);
382
383 /**
384 * Erase range of cells.
385 *
386 * Range of cells is determined by 2 points (top-left and bottom-right) (both
387 * ends are included).
388 *
389 * @param table
390 * Pointer to formatted table.
391 * @param top_left_row
392 * Row number of the top left cell in the range.
393 * @param top_left_col
394 * Column number of the top left cell in the range.
395 * @param bottom_right_row
396 * Row number of the bottom right cell in the range.
397 * @param bottom_right_col
398 * Column number of the bottom right cell in the range.
399 * @return
400 * - 0 - Operation was successfully implemented
401 * - (<0): In case of error
402 */
403 int ft_erase_range(ft_table_t *table,
404 size_t top_left_row, size_t top_left_col,
405 size_t bottom_right_row, size_t bottom_right_col);
406
407 #if defined(FT_CLANG_COMPILER) || defined(FT_GCC_COMPILER)
408
409 /**
410 * Write data formatted according to the format string to a variety of table
411 * cells.
412 *
413 * @param table
414 * Pointer to formatted table.
415 * @param fmt
416 * Pointer to a null-terminated multibyte string specifying how to interpret
417 * the data. The format string consists of ordinary characters (except % and |),
418 * which are copied unchanged into the output stream, and conversion
419 * specifications. Conversion specifications are the same as for standard
420 * printf function. Character '|' (which can be changed with
421 * {@link ft_set_default_printf_field_separator}) in the format string is treated as
422 * a cell separator.
423 * @param ...
424 * Arguments specifying data to print. Similarly to standard printf-like
425 * functions if any argument after default conversions is not the type
426 * expected by the corresponding conversion specifier, or if there are fewer
427 * arguments than required by format, the behavior is undefined. If there are
428 * more arguments than required by format, the extraneous arguments are
429 * evaluated and ignored.
430 * @return
431 * - Number of printed cells
432 * - (<0): In case of error
433 */
434 int ft_printf(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3);
435
436 /**
437 * Write data formatted according to the format string to a variety of table
438 * cells and move current position to the first cell of the next line(row).
439 *
440 * @param table
441 * Pointer to formatted table.
442 * @param fmt
443 * Pointer to a null-terminated multibyte string specifying how to interpret
444 * the data. The format string consists of ordinary characters (except % and |),
445 * which are copied unchanged into the output stream, and conversion
446 * specifications. Conversion specifications are the same as for standard
447 * printf function. Character '|' (which can be changed with
448 * {@link ft_set_default_printf_field_separator}) in the format string is treated as
449 * a cell separator.
450 * @param ...
451 * Arguments specifying data to print. Similarly to standard printf-like
452 * functions if any argument after default conversions is not the type
453 * expected by the corresponding conversion specifier, or if there are fewer
454 * arguments than required by format, the behavior is undefined. If there are
455 * more arguments than required by format, the extraneous arguments are
456 * evaluated and ignored.
457 * @return
458 * - Number of printed cells.
459 * - (<0): In case of error.
460 */
461 int ft_printf_ln(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3);
462
463 #else
464
465 /**
466 * @cond IGNORE_DOC
467 */
468
469 int ft_printf_impl(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3);
470 int ft_printf_ln_impl(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3);
471
472 #define ft_printf(table, ...) \
473 (( 0 ? fprintf(stderr, __VA_ARGS__) : 1), ft_printf_impl(table, __VA_ARGS__))
474 #define ft_printf_ln(table, ...) \
475 (( 0 ? fprintf(stderr, __VA_ARGS__) : 1), ft_printf_ln_impl(table, __VA_ARGS__))
476
477 /**
478 * @endcond
479 */
480 #endif
481
482 /**
483 * Set field separator for {@link ft_printf}, {@link ft_printf_ln}
484 * (default separator is '|').
485 *
486 * @param separator
487 * New separator.
488 */
489 void ft_set_default_printf_field_separator(char separator);
490
491
492 /**
493 * Write strings to the table.
494 *
495 * Write specified strings to the same number of consecutive cells in the
496 * current row.
497 *
498 * @param table
499 * Pointer to formatted table.
500 * @param ...
501 * Strings to write.
502 * @return
503 * - 0: Success; data were written
504 * - (<0): In case of error
505 */
506 #define ft_write(table, ...)\
507 (0 ? FT_CHECK_IF_ARGS_ARE_STRINGS(__VA_ARGS__) : ft_nwrite(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__))
508
509 /**
510 * Write strings to the table and go to the next line.
511 *
512 * Write specified strings to the same number of consecutive cells in the
513 * current row and move current position to the first cell of the next
514 * line(row).
515 *
516 * @param table
517 * Pointer to formatted table.
518 * @param ...
519 * Strings to write.
520 * @return
521 * - 0: Success; data were written
522 * - (<0): In case of error
523 */
524 #define ft_write_ln(table, ...)\
525 (0 ? FT_CHECK_IF_ARGS_ARE_STRINGS(__VA_ARGS__) : ft_nwrite_ln(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__))
526
527 /**
528 * Write specified number of strings to the table.
529 *
530 * Write specified number of strings to the same number of consecutive cells in
531 * the current row.
532 *
533 * @note In most cases it is more preferable to use MACRO @ref ft_write instead
534 * of @ref ft_nwrite, which is more safe (@ref ft_write automatically counts the
535 * number of string arguments and at compile check that all passed arguments are
536 * strings).
537 *
538 * @param table
539 * Pointer to formatted table.
540 * @param count
541 * Number of strings to write.
542 * @param cell_content
543 * First string to write.
544 * @param ...
545 * Other strings to write.
546 * @return
547 * - 0: Success; data were written
548 * - (<0): In case of error
549 */
550 int ft_nwrite(ft_table_t *table, size_t count, const char *cell_content, ...);
551
552 /**
553 * Write specified number of strings to the table and go to the next line.
554 *
555 * Write specified number of strings to the same number of consecutive cells
556 * in the current row and move current position to the first cell of the next
557 * line(row).
558 *
559 * @note In most cases it is more preferable to use MACRO @ref ft_write instead
560 * of @ref ft_nwrite, which is more safe (@ref ft_write automatically counts the
561 * number of string arguments and at compile check that all passed arguments are
562 * strings).
563 *
564 * @param table
565 * Pointer to formatted table.
566 * @param count
567 * Number of strings to write.
568 * @param cell_content
569 * First string to write.
570 * @param ...
571 * Other strings to write.
572 * @return
573 * - 0: Success; data were written
574 * - (<0): In case of error
575 */
576 int ft_nwrite_ln(ft_table_t *table, size_t count, const char *cell_content, ...);
577
578
579
580 /**
581 * Write strings from the array to the table.
582 *
583 * Write specified number of strings from the array to the same number of
584 * consecutive cells in the current row.
585 *
586 * @param table
587 * Pointer to formatted table.
588 * @param cols
589 * Number of elements in row_cells.
590 * @param row_cells
591 * Array of strings to write.
592 * @return
593 * - 0: Success; data were written
594 * - (<0): In case of error
595 */
596 int ft_row_write(ft_table_t *table, size_t cols, const char *row_cells[]);
597
598 /**
599 * Write strings from the array to the table and go to the next line.
600 *
601 * Write specified number of strings from the array to the same number of
602 * consecutive cells in the current row and move current position to the first
603 * cell of the next line(row).
604 *
605 * @param table
606 * Pointer to formatted table.
607 * @param cols
608 * Number of elements in row_cells.
609 * @param row_cells
610 * Array of strings to write.
611 * @return
612 * - 0: Success; data were written
613 * - (<0): In case of error
614 */
615 int ft_row_write_ln(ft_table_t *table, size_t cols, const char *row_cells[]);
616
617
618 /**
619 * Write strings from the 2D array to the table.
620 *
621 * Write specified number of strings from the 2D array to the formatted table.
622 *
623 * @param table
624 * Pointer to formatted table.
625 * @param rows
626 * Number of rows in the 2D array.
627 * @param cols
628 * Number of columns in the 2D array.
629 * @param table_cells
630 * 2D array of strings to write.
631 * @return
632 * - 0: Success; data were written
633 * - (<0): In case of error
634 */
635 int ft_table_write(ft_table_t *table, size_t rows, size_t cols, const char *table_cells[]);
636
637 /**
638 * Write strings from the 2D array to the table and go to the next line.
639 *
640 * Write specified number of strings from the 2D array to the formatted table
641 * and move current position to the first cell of the next line(row).
642 *
643 * @param table
644 * Pointer to formatted table.
645 * @param rows
646 * Number of rows in the 2D array.
647 * @param cols
648 * Number of columns in the 2D array.
649 * @param table_cells
650 * 2D array of strings to write.
651 * @return
652 * - 0: Success; data were written
653 * - (<0): In case of error
654 */
655 int ft_table_write_ln(ft_table_t *table, size_t rows, size_t cols, const char *table_cells[]);
656
657
658 /**
659 * Add separator after the current row.
660 *
661 * @param table
662 * Formatted table.
663 * @return
664 * - 0: Success; separator was added.
665 * - (<0): In case of error
666 */
667 int ft_add_separator(ft_table_t *table);
668
669
670 /**
671 * Convert table to string representation.
672 *
673 * ft_table_t has ownership of the returned pointer. So there is no need to
674 * free it. To take ownership user should explicitly copy the returned
675 * string with strdup or similar functions.
676 *
677 * Returned pointer may be later invalidated by:
678 * - Calling ft_destroy_table;
679 * - Other invocations of ft_to_string.
680 *
681 * @param table
682 * Formatted table.
683 * @return
684 * - The pointer to the string representation of formatted table, on success.
685 * - NULL on error.
686 */
687 const char *ft_to_string(const ft_table_t *table);
688
689
690
691
692
693
694
695 /**
696 * Structure describing border appearance.
697 */
698 struct ft_border_chars {
699 const char *top_border_ch;
700 const char *separator_ch;
701 const char *bottom_border_ch;
702 const char *side_border_ch;
703 const char *out_intersect_ch;
704 const char *in_intersect_ch;
705 };
706
707 /**
708 * Structure describing border style.
709 */
710 struct ft_border_style {
711 struct ft_border_chars border_chs;
712 struct ft_border_chars header_border_chs;
713 const char *hor_separator_char;
714 };
715
716 /**
717 * @defgroup BasicStyles
718 * @name Built-in table border styles.
719 * @note Built-in border styles (FT_BASIC_STYLE, FT_BASIC2_STYLE ...) can be
720 * used as arguments for @ref ft_set_border_style and
721 * @ref ft_set_default_border_style, but their fields shouldn't be accessed
722 * directly because implementation doesn't guarantee that these objects are
723 * properly initialized.
724 * @{
725 */
726 extern const struct ft_border_style *const FT_BASIC_STYLE;
727 extern const struct ft_border_style *const FT_BASIC2_STYLE;
728 extern const struct ft_border_style *const FT_SIMPLE_STYLE;
729 extern const struct ft_border_style *const FT_PLAIN_STYLE;
730 extern const struct ft_border_style *const FT_DOT_STYLE;
731 extern const struct ft_border_style *const FT_EMPTY_STYLE;
732 extern const struct ft_border_style *const FT_EMPTY2_STYLE;
733 extern const struct ft_border_style *const FT_SOLID_STYLE;
734 extern const struct ft_border_style *const FT_SOLID_ROUND_STYLE;
735 extern const struct ft_border_style *const FT_NICE_STYLE;
736 extern const struct ft_border_style *const FT_DOUBLE_STYLE;
737 extern const struct ft_border_style *const FT_DOUBLE2_STYLE;
738 extern const struct ft_border_style *const FT_BOLD_STYLE;
739 extern const struct ft_border_style *const FT_BOLD2_STYLE;
740 extern const struct ft_border_style *const FT_FRAME_STYLE;
741 /** @} */
742
743
744
745 /**
746 * Set default border style for all new formatted tables.
747 *
748 * @param style
749 * Pointer to border style.
750 * @return
751 * - 0: Success; default border style was changed.
752 * - (<0): In case of error
753 */
754 int ft_set_default_border_style(const struct ft_border_style *style);
755
756 /**
757 * Set border style for the table.
758 *
759 * @param table
760 * A pointer to the ft_table_t structure.
761 * @param style
762 * Pointer to border style.
763 * @return
764 * - 0: Success; table border style was changed.
765 * - (<0): In case of error
766 */
767 int ft_set_border_style(ft_table_t *table, const struct ft_border_style *style);
768
769
770
771 /**
772 * @name Special macros to define cell position (row and column).
773 * @{
774 */
775 #define FT_ANY_COLUMN (UINT_MAX) /**< Any column (can be used to refer to all cells in a row)*/
776 #define FT_CUR_COLUMN (UINT_MAX - 1) /**< Current column */
777 #define FT_ANY_ROW (UINT_MAX) /**< Any row (can be used to refer to all cells in a column)*/
778 #define FT_CUR_ROW (UINT_MAX - 1) /**< Current row */
779 /** @} */
780
781 #define FT_MAX_ROW_INDEX (UINT_MAX - 2)
782 #define FT_MAX_COL_INDEX (UINT_MAX - 2)
783
784
785 /**
786 * @name Cell properties identifiers.
787 * @{
788 */
789 #define FT_CPROP_MIN_WIDTH (0x01U << 0) /**< Minimum width */
790 #define FT_CPROP_TEXT_ALIGN (0x01U << 1) /**< Text alignment */
791 #define FT_CPROP_TOP_PADDING (0x01U << 2) /**< Top padding for cell content */
792 #define FT_CPROP_BOTTOM_PADDING (0x01U << 3) /**< Bottom padding for cell content */
793 #define FT_CPROP_LEFT_PADDING (0x01U << 4) /**< Left padding for cell content */
794 #define FT_CPROP_RIGHT_PADDING (0x01U << 5) /**< Right padding for cell content */
795 #define FT_CPROP_EMPTY_STR_HEIGHT (0x01U << 6) /**< Height of empty cell */
796 #define FT_CPROP_ROW_TYPE (0x01U << 7) /**< Row type */
797 #define FT_CPROP_CONT_FG_COLOR (0x01U << 8) /**< Cell content foreground text color */
798 #define FT_CPROP_CELL_BG_COLOR (0x01U << 9) /**< Cell background color */
799 #define FT_CPROP_CONT_BG_COLOR (0x01U << 10) /**< Cell content background color */
800 #define FT_CPROP_CELL_TEXT_STYLE (0x01U << 11) /**< Cell text style */
801 #define FT_CPROP_CONT_TEXT_STYLE (0x01U << 12) /**< Cell content text style */
802 #define FT_CPROP_CELL_BG_RGBCOLOR (0x01U << 13) /**< Cell background color */
803 /** @} */
804
805
806 /**
807 * Colors.
808 */
809 enum ft_color {
810 FT_COLOR_DEFAULT = 0, /**< Default color */
811 FT_COLOR_BLACK = 1, /**< Black color*/
812 FT_COLOR_RED = 2, /**< Red color */
813 FT_COLOR_GREEN = 3, /**< Green color */
814 FT_COLOR_YELLOW = 4, /**< Yellow color */
815 FT_COLOR_BLUE = 5, /**< Blue color */
816 FT_COLOR_MAGENTA = 6, /**< Magenta color */
817 FT_COLOR_CYAN = 7, /**< Cyan color */
818 FT_COLOR_LIGHT_GRAY = 8, /**< Light gray color */
819 FT_COLOR_DARK_GRAY = 9, /**< Dark gray color */
820 FT_COLOR_LIGHT_RED = 10, /**< Light red color */
821 FT_COLOR_LIGHT_GREEN = 11, /**< Light green color */
822 FT_COLOR_LIGHT_YELLOW = 12, /**< Light yellow color */
823 FT_COLOR_LIGHT_BLUE = 13, /**< Light blue color */
824 FT_COLOR_LIGHT_MAGENTA = 14, /**< Light magenta color */
825 FT_COLOR_LIGHT_CYAN = 15, /**< Light cyan color */
826 FT_COLOR_LIGHT_WHYTE = 16 /**< Light whyte color */
827 };
828
829 /**
830 * Text styles.
831 */
832 enum ft_text_style {
833 FT_TSTYLE_DEFAULT = (1U << 0), /**< Default style */
834 FT_TSTYLE_BOLD = (1U << 1), /**< Bold */
835 FT_TSTYLE_DIM = (1U << 2), /**< Dim */
836 FT_TSTYLE_ITALIC = (1U << 3), /**< Italic */
837 FT_TSTYLE_UNDERLINED = (1U << 4), /**< Underlined */
838 FT_TSTYLE_BLINK = (1U << 5), /**< Blink */
839 FT_TSTYLE_INVERTED = (1U << 6), /**< Reverse (invert the foreground and background colors) */
840 FT_TSTYLE_HIDDEN = (1U << 7) /**< Hidden (useful for passwords) */
841 };
842
843
844 /**
845 * Alignment of cell content.
846 */
847 enum ft_text_alignment {
848 FT_ALIGNED_LEFT = 0, /**< Align left */
849 FT_ALIGNED_CENTER, /**< Align center */
850 FT_ALIGNED_RIGHT /**< Align right */
851 };
852
853 /**
854 * Type of table row. Determines appearance of row.
855 */
856 enum ft_row_type {
857 FT_ROW_COMMON = 0, /**< Common row */
858 FT_ROW_HEADER /**< Header row */
859 };
860
861 /**
862 * Set default cell property for all new formatted tables.
863 *
864 * @param property
865 * Cell property identifier.
866 * @param value
867 * Cell property value.
868 * @return
869 * - 0: Success; default cell property was changed.
870 * - (<0): In case of error
871 */
872 int ft_set_default_cell_prop(uint32_t property, int value);
873
874 /**
875 * Set property for the specified cell of the table.
876 *
877 * @param table
878 * A pointer to the ft_table_t structure.
879 * @param row
880 * Cell row.
881 * @param col
882 * Cell column.
883 * @param property
884 * Cell property identifier.
885 * @param value
886 * Cell property value.
887 * @return
888 * - 0: Success; cell property was changed.
889 * - (<0): In case of error
890 */
891 int ft_set_cell_prop(ft_table_t *table, size_t row, size_t col, uint32_t property, int value);
892
893
894 /**
895 * @name Table properties identifiers.
896 * @{
897 */
898 #define FT_TPROP_LEFT_MARGIN (0x01U << 0)
899 #define FT_TPROP_TOP_MARGIN (0x01U << 1)
900 #define FT_TPROP_RIGHT_MARGIN (0x01U << 2)
901 #define FT_TPROP_BOTTOM_MARGIN (0x01U << 3)
902 #define FT_TPROP_ADDING_STRATEGY (0x01U << 4)
903 /** @} */
904
905 /**
906 * Adding strategy.
907 *
908 * Determines what happens with old content if current cell is not empty after
909 * adding data to it. Default strategy is FT_STRATEGY_REPLACE.
910 */
911 enum ft_adding_strategy {
912 FT_STRATEGY_REPLACE = 0, /**< Replace old content. */
913 FT_STRATEGY_INSERT /**< Insert new conten. Old content is shifted. */
914 };
915
916
917 /**
918 * Set default table property.
919 *
920 * @param property
921 * Table property identifier.
922 * @param value
923 * Table property value.
924 * @return
925 * - 0: Success; default table property was changed.
926 * - (<0): In case of error
927 */
928 int ft_set_default_tbl_prop(uint32_t property, int value);
929
930 /**
931 * Set table property.
932 *
933 * @param table
934 * A pointer to the ft_table_t structure.
935 * @param property
936 * Table property identifier.
937 * @param value
938 * Table property value.
939 * @return
940 * - 0: Success; default table property was changed.
941 * - (<0): In case of error
942 */
943 int ft_set_tbl_prop(ft_table_t *table, uint32_t property, int value);
944
945
946 /**
947 * Set column span for the specified cell of the table.
948 *
949 * @param table
950 * A pointer to the ft_table_t structure.
951 * @param row
952 * Cell row.
953 * @param col
954 * Cell column.
955 * @param hor_span
956 * Column span.
957 * @return
958 * - 0: Success; cell span was changed.
959 * - (<0): In case of error
960 */
961 int ft_set_cell_span(ft_table_t *table, size_t row, size_t col, size_t hor_span);
962
963
964 /**
965 * Set functions for memory allocation and deallocation to be used instead of
966 * standard ones.
967 *
968 * @param f_malloc
969 * Pointer to a function for memory allocation that should be used instead of
970 * malloc.
971 * @param f_free
972 * Pointer to a function for memory deallocation that should be used instead
973 * of free.
974 * @note
975 * To return memory allocation/deallocation functions to their standard values
976 * set f_malloc and f_free to NULL.
977 */
978 void ft_set_memory_funcs(void *(*f_malloc)(size_t size), void (*f_free)(void *ptr));
979
980
981 /**
982 * Return string describing the `error_code`.
983 *
984 * @param error_code
985 * Error code returned by the library.
986 * @return
987 * String describing the error.
988 */
989 const char *ft_strerror(int error_code);
990
991
992
993 #ifdef FT_HAVE_WCHAR
994
995
996 int ft_wprintf(ft_table_t *table, const wchar_t *fmt, ...);
997 int ft_wprintf_ln(ft_table_t *table, const wchar_t *fmt, ...);
998
999
1000 #define ft_wwrite(table, ...)\
1001 (0 ? CHECK_IF_ARGS_ARE_WSTRINGS(__VA_ARGS__) : ft_nwwrite(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__))
1002 #define ft_wwrite_ln(table, ...)\
1003 (0 ? CHECK_IF_ARGS_ARE_WSTRINGS(__VA_ARGS__) : ft_nwwrite_ln(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__))
1004 int ft_nwwrite(ft_table_t *table, size_t n, const wchar_t *cell_content, ...);
1005 int ft_nwwrite_ln(ft_table_t *table, size_t n, const wchar_t *cell_content, ...);
1006
1007 int ft_row_wwrite(ft_table_t *table, size_t cols, const wchar_t *row_cells[]);
1008 int ft_row_wwrite_ln(ft_table_t *table, size_t cols, const wchar_t *row_cells[]);
1009
1010 int ft_table_wwrite(ft_table_t *table, size_t rows, size_t cols, const wchar_t *table_cells[]);
1011 int ft_table_wwrite_ln(ft_table_t *table, size_t rows, size_t cols, const wchar_t *table_cells[]);
1012
1013 const wchar_t *ft_to_wstring(const ft_table_t *table);
1014 #endif
1015
1016
1017
1018 #ifdef FT_HAVE_UTF8
1019 #define ft_u8write(table, ...)\
1020 (ft_u8nwrite(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__))
1021 #define ft_u8write_ln(table, ...)\
1022 (ft_u8nwrite_ln(table, FT_PP_NARG_(__VA_ARGS__), __VA_ARGS__))
1023 int ft_u8nwrite(ft_table_t *table, size_t n, const void *cell_content, ...);
1024 int ft_u8nwrite_ln(ft_table_t *table, size_t n, const void *cell_content, ...);
1025
1026 int ft_u8printf(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3);
1027 int ft_u8printf_ln(ft_table_t *table, const char *fmt, ...) FT_PRINTF_ATTRIBUTE_FORMAT(2, 3);
1028
1029 const void *ft_to_u8string(const ft_table_t *table);
1030
1031 /**
1032 * Set custom function to compute visible width of UTF-8 string.
1033 *
1034 * libfort internally has a very simple logic to compute visible width of UTF-8
1035 * strings. It considers that each codepoint will occupy one position on the
1036 * terminal in case of monowidth font (some east asians wide and fullwidth
1037 * characters (see http://www.unicode.org/reports/tr11/tr11-33.html) will occupy
1038 * 2 positions). This logic is very simple and covers wide range of cases. But
1039 * obviously there a lot of cases when it is not sufficient. In such cases user
1040 * should use some external libraries and provide an appropriate function to
1041 * libfort.
1042 *
1043 * @param u8strwid
1044 * User provided function to evaluate width of UTF-8 string ( beg - start of
1045 * UTF-8 string, end - end of UTF-8 string (not included), width - pointer to
1046 * the result). If function succeed it should return 0, otherwise some non-
1047 * zero value. If function returns nonzero value libfort fallbacks to default
1048 * internal algorithm.
1049 */
1050 void ft_set_u8strwid_func(int (*u8strwid)(const void *beg, const void *end, size_t *width));
1051
1052 #endif /* FT_HAVE_UTF8 */
1053
1054
1055 FT_END_DECLS
1056
1057 #endif /* LIBFORT_H */