@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 …
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ês9 itens
@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 …
@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 …
@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. É …
@memcpy em Zig — Referência e Exemplos
@memcpy em Zig O @memcpy copia dados de um slice de origem para um slice de destino. Os slices devem ter o mesmo comprimento e não devem se sobrepor na memória. É a forma …
@memset em Zig — Referência e Exemplos
@memset em Zig O @memset preenche uma região de memória (slice) com um valor específico. É a forma idiomática em Zig de inicializar buffers, zerar memória ou preencher …
@popCount em Zig — Referência e Exemplos
@popCount em Zig O @popCount (Population Count) conta o número de bits com valor 1 em um inteiro. Também conhecido como “Hamming weight”. Mapeia diretamente …
@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 …
@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 …