=encoding UTF-8


=head1 НАИМЕНОВАНИЕ

BH_String - Работа со строками


=head1 СИНТАКСИС

 #include <BH/Math.h>

 cc prog.c -o prog -lbh


=head1 ОПИСАНИЕ

Библиотека BH_String предоставляет набор функций для работы со строками, включая
преобразование чисел в строки и обратно.


=head1 ОПРЕДЛЕНИЕ ОСНОВАНИЯ

В функциях семейства I<StringToInt> присутсвует алгоритм определения основания
числа по префиксам строки:

=over

=item * 

Если префикс I<0b> - основние 2

=item *

Если префикс I<0> - основние 8

=item *

Если префикс I<0x> - основние 16

=item *

Иначе - основание 10

=back


=head1 API ВЫЗОВЫ


=head2 BH_StringFromDouble

 int BH_StringFromDouble(char *string,
                         size_t size,
                         double value,
                         char format,
                         int precision,
                         size_t *actual);


Форматирует вещественное число I<value> в нуль-терминированную строку I<string>
(с ограничением по длинне I<size>).

Параметр I<format> задает формат преобразования числа в строку. Допустимые 
форматы:

=over

=item B<f>, B<F>

Фиксированный формат: [-]ddd.ddd

=item B<e>, B<E>

Научный формат: [-]d.dddedd

=item B<g>, B<G>

Фиксированный или научный формат, в зависимости от того, какой из них короче

=back

Параметр I<precision> задает точность преобразования числа в строку. Если
значение точности отрицательное, преобразование будет выполнено с минимально 
необходимой точностью, чтобы при обратном преобразовании получилось исходное 
число.

Опциональный параметр I<actual> возвращает длину записанной строки.

Данная функция следует правилу IEEE 754 округление до четного.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringFromInt8s

 int BH_StringFromInt8s(char *string,
                        size_t size,
                        int8_t value,
                        int base,
                        size_t *actual);

Форматирует целое 8-битное знаковое число I<value> в нуль-терминированную строку
I<string> (с ограничением по длинне I<size>). 

Параметр I<base> задает основание для преобразования.

Опциональный параметр I<actual> возвращает длину записанной строки.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringFromInt16s

 int BH_StringFromInt16s(char *string,
                         size_t size,
                         int16_t value,
                         int base,
                         size_t *actual);

Форматирует целое 16-битное знаковое число I<value> в нуль-терминированную 
строку I<string> (с ограничением по длинне I<size>). 

Параметр I<base> задает основание для преобразования.

Опциональный параметр I<actual> возвращает длину записанной строки.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringFromInt32s

 int BH_StringFromInt32s(char *string,
                         size_t size,
                         int32_t value,
                         int base,
                         size_t *actual);

Форматирует целое 32-битное знаковое число I<value> в нуль-терминированную 
строку I<string> (с ограничением по длинне I<size>). 

Параметр I<base> задает основание для преобразования.

Опциональный параметр I<actual> возвращает длину записанной строки.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringFromInt64s

 int BH_StringFromInt64s(char *string,
                         size_t size,
                         int64_t value,
                         int base,
                         size_t *actual);

Форматирует целое 64-битное знаковое число I<value> в нуль-терминированную 
строку I<string> (с ограничением по длинне I<size>). 

Параметр I<base> задает основание для преобразования.

Опциональный параметр I<actual> возвращает длину записанной строки.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringFromInt8u

 int BH_StringFromInt8u(char *string,
                        size_t size,
                        uint8_t value,
                        int base,
                        size_t *actual);

Форматирует целое 8-битное беззнаковое число I<value> в нуль-терминированную 
строку I<string> (с ограничением по длинне I<size>). 

Параметр I<base> задает основание для преобразования.

Опциональный параметр I<actual> возвращает длину записанной строки.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringFromInt16u

 int BH_StringFromInt16u(char *string,
                         size_t size,
                         uint16_t value,
                         int base,
                         size_t *actual);

