Runtime backend that packs arguments and executes compiled format records. More...

#include <writer.hpp>

Data Structures
class	ArgumentReader
	Sequential reader for the packed runtime argument byte blob. More...

class	CodeReader
	Sequential reader for the compiled record stream. More...

struct	DecimalScale

class	Executor
	Per-sink bytecode executor specialized by the compiled format profile. More...

struct	Spec
	Runtime view of one decoded field specification byte group. More...

Static Public Member Functions
template<typename Sink , typename Format , auto ArgumentOrder, typename... Args> requires OutputSink<Sink> && CompiledFormat<std::remove_cvref_t<Format>>
static ErrorCode	RunArgumentOrder (Sink &sink, const Format &, Args &&... args)
	Runs one compiled format whose runtime pack order is provided separately from the call-site argument order.

Private Member Functions
template<OutputSink Sink, FormatProfile Profile>
	__attribute__ ((noinline)) static ErrorCode Execute(Sink &sink

template<OutputSink Sink, auto ArgumentInfoList, auto ArgumentOrder, FormatProfile Profile, typename... Args>
	__attribute__ ((noinline)) static ErrorCode RunTaggedArgumentOrder(Sink &sink

Static Private Member Functions
static constexpr bool	HasFlag (uint8_t flags, uint8_t bit)
	Tests whether one decoded field-spec bit is set.

template<typename T >
static constexpr std::string_view	ToStringView (const T &text)

template<FormatPackKind pack, typename T >
static constexpr auto	PackValue (T &&value)
	Normalizes one matched C++ argument into the packed runtime storage kind required by one compiled argument slot.

template<typename T >
static void	StoreArgument (uint8_t *&out, const T &value)

template<auto ArgumentInfoList>
static consteval size_t	PackedArgumentBytes ()

template<auto ArgumentInfoList, auto ArgumentOrder, typename Tuple >
static void	StoreArgumentsOrdered (uint8_t *&out, Tuple &tuple)

template<std::unsigned_integral UInt>
static size_t	AppendUnsigned (char *out, UInt value, uint8_t base, bool upper_case)

static size_t	AppendSmallUnsigned (char *out, uint8_t value)

static constexpr size_t	FieldPadding (uint8_t width, size_t payload_size)
	Returns the padding width needed to expand one payload to the requested field width. / 返回把某段载荷扩展到目标字段宽度所需的填充长度

static constexpr size_t	IntegerPrecisionZeros (const Spec &spec, size_t digit_count)
	Returns the extra leading-zero count introduced by integer precision. / 返回整数精度引入的额外前导零个数

static constexpr uint8_t	IntegerBase (FormatType type)
	Returns the integer radix selected by one unsigned runtime type. / 返回某个无符号运行期类型对应的整数进制

static constexpr bool	IntegerUpperCase (FormatType type)
	Returns whether one unsigned runtime type should emit uppercase hex digits. / 判断某个无符号运行期类型是否应输出大写十六进制数字

template<std::unsigned_integral UInt>
static constexpr std::string_view	IntegerPrefix (FormatType type, const Spec &spec, UInt value)
	Returns the alternate-form prefix carried outside the digit payload. / 返回放在数字载荷之外的备用格式前缀

template<std::unsigned_integral UInt>
static size_t	ApplyAlternateOctal (char *digits, size_t digit_count, const Spec &spec, UInt value)
	Applies %#o special rules directly onto the generated digit payload.

static constexpr bool	UsesFloatTextBackend (FormatType type)
	Returns whether one runtime type is handled by the shared float text backend. / 判断某个运行期类型是否由共享浮点文本后端处理

static constexpr bool	FloatEnabled (FormatType type)
	Returns whether one runtime float type is currently enabled by feature switches. / 判断某个运行期浮点类型是否被当前功能开关启用

static bool	AppendBufferChar (char *buffer, size_t capacity, size_t &size, char ch)
	Appends one character to a bounded local formatting buffer. / 向有界本地格式化缓冲区追加一个字符

static bool	AppendBufferText (char *buffer, size_t capacity, size_t &size, std::string_view text)
	Appends one text span to a bounded local formatting buffer. / 向有界本地格式化缓冲区追加一段文本

static bool	AppendBufferU32ZeroPad (char *buffer, size_t capacity, size_t &size, uint32_t value, uint8_t width)
	Appends one uint32_t decimal value and pads leading zeros up to width. / 追加一个 uint32_t 十进制值，并在前面补零到目标宽度

static uint64_t	RoundScaledF32 (float value, uint32_t scale)
	Returns round(value * scale) using the exact float32 bit pattern and nearest-even ties. / 基于精确 float32 位模式并按最近偶数处理平局返回 round(value * scale)

template<typename Float >
static Float	Power10 (int exponent)

template<typename Float >
static DecimalScale< Float >	NormalizeDecimal (Float value)
	Normalizes one finite positive value so that value divided by scale stays in [1, 10). / 将一个有限正值规范化，使 value 除以 scale 后落在 [1, 10)

template<typename Float >
static uint8_t	ExtractDigit (Float &value, Float scale)
	Extracts one base-10 digit at the current scale while tolerating tiny FP residue. / 在当前十进制权重下提取一位数字，并容忍微小浮点残差

static size_t	TrimGeneralText (char *text, size_t size)
	Trims trailing zeros for general float output and removes a dangling decimal point when alternate form is absent. / 在未启用备用格式时修剪通用浮点输出的尾随零，并去掉孤立小数点

static bool	FormatF32FixedPrecText (float value, uint8_t precision, char *out, size_t &out_size)
	Fixed-only float32 formatter that uses a uint32_t scaled-fraction fast path when possible. / 仅供 float32 定点输出使用的格式化器，在可行时优先走 uint32_t 缩放小数快路径

template<typename Float >
static bool	FormatFixedText (Float value, uint8_t precision, bool alternate, char *out, size_t &out_size)

static bool	AppendExponentText (char *out, size_t &out_size, int exponent, bool upper_case)

template<typename Float >
static bool	FormatScientificText (Float value, uint8_t precision, bool alternate, bool upper_case, char *out, size_t &out_size)

template<typename Float >
static bool	FormatFloatText (FormatType type, const Spec &spec, Float value, char *out, size_t &out_size)

Private Attributes
const uint8_t *	codes

const uint8_t const uint8_t *	args

Static Private Attributes
static constexpr uint8_t	unspecified_precision = 0xFF
	Emits the stack argument byte blob for one compiled argument list.

static constexpr size_t	float_buffer_capacity = 512

template<FormatPackKind K>
static constexpr bool	dependent_false_v = false

static constexpr float	f32_u32_overflow_limit = 4294967296.0f
	Largest finite float32 value whose integer part still fits in uint32_t. / 整数部分仍可放入 uint32_t 的最大 float32 值上界

static constexpr std::array< uint32_t, 10 >	f32_decimal_scales_u32
	Decimal scales used by the narrow float32 fixed-precision fast path. / 窄 float32 定点快路径使用的十进制缩放表

Detailed Description

Runtime backend that packs arguments and executes compiled format records.

运行期后端，负责打包参数并执行编译后的格式记录。

Definition at line 28 of file writer.hpp.

Member Function Documentation

◆ AppendBufferChar()

static bool LibXR::Print::Writer::AppendBufferChar	(	char *	buffer,
		size_t	capacity,
		size_t &	size,
		char	ch )

inlinestaticnodiscardprivate

Appends one character to a bounded local formatting buffer. / 向有界本地格式化缓冲区追加一个字符

Definition at line 508 of file writer.hpp.

  {
    if (size >= capacity)
    {
      return false;
    }
    buffer[size++] = ch;
    return true;
  }

◆ AppendBufferText()

static bool LibXR::Print::Writer::AppendBufferText	(	char *	buffer,
		size_t	capacity,
		size_t &	size,
		std::string_view	text )

inlinestaticnodiscardprivate

Appends one text span to a bounded local formatting buffer. / 向有界本地格式化缓冲区追加一段文本

Definition at line 520 of file writer.hpp.

  {
    if (text.size() > capacity - size)
    {
      return false;
    }
    std::memcpy(buffer + size, text.data(), text.size());
    size += text.size();
    return true;
  }

◆ AppendBufferU32ZeroPad()

static bool LibXR::Print::Writer::AppendBufferU32ZeroPad	(	char *	buffer,
		size_t	capacity,
		size_t &	size,
		uint32_t	value,
		uint8_t	width )

inlinestaticnodiscardprivate

Appends one uint32_t decimal value and pads leading zeros up to width. / 追加一个 uint32_t 十进制值，并在前面补零到目标宽度

Definition at line 533 of file writer.hpp.

  {
    char digits[10];
    size_t digit_count = AppendUnsigned(digits, value, 10, false);
    size_t zero_count = (width > digit_count) ? static_cast<size_t>(width) - digit_count : 0;
 
    for (size_t i = 0; i < zero_count; ++i)
    {
      if (!AppendBufferChar(buffer, capacity, size, '0'))
      {
        return false;
      }
    }
 
    return AppendBufferText(buffer, capacity, size, std::string_view(digits, digit_count));
  }

◆ AppendExponentText()

static bool LibXR::Print::Writer::AppendExponentText	(	char *	out,
		size_t &	out_size,
		int	exponent,
		bool	upper_case )

inlinestaticnodiscardprivate

Definition at line 929 of file writer.hpp.

  {
    if (!AppendBufferChar(out, float_buffer_capacity, out_size,
                          upper_case ? 'E' : 'e'))
    {
      return false;
    }
    if (!AppendBufferChar(out, float_buffer_capacity, out_size,
                          exponent < 0 ? '-' : '+'))
    {
      return false;
    }
 
    char digits[16];
    unsigned int magnitude =
        static_cast<unsigned int>(exponent < 0 ? -exponent : exponent);
    size_t digit_count = AppendUnsigned(digits, magnitude, 10, false);
    if (digit_count < 2 &&
        !AppendBufferChar(out, float_buffer_capacity, out_size, '0'))
    {
      return false;
    }
 
    return AppendBufferText(out, float_buffer_capacity, out_size,
                            std::string_view(digits, digit_count));
  }

◆ AppendSmallUnsigned()

static size_t LibXR::Print::Writer::AppendSmallUnsigned	(	char *	out,
		uint8_t	value )

inlinestaticnodiscardprivate

Definition at line 341 of file writer.hpp.

  {
    return AppendUnsigned(out, value, 10, false);
  }

◆ AppendUnsigned()

template<std::unsigned_integral UInt>

static size_t LibXR::Print::Writer::AppendUnsigned	(	char *	out,
		UInt	value,
		uint8_t	base,
		bool	upper_case )

inlinestaticnodiscardprivate

Definition at line 312 of file writer.hpp.

  {
    constexpr char lower_digits[] = "0123456789abcdef";
    constexpr char upper_digits[] = "0123456789ABCDEF";
    const char* digits = upper_case ? upper_digits : lower_digits;
    char reverse[32];
    size_t count = 0;
 
    if (value == 0)
    {
      out[0] = '0';
      return 1;
    }
 
    while (value != 0)
    {
      reverse[count++] = digits[value % base];
      value /= base;
    }
 
    for (size_t i = 0; i < count; ++i)
    {
      out[i] = reverse[count - i - 1];
    }
 
    return count;
  }

◆ ApplyAlternateOctal()

template<std::unsigned_integral UInt>

static size_t LibXR::Print::Writer::ApplyAlternateOctal	(	char *	digits,
		size_t	digit_count,
		const Spec &	spec,
		UInt	value )

inlinestaticnodiscardprivate

Applies %#o special rules directly onto the generated digit payload.

直接在已生成的数字载荷上应用 %#o 的特殊规则。

Octal alternate form differs from hex: it is represented by a leading zero in the digit payload itself, not by a detached prefix string. This helper also preserves the required single 0 when %#.0o formats zero. 八进制备用格式与十六进制不同：它通过数字载荷本体前导一个 0 来表示，而不是额外分离出的前缀字符串。本函数也负责在 %#.0o 格式化零值时保留必需的单个 0。

Definition at line 427 of file writer.hpp.

  {
    if (!spec.Alternate())
    {
      return (value == 0 && spec.precision == 0) ? 0 : digit_count;
    }
 
    if (value == 0 && spec.precision == 0)
    {
      return 1;
    }
 
    if (value == 0)
    {
      return digit_count;
    }
 
    if (spec.HasPrecision() && spec.precision > digit_count)
    {
      return digit_count;
    }
 
    digits[digit_count++] = '0';
    for (size_t i = digit_count - 1; i > 0; --i)
    {
      digits[i] = digits[i - 1];
    }
    digits[0] = '0';
    return digit_count;
  }

◆ ExtractDigit()

template<typename Float >

static uint8_t LibXR::Print::Writer::ExtractDigit	(	Float &	value,
		Float	scale )

inlinestaticnodiscardprivate

Extracts one base-10 digit at the current scale while tolerating tiny FP residue. / 在当前十进制权重下提取一位数字，并容忍微小浮点残差

Definition at line 660 of file writer.hpp.

  {
    Float scaled = value / scale;
    auto digit = static_cast<int>(scaled + static_cast<Float>(1e-12L));
    if (digit < 0)
    {
      digit = 0;
    }
    else if (digit > 9)
    {
      digit = 9;
    }
 
    value -= static_cast<Float>(digit) * scale;
    Float epsilon = scale * static_cast<Float>(1e-9L);
    if (value < 0 && value > -epsilon)
    {
      value = 0;
    }
 
    return static_cast<uint8_t>(digit);
  }

◆ FieldPadding()

static constexpr size_t LibXR::Print::Writer::FieldPadding	(	uint8_t	width,
		size_t	payload_size )

inlinestaticnodiscardconstexprprivate

Returns the padding width needed to expand one payload to the requested field width. / 返回把某段载荷扩展到目标字段宽度所需的填充长度

Definition at line 347 of file writer.hpp.

  {
    return (width > payload_size) ? static_cast<size_t>(width) - payload_size : 0;
  }

◆ FloatEnabled()

static constexpr bool LibXR::Print::Writer::FloatEnabled ( FormatType type )

inlinestaticnodiscardconstexprprivate

Returns whether one runtime float type is currently enabled by feature switches. / 判断某个运行期浮点类型是否被当前功能开关启用

Definition at line 480 of file writer.hpp.

  {
    switch (type)
    {
      case FormatType::FloatFixed:
        return Config::enable_float_fixed;
      case FormatType::FloatScientific:
        return Config::enable_float_scientific;
      case FormatType::FloatGeneral:
        return Config::enable_float_general;
      case FormatType::DoubleFixed:
        return Config::enable_float_double && Config::enable_float_fixed;
      case FormatType::DoubleScientific:
        return Config::enable_float_double && Config::enable_float_scientific;
      case FormatType::DoubleGeneral:
        return Config::enable_float_double && Config::enable_float_general;
      case FormatType::LongDoubleFixed:
        return Config::enable_float_long_double && Config::enable_float_fixed;
      case FormatType::LongDoubleScientific:
        return Config::enable_float_long_double && Config::enable_float_scientific;
      case FormatType::LongDoubleGeneral:
        return Config::enable_float_long_double && Config::enable_float_general;
      default:
        return false;
    }
  }

◆ FormatF32FixedPrecText()

static bool LibXR::Print::Writer::FormatF32FixedPrecText	(	float	value,
		uint8_t	precision,
		char *	out,
		size_t &	out_size )

inlinestaticnodiscardprivate

Fixed-only float32 formatter that uses a uint32_t scaled-fraction fast path when possible. / 仅供 float32 定点输出使用的格式化器，在可行时优先走 uint32_t 缩放小数快路径

Definition at line 716 of file writer.hpp.

  {
    out_size = 0;
 
    // Stage 1: special IEEE spellings.
    // 第 1 阶段：处理 IEEE 特殊值文本。
    if (std::isnan(value))
    {
      return AppendBufferText(out, float_buffer_capacity, out_size, "nan");
    }
    if (std::isinf(value))
    {
      return AppendBufferText(out, float_buffer_capacity, out_size, "inf");
    }
 
    // Stage 2: narrow uint32_t-backed fixed formatter for the common case.
    // 第 2 阶段：常见场景优先走基于 uint32_t 的窄定点格式化器。
    if (precision < f32_decimal_scales_u32.size() && value < f32_u32_overflow_limit)
    {
      uint32_t integer_part = static_cast<uint32_t>(value);
      uint32_t scale = f32_decimal_scales_u32[precision];
      uint64_t scaled_total = RoundScaledF32(value, scale);
      uint64_t scaled_integer = static_cast<uint64_t>(integer_part) * scale;
      uint32_t fractional_part =
          (scaled_total >= scaled_integer)
              ? static_cast<uint32_t>(scaled_total - scaled_integer)
              : 0U;
 
      if (fractional_part >= scale)
      {
        fractional_part -= scale;
        if (integer_part == std::numeric_limits<uint32_t>::max())
        {
          if (!AppendBufferText(out, float_buffer_capacity, out_size, "4294967296"))
          {
            return false;
          }
          if (precision == 0)
          {
            return true;
          }
          if (!AppendBufferChar(out, float_buffer_capacity, out_size, '.'))
          {
            return false;
          }
          for (uint8_t i = 0; i < precision; ++i)
          {
            if (!AppendBufferChar(out, float_buffer_capacity, out_size, '0'))
            {
              return false;
            }
          }
          return true;
        }
        ++integer_part;
      }
 
      if (!AppendBufferU32ZeroPad(out, float_buffer_capacity, out_size, integer_part, 1))
      {
        return false;
      }
      if (precision == 0)
      {
        return true;
      }
      if (!AppendBufferChar(out, float_buffer_capacity, out_size, '.'))
      {
        return false;
      }
      return AppendBufferU32ZeroPad(out, float_buffer_capacity, out_size, fractional_part,
                                    precision);
    }
 
    // Stage 3: generic fixed-only fallback for larger precision or magnitude.
    // 第 3 阶段：针对更大精度或更大数量级的通用仅定点回退路径。
    float rounded = value;
    float rounding = 0.5f;
    for (uint8_t i = 0; i < precision; ++i)
    {
      rounding *= 0.1f;
    }
    rounded += rounding;
 
    if (rounded < 1.0f)
    {
      if (!AppendBufferChar(out, float_buffer_capacity, out_size, '0'))
      {
        return false;
      }
    }
    else
    {
      float integer_scale = 1.0f;
      while (true)
      {
        float next_scale = integer_scale * 10.0f;
        if (!std::isfinite(next_scale) || rounded < next_scale)
        {
          break;
        }
        integer_scale = next_scale;
      }
 
      while (integer_scale >= 1.0f)
      {
        int digit = static_cast<int>(rounded / integer_scale);
        if (digit < 0)
        {
          digit = 0;
        }
        else if (digit > 9)
        {
          digit = 9;
        }
 
        if (!AppendBufferChar(out, float_buffer_capacity, out_size,
                              static_cast<char>('0' + digit)))
        {
          return false;
        }
 
        rounded -= static_cast<float>(digit) * integer_scale;
        float epsilon = integer_scale * 1e-6f;
        if (rounded < 0.0f && rounded > -epsilon)
        {
          rounded = 0.0f;
        }
        integer_scale *= 0.1f;
      }
    }
 
    if (precision == 0)
    {
      return true;
    }
    if (!AppendBufferChar(out, float_buffer_capacity, out_size, '.'))
    {
      return false;
    }
 
    for (uint8_t i = 0; i < precision; ++i)
    {
      rounded *= 10.0f;
      int digit = static_cast<int>(rounded + 1e-6f);
      if (digit < 0)
      {
        digit = 0;
      }
      else if (digit > 9)
      {
        digit = 9;
      }
 
      if (!AppendBufferChar(out, float_buffer_capacity, out_size,
                            static_cast<char>('0' + digit)))
      {
        return false;
      }
 
      rounded -= static_cast<float>(digit);
      if (rounded < 0.0f && rounded > -1e-5f)
      {
        rounded = 0.0f;
      }
    }
 
    return true;
  }

◆ FormatFixedText()

template<typename Float >

static bool LibXR::Print::Writer::FormatFixedText	(	Float	value,
		uint8_t	precision,
		bool	alternate,
		char *	out,
		size_t &	out_size )

inlinestaticnodiscardprivate

Definition at line 887 of file writer.hpp.

  {
    Float rounded =
        value + static_cast<Float>(0.5L) * Power10<Float>(-static_cast<int>(precision));
    auto normalized = NormalizeDecimal(rounded);
    int integer_exponent = (rounded == 0) ? 0 : normalized.exponent;
    int start_pos = (integer_exponent > 0) ? integer_exponent : 0;
    Float scale = Power10<Float>(start_pos);
 
    out_size = 0;
    for (int pos = start_pos; pos >= 0; --pos)
    {
      if (!AppendBufferChar(out, float_buffer_capacity, out_size,
                            static_cast<char>('0' + ExtractDigit(rounded, scale))))
      {
        return false;
      }
      scale /= 10;
    }
 
    if (precision != 0 || alternate)
    {
      if (!AppendBufferChar(out, float_buffer_capacity, out_size, '.'))
      {
        return false;
      }
    }
 
    for (uint8_t i = 0; i < precision; ++i)
    {
      if (!AppendBufferChar(out, float_buffer_capacity, out_size,
                            static_cast<char>('0' + ExtractDigit(rounded, scale))))
      {
        return false;
      }
      scale /= 10;
    }
 
    return true;
  }

◆ FormatFloatText()

template<typename Float >

static bool LibXR::Print::Writer::FormatFloatText	(	FormatType	type,
		const Spec &	spec,
		Float	value,
		char *	out,
		size_t &	out_size )

inlinestaticnodiscardprivate

Definition at line 1004 of file writer.hpp.

  {
    out_size = 0;
 
    if (std::isnan(value))
    {
      return AppendBufferText(out, float_buffer_capacity, out_size,
                              spec.UpperCase() ? "NAN" : "nan");
    }
    if (std::isinf(value))
    {
      return AppendBufferText(out, float_buffer_capacity, out_size,
                              spec.UpperCase() ? "INF" : "inf");
    }
 
    uint8_t precision = spec.HasPrecision() ? spec.precision : 6;
    switch (type)
    {
      case FormatType::FloatFixed:
      case FormatType::DoubleFixed:
      case FormatType::LongDoubleFixed:
        return FormatFixedText(value, precision, spec.Alternate(), out, out_size);
      case FormatType::FloatScientific:
      case FormatType::DoubleScientific:
      case FormatType::LongDoubleScientific:
        return FormatScientificText(value, precision, spec.Alternate(), spec.UpperCase(),
                                    out, out_size);
      case FormatType::FloatGeneral:
      case FormatType::DoubleGeneral:
      case FormatType::LongDoubleGeneral:
      {
        uint8_t significant = precision == 0 ? 1 : precision;
        int exponent = (value == 0) ? 0 : NormalizeDecimal(value).exponent;
        if (exponent < -4 || exponent >= significant)
        {
          if (!FormatScientificText(value, static_cast<uint8_t>(significant - 1),
                                    spec.Alternate(), spec.UpperCase(), out, out_size))
          {
            return false;
          }
        }
        else
        {
          int fractional_precision = static_cast<int>(significant) - (exponent + 1);
          if (fractional_precision < 0)
          {
            fractional_precision = 0;
          }
          if (!FormatFixedText(value, static_cast<uint8_t>(fractional_precision),
                               spec.Alternate(), out, out_size))
          {
            return false;
          }
        }
 
        if (!spec.Alternate())
        {
          out_size = TrimGeneralText(out, out_size);
        }
        return true;
      }
      default:
        return false;
    }
  }

◆ FormatScientificText()

template<typename Float >

static bool LibXR::Print::Writer::FormatScientificText	(	Float	value,
		uint8_t	precision,
		bool	alternate,
		bool	upper_case,
		char *	out,
		size_t &	out_size )

inlinestaticnodiscardprivate

Definition at line 958 of file writer.hpp.

  {
    auto initial = NormalizeDecimal(value);
    Float rounded = value;
    if (value != 0)
    {
      rounded += static_cast<Float>(0.5L) *
                 Power10<Float>(initial.exponent - static_cast<int>(precision));
    }
 
    auto normalized = NormalizeDecimal(rounded);
    int exponent = (rounded == 0) ? 0 : normalized.exponent;
    Float scale = Power10<Float>(exponent);
 
    out_size = 0;
    if (!AppendBufferChar(out, float_buffer_capacity, out_size,
                          static_cast<char>('0' + ExtractDigit(rounded, scale))))
    {
      return false;
    }
 
    if (precision != 0 || alternate)
    {
      if (!AppendBufferChar(out, float_buffer_capacity, out_size, '.'))
      {
        return false;
      }
    }
 
    scale /= 10;
    for (uint8_t i = 0; i < precision; ++i)
    {
      if (!AppendBufferChar(out, float_buffer_capacity, out_size,
                            static_cast<char>('0' + ExtractDigit(rounded, scale))))
      {
        return false;
      }
      scale /= 10;
    }
 
    return AppendExponentText(out, out_size, exponent, upper_case);
  }

◆ HasFlag()

static constexpr bool LibXR::Print::Writer::HasFlag	(	uint8_t	flags,
		uint8_t	bit )

inlinestaticnodiscardconstexprprivate

Tests whether one decoded field-spec bit is set.

判断某个已解码字段修饰位是否被设置。

Definition at line 87 of file writer.hpp.

  {
    return (flags & bit) != 0;
  }

◆ IntegerBase()

static constexpr uint8_t LibXR::Print::Writer::IntegerBase ( FormatType type )

inlinestaticnodiscardconstexprprivate

Returns the integer radix selected by one unsigned runtime type. / 返回某个无符号运行期类型对应的整数进制

Definition at line 362 of file writer.hpp.

  {
    switch (type)
    {
      case FormatType::Unsigned32:
      case FormatType::Unsigned64:
        return 10;
      case FormatType::Binary32:
      case FormatType::Binary64:
        return 2;
      case FormatType::Octal32:
      case FormatType::Octal64:
        return 8;
      case FormatType::HexLower32:
      case FormatType::HexLower64:
      case FormatType::HexUpper32:
      case FormatType::HexUpper64:
        return 16;
      default:
        return 0;
    }
  }

◆ IntegerPrecisionZeros()

static constexpr size_t LibXR::Print::Writer::IntegerPrecisionZeros	(	const Spec &	spec,
		size_t	digit_count )

inlinestaticnodiscardconstexprprivate

Returns the extra leading-zero count introduced by integer precision. / 返回整数精度引入的额外前导零个数

Definition at line 353 of file writer.hpp.

  {
    return (spec.HasPrecision() && spec.precision > digit_count)
               ? static_cast<size_t>(spec.precision) - digit_count
               : 0;
  }

◆ IntegerPrefix()

template<std::unsigned_integral UInt>

static constexpr std::string_view LibXR::Print::Writer::IntegerPrefix	(	FormatType	type,
		const Spec &	spec,
		UInt	value )

inlinestaticnodiscardconstexprprivate

Returns the alternate-form prefix carried outside the digit payload. / 返回放在数字载荷之外的备用格式前缀

Definition at line 393 of file writer.hpp.

  {
    if (!spec.Alternate() || value == 0)
    {
      return {};
    }
    if (type == FormatType::HexLower32 || type == FormatType::HexLower64)
    {
      return "0x";
    }
    if (type == FormatType::HexUpper32 || type == FormatType::HexUpper64)
    {
      return "0X";
    }
    if (type == FormatType::Binary32 || type == FormatType::Binary64)
    {
      return spec.UpperCase() ? "0B" : "0b";
    }
    return {};
  }

◆ IntegerUpperCase()

static constexpr bool LibXR::Print::Writer::IntegerUpperCase ( FormatType type )

inlinestaticnodiscardconstexprprivate

Returns whether one unsigned runtime type should emit uppercase hex digits. / 判断某个无符号运行期类型是否应输出大写十六进制数字

Definition at line 386 of file writer.hpp.

  {
    return type == FormatType::HexUpper32 || type == FormatType::HexUpper64;
  }

◆ NormalizeDecimal()

template<typename Float >

static DecimalScale< Float > LibXR::Print::Writer::NormalizeDecimal ( Float value )

inlinestaticnodiscardprivate

Normalizes one finite positive value so that value divided by scale stays in [1, 10). / 将一个有限正值规范化，使 value 除以 scale 后落在 [1, 10)

Definition at line 625 of file writer.hpp.

  {
    DecimalScale<Float> normalized{};
    if (value == 0)
    {
      return normalized;
    }
 
    int binary_exponent = 0;
    std::frexp(value, &binary_exponent);
    constexpr Float log10_of_2 =
        static_cast<Float>(0.30102999566398119521373889472449L);
    normalized.exponent =
        static_cast<int>(static_cast<Float>(binary_exponent - 1) * log10_of_2);
    normalized.scale = Power10<Float>(normalized.exponent);
 
    Float scaled = value / normalized.scale;
    while (scaled < 1)
    {
      normalized.scale /= 10;
      --normalized.exponent;
      scaled *= 10;
    }
    while (scaled >= 10)
    {
      normalized.scale *= 10;
      ++normalized.exponent;
      scaled /= 10;
    }
 
    return normalized;
  }

◆ PackedArgumentBytes()

template<auto ArgumentInfoList>

static consteval size_t LibXR::Print::Writer::PackedArgumentBytes ( )

inlinestaticnodiscardconstevalprivate

Definition at line 291 of file writer.hpp.

  {
    size_t bytes = 0;
    for (const auto& argument : ArgumentInfoList)
    {
      bytes += FormatArgumentBytes(argument.pack);
    }
    return bytes;
  }

◆ PackValue()

template<FormatPackKind pack, typename T >

static constexpr auto LibXR::Print::Writer::PackValue ( T && value )

inlinestaticnodiscardconstexprprivate

Normalizes one matched C++ argument into the packed runtime storage kind required by one compiled argument slot.

将一个已匹配的 C++ 实参归一化为某个编译参数槽要求的运行期打包存储类型。

Definition at line 183 of file writer.hpp.

  {
    using Traits = Detail::FormatArgument::TypeTraits<T>;
    using Normalized = typename Traits::Normalized;
 
    if constexpr (pack == FormatPackKind::I32)
    {
      if constexpr (Traits::is_signed_integer)
      {
        return static_cast<int32_t>(static_cast<Normalized>(value));
      }
    }
    else if constexpr (pack == FormatPackKind::I64)
    {
      if constexpr (Traits::is_signed_integer)
      {
        return static_cast<int64_t>(static_cast<Normalized>(value));
      }
    }
    else if constexpr (pack == FormatPackKind::U32)
    {
      if constexpr (std::is_same_v<Normalized, bool>)
      {
        return static_cast<uint32_t>(value ? 1U : 0U);
      }
      else if constexpr (std::is_integral_v<Normalized>)
      {
        return static_cast<uint32_t>(static_cast<std::make_unsigned_t<Normalized>>(
            static_cast<Normalized>(value)));
      }
    }
    else if constexpr (pack == FormatPackKind::U64)
    {
      if constexpr (std::is_same_v<Normalized, bool>)
      {
        return static_cast<uint64_t>(value ? 1U : 0U);
      }
      else if constexpr (std::is_integral_v<Normalized>)
      {
        return static_cast<uint64_t>(static_cast<std::make_unsigned_t<Normalized>>(
            static_cast<Normalized>(value)));
      }
    }
    else if constexpr (pack == FormatPackKind::Pointer)
    {
      if constexpr (Traits::is_pointer_like)
      {
        if constexpr (std::is_same_v<typename Traits::Decayed, std::nullptr_t>)
        {
          return static_cast<uintptr_t>(0);
        }
        else
        {
          return (value == nullptr) ? static_cast<uintptr_t>(0)
                                    : reinterpret_cast<uintptr_t>(value);
        }
      }
    }
    else if constexpr (pack == FormatPackKind::Character)
    {
      if constexpr (Traits::is_character_like)
      {
        return static_cast<char>(static_cast<Normalized>(value));
      }
    }
    else if constexpr (pack == FormatPackKind::StringView)
    {
      if constexpr (Traits::is_string_like)
      {
        return ToStringView(value);
      }
    }
    else if constexpr (pack == FormatPackKind::F32)
    {
      if constexpr (std::is_arithmetic_v<Normalized>)
      {
        return static_cast<float>(value);
      }
    }
    else if constexpr (pack == FormatPackKind::F64)
    {
      if constexpr (std::is_arithmetic_v<Normalized>)
      {
        return static_cast<double>(value);
      }
    }
    else if constexpr (pack == FormatPackKind::LongDouble)
    {
      if constexpr (std::is_arithmetic_v<Normalized>)
      {
        return static_cast<long double>(value);
      }
    }
    else
    {
      static_assert(dependent_false_v<pack>,
                    "LibXR::Print::Writer::PackValue: unsupported packed argument kind");
    }
  }

◆ Power10()

template<typename Float >

static Float LibXR::Print::Writer::Power10 ( int exponent )

inlinestaticnodiscardprivate

Definition at line 592 of file writer.hpp.

  {
    Float result = 1;
    Float base = 10;
    unsigned int remaining =
        static_cast<unsigned int>(exponent < 0 ? -exponent : exponent);
 
    while (remaining != 0)
    {
      if ((remaining & 1U) != 0U)
      {
        if (exponent < 0)
        {
          result /= base;
        }
        else
        {
          result *= base;
        }
      }
 
      remaining >>= 1U;
      if (remaining != 0U)
      {
        base *= base;
      }
    }
 
    return result;
  }

◆ RoundScaledF32()

static uint64_t LibXR::Print::Writer::RoundScaledF32	(	float	value,
		uint32_t	scale )

inlinestaticnodiscardprivate

Returns round(value * scale) using the exact float32 bit pattern and nearest-even ties. / 基于精确 float32 位模式并按最近偶数处理平局返回 round(value * scale)

Definition at line 553 of file writer.hpp.

  {
    uint32_t bits = std::bit_cast<uint32_t>(value);
    uint32_t exponent_bits = (bits >> 23) & 0xFFU;
    uint32_t fraction_bits = bits & 0x7FFFFFU;
    uint32_t significand =
        (exponent_bits == 0) ? fraction_bits : ((1U << 23) | fraction_bits);
    int exponent2 =
        (exponent_bits == 0) ? -149 : static_cast<int>(exponent_bits) - 150;
    uint64_t numerator = static_cast<uint64_t>(significand) * scale;
 
    if (exponent2 >= 0)
    {
      return numerator << exponent2;
    }
 
    unsigned int shift = static_cast<unsigned int>(-exponent2);
    if (shift >= 64)
    {
      return 0;
    }
    uint64_t quotient = numerator >> shift;
    uint64_t remainder = numerator & ((uint64_t{1} << shift) - 1U);
    uint64_t halfway = uint64_t{1} << (shift - 1);
    if (remainder > halfway || (remainder == halfway && (quotient & 1U) != 0U))
    {
      ++quotient;
    }
    return quotient;
  }

◆ RunArgumentOrder()

template<typename Sink , typename Format , auto ArgumentOrder, typename... Args>
requires OutputSink<Sink> && CompiledFormat<std::remove_cvref_t<Format>>

static ErrorCode LibXR::Print::Writer::RunArgumentOrder	(	Sink &	sink,
		const Format &	,
		Args &&...	args )

inlinestaticnodiscard

Runs one compiled format whose runtime pack order is provided separately from the call-site argument order.

执行一份已编译格式；其运行期打包顺序由独立的编译期参数顺序表提供。

This is used by brace-style frontends that allow repeated or reordered argument references such as {1} {0} while keeping the runtime bytecode stream itself strictly source-ordered. 该接口用于 brace 风格前端：它允许 {1} {0} 这种重复或重排参数引用，同时保持运行期字节码流本身仍然严格按源串顺序执行。

Definition at line 44 of file writer.hpp.

  {
    using Built = std::remove_cvref_t<Format>;
    static_assert(ArgumentOrder.size() == Built::ArgumentList().size(),
                  "LibXR::Print::Writer: argument reorder list must match the "
                  "compiled field count");
    static_assert(Built::template Matches<Args...>(),
                  "LibXR::Print::Writer::RunArgumentOrder: format arguments do not match");
 
    return RunTaggedArgumentOrder<Sink, Built::ArgumentList(), ArgumentOrder,
                                  Built::Profile()>(
        sink, Built::Codes().data(), std::forward<Args>(args)...);
  }

◆ StoreArgument()

template<typename T >

static void LibXR::Print::Writer::StoreArgument	(	uint8_t *&	out,
		const T &	value )

inlinestaticprivate

Definition at line 284 of file writer.hpp.

  {
    std::memcpy(out, &value, sizeof(T));
    out += sizeof(T);
  }

◆ StoreArgumentsOrdered()

template<auto ArgumentInfoList, auto ArgumentOrder, typename Tuple >

static void LibXR::Print::Writer::StoreArgumentsOrdered	(	uint8_t *&	out,
		Tuple &	tuple )

inlinestaticprivate

Definition at line 302 of file writer.hpp.

  {
    [&]<size_t... I>(std::index_sequence<I...>) {
      (StoreArgument(out, PackValue<ArgumentInfoList[I].pack>(
                              std::get<ArgumentOrder[I]>(tuple))),
       ...);
    }(std::make_index_sequence<ArgumentInfoList.size()>{});
  }

◆ ToStringView()

template<typename T >

static constexpr std::string_view LibXR::Print::Writer::ToStringView ( const T & text )

inlinestaticnodiscardconstexprprivate

Definition at line 146 of file writer.hpp.

  {
    using Traits = Detail::FormatArgument::TypeTraits<T>;
 
    if constexpr (std::is_same_v<typename Traits::Decayed, std::string_view>)
    {
      return text;
    }
    else if constexpr (std::is_same_v<typename Traits::Decayed, std::string>)
    {
      return std::string_view(text.data(), text.size());
    }
    else if constexpr (std::is_same_v<typename Traits::Decayed, const char*> ||
                       std::is_same_v<typename Traits::Decayed, char*>)
    {
      if (text == nullptr)
      {
        return "(null)";
      }
      return std::string_view(text, std::strlen(text));
    }
    else if constexpr (Traits::is_char_array)
    {
      return std::string_view(text, std::strlen(text));
    }
    else
    {
      return {};
    }
  }

◆ TrimGeneralText()

static size_t LibXR::Print::Writer::TrimGeneralText	(	char *	text,
		size_t	size )

inlinestaticnodiscardprivate

Trims trailing zeros for general float output and removes a dangling decimal point when alternate form is absent. / 在未启用备用格式时修剪通用浮点输出的尾随零，并去掉孤立小数点

Definition at line 684 of file writer.hpp.

  {
    size_t exponent_pos = size;
    for (size_t i = 0; i < size; ++i)
    {
      if (text[i] == 'e' || text[i] == 'E')
      {
        exponent_pos = i;
        break;
      }
    }
 
    size_t mantissa_end = exponent_pos;
    while (mantissa_end > 0 && text[mantissa_end - 1] == '0')
    {
      --mantissa_end;
    }
    if (mantissa_end > 0 && text[mantissa_end - 1] == '.')
    {
      --mantissa_end;
    }
 
    if (exponent_pos == size)
    {
      return mantissa_end;
    }
 
    std::memmove(text + mantissa_end, text + exponent_pos, size - exponent_pos);
    return mantissa_end + (size - exponent_pos);
  }

◆ UsesFloatTextBackend()

static constexpr bool LibXR::Print::Writer::UsesFloatTextBackend ( FormatType type )

inlinestaticnodiscardconstexprprivate

Returns whether one runtime type is handled by the shared float text backend. / 判断某个运行期类型是否由共享浮点文本后端处理

Definition at line 460 of file writer.hpp.

  {
    switch (type)
    {
      case FormatType::FloatScientific:
      case FormatType::DoubleScientific:
      case FormatType::LongDoubleScientific:
      case FormatType::FloatGeneral:
      case FormatType::DoubleGeneral:
      case FormatType::LongDoubleGeneral:
      case FormatType::FloatFixed:
      case FormatType::DoubleFixed:
      case FormatType::LongDoubleFixed:
        return true;
      default:
        return false;
    }
  }

Field Documentation

◆ args

const uint8_t const uint8_t* LibXR::Print::Writer::args

private

Initial value:

{

return Executor<Sink, Profile>(sink, codes, args).Run()

Definition at line 1079 of file writer.hpp.

◆ codes

const uint8_t * LibXR::Print::Writer::codes

private

Definition at line 1079 of file writer.hpp.

◆ dependent_false_v

template<FormatPackKind K>

bool LibXR::Print::Writer::dependent_false_v = false

staticconstexprprivate

Definition at line 66 of file writer.hpp.

◆ f32_decimal_scales_u32

std::array<uint32_t, 10> LibXR::Print::Writer::f32_decimal_scales_u32

inlinestaticconstexprprivate

Initial value:

{
      1U,
      10U,
      100U,
      1000U,
      10000U,
      100000U,
      1000000U,
      10000000U,
      100000000U,
      1000000000U,
  }

Decimal scales used by the narrow float32 fixed-precision fast path. / 窄 float32 定点快路径使用的十进制缩放表

Definition at line 70 of file writer.hpp.

                                                                       {
      1U,
      10U,
      100U,
      1000U,
      10000U,
      100000U,
      1000000U,
      10000000U,
      100000000U,
      1000000000U,
  };

◆ f32_u32_overflow_limit

float LibXR::Print::Writer::f32_u32_overflow_limit = 4294967296.0f

staticconstexprprivate

Largest finite float32 value whose integer part still fits in uint32_t. / 整数部分仍可放入 uint32_t 的最大 float32 值上界

Definition at line 68 of file writer.hpp.

◆ float_buffer_capacity

size_t LibXR::Print::Writer::float_buffer_capacity = 512

staticconstexprprivate

Definition at line 64 of file writer.hpp.

◆ unspecified_precision

uint8_t LibXR::Print::Writer::unspecified_precision = 0xFF

staticconstexprprivate

Emits the stack argument byte blob for one compiled argument list.

为某个已编译参数列表生成栈上参数字节块。

Definition at line 63 of file writer.hpp.

The documentation for this class was generated from the following file:

src/core/print/writer.hpp

Data Structures

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ AppendBufferChar()

◆ AppendBufferText()

◆ AppendBufferU32ZeroPad()

◆ AppendExponentText()

◆ AppendSmallUnsigned()

◆ AppendUnsigned()

◆ ApplyAlternateOctal()

◆ ExtractDigit()

◆ FieldPadding()

◆ FloatEnabled()

◆ FormatF32FixedPrecText()

◆ FormatFixedText()

◆ FormatFloatText()

◆ FormatScientificText()

◆ HasFlag()

◆ IntegerBase()

◆ IntegerPrecisionZeros()

◆ IntegerPrefix()

◆ IntegerUpperCase()

◆ NormalizeDecimal()

◆ PackedArgumentBytes()

◆ PackValue()

◆ Power10()

◆ RoundScaledF32()

◆ RunArgumentOrder()

◆ StoreArgument()

◆ StoreArgumentsOrdered()

◆ ToStringView()

◆ TrimGeneralText()

◆ UsesFloatTextBackend()

Field Documentation

◆ args

◆ codes

◆ dependent_false_v

◆ f32_decimal_scales_u32

◆ f32_u32_overflow_limit

◆ float_buffer_capacity

◆ unspecified_precision