Arcus is a C# manipulation library for calculating, parsing, formatting, converting, and comparing both IPv4 and IPv6 addresses and subnets. It accounts for 128-bit numbers on 32-bit platforms.
The latest stable release of Arcus is available on NuGet.
The latest Arcus documentation may be found on ReadTheDocs.
At its heart Arcus is split amongst five separate interdependent units. Types, Comparers, Converters, Math, and Utilities.
These units each work across Arcus's IPAddressRange, Subnet and .NET's System.Net.IPAddress. Arcus adds extra desired functionality where the standard C# libraries left off.
An IPv4 or IPv6 subnetwork representation - the work horse and original reason for the Arcus library. Outside the concept of the Subnet object, most everything else in Arcus is auxiliary and exists only in support of the Subnet object. That’s not to say that the remaining pieces of the Arcus library aren’t useful, on the contrary their utility can benefit a developer greatly.
A Subnet may be instantiated in several ways:
The most common way to create a Subnet object is to construct it via a high and low IPAddress by calling the constructor Subnet(IPAddress primary, IPAddress secondary). This constructs the smallest possible subnet that would contain both IP addresses. Typically the addresses specified are the Network and Broadcast addresses (lower and higher bounds of a subnet) but this is not necessary. Addresses MUST be the same address family (either Internetwork or InternetworkV6).
It is also possible to create a Subnet from an IPAddress and an integer based route prefix. Eg: Subnet(IPAddress ipAddress, int routingPrefix).
Likewise it may be desired to statically parse a subnet string with Subnet.Parse(string input) or it’s safe equivalent of bool Subnet.TryParse(string input, out Subnet subnet)
For example, one could safely parse the string "192.168.1.0/16" via
Subnet subnet;
var success = Subnet.TryParse("192.168.1.0/16", out subnet)IPAddressRange is a basic implementation of IIPAddressRange it is used to represent an inclusive range of arbitrary IP Addresses of the same address family. Unlike Subnet, IPAddressRange is not restricted to a power of two length, nor a valid broadcast address head.
The Comparers package contains useful Comparer objects for comparing properties of IP Addresses and IP Address composite objects.
DefaultAddressFamilyComparer- A comparer that compares address families. Most frequentlyInternetwork(IPv4) andInternetworkV6(IPv6)DefaultIPAddressComparer- A comparer forIPAddressobjectsDefaultIPAddressRangeComparer- A comparer forIIPAddressRange. Compares such that lower order ranges are less that higher order ranges accounting for size at matching range starts
The Converters package is a package of static utility classes for converting one type into another type.
Static utility class containing conversion methods for converting IPAddress objects into something else.
The Math package is a package of static utility classes for doing computational mathematics on objects.
In some cases the C# IPAddress object doesn't go far enough with what you can do with it mathematically, this static utility class containing mathematical methods to fill in the gaps.
Incrementing and Decrementing an IPAddress is easy.
Incrementing by one is a simple call to the extension method:
var address = IPAddress.Parse("192.168.1.1");
var result = address.Increment(); // result is 192.168.1.2Decrementing is just as simple:
var address = IPAddress.Parse("192.168.1.1");
var result = address.Increment(-2); // result is 192.168.0.0Overflow and Underflow conditions will result in an InvalidOperationException.
Equality may also be tested via a host of equality extension methods:
bool IsEqualTo(this IPAddress alpha, IPAddress beta)bool IsGreaterThan(this IPAddress alpha, IPAddress beta)bool IsGreaterThanOrEqualTo(this IPAddress alpha, IPAddress beta)bool IsLessThan(this IPAddress alpha, IPAddress beta)bool IsLessThanOrEqualTo(this IPAddress alpha, IPAddress beta)
The Utilities package contains static classes for miscellaneous operations on specific types.
Static utility class containing miscellaneous operations for IPAddress objects
A couple of extension methods were created to quickly determine the address family of an IP Address. To determine if an address is IPv4 use bool IsIPv4(this IPAddress ipAddress), likewise bool IsIPv6(this IPAddress ipAddress) can be used to test for IPv6.
It is possible to parse an IPAddress from a hexadecimal string into either an IPv4 of IPv6 address using the IPAddress ParseFromHexString(string input, AddressFamily addressFamily) method. Likewise it can be done safely with bool TryParseFromHexString(string input, AddressFamily addressFamily, out IPAddress address).
Similarly, conversion may be done from an octal string by using bool TryParseIgnoreOctalInIPv4(string input, out IPAddress address) or even a BigInteger by way of bool TryParse(BigInteger input, AddressFamily addressFamily, out IPAddress address).
Static utility class containing miscellaneous operations for Subnet objects that didn't make sense to put on the object itself.
Given two arbitrary IP Addresses of the same family it may be desired to calculate the fewest consecutive subnets that would hold the inclusive range between them. For example
SubnetUtilities.FewestConsecutiveSubnetsFor(IPAddress.Parse("128.64.20.3"), IPAddress.Parse("128.64.20.12"))would return an Enumerable containing the subnets 128.64.20.3/32, 128.64.20.4/30, 128.64.20.8/30, 128.64.20.12/32.
- Gulliver - A self created library that helped us keep our bits and bytes in order
- NuGet - Dependency Management
- JetBrains.Annotations - Used to keep developers honest
- moq - Fake it until you make it!
- Stackoverflow - Because who really remembers how to code
- xUnit.net - Testing, testing, 1, 2, 3...
We use SemVer for versioning.
- Robert H. Engelhardt - Primary Developer, Source of Ideas Good and Bad - @rheone
- Andrew Steele - Review and Suggestions - @ahsteele
- Nick Bachicha - Git Wrangler and DevOps Extraordinaire - @nicksterx
Copyright 2018 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.