Форматирует целое 16-битное беззнаковое число I<value> в нуль-терминированную 
строку I<string> (с ограничением по длинне I<size>). 

Параметр I<base> задает основание для преобразования.

Опциональный параметр I<actual> возвращает длину записанной строки.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringFromInt32u

 int BH_StringFromInt32u(char *string,
                         size_t size,
                         uint32_t value,
                         int base,
                         size_t *actual);

Форматирует целое 32-битное беззнаковое число I<value> в нуль-терминированную 
строку I<string> (с ограничением по длинне I<size>). 

Параметр I<base> задает основание для преобразования.

Опциональный параметр I<actual> возвращает длину записанной строки.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringFromInt64u

 int BH_StringFromInt64u(char *string,
                         size_t size,
                         uint64_t value,
                         int base,
                         size_t *actual);

Форматирует целое 64-битное беззнаковое число I<value> в нуль-терминированную 
строку I<string> (с ограничением по длинне I<size>). 

Параметр I<base> задает основание для преобразования.

Опциональный параметр I<actual> возвращает длину записанной строки.

В случае успеха, возвращает 0 или код ошибки.


=head2 BH_StringToDouble

 double BH_StringToDouble(const char *string,
                          size_t *size);

Преобразовывает строку I<string> в вещественное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

В случае успеха, возвращает преобразованное число или 0.


=head2 BH_StringToInt8s

 int8_t BH_StringToInt8s(const char *string,
                         size_t *size,
                         int base);

Преобразовывает строку I<string> в целое знаковое 8-битное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

Опциональный параметр I<base> задает основание числа.

В случае успеха, возвращает преобразованное число или 0.


=head2 BH_StringToInt16s

 int16_t BH_StringToInt16s(const char *string,
                           size_t *size,
                           int base);

Преобразовывает строку I<string> в целое знаковое 16-битное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

Опциональный параметр I<base> задает основание числа.

В случае успеха, возвращает преобразованное число или 0.


=head2 BH_StringToInt32s

 int32_t BH_StringToInt32s(const char *string,
                           size_t *size,
                           int base);

Преобразовывает строку I<string> в целое знаковое 32-битное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

Опциональный параметр I<base> задает основание числа.

В случае успеха, возвращает преобразованное число или 0.


=head2 BH_StringToInt64s

 int64_t BH_StringToInt64s(const char *string,
                           size_t *size,
                           int base);

Преобразовывает строку I<string> в целое знаковое 64-битное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

Опциональный параметр I<base> задает основание числа.

В случае успеха, возвращает преобразованное число или 0.


=head2 BH_StringToInt8u

 uint8_t BH_StringToInt8u(const char *string,
                          size_t *size,
                          int base);

Преобразовывает строку I<string> в целое беззнаковое 8-битное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

Опциональный параметр I<base> задает основание числа.

В случае успеха, возвращает преобразованное число или 0.


=head2 BH_StringToInt16u

 uint16_t BH_StringToInt16u(const char *string,
                            size_t *size,
                            int base);

Преобразовывает строку I<string> в целое беззнаковое 16-битное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

Опциональный параметр I<base> задает основание числа.

В случае успеха, возвращает преобразованное число или 0.


=head2 BH_StringToInt32u

 uint32_t BH_StringToInt32u(const char *string,
                            size_t *size,
                            int base);

Преобразовывает строку I<string> в целое беззнаковое 32-битное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

Опциональный параметр I<base> задает основание числа.

В случае успеха, возвращает преобразованное число или 0.


=head2 BH_StringToInt64u

 uint64_t BH_StringToInt64u(const char *string,
                            size_t *size,
                            int base);

Преобразовывает строку I<string> в целое беззнаковое 64-битное число.

Опциональный параметр I<size> возвращает число прочитанных символов из строки. 

Опциональный параметр I<base> задает основание числа.

В случае успеха, возвращает преобразованное число или 0.


=head1 СМ. ТАКЖЕ

L<BH>