1 /*************************************************************************************************** 2 3 Zyan Core Library (Zycore-C) 4 5 Original Author : Florian Bernd 6 7 * Permission is hereby granted, free of charge, to any person obtaining a copy 8 * of this software and associated documentation files (the "Software"), to deal 9 * in the Software without restriction, including without limitation the rights 10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 * copies of the Software, and to permit persons to whom the Software is 12 * furnished to do so, subject to the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be included in all 15 * copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 * SOFTWARE. 24 25 ***************************************************************************************************/ 26 27 /** 28 * @file 29 * Provides helper functions for performant number to string conversion. 30 */ 31 32 #ifndef ZYCORE_FORMAT_H 33 #define ZYCORE_FORMAT_H 34 35 #include <Zycore/Status.h> 36 #include <Zycore/String.h> 37 #include <Zycore/Types.h> 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /* ============================================================================================== */ 44 /* Exported functions */ 45 /* ============================================================================================== */ 46 47 /* ---------------------------------------------------------------------------------------------- */ 48 /* Helpers */ 49 /* ---------------------------------------------------------------------------------------------- */ 50 51 /** 52 * Get the absolute value of a 64 bit int. 53 * 54 * @param x The value to process. 55 * @return The absolute, unsigned value. 56 * 57 * This gracefully deals with the special case of `x` being `INT_MAX`. 58 */ 59 ZYAN_INLINE ZyanU64 ZyanAbsI64(ZyanI64 x) 60 { 61 // INT_MIN special case. Can't use the value directly because GCC thinks 62 // it's too big for an INT64 literal, however is perfectly happy to accept 63 // this expression. This is also hit INT64_MIN is defined in `stdint.h`. 64 #if defined(__GNUC__) && (__GNUC__ >= 4) 65 if (x == (-0x7fffffffffffffff - 1)) 66 { 67 return 0x8000000000000000u; 68 } 69 #endif 70 71 return (ZyanU64)(x < 0 ? -x : x); 72 } 73 74 /* ---------------------------------------------------------------------------------------------- */ 75 /* Insertion */ 76 /* ---------------------------------------------------------------------------------------------- */ 77 78 /** 79 * Inserts formatted text in the destination string at the given `index`. 80 * 81 * @param string The destination string. 82 * @param index The insert index. 83 * @param format The format string. 84 * @param ... The format arguments. 85 * 86 * @return A zyan status code. 87 * 88 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 89 * `ZyanString` instance. 90 */ 91 ZYAN_PRINTF_ATTR(3, 4) 92 ZYCORE_EXPORT ZyanStatus ZyanStringInsertFormat(ZyanString* string, ZyanUSize index, 93 const char* format, ...); 94 95 /* ---------------------------------------------------------------------------------------------- */ 96 97 /** 98 * Formats the given unsigned ordinal `value` to its decimal text-representation and 99 * inserts it to the `string`. 100 * 101 * @param string A pointer to the `ZyanString` instance. 102 * @param index The insert index. 103 * @param value The value. 104 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 105 * less than the `padding_length`. 106 * 107 * @return A zyan status code. 108 * 109 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 110 * `ZyanString` instance. 111 */ 112 ZYCORE_EXPORT ZyanStatus ZyanStringInsertDecU(ZyanString* string, ZyanUSize index, ZyanU64 value, 113 ZyanU8 padding_length); 114 115 /** 116 * Formats the given signed ordinal `value` to its decimal text-representation and 117 * inserts it to the `string`. 118 * 119 * @param string A pointer to the `ZyanString` instance. 120 * @param index The insert index. 121 * @param value The value. 122 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 123 * less than the `padding_length`. 124 * @param force_sign Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. 125 * @param prefix The string to use as prefix or `ZYAN_NULL`, if not needed. 126 * 127 * @return A zyan status code. 128 * 129 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 130 * `ZyanString` instance. 131 */ 132 ZYCORE_EXPORT ZyanStatus ZyanStringInsertDecS(ZyanString* string, ZyanUSize index, ZyanI64 value, 133 ZyanU8 padding_length, ZyanBool force_sign, const ZyanString* prefix); 134 135 /** 136 * Formats the given unsigned ordinal `value` to its hexadecimal text-representation and 137 * inserts it to the `string`. 138 * 139 * @param string A pointer to the `ZyanString` instance. 140 * @param index The insert index. 141 * @param value The value. 142 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 143 * less than the `padding_length`. 144 * @param uppercase Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase 145 * ones ('a'-'f'). 146 * 147 * @return A zyan status code. 148 * 149 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 150 * `ZyanString` instance. 151 */ 152 ZYCORE_EXPORT ZyanStatus ZyanStringInsertHexU(ZyanString* string, ZyanUSize index, ZyanU64 value, 153 ZyanU8 padding_length, ZyanBool uppercase); 154 155 /** 156 * Formats the given signed ordinal `value` to its hexadecimal text-representation and 157 * inserts it to the `string`. 158 * 159 * @param string A pointer to the `ZyanString` instance. 160 * @param index The insert index. 161 * @param value The value. 162 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 163 * less than the `padding_length`. 164 * @param uppercase Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase 165 * ones ('a'-'f'). 166 * @param force_sign Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. 167 * @param prefix The string to use as prefix or `ZYAN_NULL`, if not needed. 168 * 169 * @return A zyan status code. 170 * 171 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 172 * `ZyanString` instance. 173 */ 174 ZYCORE_EXPORT ZyanStatus ZyanStringInsertHexS(ZyanString* string, ZyanUSize index, ZyanI64 value, 175 ZyanU8 padding_length, ZyanBool uppercase, ZyanBool force_sign, const ZyanString* prefix); 176 177 /* ---------------------------------------------------------------------------------------------- */ 178 /* Appending */ 179 /* ---------------------------------------------------------------------------------------------- */ 180 181 #ifndef ZYAN_NO_LIBC 182 183 /** 184 * Appends formatted text to the destination string. 185 * 186 * @param string The destination string. 187 * @param format The format string. 188 * @param ... The format arguments. 189 * 190 * @return A zyan status code. 191 * 192 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 193 * `ZyanString` instance. 194 */ 195 ZYAN_PRINTF_ATTR(2, 3) 196 ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanStringAppendFormat( 197 ZyanString* string, const char* format, ...); 198 199 #endif // ZYAN_NO_LIBC 200 201 /* ---------------------------------------------------------------------------------------------- */ 202 203 /** 204 * Formats the given unsigned ordinal `value` to its decimal text-representation and 205 * appends it to the `string`. 206 * 207 * @param string A pointer to the `ZyanString` instance. 208 * @param value The value. 209 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 210 * less than the `padding_length`. 211 * 212 * @return A zyan status code. 213 * 214 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 215 * `ZyanString` instance. 216 */ 217 ZYCORE_EXPORT ZyanStatus ZyanStringAppendDecU(ZyanString* string, ZyanU64 value, 218 ZyanU8 padding_length); 219 220 /** 221 * Formats the given signed ordinal `value` to its decimal text-representation and 222 * appends it to the `string`. 223 * 224 * @param string A pointer to the `ZyanString` instance. 225 * @param value The value. 226 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 227 * less than the `padding_length`. 228 * @param force_sign Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. 229 * @param prefix The string to use as prefix or `ZYAN_NULL`, if not needed. 230 * 231 * @return A zyan status code. 232 * 233 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 234 * `ZyanString` instance. 235 */ 236 ZYCORE_EXPORT ZyanStatus ZyanStringAppendDecS(ZyanString* string, ZyanI64 value, 237 ZyanU8 padding_length, ZyanBool force_sign, const ZyanStringView* prefix); 238 239 /** 240 * Formats the given unsigned ordinal `value` to its hexadecimal text-representation and 241 * appends it to the `string`. 242 * 243 * @param string A pointer to the `ZyanString` instance. 244 * @param value The value. 245 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 246 * less than the `padding_length`. 247 * @param uppercase Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase 248 * ones ('a'-'f'). 249 * 250 * @return A zyan status code. 251 * 252 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 253 * `ZyanString` instance. 254 */ 255 ZYCORE_EXPORT ZyanStatus ZyanStringAppendHexU(ZyanString* string, ZyanU64 value, 256 ZyanU8 padding_length, ZyanBool uppercase); 257 258 /** 259 * Formats the given signed ordinal `value` to its hexadecimal text-representation and 260 * appends it to the `string`. 261 * 262 * @param string A pointer to the `ZyanString` instance. 263 * @param value The value. 264 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 265 * less than the `padding_length`. 266 * @param uppercase Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase 267 * ones ('a'-'f'). 268 * @param force_sign Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. 269 * @param prefix The string to use as prefix or `ZYAN_NULL`, if not needed. 270 * 271 * @return A zyan status code. 272 * 273 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 274 * `ZyanString` instance. 275 */ 276 ZYCORE_EXPORT ZyanStatus ZyanStringAppendHexS(ZyanString* string, ZyanI64 value, 277 ZyanU8 padding_length, ZyanBool uppercase, ZyanBool force_sign, const ZyanStringView* prefix); 278 279 /* ---------------------------------------------------------------------------------------------- */ 280 281 /* ============================================================================================== */ 282 283 #ifdef __cplusplus 284 } 285 #endif 286 287 #endif // ZYCORE_FORMAT_H 288