@constCast em Zig — Referência e Exemplos
@constCast em Zig O @constCast remove o qualificador const de um ponteiro, transformando um *const T em *T. Esta operação é necessária em cenários de interoperabilidade …
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
@ctz em Zig — Referência e Exemplos
@ctz em Zig O @ctz (Count Trailing Zeros) conta o número de bits zero consecutivos a partir do bit menos significativo (direita) de um valor inteiro. Mapeia diretamente …
@embedFile em Zig — Referência e Exemplos
@embedFile em Zig O @embedFile incorpora o conteúdo de um arquivo diretamente no binário compilado, em tempo de compilação. Retorna um ponteiro para um array de bytes …
@enumFromInt em Zig — Referência e Exemplos
@enumFromInt em Zig O @enumFromInt cria um valor enum a partir de um valor inteiro. É a operação inversa de @intFromEnum. Este builtin é especialmente útil ao …
@errorName em Zig — Referência e Exemplos
@errorName em Zig O @errorName retorna o nome de um valor de erro como uma string legível. É uma ferramenta essencial para depuração, logging e mensagens de erro …
@field em Zig — Referência e Exemplos
@field em Zig O @field permite acessar campos de structs, unions e enums usando um nome de campo determinado em tempo de compilação (comptime). Isso é fundamental para …
@floatFromInt em Zig — Referência e Exemplos
@floatFromInt em Zig O @floatFromInt converte um valor inteiro para um tipo de ponto flutuante. É a operação inversa de @intFromFloat. Essa conversão é necessária em Zig …
@hasDecl em Zig — Referência e Exemplos
@hasDecl em Zig O @hasDecl verifica em tempo de compilação se um tipo (geralmente um struct, enum ou union) possui uma declaração específica — seja uma função, constante …
@hasField em Zig — Referência e Exemplos
@hasField em Zig O @hasField verifica se um tipo (struct, union ou enum) possui um campo com o nome especificado. Retorna true ou false em tempo de compilação. É …
@import em Zig — Referência e Exemplos
@import em Zig O @import é o builtin mais utilizado em Zig. Ele é responsável por importar módulos, pacotes externos e a biblioteca padrão para o escopo atual do código. …
@intFromBool em Zig — Referência e Exemplos
@intFromBool em Zig O @intFromBool converte um valor booleano para um inteiro: true torna-se 1 e false torna-se 0. Em Zig, não há conversão implícita entre bool e tipos …
@intFromEnum em Zig — Referência e Exemplos
@intFromEnum em Zig O @intFromEnum extrai o valor inteiro subjacente (tag value) de um valor enum. Todo enum em Zig possui internamente um tipo inteiro que representa …