1 /**************************************************************************** 2 * Copyright (C) 2008 by Matteo Franchin * 3 * * 4 * This file is part of Box. * 5 * * 6 * Box is free software: you can redistribute it and/or modify it * 7 * under the terms of the GNU Lesser General Public License as published * 8 * by the Free Software Foundation, either version 3 of the License, or * 9 * (at your option) any later version. * 10 * * 11 * Box is distributed in the hope that it will be useful, * 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 14 * GNU Lesser General Public License for more details. * 15 * * 16 * You should have received a copy of the GNU Lesser General Public * 17 * License along with Box. If not, see <http://www.gnu.org/licenses/>. * 18 ****************************************************************************/ 19 20 /** 21 * @file print.h 22 * @brief A simplified version of sprintf with automatic memory management. 23 * 24 * This file provides the function print, which is a simplified version 25 * of the function sprintf, but offers a number of advantages over it. 26 * Memory is managed automatically, the Name data type is supported 27 * with the specified %N, string deallocation is allowed with %~s. 28 */ 29 30 #ifndef _BOX_PRINT_H 31 # define _BOX_PRINT_H 32 33 # include <stdarg.h> 34 35 # include <box/mem.h> 36 37 # define BOX_PRINT_BUF_SIZE 512 38 39 /** 40 * To be called when exiting, to release memory allocated by Box_Print(). 41 */ 42 BOXEXPORT void 43 Box_Print_Finish(void); 44 45 /** 46 * @brief An improved version of sprintf used internally by the compiler. 47 * 48 * An improved version of sprintf, with a number of desirable features: 49 * 50 * - handles memory in a nice way: the user does not need to allocate/free 51 * the memory or to worry about buffer overflow when using the %s 52 * specifier to write substrings. Usage is as follows: 53 * 54 * @code 55 * const char *msg = Box_Print("string = %s, number = %d\n", "Hi!", 12); 56 * // No need to call the free(...) function. The user mustn't do it! 57 * @endcode 58 * 59 * - has additional format specifiers to handle objects like #BoxName or 60 * #BoxType. 61 * 62 * - has %~s to print a string and deallocate it with free(...). 63 * 64 * @code 65 * msg = Box_Print("%~s", Box_Mem_Strdup("allocated string")); 66 * @endcode 67 */ 68 BOXEXPORT const char * 69 Box_Print(const char *fmt, ...); 70 71 # define printdup(...) Box_Mem_Strdup(Box_Print(__VA_ARGS__)) 72 # define Box_SPrintF(...) Box_Mem_Strdup(Box_Print(__VA_ARGS__)) 73 74 #endif /* _BOX_PRINT_H */ 75