You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+78-11Lines changed: 78 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,15 +23,19 @@
23
23
—_Sir Evander Marchbank_, self-proclaimed cider cartographer who insists that every orchard has its own “gravitational pull” affecting the bubbles.
24
24
25
25
---
26
+
26
27
CIDRE focuses on parsing and representing IP addresses, IP networks and providing CIDR math. On the JVM and Android it maps from/to `InetAddress`/`Inet4Address`/`Inet6Address`. On native targets, it maps from/to `in_addr`/`in6_addr`.
27
28
It is not a full IP networking implementation, but you can use it to implement IP routing.
28
29
It has a total of zero external dependencies.
29
-
Currently, CIDRE can
30
-
* parse and encode IPv4 and IPv6 addresses from/to String and ByteArray representations
31
-
* iterate over, slice, split, and merge networks,
32
-
* convert prefixes from/to netmasks
33
-
* subnet and supernet
34
-
* sorting of networks and addresses
30
+
Currently, CIDRE provides the following functionality:
31
+
* parsing and encoding IPv4 and IPv6 addresses from/to String and ByteArray representations
32
+
* converting CIDR prefixes from/to netmasks
33
+
* checking whether addresses or networks are are fully contained within a network
34
+
* comparability of networks and addresses inside a family (IPv4/IPv6)
35
+
36
+
Planned features are:
37
+
* iterating over, slicing, splitting, and merging networks
38
+
* subnetting and supernetting
35
39
36
40
37
41
In general, CIDRE's data model has semantics influenced by [netaddr](https://github.com/netaddr/netaddr/?tab=readme-ov-file): An `IpNetwork` covers a range of `IpInterface`s, both of which consist of an `IpAddress` and a `prefix`.
@@ -78,6 +82,10 @@ Simply `toString()` any IP address to get its string representation, or access `
78
82
An `IpAddress`'s companion object also provides helpful properties such as segment separator, number of octets, and readily usable `Regex` instances to check whether a string is a valid representation of
79
83
an IP address or a single address segment.
80
84
85
+
#### Ordering
86
+
87
+
IP addresses are `Comparable` inside a family (IPv4, IPv6) and are ordered by comparing their octets interpreted as a BE-encoded unsigned integer.
- consistent `toString()` behavior with address/prefix; IPv4 variants also support netmask printing helpers.
132
+
133
+
134
+
#### Creating IpInterfaces from Networks
111
135
112
-
### Working with Networks IpInterfaces
136
+
Given an `IpAddress` and a prefix, it is possible to get the corresponding network in two ways:
137
+
-`IpNetwork(address strict = false)` to create a new `IpNetwork` and deep-copy the ip address into the network's `address` property.
138
+
- If `strict = true` the passed address must already be the network address (i.e., correctly masked), according to the specified prefix
139
+
- If `strict = false` the passed address will be masked to the network address, according to the specified prefix
140
+
-`IpNetwork.forAddress(address, prefix)` creates a new network, referencing and masking the passed `address`. This avoids copying, but modifies any not-correctly-masked address in-place, according to the given `prefix`.
113
141
114
142
#### Netmasks and Prefixes
115
143
144
+
CIDRE uses type aliases
145
+
- Prefix is a UInt (`typealias Prefix = UInt`)
146
+
- Netmask is a network-order byte array (`typealias Netmask = ByteArray`)
147
+
148
+
Round-tripping between prefixes and netmasks is straightforward:
149
+
- Create a netmask from a prefix:
150
+
- For a specific IP family: `prefix.toNetmask(IpAddress.Family.V4)` or `prefix.toNetmask(IpAddress.Family.V6)`
151
+
- For an arbitrary octet count: `prefix.toNetmask(octetCount)`
152
+
- Convert a netmask back to a prefix and validate contiguity: `netmask.toPrefix()`
153
+
154
+
IP addresses can be masked in-place by calling either `mask(prefix)` or `mask(netmask)`.
155
+
To create a deep-copied masked version of an address, manually `copy()` it before masking.
156
+
157
+
For IPv4, it is also possible to get a dotted-quad representation and choose a preferred textual form when working with `IpAddressAndPrefix`:
158
+
-`netmaskToString()` yields a `#.#.#.#` string
159
+
-`toString(preferNetmaskOverPrefix = true)` prints `A.A.A.A N.N.N.N`, where `A` is an IP address quad and `N` is a netmask quad.
160
+
-`toString(preferNetmaskOverPrefix = false)` prints standard `#.#.#.#/prefix`
161
+
116
162
#### Host Ranges and Address Spaces
117
163
118
-
#### Containment, Overlap Checks, and Adjacency
164
+
Conceptually:
165
+
- An `IpNetwork` represents a contiguous range of addresses.
166
+
- An `IpInterface` is a single address bound to a prefix.
167
+
- The network address is part of the network; for IPv4, the broadcast address (when applicable) is also inside.
119
168
120
-
To check whether an address, a network, or an `IpInterface` falls inside a target network, call `targetNetwork.contanins(addrNwOrIf)`.
169
+
Coming soon:
170
+
- Iteration over the full address space of a network
171
+
- Convenience accessors for first/last interface and broadcast (where applicable)
172
+
- Efficient network size computations
121
173
122
174
123
-
#### Subnetting and Supernetting
175
+
#### Containment
176
+
177
+
Containment checks are explicit (and fast!):
178
+
- Address in network: `network.contains(ipAddress)`
179
+
- Interface in network: `network.contains(ipInterface)`
180
+
- Network fully contained in another network: `anotherNetwork.contains(network)`
*`infix fun ByteArray.and(other: ByteArray): ByteArray` performing a logical `AND` operation, returning a fresh ByteArray.
130
188
*`fun ByteArray.andInplace(other: ByteArray): Int` performing an in-place logical `AND` operation, modifying the receiver ByteArray. Returns the number of modified bits.
131
189
*`fun ByteArray.compareUnsignedBE(other: ByteArray): Int` comparing two same-sized byte arrays by interpreting their contents as unsigned BE integers
132
-
*`fun Prefix.toNetmask(version: IpAddress.Version): Netmask` converting an `UInt` CIDR prefix to its byte representation
190
+
*`fun Prefix.toNetmask(family: IpAddress.Family): Netmask` converting an `UInt` CIDR prefix to its byte representation
133
191
*`fun Netmask.toPrefix(): Prefix` converting a netmask into its CIDR prefix length
134
192
*`ByteArray.toShortArray(bigEndian: Boolean = true): ShortArray` grouping pairs of bytes into a short. Useful to get IPv6 hextets from octets.
135
193
194
+
195
+
## Roadmap:
196
+
- More comprehensive tests
197
+
- Address range enumeration
198
+
- Subnet enumeration (absolute and relative, e.g., `/24` or “+2 bits”)
199
+
- Supernetting helpers (absolute and relative)
200
+
- Overlap and adjacency checks
201
+
- Safe aggregation of adjacent/overlapping ranges where possible and merging of networks
202
+
136
203
## Contributing
137
204
External contributions are greatly appreciated!
138
205
Just be sure to observe the contribution guidelines (see [CONTRIBUTING.md](CONTRIBUTING.md)).
0 commit comments