---
<a id="en"></a>
# ipbin : Seamless IP Address to Binary Conversion
[中文](./zh.md)
A lightweight, zero-dependency Rust utility for converting IP addresses (IPv4 and IPv6) into their binary representation (byte vectors).
## Table of Contents
- [Features](#features)
- [Usage](#usage)
- [Design Philosophy](#design-philosophy)
- [Tech Stack](#tech-stack)
- [Directory Structure](#directory-structure)
- [API Documentation](#api-documentation)
- [Historical Anecdote](#historical-anecdote)
## Features
- **Universal Support**: Handles both IPv4 and IPv6 addresses seamlessly.
- **Zero Dependencies**: Built entirely on the Rust standard library (`std`).
- **Efficient**: Direct conversion using native Rust methods.
- **Simple API**: A single function to handle all conversions.
## Usage
Add `ipbin` to your project dependencies. Here is a quick example of how to use it:
```rust
use ipbin::ipbin;
use std::net::IpAddr;
fn main() {
// IPv4 Example
let ipv4: IpAddr = "127.0.0.1".parse().unwrap();
let bytes_v4 = ipbin(ipv4);
println!("IPv4 Bytes: {:?}", bytes_v4); // [127, 0, 0, 1]
// IPv6 Example
let ipv6: IpAddr = "::1".parse().unwrap();
let bytes_v6 = ipbin(ipv6);
println!("IPv6 Bytes: {:?}", bytes_v6); // [0, 0, ..., 1]
}
```
## Design Philosophy
The core design revolves around simplicity and leveraging Rust's strong type system. The `ipbin` function takes a `std::net::IpAddr` enum, which can be either `V4` or `V6`.
1. **Input**: Accepts `IpAddr`.
2. **Matching**: Matches the enum variant.
3. **Conversion**: Calls `.octets()` on the inner IP struct.
4. **Output**: Converts the array of octets into a `Vec<u8>`.
This ensures that the output is always a raw byte vector representing the IP address, regardless of its version.
## Tech Stack
- **Language**: Rust
- **Standard Library**: `std::net`
## Directory Structure
```
.
├── Cargo.toml # Project configuration
├── readme # Documentation
│ ├── en.md # English README
│ └── zh.md # Chinese README
├── src
│ └── lib.rs # Source code
└── tests
└── main.rs # Integration tests
```
## API Documentation
### `ipbin`
```rust
pub fn ipbin(ipaddr: IpAddr) -> Vec<u8>
```
- **Parameters**: `ipaddr` - An `IpAddr` enum representing either an IPv4 or IPv6 address.
- **Returns**: `Vec<u8>` - A vector containing the octets of the IP address.
- For IPv4, the vector length is 4.
- For IPv6, the vector length is 16.
## Historical Anecdote
**The 32-bit "Experiment"**
In the 1970s, when Vint Cerf and his colleagues were designing the Internet Protocol (IPv4), they had to decide on the address size. After much debate, Cerf decided on 32 bits, which allows for about 4.3 billion unique addresses. At the time, this seemed like an astronomical number for what was essentially a military experiment. Cerf famously remarked, "It's enough for an experiment." He expected that if the experiment worked, a production version with a larger address space would be developed later.
That "experiment" escaped the lab and became the global Internet we know today. The 32-bit limit eventually led to address exhaustion, necessitating the creation of IPv6 with its massive 128-bit address space—which `ipbin` fully supports!
---
## About
This project is an open-source component of [js0.site ⋅ Refactoring the Internet Plan](https://js0.site).
We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:
* [Google Group](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)
---
<a id="zh"></a>
# ipbin : IP地址到二进制的无缝转换
[English](./en.md)
一个轻量级、无依赖的 Rust 工具，用于将 IP 地址（IPv4 和 IPv6）转换为其二进制表示（字节向量）。
## 目录
- [功能特性](#功能特性)
- [使用演示](#使用演示)
- [设计思路](#设计思路)
- [技术堆栈](#技术堆栈)
- [目录结构](#目录结构)
- [API 说明](#api-说明)
- [历史轶事](#历史轶事)
## 功能特性
- **通用支持**：无缝处理 IPv4 和 IPv6 地址。
- **零依赖**：完全基于 Rust 标准库 (`std`) 构建。
- **高效**：使用原生 Rust 方法进行直接转换。
- **简单 API**：只需一个函数即可处理所有转换。
## 使用演示
将 `ipbin` 添加到您的项目依赖中。以下是快速使用示例：
```rust
use ipbin::ipbin;
use std::net::IpAddr;
fn main() {
// IPv4 示例
let ipv4: IpAddr = "127.0.0.1".parse().unwrap();
let bytes_v4 = ipbin(ipv4);
println!("IPv4 字节: {:?}", bytes_v4); // [127, 0, 0, 1]
// IPv6 示例
let ipv6: IpAddr = "::1".parse().unwrap();
let bytes_v6 = ipbin(ipv6);
println!("IPv6 字节: {:?}", bytes_v6); // [0, 0, ..., 1]
}
```
## 设计思路
核心设计围绕简单性和利用 Rust 强大的类型系统。`ipbin` 函数接收一个 `std::net::IpAddr` 枚举，它可以是 `V4` 或 `V6`。
1. **输入**：接收 `IpAddr`。
2. **匹配**：匹配枚举变体。
3. **转换**：在内部 IP 结构上调用 `.octets()`。
4. **输出**：将八位字节数组转换为 `Vec<u8>`。
这确保了无论 IP 版本如何，输出始终是表示 IP 地址的原始字节向量。
## 技术堆栈
- **语言**：Rust
- **标准库**：`std::net`
## 目录结构
```
.
├── Cargo.toml # 项目配置
├── readme # 文档
│ ├── en.md # 英文说明
│ └── zh.md # 中文说明
├── src
│ └── lib.rs # 源代码
└── tests
└── main.rs # 集成测试
```
## API 说明
### `ipbin`
```rust
pub fn ipbin(ipaddr: IpAddr) -> Vec<u8>
```
- **参数**：`ipaddr` - 表示 IPv4 或 IPv6 地址的 `IpAddr` 枚举。
- **返回**：`Vec<u8>` - 包含 IP 地址八位字节的向量。
- 对于 IPv4，向量长度为 4。
- 对于 IPv6，向量长度为 16。
## 历史轶事
**32位的“实验”**
20世纪70年代，当 Vint Cerf 和他的同事们设计互联网协议（IPv4）时，他们必须决定地址的大小。经过一番争论，Cerf 决定使用 32 位，这允许大约 43 亿个唯一地址。在当时，对于本质上是军事实验的网络来说，这似乎是一个天文数字。Cerf 有句名言：“这对于一个实验来说足够了。”他预计如果实验成功，稍后将开发具有更大地址空间的生产版本。
那个“实验”最终走出了实验室，成为了我们今天所知的全球互联网。32 位的限制最终导致了地址耗尽，迫使人们创建了具有巨大 128 位地址空间的 IPv6——而 `ipbin` 完全支持它！
---
## 关于
本项目为 [js0.site ⋅ 重构互联网计划](https://js0.site) 的开源组件。
我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：
* [谷歌邮件列表](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)