---
title: SAIF.Framework.Version operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: SAIF Team
last_reviewed: 2026-07-30
library: SAIF.Framework.Version
reference_type: package
---

# SAIF.Framework.Version operations and processes

`SAIF.Framework.Version` exposes four operations on its `Version` value object: parsing a version string, formatting a version back to a string, comparing two versions numerically, and incrementing a version from a caller-supplied template. Every operation is implemented directly on the `Version` class — there are no external dependencies, no delegated logic, and no database interaction anywhere in this library. This page is the operation catalog and cross-operation hub; each operation's detailed, step-by-step logic lives in its own page under `operations/`.

## Operation catalog
| Operation | Intent | Trigger | Inputs | Outputs | Rules | Tables | SQL |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Parse version input](operations/parse-version-input.md) | Convert a dot-delimited string into a four-segment `Version` instance | Caller constructs `New Version(input)` or invokes `Version.Parse(input)` | `input As String` | New `Version` instance | [BR-002](business-rules.md#br-002-missing-trailing-version-segments-default-to-0-when-parsing) | — | — |
| [Format version string](operations/format-version-string.md) | Render the current version as its canonical four-part string | Caller invokes `Version.ToString()` | Current `Major`, `Minor`, `Build`, `Revision` values | `Major.Minor.Build.Revision` string | — | — | — |
| [Compare versions numerically](operations/compare-versions-numerically.md) | Determine equality or ordering from each segment's numeric value, not its literal text | Caller invokes `CompareTo` or operators `=`, `<>`, `<`, `>` | Two `Version` instances, or `obj As Object` for `CompareTo` | Boolean comparison result or integer `CompareTo` result | [BR-001](business-rules.md#br-001-non-numeric-leading-characters-in-a-version-segment-are-coerced-to-0), [BR-006](business-rules.md#br-006-equality-and-ordering-are-defined-purely-by-the-four-numeric-components-not-by-string-equality), [BR-007](business-rules.md#br-007-tautological-major-equality-check-in-the--and--operators) | — | — |
| [Increment version from template](operations/increment-version-from-template.md) | Advance the version in place using a template that mixes wildcard, retention, literal, and date tokens | Caller invokes `Version.Increment(format)` | `format As String`, current segment values | Updated `Version` instance (`Me`) | [BR-001](business-rules.md#br-001-non-numeric-leading-characters-in-a-version-segment-are-coerced-to-0), [BR-003](business-rules.md#br-003-a-wildcard-token-in-an-increment-format-means-auto-increment-this-segment), [BR-004](business-rules.md#br-004-an-empty-increment-format-token-means-retain-the-current-segment-value-unchanged), [BR-005](business-rules.md#br-005-increment-format-supports-date-template-tokens-year-month-day) | — | — |

## Process flow diagram
The following diagram visualizes how a caller reaches each of the four operations and what each returns.

```mermaid
flowchart TD
	Start([Caller request]) --> Choice{Requested operation}
	Choice -->|Parse a string| Parse[Parse version input]
	Choice -->|Render to text| Format[Format version string]
	Choice -->|Compare two versions| Compare[Compare versions numerically]
	Choice -->|Advance a version| Increment[Increment version from template]
	Parse --> Parsed([Return new Version instance])
	Format --> Formatted([Return version string])
	Compare --> Compared([Return comparison result])
	Increment --> Updated([Return updated Version instance, mutated in place])
```

## Failure and edge-case behavior
- `Version.Parse(input)` and `Version.Increment(format)` perform no null check of their own; passing `Nothing` for `input` or `format` lets the underlying `String.Split` failure propagate to the caller as an unhandled runtime exception.
- Parsing defaults only the trailing segments — `Minor`, `Build`, and `Revision` — to `"0"` when they are absent ([BR-002](business-rules.md#br-002-missing-trailing-version-segments-default-to-0-when-parsing)); any segments beyond the fourth are silently discarded, and a blank `Major` token is preserved as-is rather than defaulted.
- `ToString()` performs no normalization: whatever text is currently stored in each segment — including blank or non-numeric values — is emitted verbatim.
- Every comparison first normalizes each segment through `ToInt`, so a segment that is non-numeric or fails conversion is treated as `0` rather than raising an error ([BR-001](business-rules.md#br-001-non-numeric-leading-characters-in-a-version-segment-are-coerced-to-0), [BR-006](business-rules.md#br-006-equality-and-ordering-are-defined-purely-by-the-four-numeric-components-not-by-string-equality)).
- The `<` and `>` operators contain a tautological `v2.Major.ToInt = v2.Major.ToInt` guard ahead of the minor-segment comparison; it always evaluates `True` and is a likely copy-paste defect that does not currently distort comparison results ([BR-007](business-rules.md#br-007-tautological-major-equality-check-in-the--and--operators)).
- `Increment(format)` copies literal segment text through unvalidated; only the wildcard path routes the prior segment value through `ToInt` normalization before incrementing it ([BR-001](business-rules.md#br-001-non-numeric-leading-characters-in-a-version-segment-are-coerced-to-0), [BR-003](business-rules.md#br-003-a-wildcard-token-in-an-increment-format-means-auto-increment-this-segment), [BR-004](business-rules.md#br-004-an-empty-increment-format-token-means-retain-the-current-segment-value-unchanged), [BR-005](business-rules.md#br-005-increment-format-supports-date-template-tokens-year-month-day)).

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- `SAIF.Framework.Version\Version.vb`