@intFromFloat em Zig — Referência e Exemplos
@intFromFloat em Zig O @intFromFloat converte um valor de ponto flutuante para um tipo inteiro, truncando a parte fracionária. Diferente de conversões implícitas em C que …
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
@intFromPtr em Zig — Referência e Exemplos
@intFromPtr em Zig O @intFromPtr converte um ponteiro para seu valor numérico de endereço de memória, representado como um usize. Esse builtin é essencial para …
@max em Zig — Referência e Exemplos
@max em Zig O @max retorna o maior de dois valores. Funciona com inteiros, floats e valores comptime. Se os dois valores forem conhecidos em comptime, o resultado também …
@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 …
@min em Zig — Referência e Exemplos
@min em Zig O @min retorna o menor de dois valores. Funciona com inteiros, floats e valores comptime. Se os dois valores forem conhecidos em comptime, o resultado também …
@mulWithOverflow em Zig — Referência e Exemplos
@mulWithOverflow em Zig O @mulWithOverflow realiza uma multiplicação e indica se houve overflow. Retorna uma tupla com o resultado (possivelmente truncado) e um bit de …
@panic em Zig — Referência e Exemplos
@panic em Zig O @panic encerra a execução do programa imediatamente com uma mensagem de erro e, em modo debug, um stack trace. É usado para situações irrecuperáveis onde …
@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 …
@ptrCast em Zig — Referência e Exemplos
@ptrCast em Zig O @ptrCast converte um ponteiro de um tipo para outro. É a forma principal de reinterpretar dados na memória através de ponteiros com tipos diferentes. …
@ptrFromInt em Zig — Referência e Exemplos
@ptrFromInt em Zig O @ptrFromInt converte um valor inteiro (usize) para um ponteiro tipado. É a operação inversa de @intFromPtr. Este builtin é essencial para programação …
@shlExact em Zig — Referência e Exemplos
@shlExact em Zig O @shlExact realiza um shift left (deslocamento à esquerda) e garante que nenhum bit significativo é perdido (descartado pelo topo). Se algum bit 1 for …