.\" Copyright 2026 Andrew V.Kosteltsev (kx@radix-linux.su)
.\"
.\"
.TH _int_digs 3  "September 15, 2026" "libmpu" "LibMPU Programmer's Manual"
.SH NAME
\fB_int_digs\fP \- maximum buffer size for the decimal representation of an unsigned integer
.SH SYNOPSIS
.nf
.B #include <libmpu.h>
.PP
.BI "int _int_digs( int " nb " );"
.fi
.SH DESCRIPTION
The \fB_int_digs()\fP function returns the maximum buffer size, in bytes, required to
store the decimal representation of an unsigned integer occupying \fBnb\fP bytes,
including the terminating \fB'\\0'\fP character.
.PP
The function does not examine an integer value.  The result depends only on the size
specified by \fBnb\fP and therefore is suitable for allocating a buffer before converting
an unsigned LibMPU integer to a decimal string.
.PP
For an integer occupying \fBnb\fP bytes, the maximum number of significant bits is
.sp
.nf
        8 * nb
.fi
.sp
and the maximum number of decimal digits is
.sp
.nf
        ceil( 8 * nb * log10(2) ).
.fi
.sp
The implementation does not use floating-point arithmetic or functions from \fBlibm\fP.
It uses the upper rational approximation
.sp
.nf
        log10(2) < 30103 / 100000
.fi
.sp
so the number of decimal digits is calculated as
.sp
.nf
        (nb * 30103 + 12499) / 12500
.fi
.sp
using integer arithmetic.  One additional byte is included for the terminating
\fB'\\0'\fP character.
.PP
The \fBnb\fP argument should normally be one of the integer-size constants declared in
\fBlibmpu.h\fP, for example \fBNB_I8\fP, \fBNB_I16\fP, ..., \fBNB_I65536\fP.
.PP
The function does not require a \fBLibMPU\fP arithmetic context and does not change the integer
operation flags.
.SH RETURN VALUE
For \fBnb > 0\fP, the function returns a buffer size sufficient to hold the largest
possible unsigned decimal value of that size together with the terminating \fB'\\0'\fP.
For \fBnb < 1\fP, it returns \fB0\fP.
.sp
For example:
.sp
.nf
        _int_digs( NB_I8 )      =     4
        _int_digs( NB_I16 )     =     6
        _int_digs( NB_I32 )     =    11
        _int_digs( NB_I64 )     =    21
        _int_digs( NB_I1024 )   =   310
        _int_digs( NB_I65536 )  = 19730
.fi
.SH EXAMPLES
.nf
.sp
#include <libmpu.h>
#include <stdio.h>

int main( void )
{
  int  rc = 0;

  __mpu_init();
  __mpu_extra_warnings = 1;

  {
    mpu_int65536_t  c;
    int             nb = NB_I65536;

    printf( "sizeof(c) = %d;\\n", (int)sizeof(c) );

    /* Maximum buffer size in bytes, including terminating '\\0'. */
    printf( "_int_digs(%d) = %d;\\n", nb,         _int_digs(nb)         );
    printf( "_int_digs(%d) = %d;\\n", NB_I32768,  _int_digs(NB_I32768)  );
    printf( "_int_digs(%d) = %d;\\n", NB_I16384,  _int_digs(NB_I16384)  );
    printf( "_int_digs(%d) = %d;\\n", NB_I8192,   _int_digs(NB_I8192)   );
    printf( "_int_digs(%d) = %d;\\n", NB_I4096,   _int_digs(NB_I4096)   );
    printf( "_int_digs(%d) = %d;\\n", NB_I2048,   _int_digs(NB_I2048)   );
    printf( "_int_digs(%d) = %d;\\n", NB_I1024,   _int_digs(NB_I1024)   );
    printf( "_int_digs(%d) = %d;\\n", NB_I512,    _int_digs(NB_I512)    );
    printf( "_int_digs(%d) = %d;\\n", NB_I256,    _int_digs(NB_I256)    );
    printf( "_int_digs(%d) = %d;\\n", NB_I128,    _int_digs(NB_I128)    );
    printf( "_int_digs(%d) = %d;\\n", NB_I64,     _int_digs(NB_I64)     );
    printf( "_int_digs(%d) = %d;\\n", NB_I32,     _int_digs(NB_I32)     );
    printf( "_int_digs(%d) = %d;\\n", NB_I16,     _int_digs(NB_I16)     );
    printf( "_int_digs(%d) = %d;\\n", NB_I8,      _int_digs(NB_I8)      );
  }

  __mpu_free_context();

  return( rc );
}
.fi
.sp
.SH SEE ALSO
.BR ibits_len(3),
.BR libmpu(7).