Pular para o conteúdo principal

Biblioteca padrão BASICGOL (Fase 5)

A biblioteca padrão reúne utilidades pequenas para os programas BASICGOL e para C comum. O núcleo é C11 portátil, divide-se por responsabilidade e usa stdio, string, stdlib e math da plataforma em vez de duplicá-los. Os headers são independentes; <basicgol/biblioteca.h> agrega os cinco módulos. <basicgol.h> também os inclui e preserva os nomes de linguagem (COPIA_TEXTO, LEIA_INTEIRO, ABS etc.).

1. Módulos e arquivos​

MóduloHeader públicoImplementaçãoEscopo
Consolebasicgol/consola.hsrc/biblioteca/consola.cleitura de linhas, leitura numérica por linha, escrita literal e diagnóstico
Matemáticabasicgol/matematica.hsrc/biblioteca/matematica.cdivisão/resto verificados e primitivas de ABS, MINIMO, MAXIMO e ARREDONDA
Textobasicgol/texto.hsrc/biblioteca/texto.coperações limitadas sobre strings C e conversões numéricas
Caracterebasicgol/caractere.hsrc/biblioteca/caractere.cclassificação e mudança de caixa ASCII
Utilidadesbasicgol/utilidades.hsrc/biblioteca/utilidades.csemente e sorteio com PRNG próprio (xorshift64*) portável
Agregadobasicgol/biblioteca.h—inclui os cinco headers portáteis e informa a versão 1.0.0

Inclua somente o módulo necessário ou use o agregado:

#include <basicgol/biblioteca.h>

A interface de palavras-chave #include <basicgol.h> reexporta esses módulos para compatibilidade. Ao chamar helpers, ligue a biblioteca compilada; não é header-only.

2. Convenções da API​

  • Nomes: funções C usam o prefixo bg_ e palavras em português; macros de linguagem continuam em maiúsculas (TEXTO_PARA_INTEIRO, ESCREVAL).
  • Sucesso e erro recuperável: funções que podem falhar devolvem bool: true significa sucesso e false, argumento inválido, entrada inválida, truncamento, falha de conversão ou erro de E/S. Não há código global de erro nem encerramento silencioso.
  • Saídas: em falha, ponteiros de saída numéricos permanecem inalterados. Uma função que escreve em string deixa destino[0] == '\0' em falha sempre que destino e capacidade permitem escrever esse terminador.
  • Memória: o chamador aloca e libera os buffers. A biblioteca não retém ponteiros nem transfere propriedade. bg_junta_texto usa temporário interno para suportar sobreposição; esse armazenamento é liberado antes de retornar.
  • Strings: são strings C terminadas em NUL; todos os limites e posições contam bytes, não caracteres Unicode. A capacidade inclui o byte NUL. O chamador deve passar ponteiros para objetos válidos e, quando aplicável, buffers realmente tão grandes quanto a capacidade informada.
  • Fatal, por compatibilidade da linguagem: bg_erro imprime o diagnóstico e encerra com status 1. DIVIDE, RESTO e ABS usam esse caminho quando a operação não é definida ou o resultado não cabe (por exemplo, divisor zero; em representações usuais, INT_MIN / -1 e ABS(INT_MIN)). Para novas funções, prefira retorno bool.
  • Locale e concorrência: os helpers de caractere são sempre ASCII. Conversão de real acompanha a locale C corrente (strtod); BASICGOL não chama setlocale. o PRNG próprio (xorshift64*) compartilha estado global do processo e não fornece garantia de segurança entre threads.

3. API por módulo​

3.1 Console — basicgol/consola.h​

