Enum VersionConstraint 

pub enum VersionConstraint {
    Exact(Version),
    Requirement(VersionReq),
    Latest,
    LatestPrerelease,
    GitRef(String),
}

A version constraint that defines acceptable versions for a dependency.

Version constraints in CCPM support multiple formats to handle different versioning strategies and Git-based dependencies. Each constraint type provides specific matching behavior for version resolution.

Constraint Types

• Exact: Matches exactly one specific semantic version
• Requirement: Matches versions using semver ranges
• Latest: Matches the newest stable version available
• LatestPrerelease: Matches newest version including prereleases
• GitRef: Matches specific Git branches, tags, or commit hashes

Examples

use ccpm::version::constraints::VersionConstraint;
use semver::Version;

// Parse various constraint formats
let exact = VersionConstraint::parse("1.0.0")?;
let caret = VersionConstraint::parse("^1.0.0")?; // Compatible versions
let tilde = VersionConstraint::parse("~1.2.0")?; // Patch-level compatible
let range = VersionConstraint::parse(">=1.0.0, <2.0.0")?; // Version range
let latest = VersionConstraint::parse("latest")?;
let branch = VersionConstraint::parse("main")?;
let commit = VersionConstraint::parse("abc123def")?;

// Test version matching
let version = Version::parse("1.2.3")?;
assert!(caret.matches(&version));

Prerelease Handling

By default, most constraints exclude prerelease versions to ensure stability:

• Latest only matches stable versions (no -alpha, -beta, -rc suffixes)
• LatestPrerelease includes all versions including prereleases
• GitRef constraints allow prereleases since they reference specific commits

Git Reference Matching

Git references are matched by name rather than semantic version:

• Branch names: "main", "develop", "feature/auth"
• Tag names: "v1.0.0", "release-2023-01"
• Commit hashes: "abc123def456" (full or abbreviated)

Variants

Exact(Version)

Exact version match (e.g., “1.0.0”)

Requirement(VersionReq)

Semantic version requirement (e.g., “^1.0.0”, “~1.2.0”, “>=1.0.0”)

Latest

Latest stable version

LatestPrerelease

Latest version including prereleases

GitRef(String)

Git tag or branch name

Implementations

impl VersionConstraint

pub fn parse(constraint: &str) -> Result<Self>

Parse a constraint string into a VersionConstraint.

This method intelligently determines the constraint type based on the input format. It handles various syntaxes including semantic versions, version ranges, special keywords, and Git references.

Parsing Logic

1. Special keywords: "latest", "*", "latest-prerelease"
2. Exact versions: "1.0.0", "v1.0.0" (without range operators)
3. Version requirements: "^1.0.0", "~1.2.0", ">=1.0.0", "<2.0.0"
4. Git references: Any string that doesn’t match the above patterns

Arguments

• constraint - The constraint string to parse (whitespace is trimmed)

Returns

Returns Ok(VersionConstraint) on successful parsing, or Err if the semantic version parsing fails (Git references always succeed).

Examples

use ccpm::version::constraints::VersionConstraint;

// Exact version matching
let exact = VersionConstraint::parse("1.0.0")?;
let exact_with_v = VersionConstraint::parse("v1.0.0")?;

// Semantic version ranges
let caret = VersionConstraint::parse("^1.0.0")?;      // 1.x.x compatible
let tilde = VersionConstraint::parse("~1.2.0")?;      // 1.2.x compatible
let gte = VersionConstraint::parse(">=1.0.0")?;       // Greater or equal
let range = VersionConstraint::parse(">1.0.0, <2.0.0")?; // Range

// Special keywords
let latest = VersionConstraint::parse("latest")?;     // Latest stable
let any = VersionConstraint::parse("*")?;             // Any version
let latest_pre = VersionConstraint::parse("latest-prerelease")?;

// Git references
let branch = VersionConstraint::parse("main")?;       // Branch name
let tag = VersionConstraint::parse("release-v1")?;    // Tag name
let commit = VersionConstraint::parse("abc123def")?;  // Commit hash

Error Handling

This method only returns errors for malformed semantic version strings. Git references and special keywords always parse successfully.

pub fn matches(&self, version: &Version) -> bool

Check if a semantic version satisfies this constraint.

This method tests whether a given semantic version matches the requirements of this constraint. Different constraint types use different matching logic:

• Exact: Version must match exactly
• Requirement: Version must satisfy the semver range
• Latest: Version must be stable (no prerelease components)
• LatestPrerelease: Any version matches (selection happens during resolution)
• GitRef: Never matches semantic versions (Git refs are matched separately)

