--- title: "@intFromFloat em Zig — Referência e Exemplos" url: "https://ziglang.com.br/builtins/@intfromfloat-em-zig-refer%C3%AAncia-e-exemplos/" markdown_url: "https://ziglang.com.br/builtins/@intfromfloat-em-zig-refer%C3%AAncia-e-exemplos.MD" description: "Referência completa do @intFromFloat em Zig. Aprenda a converter valores de ponto flutuante para inteiros com exemplos práticos." date: "2026-02-21" author: "Zig Brasil" --- # @intFromFloat em Zig — Referência e Exemplos Referência completa do @intFromFloat em Zig. Aprenda a converter valores de ponto flutuante para inteiros com exemplos práticos. # @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 podem gerar comportamento indefinido, o Zig torna essa conversão explícita e definida, garantindo que o programador esteja ciente da perda de precisão. ## Sintaxe ```zig @intFromFloat(valor: anytype) IntType ``` O tipo de retorno é inferido pelo contexto onde o resultado é usado. ## O que faz O `@intFromFloat` converte um valor de ponto flutuante (`f16`, `f32`, `f64`, `f80`, `f128`) para um tipo inteiro. A parte fracionária é truncada (arredondada em direção a zero). Se o valor estiver fora do intervalo representável pelo tipo inteiro de destino, o resultado é um comportamento de segurança ilegal (safety-checked illegal behavior) — o que em modo debug causa um panic. ## Parâmetros - **valor** (`anytype`): Um valor de ponto flutuante a ser convertido. Deve ser um tipo float válido (`f16`, `f32`, `f64`, `f80`, `f128` ou `comptime_float`). ## Valor de retorno Retorna o valor truncado como o tipo inteiro de destino, inferido pelo contexto. A parte fracionária é descartada. ## Exemplos práticos ### Exemplo 1: Conversões básicas ```zig const std = @import("std"); test "conversão float para inteiro" { const a: f64 = 42.7; const b: f64 = -15.9; const c: f64 = 0.99; const x: i32 = @intFromFloat(a); const y: i32 = @intFromFloat(b); const z: i32 = @intFromFloat(c); // Truncamento: parte fracionária é descartada try std.testing.expect(x == 42); // 42.7 -> 42 try std.testing.expect(y == -15); // -15.9 -> -15 (trunca em direção a zero) try std.testing.expect(z == 0); // 0.99 -> 0 } ``` ### Exemplo 2: Conversão em cálculos gráficos ```zig const std = @import("std"); const Ponto = struct { x: i32, y: i32, }; fn pontoNaTela(x_mundo: f64, y_mundo: f64, escala: f64) Ponto { return .{ .x = @intFromFloat(x_mundo * escala), .y = @intFromFloat(y_mundo * escala), }; } test "conversão para coordenadas de pixel" { const ponto = pontoNaTela(3.7, 2.1, 100.0); try std.testing.expect(ponto.x == 370); try std.testing.expect(ponto.y == 210); } ``` ### Exemplo 3: Arredondamento antes da conversão ```zig const std = @import("std"); fn arredondar(valor: f64) i64 { // @intFromFloat trunca, então somamos 0.5 para arredondar if (valor >= 0) { return @intFromFloat(valor + 0.5); } else { return @intFromFloat(valor - 0.5); } } fn teto(valor: f64) i64 { const truncado: i64 = @intFromFloat(valor); const como_float: f64 = @floatFromInt(truncado); if (como_float < valor) return truncado + 1; return truncado; } test "arredondamento personalizado" { try std.testing.expect(arredondar(3.7) == 4); try std.testing.expect(arredondar(3.2) == 3); try std.testing.expect(arredondar(-2.6) == -3); try std.testing.expect(teto(3.1) == 4); try std.testing.expect(teto(3.0) == 3); try std.testing.expect(teto(-2.3) == -2); } ``` ## Casos de uso comuns 1. **Renderização gráfica**: Converter coordenadas de mundo (float) para coordenadas de pixel (inteiro). 2. **Processamento de áudio**: Converter amostras de ponto flutuante (normalizadas entre -1.0 e 1.0) para valores inteiros de PCM. 3. **Física e simulação**: Converter resultados de cálculos físicos para índices de grade ou posições discretas. 4. **Formatação de números**: Extrair a parte inteira de um número para exibição. 5. **Quantização**: Converter valores contínuos para valores discretos em processamento de sinais. ## Cuidados importantes - Se o valor float for `NaN`, `+Inf` ou `-Inf`, a conversão causa panic em modo debug. - Se o valor truncado estiver fora do intervalo do tipo inteiro de destino, também causa panic em modo debug. - Em modo `ReleaseFast`, esses casos resultam em comportamento indefinido, assim como em C. ## Comportamento de truncamento vs. arredondamento O `@intFromFloat` **sempre trunca** em direção a zero — não arredonda para o inteiro mais próximo. Esse comportamento é consistente e previsível: ```zig // Todos truncam em direção a zero: @intFromFloat(3.9) // → 3 (trunca para baixo) @intFromFloat(3.1) // → 3 (trunca para baixo) @intFromFloat(-3.9) // → -3 (trunca em direção a zero, não para -4) @intFromFloat(-3.1) // → -3 (trunca em direção a zero) ``` Para outros comportamentos de arredondamento, use as funções da biblioteca padrão antes de converter: ```zig const std = @import("std"); const valor: f64 = 3.7; const arredondado: i64 = @intFromFloat(@round(valor)); // 4 — arredonda para o mais próximo const piso: i64 = @intFromFloat(@floor(valor)); // 3 — arredonda para baixo const teto: i64 = @intFromFloat(@ceil(valor)); // 4 — arredonda para cima ``` ## Comparação com C equivalente Em C, a conversão de float para int é feita com cast e pode causar comportamento indefinido silencioso: ```c double valor = 1e18; int resultado = (int)valor; // Comportamento indefinido! overflow silencioso ``` Em Zig, o overflow é detectado em modo debug: ```zig const valor: f64 = 1e18; const resultado: i32 = @intFromFloat(valor); // panic em debug: float out of range ``` Além disso, em C não há verificação de `NaN` ou `Inf`, enquanto Zig detecta esses casos automaticamente em builds com safety checks. ## Estratégia de validação antes da conversão Para código robusto que lida com dados de entrada externos, valide o float antes de converter: ```zig const std = @import("std"); fn floatParaIntSafe(valor: f64, comptime T: type) !T { if (std.math.isNan(valor)) return error.NaN; if (std.math.isInf(valor)) return error.Infinito; const min: f64 = @floatFromInt(std.math.minInt(T)); const max: f64 = @floatFromInt(std.math.maxInt(T)); if (valor < min or valor > max) return error.ForaDoIntervalo; return @intFromFloat(valor); } test "conversão segura" { try std.testing.expect(try floatParaIntSafe(42.7, i32) == 42); try std.testing.expectError(error.ForaDoIntervalo, floatParaIntSafe(1e20, i32)); try std.testing.expectError(error.NaN, floatParaIntSafe(std.math.nan(f64), i32)); } ``` ## Perguntas Frequentes **P: Como diferenciar `@intFromFloat` de `std.math.lossyCast`?** `@intFromFloat` trunca e causa panic se o valor estiver fora do intervalo. `std.math.lossyCast` faz o melhor possível — clampea ao min/max do tipo de destino e retorna zero para NaN — sem panic. Use `lossyCast` quando um resultado aproximado é aceitável. **P: É seguro usar `@intFromFloat` em modo `ReleaseFast`?** Não, se os valores de entrada podem ser inválidos. Em `ReleaseFast`, safety checks são desabilitados e overflow ou NaN resultam em comportamento indefinido. Valide os dados antes ou use `ReleaseSafe` para manter as verificações mesmo em builds de produção. **P: Por que `@intFromFloat` trunca em vez de arredondar?** Truncamento é a operação mais próxima do que a maioria das CPUs faz nativamente (instrução `cvttss2si` em x86, onde o duplo `t` significa "truncate"). Arredondamento exigiria uma operação extra. Quando arredondamento é necessário, use `@round`, `@floor` ou `@ceil` da biblioteca padrão antes de converter. ## Builtins relacionados - [@floatFromInt](/builtins/float-from-int/) — Operação inversa: converte inteiro para float - [@as](/builtins/as/) — Conversão de tipo genérica - [@intFromEnum](/builtins/int-from-enum/) — Converte enum para inteiro - [@intFromBool](/builtins/int-from-bool/) — Converte booleano para inteiro ## Tutoriais relacionados - [Tipos numéricos em Zig](/tutoriais/tipos-numericos/) - [Sistema de tipos do Zig](/tutoriais/tipos/) - [Segurança em Zig](/tutoriais/seguranca/)