FunçãoParâmetrosRetorno e efeito
bg_leia_linha(entrada, destino, capacidade)entrada: FILE * aberto para leitura; destino: buffer; capacidade: bytes totais, incluindo NULtrue para uma linha completa. Remove LF, CRLF ou CR. Linha vazia é válida. EOF sem bytes, NUL embutido, erro e linha longa devolvem false; linha longa é drenada e o destino fica vazio.
bg_leia_texto(destino, capacidade)buffer e capacidade; usa stdintrue/false como acima. Compatibilidade com LEIA_TEXTO: consome um LF ou CRLF pendente de uma leitura formatada. Para preservar uma linha vazia, use bg_leia_linha(stdin, ...).
bg_leia_inteiro_de(entrada, saida)fluxo e ponteiro para intLê uma linha inteira e converte decimal; false em EOF, linha longa, texto inválido ou overflow. Em falha *saida não muda.
bg_leia_real_de(entrada, saida)fluxo e ponteiro para doubleLê uma linha e converte via strtod; mesmos critérios de falha, incluindo overflow/underflow sinalizado por ERANGE.
bg_leia_inteiro(saida)ponteiro para int; usa stdinIgual a bg_leia_inteiro_de, com compatibilidade de descarte do terminador pendente.
bg_leia_real(saida)ponteiro para double; usa stdinIgual a bg_leia_real_de, com compatibilidade de descarte do terminador pendente.
bg_escreva_texto(saida, texto)FILE * de saída e texto literal não nulotrue se fputs concluir; não interpreta % como formato e não adiciona quebra de linha.
bg_escreva_linha(saida, texto)fluxo de saída e texto literal não nuloEscreve o texto e LF; true se ambas as escritas concluírem. Pode haver saída parcial se o fluxo falhar no meio.
bg_erro(arquivo, linha, mensagem)origem, linha e mensagemNão retorna: escreve arquivo:linha: erro: mensagem em stderr e encerra com status 1. NULL vira ?/texto vazio.
bg_passo_zero(arquivo, linha)origem e linhaNão retorna: emite diagnóstico de passo zero via bg_erro. O retorno declarado int existe somente para uso em expressão C.

bg_leia_linha consome um terminador por chamada. Em EOF, devolve false se não havia bytes; se havia uma última linha sem terminador, essa linha é sucesso. A função não fecha nem toma posse do FILE *.

3.2 Matemática — basicgol/matematica.h​

As funções bg_divide_i/l/ll/u/ul/ull/f/d/ld(a, b, arquivo, linha) recebem dois operandos do sufixo indicado (i = int, l = long, ll = long long, u/ul/ull sem sinal, f/d/ld real). Devolvem o quociente no mesmo tipo. Zero como divisor é fatal; para inteiros com sinal, também é fatal se o quociente não couber (em geral, MIN / -1). Os parâmetros arquivo e linha identificam o ponto de uso; os macros DIVIDE e BG_DIVIDE os preenchem automaticamente.

As funções bg_resto_i/l/ll/u/ul/ull(a, b, arquivo, linha) têm a mesma convenção de parâmetros e retorno, para resto inteiro. Divisor zero e quociente não representável (geralmente MIN % -1) são fatais. Para capturar esses casos no programa, use RESTO/BG_RESTO; / e MOD continuam sendo operadores C não verificados.

FunçãoParâmetrosRetorno
bg_abs_i, bg_abs_l, bg_abs_llvalor int, long ou long longvalor absoluto no mesmo tipo; é fatal quando a magnitude excede o máximo positivo (em geral no mínimo assinado).
bg_abs_f, bg_abs_dfloat ou doublevalor absoluto do mesmo tipo, por fabsf/fabs; NaN segue a semântica da libm.
bg_min_i, bg_min_l, bg_min_ddois operandos do tipo indicadomenor dos dois, no mesmo tipo; o caso double usa fmin.
bg_max_i, bg_max_l, bg_max_ddois operandos do tipo indicadomaior dos dois, no mesmo tipo; o caso double usa fmax.
bg_round_l(valor)double finito cujo arredondamento cabe em long longlong long mais próximo; empates arredondam para longe de zero (llround). Fora do domínio documentado, vale a condição de domínio de llround.

As macros didáticas POTENCIA, RAIZ, PISO e TETO usam, respectivamente, pow, sqrt, floor e ceil de <math.h>; os resultados e domínios são os da biblioteca matemática C. ARREDONDA usa llround e devolve long long. O programa que usa essas funções deve ligar -lm quando a plataforma mantém a libm separada.

3.3 Texto — basicgol/texto.h​