Arguments

• version - The semantic version to test against this constraint

Returns

Returns true if the version satisfies the constraint, false otherwise.

Examples

use ccpm::version::constraints::VersionConstraint;
use semver::Version;

let constraint = VersionConstraint::parse("^1.0.0")?;
let version = Version::parse("1.2.3")?;

assert!(constraint.matches(&version)); // 1.2.3 is compatible with ^1.0.0

let prerelease = Version::parse("1.0.0-alpha.1")?;
let latest = VersionConstraint::parse("latest")?;
assert!(!latest.matches(&prerelease)); // Latest excludes prereleases

Note

Git reference constraints always return false for this method since they operate on Git refs rather than semantic versions. Use matches_ref to test Git reference matching.

pub fn matches_ref(&self, git_ref: &str) -> bool

Check if a Git reference satisfies this constraint.

This method tests whether a Git reference (branch, tag, or commit hash) matches a Git reference constraint. Only GitRef constraints can match Git references - all other constraint types return false.

Arguments

• git_ref - The Git reference string to test (branch, tag, or commit)

Returns

Returns true if this is a GitRef constraint with matching reference name, false otherwise.

Examples

use ccpm::version::constraints::VersionConstraint;

let branch_constraint = VersionConstraint::parse("main")?;
assert!(branch_constraint.matches_ref("main"));
assert!(!branch_constraint.matches_ref("develop"));

let version_constraint = VersionConstraint::parse("^1.0.0")?;
assert!(!version_constraint.matches_ref("main")); // Version constraints don't match refs

Use Cases

This method is primarily used during dependency resolution to match dependencies that specify Git branches, tags, or commit hashes rather than semantic versions.

pub fn to_version_req(&self) -> Option<VersionReq>

Convert this constraint to a semantic version requirement if applicable.

This method converts version-based constraints into VersionReq objects that can be used with the semver crate for version matching. Git reference constraints cannot be converted since they don’t represent version ranges.

Returns

Returns Some(VersionReq) for constraints that can be expressed as semantic version requirements, or None for Git reference constraints.

Conversion Rules

• Exact: Converted to =1.0.0 requirement
• Requirement: Returns the inner VersionReq directly
• Latest/LatestPrerelease: Converted to * (any version) requirement
• GitRef: Returns None (cannot be converted)

Examples

use ccpm::version::constraints::VersionConstraint;
use semver::Version;

let exact = VersionConstraint::parse("1.0.0")?;
let req = exact.to_version_req().unwrap();
assert!(req.matches(&Version::parse("1.0.0")?));

let caret = VersionConstraint::parse("^1.0.0")?;
let req = caret.to_version_req().unwrap();
assert!(req.matches(&Version::parse("1.2.0")?));

let git_ref = VersionConstraint::parse("main")?;
assert!(git_ref.to_version_req().is_none()); // Git refs can't be converted

Use Cases

This method is useful for integrating with existing semver-based tooling or for performing version calculations that require VersionReq objects.

pub fn allows_prerelease(&self) -> bool

Check if this constraint allows prerelease versions.

Prerelease versions contain identifiers like -alpha, -beta, -rc that indicate pre-release status. This method determines whether the constraint should consider such versions during resolution.

Prerelease Policy

• Latest: Excludes prereleases (stable versions only)
• LatestPrerelease: Explicitly allows prereleases
• GitRef: Allows prereleases (Git refs may point to any commit)
• Exact/Requirement: Excludes prereleases unless explicitly specified

Returns

Returns true if prerelease versions should be considered, false if only stable versions should be considered.

Examples

use ccpm::version::constraints::VersionConstraint;

let latest = VersionConstraint::parse("latest")?;
assert!(!latest.allows_prerelease()); // Stable only

let latest_pre = VersionConstraint::parse("latest-prerelease")?;
assert!(latest_pre.allows_prerelease()); // Includes prereleases

let branch = VersionConstraint::parse("main")?;
assert!(branch.allows_prerelease()); // Git refs may be any version

let exact = VersionConstraint::parse("1.0.0")?;
assert!(!exact.allows_prerelease()); // Exact stable version

Impact on Resolution

During version resolution, if any constraint in a set allows prereleases, the entire constraint set will consider prerelease versions as candidates.

Trait Implementations

impl Clone for VersionConstraint

fn clone(&self) -> VersionConstraint

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VersionConstraint

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

Formats the value using the given formatter.

impl Display for VersionConstraint

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

Formats the value using the given formatter.