--- name: "Format.h" section: "3" platform: "linux" package: "libzycore-doc" version: "1.5.2-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Format.h" --- # Format.h(3) ## NAME include/Zycore/Format.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ ### Functions ZYAN\_INLINE ZyanU64 **ZyanAbsI64** (ZyanI64 x)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInsertFormat** (**ZyanString** \*string, ZyanUSize index, const char \*format,...)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInsertDecU** (**ZyanString** \*string, ZyanUSize index, ZyanU64 value, ZyanU8 padding\_length)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInsertDecS** (**ZyanString** \*string, ZyanUSize index, ZyanI64 value, ZyanU8 padding\_length, **ZyanBool** force\_sign, const **ZyanString** \*prefix)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInsertHexU** (**ZyanString** \*string, ZyanUSize index, ZyanU64 value, ZyanU8 padding\_length, **ZyanBool** uppercase)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringInsertHexS** (**ZyanString** \*string, ZyanUSize index, ZyanI64 value, ZyanU8 padding\_length, **ZyanBool** uppercase, **ZyanBool** force\_sign, const **ZyanString** \*prefix)\ **ZYCORE\_EXPORT** **ZYAN\_REQUIRES\_LIBC** **ZyanStatus** **ZyanStringAppendFormat** (**ZyanString** \*string, const char \*format,...)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringAppendDecU** (**ZyanString** \*string, ZyanU64 value, ZyanU8 padding\_length)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringAppendDecS** (**ZyanString** \*string, ZyanI64 value, ZyanU8 padding\_length, **ZyanBool** force\_sign, const **ZyanStringView** \*prefix)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringAppendHexU** (**ZyanString** \*string, ZyanU64 value, ZyanU8 padding\_length, **ZyanBool** uppercase)\ **ZYCORE\_EXPORT** **ZyanStatus** **ZyanStringAppendHexS** (**ZyanString** \*string, ZyanI64 value, ZyanU8 padding\_length, **ZyanBool** uppercase, **ZyanBool** force\_sign, const **ZyanStringView** \*prefix)\ ## Detailed Description Provides helper functions for performant number to string conversion. ## Function Documentation ### ZYAN\_INLINE ZyanU64 ZyanAbsI64 (ZyanI64 x) Get the absolute value of a 64 bit int. **Parameters** *x* The value to process. **Returns** The absolute, unsigned value. This gracefully deals with the special case of `x` being `INT_MAX`. ### ZYCORE\_EXPORT ZyanStatus ZyanStringAppendDecS (ZyanString \* string, ZyanI64 value, ZyanU8 padding\_length, ZyanBool force\_sign, const ZyanStringView \* prefix) Formats the given signed ordinal `value` to its decimal text-representation and appends it to the `string`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *value* The value. \ *padding\_length* Padds the converted value with leading zeros, if the number of chars is less than the `padding_length`. \ *force\_sign* Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. \ *prefix* The string to use as prefix or `ZYAN_NULL`, if not needed. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringAppendDecU (ZyanString \* string, ZyanU64 value, ZyanU8 padding\_length) Formats the given unsigned ordinal `value` to its decimal text-representation and appends it to the `string`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *value* The value. \ *padding\_length* Padds the converted value with leading zeros, if the number of chars is less than the `padding_length`. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZYAN\_REQUIRES\_LIBC ZyanStatus ZyanStringAppendFormat (ZyanString \* string, const char \* format, ...) Appends formatted text to the destination string. **Parameters** *string* The destination string. \ *format* The format string. \ *...* The format arguments. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringAppendHexS (ZyanString \* string, ZyanI64 value, ZyanU8 padding\_length, ZyanBool uppercase, ZyanBool force\_sign, const ZyanStringView \* prefix) Formats the given signed ordinal `value` to its hexadecimal text-representation and appends it to the `string`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *value* The value. \ *padding\_length* Padds the converted value with leading zeros, if the number of chars is less than the `padding_length`. \ *uppercase* Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase ones ('a'-'f'). \ *force\_sign* Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. \ *prefix* The string to use as prefix or `ZYAN_NULL`, if not needed. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringAppendHexU (ZyanString \* string, ZyanU64 value, ZyanU8 padding\_length, ZyanBool uppercase) Formats the given unsigned ordinal `value` to its hexadecimal text-representation and appends it to the `string`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *value* The value. \ *padding\_length* Padds the converted value with leading zeros, if the number of chars is less than the `padding_length`. \ *uppercase* Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase ones ('a'-'f'). **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInsertDecS (ZyanString \* string, ZyanUSize index, ZyanI64 value, ZyanU8 padding\_length, ZyanBool force\_sign, const ZyanString \* prefix) Formats the given signed ordinal `value` to its decimal text-representation and inserts it to the `string`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The insert index. \ *value* The value. \ *padding\_length* Padds the converted value with leading zeros, if the number of chars is less than the `padding_length`. \ *force\_sign* Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. \ *prefix* The string to use as prefix or `ZYAN_NULL`, if not needed. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInsertDecU (ZyanString \* string, ZyanUSize index, ZyanU64 value, ZyanU8 padding\_length) Formats the given unsigned ordinal `value` to its decimal text-representation and inserts it to the `string`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The insert index. \ *value* The value. \ *padding\_length* Padds the converted value with leading zeros, if the number of chars is less than the `padding_length`. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInsertFormat (ZyanString \* string, ZyanUSize index, const char \* format, ...) Inserts formatted text in the destination string at the given `index`. **Parameters** *string* The destination string. \ *index* The insert index. \ *format* The format string. \ *...* The format arguments. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInsertHexS (ZyanString \* string, ZyanUSize index, ZyanI64 value, ZyanU8 padding\_length, ZyanBool uppercase, ZyanBool force\_sign, const ZyanString \* prefix) Formats the given signed ordinal `value` to its hexadecimal text-representation and inserts it to the `string`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The insert index. \ *value* The value. \ *padding\_length* Padds the converted value with leading zeros, if the number of chars is less than the `padding_length`. \ *uppercase* Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase ones ('a'-'f'). \ *force\_sign* Set `ZYAN_TRUE`, to force printing of the `+` sign for positive numbers. \ *prefix* The string to use as prefix or `ZYAN_NULL`, if not needed. **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ### ZYCORE\_EXPORT ZyanStatus ZyanStringInsertHexU (ZyanString \* string, ZyanUSize index, ZyanU64 value, ZyanU8 padding\_length, ZyanBool uppercase) Formats the given unsigned ordinal `value` to its hexadecimal text-representation and inserts it to the `string`. **Parameters** *string* A pointer to the `ZyanString` instance. \ *index* The insert index. \ *value* The value. \ *padding\_length* Padds the converted value with leading zeros, if the number of chars is less than the `padding_length`. \ *uppercase* Set `ZYAN_TRUE` to use uppercase letters ('A'-'F') instead of lowercase ones ('a'-'f'). **Returns** A zyan status code. This function will fail, if the `ZYAN_STRING_IS_IMMUTABLE` flag is set for the specified `ZyanString` instance. ## Author Generated automatically by Doxygen for Zycore from the source code.