FunçãoParâmetrosRetorno
bg_tamanho_texto(texto)string C ou NULLcomprimento em bytes (strlen); NULL equivale a vazio.
bg_copia_texto(destino, capacidade, origem)buffer, capacidade incluindo NUL, string de origemtrue se couber inteira; NULL como origem vazia. Em falha limpa destino quando utilizável. Suporta origem/destino sobrepostos.
bg_junta_texto(destino, capacidade, primeiro, segundo)buffer, capacidade e duas stringstrue se a concatenação couber; NULL equivale a vazio. Suporta sobreposição entre origens e destino; falha por falta de espaço ou alocação devolve false e limpa destino.
bg_acrescenta_texto(destino, capacidade, origem)buffer já terminado em NUL, capacidade real e origemacrescenta a origem inteira; aceita autoacréscimo. false se inválido/não couber, limpando destino quando possível.
bg_trecho_texto(destino, capacidade, origem, inicio, quantidade)buffer, origem, índice inicial e número máximo de bytescopia no máximo a quantidade disponível. Início além do fim produz vazio com true; falta de espaço devolve false.
bg_compara_texto(primeiro, segundo)duas strings; NULL equivale a ""comparação lexicográfica normalizada: -1, 0 ou 1.
bg_texto_vazio(texto)string ou NULLtrue se vazio ou nulo.
bg_formata_texto(destino, capacidade, formato, ...)buffer, capacidade e formato de printf com argumentos correspondentesusa vsnprintf; true se a saída inteira couber. Em truncamento, formato nulo ou falha, limpa destino e devolve false. O compilador C não verifica a correspondência do formato.
bg_texto_para_inteiro(texto, saida)string decimal e int *aceita o número inteiro completo, com espaços ASCII nas bordas; recusa sobra e overflow. false não altera *saida.
bg_texto_para_natural(texto, saida)string decimal não negativa e unsigned *aceita + opcional; recusa -, sobra e overflow. false não altera *saida.
bg_texto_para_real(texto, saida)string e double *conversão de strtod na locale atual; exige consumo integral (espaços ASCII finais são tolerados) e recusa ERANGE. false não altera *saida.
bg_numero_para_inteiro(valor, saida)double e int *trunca em direção a zero; NaN e valores fora da faixa de int falham sem alterar *saida.

As conversões textuais preservam errno; o resultado de erro é o booleano, não um código global. bg_formata_texto segue as regras de printf: passar argumentos com tipo incompatível com o formato é erro do chamador. Para escrita literal em console, use bg_escreva_texto, não a função de formatação.

3.4 Caractere — basicgol/caractere.h​

FunçãoParâmetroRetorno
bg_e_digito(c)byte em chartrue somente para ASCII '0' a '9'.
bg_e_letra(c)byte em chartrue somente para ASCII A-Z ou a-z.
bg_caractere_maiusculo(c)byte em charconverte ASCII a-z para A-Z; todos os demais bytes não mudam.
bg_caractere_minusculo(c)byte em charconverte ASCII A-Z para a-z; todos os demais bytes não mudam.

Não é uma API Unicode: bytes UTF-8 fora de ASCII passam inalterados. O contrato é independente de locale e não sofre as restrições de argumento negativo de <ctype.h>.

3.5 Utilidades e aleatoriedade — basicgol/utilidades.h​

FunçãoParâmetrosRetorno
bg_inicia_sorteio(semente)semente unsignednão devolve valor; deriva o estado por splitmix64. Não há semente automática.
bg_sorteia_ate(limite_exclusivo, saida)limite positivo (qualquer unsigned, até 2^32−1) e ponteiro unsigned *true e um valor em [0, limite); false para limite zero ou ponteiro nulo. Falha não altera *saida.
bg_sorteia(n)limite legado intvalor em [0,n); devolve 0 para n <= 0. Prefira a variante verificável bg_sorteia_ate.

O gerador é próprio (xorshift64*, com semente de 32 bits derivada por splitmix64), o que independe da libc: repetir a mesma semente reproduz a sequência em qualquer plataforma C11. Ele é previsível e global ao processo; não é criptográfico, não é adequado para tokens/segurança e não promete independência entre threads. A rejeição em bg_sorteia_ate remove o viés de módulo supondo amostras uniformes dos 32 bits de estado.

4. Nomes da linguagem e compatibilidade​

<basicgol.h> mantém os helpers didáticos e os aliases BG_*/nomes curtos descritos em 02 — Referência. As operações de string e caractere encaminham para os módulos correspondentes. ESCREVA_TEXTO e ESCREVA_ERRO escrevem texto literal e agora devolvem o booleano da escrita. LEIA_TEXTO, LEIA_INTEIRO e LEIA_REAL continuam usando stdin. Os formatos ESCREVA_FMT e LEIA continuam sendo os da biblioteca C.

O único módulo de compilador opcional continua sendo BG_USAR_EXTENSOES em basicgol.h (GCC/Clang); ele é independente da biblioteca padrão. Não há helpers específicos de plataforma nesta versão. Por isso não há dependência de POSIX, Windows, unistd.h ou windows.h, nem headers de plataforma no agregado. Uma futura extensão de plataforma deve ter header e implementação separados, não incluídos pelo core portátil.

