README.md

eui48

A Rust library to represent and parse IEEE EUI-48 also known as MAC-48 media access control addresses. The IEEE claims trademarks on the names EUI-48 and EUI-64, in which EUI is an abbreviation for Extended Unique Identifier.

Usage

Add this to your Cargo.toml:

[dependencies]

eui48 = "1.0.1"

and this to your crate root:

extern crate eui48;

Examples

To create a new MAC address and print it out in canonical form:

extern crate eui48;
use eui48::{MacAddress, Eui48};

fn main() {
	let eui: Eui48 = [ 0x12, 0x34, 0x56, 0xAB, 0xCD, 0xEF ];
	let mac = MacAddress::new( eui );

	println!("{}", mac.to_canonical());
	println!("{}", mac.to_hex_string());
	println!("{}", mac.to_dot_string());
	println!("{}", mac.to_hexadecimal());
	println!("{}", mac.to_interfaceid());
	println!("{}", mac.to_link_local());

	let mac = MacAddress::parse_str( "01-02-03-0A-0b-0f" ).expect("Parse error {}");
	let mac = MacAddress::parse_str( "01:02:03:0A:0b:0f" ).expect("Parse error {}");
	let mac = MacAddress::parse_str( "0102.030A.0b0f" ).expect("Parse error {}");
	let mac = MacAddress::parse_str( "0x1234567890ab" ).expect("Parse error {}");
}

Notes

• The default display format is cannonical form 01-02-03-04-05-06 unless a compile time feature disp_hexstring is enabled, then the default format is of the form 01:02:03:04:05:06.

Version 1.0.0 and above allows a more flexible parsing of MAC address strings, compliments of Stan Drozd:

• Enables the library's caller to parse the MACs that don't follow fixed-length MAC address convention (I'm looking at you, ebtables!). In general, the parsing function tries harder to interpret a given string than before.
• Rewrite parse_str to use a regex and be more lenient (now it permits one-off string chopping errors and mixed delimiters are accepted as long as we manage to read 6 bytes)
• Exchange the InvalidCharacter error enum value for InvalidByteCount - InvalidCharacter is no longer supported. See versions >=0.5.0 and < 1.0.0 if you need legacy behavior.

Serialization

When using serde to serialize a MAC address the address is stored as a formatted string. This fits well for text-based protocols like JSON but creates overhead for binary serialization. The overhead gets even bigger when the string is deserialized again, as a full-grown parser is needed instead of reading raw bytes. To reduce this overhead use the serde_bytes feature when serializing and deserializing MAC addresses to binary protocols.

NOTE: serde_bytes and serde_json are mutually exclusive!

References

Wikipedia: MAC address

Authors

• 0.1 Andrew Baumhauer - Initial design
• 0.2 rlcomstock3 - Added support for btree keys
• 0.3 Michal 'vorner' Vaner [email protected] - Serde 1.0 support
• 0.3.1 Michal 'vorner' Vaner [email protected] - Derive useful traits
• 0.4.0 Rainer Stademann - Define ABI as repr(C)
• 0.4.1 Andrew Baumhauer - Add IPv6 Interface ID and Link Local conversions
• 0.4.2 Andrew Baumhauer / Eric Clone - Bug fix in is_local() and is_unicast() functions
• 0.4.3 Andrew Baumhauer - Update travis-ci, appveyor, codecov
• 0.4.4 Andrew Baumhauer - Update documentation
• 0.4.5 Andrew Baumhauer - Improve code coverage and tests
• 0.4.6 Jiwoong Lee - Add to_array() for compatibility, add feature disp_hexstring
• 0.4.7 Adam Reichold - WASM updates
• 0.4.8 @kamek-pf - respect disp_hexstring flag
• 0.4.9 Sebastian Dietze - New const added
• 0.5.0 Andrew Baumhauer - cleanup, update versions, fmt, merge PRs, update unit tests
• 0.5.1 jrb0001 - Fixed incorrect IPv6 to_link_local for Link-Scoped Unicast
• 1.0.0 Stan Drozd, @rlcomstock3, and Andrew Baumhauer - merged all forks and improvements back to this repo
• 1.0.1 jrb0001 - Fixed incorrect IPv6 to_link_local for Link-Scoped Unicast
• 1.1.0 Felix Schreiner - binary serialization optimization