Struct Reference

pub struct Reference<'r> { /* private fields */ }

A reference to a docker image, e.g. ubuntu:20.04 or localhost:5000/example:1.0-dev.

Reference::from_str() can be used to parse an image reference following the grammar specified in https://github.com/distribution/distribution/blob/v2.7.1/reference/reference.go.

In short, a reference is of the form name [':' tag] ['@' digest], where tag and digest parts are optional. More information on the grammar can be found in the link above.

Note that no semantic check is performed, e.g. whether the port number is too long, etc. However it should be able to correctly parse the name, tag and digest components of a reference.

Implementations

impl<'r> Reference<'r>

pub fn from_str(s: &'r str) -> Result<Self>

Parse a reference string.

For example:

use docker_image_reference::Reference;
let r = Reference::from_str("ubuntu:20.04").unwrap();
assert_eq!(r.name(), "ubuntu");
assert_eq!(r.tag(), Some("20.04"));

pub fn name(&self) -> &'r str

Get the name component of the reference. This might start with a host[:port] part followed by one or more path components separated by slash.

For example:

use docker_image_reference::Reference;
let r = Reference::from_str("index.docker.io/library/ubuntu:latest").unwrap();
assert_eq!(r.name(), "index.docker.io/library/ubuntu");

pub fn tag(&self) -> Option<&'r str>

Get the tag component if present. This is a sequence of up to 128 alphanumerics, -, . and _ not starting with . or -.

For example:

use docker_image_reference::Reference;
let r = Reference::from_str("example:1.2.3-dev_test").unwrap();
assert_eq!(r.tag(), Some("1.2.3-dev_test"));

pub fn has_digest(&self) -> bool

Returns true if the reference contains a digest component. If this function returns true, then both digest_algorithm() and digest_hex() will return Some.

For example:

use docker_image_reference::Reference;
let r = Reference::from_str("image-name@sha256:9d78ad0da0e88ca15da5735b9f70064d3099ac0a8cd9dc839795789400a38e42").unwrap();
assert!(r.has_digest());
assert_eq!(r.digest_algorithm(), Some("sha256"));
assert_eq!(r.digest_hex(), Some("9d78ad0da0e88ca15da5735b9f70064d3099ac0a8cd9dc839795789400a38e42"));

pub fn digest_algorithm(&self) -> Option<&'r str>

pub fn digest_hex(&self) -> Option<&'r str>

Trait Implementations

impl<'r> Display for Reference<'r>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'r> PartialEq for Reference<'r>

fn eq(&self, other: &Reference<'r>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'r> StructuralPartialEq for Reference<'r>