5. Compilação e dependências​

Compilar com o Makefile do projeto​

make # build/basicgolc e build/libbasicgol.a
make biblioteca # somente a biblioteca estática
make test # testes da linguagem e da biblioteca
make test-biblioteca # somente os testes unitários dos módulos
make exemplos # compila os exemplos

Ligar um programa​

make biblioteca
cc -std=c11 -Wall -Wextra -Wformat=2 -Wvla -Werror \
-I include programa.c build/libbasicgol.a -lm -o programa
./programa

A ordem importa em toolchains Unix: objetos/fontes primeiro, archive depois, -lm por último. Se a plataforma já incorpora libm, omita -lm. Também é possível compilar as implementações diretamente, sem criar o archive:

cc -std=c11 -Wall -Wextra -I include programa.c \
src/biblioteca/*.c -lm -o programa

Para o caminho M1, gere o C e ligue a mesma biblioteca:

make
build/basicgolc programa.c -o programa.gerado.c
cc -std=c11 -Wall -Wextra -I include programa.gerado.c \
build/libbasicgol.a -lm -o programa

Inventário mínimo​

ItemUso
Compilador C11 hospedado (cc, GCC, Clang ou compatível)compilação do core e do programa
Biblioteca padrão C (libc)stdio, stdlib, string, conversões, alocação e I/O
Biblioteca matemática C (libm, quando separada)pow, sqrt, round/llround, floor, ceil, fabs, fmin, fmax
make e arbuild e archive estático; não necessários para compilar diretamente os fontes
Bash, mktemp, diff e Python 3runner de testes e geração da matriz de cobertura
Dependências de terceirosnenhuma

6. Demonstrações e testes​

Os exemplos docs/exemplos/biblioteca_{consola,matematica,texto,caractere,utilidades}.c demonstram um programa pequeno por módulo. Eles são compilados e executados com entradas/saídas douradas pela suíte regular.

tests/test_biblioteca.c exercita a API diretamente: entradas vazias e longas, terminadores LF/CRLF, EOF, NUL embutido, limites e sobreposição de buffers, conversões válidas/inválidas/fora de faixa, ASCII, limites matemáticos, sequência aleatória, entradas inválidas e diagnósticos fatais. make test-biblioteca executa os 230 checks unitários e os casos de integração em processos separados para as rotinas fatais.

Consulte tests/README.md para a suíte completa. A licença é Apache-2.0, igual à do restante do repositório.

Símbolos citados neste documento​

Nomes que aparecem literalmente no texto acima e que possuem página de referência gerada do fonte:

bg_erro, bg_leia_linha, bg_sorteia_ate, bg_escreva_texto, bg_formata_texto, bg_junta_texto, bg_leia_inteiro_de, bg_leia_real_de, BG_DIVIDE, BG_RESTO, BG_USAR_EXTENSOES, bg_abs_d, bg_abs_f, bg_abs_i, bg_abs_l, bg_abs_ll, bg_acrescenta_texto, bg_caractere_maiusculo.

Perguntas frequentes​

Perguntas frequentes sobre este documento, respondidas a partir do conteúdo versionado e da referência gerada.

Preciso linkar -lm?​

No caminho GCC/Clang sim, quando o programa usa funções de matemática: o glibc separa libm. A ordem importa — fonte/objeto, depois build/libbasicgol.a, e -lm por último. O CRT do MSVC não usa essa flag.

make biblioteca
cc -std=c11 -Wall -Wextra -Wformat=2 -I include programa.c \
build/libbasicgol.a -lm -o programa

Como a biblioteca reporta erro?​

Funções recuperáveis devolvem LOGICO: false significa argumento inválido, entrada inválida, truncamento ou falha de E/S. Saídas numéricas não são alteradas em falha e strings ficam vazias quando há espaço para o NUL.

Poucas operações são fatais por decisão de linguagem: bg_erro, DIVIDE, RESTO e ABS em casos não definidos ou não representáveis.

Quem é dono da memória dos buffers?​

O chamador. A biblioteca não retém ponteiros nem transfere propriedade; bg_junta_texto usa um temporário interno e o libera antes de retornar. Capacidade é sempre em bytes, incluindo o NUL.

A biblioteca pode ser usada de C++?​

Sim, de forma opcional: os cabeçalhos foram corrigidos para compilar em C++ (DF-03) e o teste cpp_inclusao.cpp cobre a inclusão. C++ não é a linguagem-alvo nem muda a API.