@addWithOverflow em Zig — Referência e Exemplos
@addWithOverflow em Zig O @addWithOverflow realiza uma adição e indica se houve overflow. Retorna uma tupla com o resultado (possivelmente truncado) e um bit de overflow. …
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.
| Builtin | Descrição |
|---|---|
| @import | Importa módulos e pacotes |
| @typeInfo | Obtém informações detalhadas sobre um tipo |
| @typeName | Retorna o nome de um tipo como string |
| @TypeOf | Obtém o tipo de uma expressão |
| @as | Conversão explícita de tipos |
| @intFromPtr | Converte ponteiro para inteiro |
| @ptrFromInt | Converte inteiro para ponteiro |
| @intFromFloat | Converte float para inteiro |
| @floatFromInt | Converte inteiro para float |
| @intFromEnum | Obtém valor inteiro de um enum |
| @enumFromInt | Cria enum a partir de inteiro |
| @intFromBool | Converte booleano para inteiro |
| @errorName | Obtém nome de um erro como string |
| @tagName | Obtém nome do campo ativo de uma union |
| @alignOf | Retorna o alinhamento de um tipo |
| @sizeOf | Retorna o tamanho em bytes de um tipo |
| @bitSizeOf | Retorna o tamanho em bits de um tipo |
Comptime e Metaprogramação
Builtins para operações em tempo de compilação e reflexão.
| Builtin | Descrição |
|---|---|
| @compileError | Gera erro de compilação com mensagem personalizada |
| @compileLog | Imprime valores em tempo de compilação para depuração |
| @field | Acessa campo de struct por nome em tempo de compilação |
| @hasField | Verifica se um tipo possui determinado campo |
| @hasDecl | Verifica se um tipo possui determinada declaração |
| @embedFile | Incorpora arquivo no binário em tempo de compilação |
| @src | Obté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.
| Builtin | Descrição |
|---|---|
| @memset | Preenche região de memória com valor |
| @memcpy | Copia bloco de memória |
| @ptrCast | Conversão entre tipos de ponteiro |
| @alignCast | Converte alinhamento de ponteiro |
| @constCast | Remove qualificador const de ponteiro |
| @volatileCast | Remove qualificador volatile de ponteiro |
Matemática e Operações Bit a Bit
Builtins para aritmética segura e manipulação de bits.
| Builtin | Descrição |
|---|---|
| @addWithOverflow | Adição com detecção de overflow |
| @subWithOverflow | Subtração com detecção de overflow |
| @mulWithOverflow | Multiplicação com detecção de overflow |
| @shlExact | Shift left exato (sem perda de bits) |
| @shrExact | Shift right exato (sem perda de bits) |
| @min | Retorna o menor de dois valores |
| @max | Retorna o maior de dois valores |
| @clz | Conta zeros à esquerda (leading zeros) |
| @ctz | Conta zeros à direita (trailing zeros) |
| @popCount | Conta bits em 1 (population count) |
| @byteSwap | Inverte a ordem dos bytes |
| @bitReverse | Inverte a ordem dos bits |
Outros Builtins
| Builtin | Descrição |
|---|---|
| @panic | Encerra execução com mensagem de pânico |
| @cImport / @cInclude | Importa cabeçalhos C para uso em Zig |
| @call | Chama função com controle avançado de invocação |
Como usar esta referência
Cada página de builtin contém:
- Assinatura de sintaxe — A forma completa de chamar o builtin
- Descrição — Explicação detalhada do que o builtin faz
- Parâmetros — Descrição de cada parâmetro aceito
- Valor de retorno — O que o builtin retorna
- Exemplos práticos — Código funcional demonstrando uso real
- Casos de uso comuns — Cenários onde o builtin é mais útil
- 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:@intFromFloatconverte float para int) - Prefixo @: Todos os builtins começam com
@para distingui-los de funções comuns - TypeOf com T maiúsculo:
@TypeOfusa 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
Funções Builtin do Zig — Referência Completa em Português45 itens
@alignCast em Zig — Referência e Exemplos
@alignCast em Zig O @alignCast converte um ponteiro para ter um alinhamento diferente. É necessário quando você precisa converter ponteiros entre tipos com requisitos de …
@alignOf em Zig — Referência e Exemplos
@alignOf em Zig O @alignOf retorna o alinhamento de memória de um tipo em bytes. O alinhamento determina em quais endereços de memória um valor desse tipo pode ser …
@as em Zig — Referência e Exemplos
@as em Zig O @as é o builtin de conversão explícita de tipos (type cast) do Zig. Ele permite converter um valor de um tipo para outro de forma segura e explícita, …
@bitReverse em Zig — Referência e Exemplos
@bitReverse em Zig O @bitReverse inverte a ordem de todos os bits de um valor inteiro — o bit mais significativo se torna o menos significativo e vice-versa. Diferente de …
@bitSizeOf em Zig — Referência e Exemplos
@bitSizeOf em Zig O @bitSizeOf retorna o tamanho de um tipo em bits, sem incluir padding de alinhamento. Diferente de @sizeOf, que retorna bytes incluindo padding, …
@byteSwap em Zig — Referência e Exemplos
@byteSwap em Zig O @byteSwap inverte a ordem dos bytes de um valor inteiro. É a operação fundamental para converter entre big-endian e little-endian, essencial para …
@call em Zig — Referência e Exemplos
@call em Zig O @call invoca uma função com controle avançado sobre como a chamada é realizada. Permite forçar inlining, prevenir tail calls, controlar otimizações de …
@cImport em Zig — Referência e Exemplos
@cImport / @cInclude em Zig O @cImport importa cabeçalhos C diretamente para Zig, permitindo chamar funções C sem escrever bindings manuais. Dentro do bloco @cImport, use …
@clz em Zig — Referência e Exemplos
@clz em Zig O @clz (Count Leading Zeros) conta o número de bits zero consecutivos a partir do bit mais significativo (esquerda) de um valor inteiro. É uma operação …
@compileError em Zig — Referência e Exemplos
@compileError em Zig O @compileError gera um erro de compilação com uma mensagem personalizada. É usado principalmente em código genérico e metaprogramação para rejeitar …
@compileLog em Zig — Referência e Exemplos
@compileLog em Zig O @compileLog imprime valores em tempo de compilação, permitindo depurar código comptime. Quando presente no código, o compilador exibe os valores e …