Funções Builtin do Zig — Referência Completa em Português

Funções Builtin do Zig — Referência Completa

As funções builtin do Zig são operações especiais fornecidas diretamente pelo compilador. Diferente de funções comuns da biblioteca padrão, os builtins são resolvidos em tempo de compilação ou mapeados diretamente para instruções de máquina otimizadas. Eles são identificados pelo prefixo @ e não podem ser redefinidos pelo programador.

Por que usar builtins?

Os builtins existem por motivos fundamentais na filosofia do Zig:

  • Desempenho: Mapeiam diretamente para instruções de CPU ou são resolvidos em tempo de compilação, sem overhead de chamada de função.
  • Segurança: Fornecem operações seguras onde a linguagem C dependeria de comportamento indefinido (como aritmética com overflow).
  • Metaprogramação: Permitem introspecção de tipos e geração de código em tempo de compilação.
  • Interoperabilidade: Facilitam a integração com código C existente.

Categorias de Builtins

Operações de Tipo

Builtins para conversão, introspecção e manipulação de tipos.

BuiltinDescrição
@importImporta módulos e pacotes
@typeInfoObtém informações detalhadas sobre um tipo
@typeNameRetorna o nome de um tipo como string
@TypeOfObtém o tipo de uma expressão
@asConversão explícita de tipos
@intFromPtrConverte ponteiro para inteiro
@ptrFromIntConverte inteiro para ponteiro
@intFromFloatConverte float para inteiro
@floatFromIntConverte inteiro para float
@intFromEnumObtém valor inteiro de um enum
@enumFromIntCria enum a partir de inteiro
@intFromBoolConverte booleano para inteiro
@errorNameObtém nome de um erro como string
@tagNameObtém nome do campo ativo de uma union
@alignOfRetorna o alinhamento de um tipo
@sizeOfRetorna o tamanho em bytes de um tipo
@bitSizeOfRetorna o tamanho em bits de um tipo

Comptime e Metaprogramação

Builtins para operações em tempo de compilação e reflexão.

BuiltinDescrição
@compileErrorGera erro de compilação com mensagem personalizada
@compileLogImprime valores em tempo de compilação para depuração
@fieldAcessa campo de struct por nome em tempo de compilação
@hasFieldVerifica se um tipo possui determinado campo
@hasDeclVerifica se um tipo possui determinada declaração
@embedFileIncorpora arquivo no binário em tempo de compilação
@srcObtém informações sobre localização no código-fonte

Operações de Memória

Builtins para manipulação e conversão de ponteiros e memória.

BuiltinDescrição
@memsetPreenche região de memória com valor
@memcpyCopia bloco de memória
@ptrCastConversão entre tipos de ponteiro
@alignCastConverte alinhamento de ponteiro
@constCastRemove qualificador const de ponteiro
@volatileCastRemove qualificador volatile de ponteiro

Matemática e Operações Bit a Bit

Builtins para aritmética segura e manipulação de bits.

BuiltinDescrição
@addWithOverflowAdição com detecção de overflow
@subWithOverflowSubtração com detecção de overflow
@mulWithOverflowMultiplicação com detecção de overflow
@shlExactShift left exato (sem perda de bits)
@shrExactShift right exato (sem perda de bits)
@minRetorna o menor de dois valores
@maxRetorna o maior de dois valores
@clzConta zeros à esquerda (leading zeros)
@ctzConta zeros à direita (trailing zeros)
@popCountConta bits em 1 (population count)
@byteSwapInverte a ordem dos bytes
@bitReverseInverte a ordem dos bits

Outros Builtins

BuiltinDescrição
@panicEncerra execução com mensagem de pânico
@cImport / @cIncludeImporta cabeçalhos C para uso em Zig
@callChama função com controle avançado de invocação

Como usar esta referência

Cada página de builtin contém:

  1. Assinatura de sintaxe — A forma completa de chamar o builtin
  2. Descrição — Explicação detalhada do que o builtin faz
  3. Parâmetros — Descrição de cada parâmetro aceito
  4. Valor de retorno — O que o builtin retorna
  5. Exemplos práticos — Código funcional demonstrando uso real
  6. Casos de uso comuns — Cenários onde o builtin é mais útil
  7. Builtins relacionados — Links para builtins complementares

Convenções de nomenclatura

O Zig segue convenções consistentes na nomenclatura dos builtins:

  • camelCase: Todos os builtins usam camelCase (ex: @intFromFloat)
  • Direção de conversão: Conversões seguem o padrão @destinoFromOrigem (ex: @intFromFloat converte float para int)
  • Prefixo @: Todos os builtins começam com @ para distingui-los de funções comuns
  • TypeOf com T maiúsculo: @TypeOf usa T maiúsculo pois retorna um tipo (que em Zig é um valor de primeira classe em comptime)

Compatibilidade

Esta referência é baseada no Zig 0.13.x e versões recentes do compilador. Alguns builtins podem ter comportamento diferente em versões anteriores. Consulte sempre a documentação oficial para detalhes específicos da versão que você está utilizando.

Tutoriais relacionados