Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C++

std::to_chars — escrever um número num buffer de caracteres

std::to_chars escreve a representação textual de um número num buffer fornecido pelo chamador. O resultado contém um apontador para o fim e um código de erro; a função não acrescenta um '\0' terminador.

Versão: C++23; repository compiler flag, production runtime not attested

Sintaxe

#include <charconv>
std::to_chars(first, last, value);
std::to_chars(first, last, integer_value, base);
std::to_chars(first, last, floating_value, fmt);
std::to_chars(first, last, floating_value, fmt, precision);

std::to_chars, declarada em <charconv>, escreve um número no intervalo válido e gravável [first, last). Não acrescenta '\0' nem lança exceções. Trata os dados obtidos como um intervalo de caracteres, e não automaticamente como uma cadeia terminada em nulo.

O std::to_chars_result devolvido contém std::to_chars_result::ptr, do tipo char*, e std::to_chars_result::ec, do tipo std::errc. Quando ec == std::errc{}, a conversão foi bem-sucedida: ptr aponta imediatamente após o último carácter escrito e ptr - first indica o comprimento. Se o buffer for demasiado pequeno, ec == std::errc::value_too_large e ptr == last; o conteúdo do intervalo não é especificado. Não uses esse buffer como resultado parcial.

Para inteiros, base é 10 por omissão e tem de estar entre 2 e 36. Os algarismos acima de 9 são escritos como a–z; os valores negativos recebem -. A sobrecarga para bool foi eliminada. As sobrecargas de vírgula flutuante aceitam opcionalmente std::chars_format e uma precisão; usam as regras de formatação da localização "C", independentemente das definições de localização atuais.

O exemplo verifica ec antes de usar ptr e constrói um std::string_view com comprimento explícito. Destina-se a ser compilado com -std=c++23; não atesta o comportamento em execução num ambiente de produção. As fontes eel.is apresentam um projeto de norma em evolução, pelo que podem conter adições posteriores a C++23.

Exemplos

#include <charconv>
#include <cstddef>
#include <iostream>
#include <string_view>
#include <system_error>

int main() {
    char buffer[16];
    const std::to_chars_result result =
        std::to_chars(buffer, buffer + sizeof buffer, 255, 16);

    if (result.ec != std::errc{}) {
        std::cerr << "conversion failed\n";
        return 1;
    }

    const std::string_view text(
        buffer, static_cast<std::size_t>(result.ptr - buffer));
    std::cout << text << '\n';
}

Resultado

ff

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes