Format.h (12133B)
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 "zydis/Zycore/Status.h" 36 #include "zydis/Zycore/String.h" 37 #include "zydis/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 (x == (-0x7fffffffffffffff - 1)) 65 { 66 return 0x8000000000000000u; 67 } 68 69 return (ZyanU64)(x < 0 ? -x : x); 70 } 71 72 /* ---------------------------------------------------------------------------------------------- */ 73 /* Insertion */ 74 /* ---------------------------------------------------------------------------------------------- */ 75 76 /** 77 * Inserts formatted text in the destination string at the given `index`. 78 * 79 * @param string The destination string. 80 * @param index The insert index. 81 * @param format The format string. 82 * @param ... The format arguments. 83 * 84 * @return A zyan status code. 85 * 86 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 87 * `ZyanString` instance. 88 */ 89 ZYAN_PRINTF_ATTR(3, 4) 90 ZYCORE_EXPORT ZyanStatus ZyanStringInsertFormat(ZyanString* string, ZyanUSize index, 91 const char* format, ...); 92 93 /* ---------------------------------------------------------------------------------------------- */ 94 95 /** 96 * Formats the given unsigned ordinal `value` to its decimal text-representation and 97 * inserts it to the `string`. 98 * 99 * @param string A pointer to the `ZyanString` instance. 100 * @param index The insert index. 101 * @param value The value. 102 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 103 * less than the `padding_length`. 104 * 105 * @return A zyan status code. 106 * 107 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 108 * `ZyanString` instance. 109 */ 110 ZYCORE_EXPORT ZyanStatus ZyanStringInsertDecU(ZyanString* string, ZyanUSize index, ZyanU64 value, 111 ZyanU8 padding_length); 112 113 /** 114 * Formats the given signed ordinal `value` to its decimal text-representation and 115 * inserts it to the `string`. 116 * 117 * @param string A pointer to the `ZyanString` instance. 118 * @param index The insert index. 119 * @param value The value. 120 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 121 * less than the `padding_length`. 122 * @param force_sign Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. 123 * @param prefix The string to use as prefix or `ZYAN_NULL`, if not needed. 124 * 125 * @return A zyan status code. 126 * 127 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 128 * `ZyanString` instance. 129 */ 130 ZYCORE_EXPORT ZyanStatus ZyanStringInsertDecS(ZyanString* string, ZyanUSize index, ZyanI64 value, 131 ZyanU8 padding_length, ZyanBool force_sign, const ZyanString* prefix); 132 133 /** 134 * Formats the given unsigned ordinal `value` to its hexadecimal text-representation and 135 * inserts it to the `string`. 136 * 137 * @param string A pointer to the `ZyanString` instance. 138 * @param index The insert index. 139 * @param value The value. 140 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 141 * less than the `padding_length`. 142 * @param uppercase Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase 143 * ones ('a'-'f'). 144 * 145 * @return A zyan status code. 146 * 147 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 148 * `ZyanString` instance. 149 */ 150 ZYCORE_EXPORT ZyanStatus ZyanStringInsertHexU(ZyanString* string, ZyanUSize index, ZyanU64 value, 151 ZyanU8 padding_length, ZyanBool uppercase); 152 153 /** 154 * Formats the given signed ordinal `value` to its hexadecimal text-representation and 155 * inserts it to the `string`. 156 * 157 * @param string A pointer to the `ZyanString` instance. 158 * @param index The insert index. 159 * @param value The value. 160 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 161 * less than the `padding_length`. 162 * @param uppercase Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase 163 * ones ('a'-'f'). 164 * @param force_sign Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. 165 * @param prefix The string to use as prefix or `ZYAN_NULL`, if not needed. 166 * 167 * @return A zyan status code. 168 * 169 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 170 * `ZyanString` instance. 171 */ 172 ZYCORE_EXPORT ZyanStatus ZyanStringInsertHexS(ZyanString* string, ZyanUSize index, ZyanI64 value, 173 ZyanU8 padding_length, ZyanBool uppercase, ZyanBool force_sign, const ZyanString* prefix); 174 175 /* ---------------------------------------------------------------------------------------------- */ 176 /* Appending */ 177 /* ---------------------------------------------------------------------------------------------- */ 178 179 #ifndef ZYAN_NO_LIBC 180 181 /** 182 * Appends formatted text to the destination string. 183 * 184 * @param string The destination string. 185 * @param format The format string. 186 * @param ... The format arguments. 187 * 188 * @return A zyan status code. 189 * 190 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 191 * `ZyanString` instance. 192 */ 193 ZYAN_PRINTF_ATTR(2, 3) 194 ZYCORE_EXPORT ZYAN_REQUIRES_LIBC ZyanStatus ZyanStringAppendFormat( 195 ZyanString* string, const char* format, ...); 196 197 #endif // ZYAN_NO_LIBC 198 199 /* ---------------------------------------------------------------------------------------------- */ 200 201 /** 202 * Formats the given unsigned ordinal `value` to its decimal text-representation and 203 * appends it to the `string`. 204 * 205 * @param string A pointer to the `ZyanString` instance. 206 * @param value The value. 207 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 208 * less than the `padding_length`. 209 * 210 * @return A zyan status code. 211 * 212 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 213 * `ZyanString` instance. 214 */ 215 ZYCORE_EXPORT ZyanStatus ZyanStringAppendDecU(ZyanString* string, ZyanU64 value, 216 ZyanU8 padding_length); 217 218 /** 219 * Formats the given signed ordinal `value` to its decimal text-representation and 220 * appends it to the `string`. 221 * 222 * @param string A pointer to the `ZyanString` instance. 223 * @param value The value. 224 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 225 * less than the `padding_length`. 226 * @param force_sign Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. 227 * @param prefix The string to use as prefix or `ZYAN_NULL`, if not needed. 228 * 229 * @return A zyan status code. 230 * 231 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 232 * `ZyanString` instance. 233 */ 234 ZYCORE_EXPORT ZyanStatus ZyanStringAppendDecS(ZyanString* string, ZyanI64 value, 235 ZyanU8 padding_length, ZyanBool force_sign, const ZyanStringView* prefix); 236 237 /** 238 * Formats the given unsigned ordinal `value` to its hexadecimal text-representation and 239 * appends it to the `string`. 240 * 241 * @param string A pointer to the `ZyanString` instance. 242 * @param value The value. 243 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 244 * less than the `padding_length`. 245 * @param uppercase Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase 246 * ones ('a'-'f'). 247 * 248 * @return A zyan status code. 249 * 250 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 251 * `ZyanString` instance. 252 */ 253 ZYCORE_EXPORT ZyanStatus ZyanStringAppendHexU(ZyanString* string, ZyanU64 value, 254 ZyanU8 padding_length, ZyanBool uppercase); 255 256 /** 257 * Formats the given signed ordinal `value` to its hexadecimal text-representation and 258 * appends it to the `string`. 259 * 260 * @param string A pointer to the `ZyanString` instance. 261 * @param value The value. 262 * @param padding_length Padds the converted value with leading zeros, if the number of chars is 263 * less than the `padding_length`. 264 * @param uppercase Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase 265 * ones ('a'-'f'). 266 * @param force_sign Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. 267 * @param prefix The string to use as prefix or `ZYAN_NULL`, if not needed. 268 * 269 * @return A zyan status code. 270 * 271 * This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified 272 * `ZyanString` instance. 273 */ 274 ZYCORE_EXPORT ZyanStatus ZyanStringAppendHexS(ZyanString* string, ZyanI64 value, 275 ZyanU8 padding_length, ZyanBool uppercase, ZyanBool force_sign, const ZyanStringView* prefix); 276 277 /* ---------------------------------------------------------------------------------------------- */ 278 279 /* ============================================================================================== */ 280 281 #ifdef __cplusplus 282 } 283 #endif 284 285 #endif // ZYCORE_FORMAT_H