@shrExact em Zig — Referência e Exemplos
@shrExact em Zig O @shrExact realiza um shift right (deslocamento à direita) e garante que nenhum bit significativo é perdido (descartado pela parte inferior). Se algum …
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
@sizeOf em Zig — Referência e Exemplos
@sizeOf em Zig O @sizeOf retorna o tamanho de armazenamento de um tipo em bytes, incluindo qualquer padding de alinhamento. É o equivalente do sizeof do C, mas disponível …
@src em Zig — Referência e Exemplos
@src em Zig O @src retorna uma struct com informações sobre a localização no código-fonte onde ele é invocado — incluindo o nome do arquivo, número da linha e coluna. …
@subWithOverflow em Zig — Referência e Exemplos
@subWithOverflow em Zig O @subWithOverflow realiza uma subtração e indica se houve overflow (ou underflow). Retorna uma tupla com o resultado (possivelmente truncado) e …
@tagName em Zig — Referência e Exemplos
@tagName em Zig O @tagName retorna o nome do campo ativo de uma tagged union ou o nome de uma variante de enum como string. É fundamental para serialização, logging e …
@typeInfo em Zig — Referência e Exemplos
@typeInfo em Zig O @typeInfo é um dos builtins mais poderosos do Zig para metaprogramação. Ele permite inspecionar qualquer tipo em tempo de compilação, retornando uma …
@typeName em Zig — Referência e Exemplos
@typeName em Zig O @typeName é um builtin que retorna o nome de qualquer tipo como uma string legível. É extremamente útil para depuração, logging e geração de mensagens …
@TypeOf em Zig — Referência e Exemplos
@TypeOf em Zig O @TypeOf é um builtin que deduz e retorna o tipo de qualquer expressão em tempo de compilação. É o equivalente ao decltype do C++ ou ao typeof do …
@volatileCast em Zig — Referência e Exemplos
@volatileCast em Zig O @volatileCast remove o qualificador volatile de um ponteiro. Ponteiros volatile indicam que a memória apontada pode ser modificada externamente …