---
title: "usize em Zig — O que é e Como Usar"
url: "https://ziglang.com.br/glossario/usize-em-zig-o-que-%C3%A9-e-como-usar/"
markdown_url: "https://ziglang.com.br/glossario/usize-em-zig-o-que-%C3%A9-e-como-usar.MD"
description: "Entenda o tipo usize em Zig: o inteiro sem sinal cujo tamanho depende da arquitetura. Usado para índices, tamanhos e aritmética de ponteiros. Guia pt-BR."
date: "2026-02-21"
author: "Zig Brasil"
---

# usize em Zig — O que é e Como Usar

Entenda o tipo usize em Zig: o inteiro sem sinal cujo tamanho depende da arquitetura. Usado para índices, tamanhos e aritmética de ponteiros. Guia pt-BR.


# usize em Zig — O que é e Como Usar

## Definição

**usize** é o tipo inteiro sem sinal (unsigned) cujo tamanho corresponde ao tamanho nativo de um ponteiro na arquitetura-alvo. Em sistemas de 64 bits, `usize` tem 64 bits (8 bytes); em sistemas de 32 bits, tem 32 bits (4 bytes). É o tipo padrão para indexação de arrays, comprimento de slices e aritmética de ponteiros.

Em termos práticos, `usize` é equivalente ao `size_t` do C.

## Por que usize Importa

1. **Indexação**: Todo acesso a arrays e slices em Zig usa `usize` como tipo de índice.
2. **Tamanhos**: O campo `.len` de slices e arrays retorna `usize`.
3. **Portabilidade**: Garante que o código funcione em arquiteturas de 32 e 64 bits sem alteração.
4. **Aritmética de ponteiros**: Operações de ponteiro usam `usize` para deslocamentos.

## Exemplo Prático

### Indexação de Arrays e Slices

```zig
const std = @import("std");

pub fn main() void {
    const dados = [_]u8{ 10, 20, 30, 40, 50 };

    // .len retorna usize
    const tamanho: usize = dados.len;
    std.debug.print("Tamanho: {}\n", .{tamanho}); // 5

    // Índice de iteração é usize
    for (dados, 0..) |valor, i| {
        std.debug.print("[{}] = {}\n", .{ i, valor });
    }
}
```

### Conversão entre Tipos Inteiros

```zig
const std = @import("std");

fn buscar(slice: []const u8, indice: usize) ?u8 {
    if (indice >= slice.len) return null;
    return slice[indice];
}

pub fn main() void {
    const dados = [_]u8{ 'Z', 'i', 'g' };

    // Converter u32 para usize com @intCast
    const pos: u32 = 1;
    const resultado = buscar(&dados, @intCast(pos));

    if (resultado) |byte| {
        std.debug.print("Encontrado: {c}\n", .{byte}); // 'i'
    }
}
```

### Tamanho em Bytes com @sizeOf

```zig
const std = @import("std");

pub fn main() void {
    std.debug.print("usize = {} bytes\n", .{@sizeOf(usize)});   // 8 em 64-bit
    std.debug.print("isize = {} bytes\n", .{@sizeOf(isize)});   // 8 em 64-bit
    std.debug.print("*u8   = {} bytes\n", .{@sizeOf(*u8)});     // 8 em 64-bit

    // Todos têm o mesmo tamanho: usize == tamanho de ponteiro
}
```

## usize vs isize

| Tipo | Descrição |
|------|-----------|
| `usize` | Inteiro **sem sinal** do tamanho de um ponteiro (0 a 2^N-1) |
| `isize` | Inteiro **com sinal** do tamanho de um ponteiro (-2^(N-1) a 2^(N-1)-1) |

Use `usize` para índices e tamanhos (que nunca são negativos). Use `isize` quando precisar representar deslocamentos que podem ser negativos.

## Boas Práticas

- **Sempre use `usize` para índices**: Qualquer variável que serve de índice para array ou slice deve ser `usize`. Isso evita conversões desnecessárias e expressa intenção claramente.
- **Prefira `.len` em vez de constantes mágicas**: Acesse `slice.len` (que retorna `usize`) em vez de codificar tamanhos fixos.
- **Use `@intCast` com cuidado**: A conversão de `u32` para `usize` é sempre segura em sistemas de 64 bits, mas pode truncar em 32 bits se o valor for maior que `maxInt(u32)`. Em geral, porém, `u32` → `usize` é expansão segura.
- **Para deslocamentos negativos, use `isize`**: Se você precisa calcular `ptr - offset` onde offset pode ser positivo ou negativo, use `isize` para o deslocamento.

## Comparação com Outras Linguagens

| Linguagem | Equivalente a `usize` | Notas |
|----------|----------------------|-------|
| C | `size_t` | Mesmo comportamento |
| C++ | `std::size_t` | Mesmo comportamento |
| Rust | `usize` | Idêntico em conceito e comportamento |
| Go | `int` (com sinal) | Go usa int com sinal para índices |
| Java | `int` (32 bits fixo) | Sem tipo dependente de arquitetura |

Ao contrário de Go e Java, Zig (como Rust e C) usa um tipo sem sinal para tamanhos e índices, refletindo a realidade de que tamanhos nunca são negativos.

## Armadilhas Comuns

- **Misturar tipos inteiros**: Usar `u32` ou `i32` como índice exige conversão explícita com `@intCast`. Zig não faz conversão implícita.
- **Overflow em 32 bits**: Código que funciona em 64 bits pode ter overflow em 32 bits se os valores excederem 4 GB. Teste em ambas as arquiteturas.
- **Subtração de usize**: Como `usize` é unsigned, subtrair um valor maior do menor causa panic em modo safe. Use `std.math.sub` para subtração segura.
- **Confundir com u64**: `usize` nem sempre é 64 bits. Em sistemas de 32 bits, é `u32`. Usar `u64` onde `usize` é esperado requer conversão.

## Termos Relacionados

- [Slice](/glossario/slice/) — Referência a sequência contígua com `.len` do tipo usize
- [Pointer Types](/glossario/pointer-types/) — Tipos de ponteiro em Zig
- [comptime_int](/glossario/comptime-int/) — Inteiro de precisão arbitrária em comptime
- [Type Coercion](/glossario/type-coercion/) — Regras de conversão de tipos

## Tutoriais Relacionados

- [Sistema de Tipos do Zig](/tutoriais/tipos/)
- [Strings e Arrays em Zig](/tutoriais/strings-e-arrays-zig/)
- [Introdução ao Zig](/tutoriais/introducao-ao-zig/)