semver

README

semver

A small version parser supporting SemVer syntax and partial versions.

Supported formats

1
1.2
1.2.3
v1.2.3
1.2.3-alpha.1
1.2.3+build.2026
1.2.3-rc.1+build.2026

Leading and trailing whitespace is trimmed. Numeric components are limited to uint16 and cannot contain leading zeros.

Partial versions, the v prefix and Unicode suffix identifiers are extensions to SemVer 2.0.0.

Usage

version, err := ParseSemVer("v1.2.3-rc.1", true)
if err != nil {
	log.Fatal(err)
}

fmt.Println(version.Major)      // 1
fmt.Println(version.Minor)      // 2
fmt.Println(version.Patch)      // 3
fmt.Println(version.Suffix)     // -rc.1
fmt.Println(version.String())   // v1.2.3-rc.1

Set allowSuffix to false to reject prerelease and build metadata:

_, err := ParseSemVer("1.2.3-alpha", false)
if errors.Is(err, ErrDisallowedSuffix) {
	// Suffixes are not allowed.
}

Comparison

stable, _ := ParseSemVer("1.0.0", true)
candidate, _ := ParseSemVer("1.0.0-rc.1", true)

stable.HigherThan(candidate) // true
stable.Compare(candidate)    // 1

Compare follows SemVer precedence:

• Missing components compare as zero.
• Prerelease versions have lower precedence than releases.
• Build metadata and the v prefix do not affect precedence.

Equal compares the parsed components, component presence and complete suffix. It ignores the optional v prefix.

Performance

Successful parsing is designed to perform no heap allocations. String allocates the returned string.

Run the tests and benchmarks with:

go test ./...
go test -race ./...
go test -bench=. -benchmem ./...

Documentation

Index

• Variables
• type SemVer
  • func NewEmptySemVer() SemVer
  • func ParseSemVer(input string, allowSuffix bool) (SemVer, error)
  • func (s SemVer) Compare(b SemVer) int
  • func (s SemVer) Equal(b SemVer) bool
  • func (s SemVer) HigherThan(b SemVer) bool
  • func (s SemVer) MajorString() string
  • func (s *SemVer) SetMajorMinorOnly()
  • func (s *SemVer) SetMajorOnly()
  • func (s SemVer) String() string

Variables

var (
	ErrEmptyVersion     = errors.New("empty version")
	ErrInvalidVersion   = errors.New("invalid version")
	ErrInvalidSuffix    = errors.New("invalid version suffix")
	ErrDisallowedSuffix = errors.New("disallowed version suffix")
)

Types

type SemVer

type SemVer struct {
	Major uint16
	Minor uint16
	Patch uint16

	HasMinor bool
	HasPatch bool

	Prefix byte
	Suffix string
}

func NewEmptySemVer

func NewEmptySemVer() SemVer

NewEmptySemVer returns a zeroed SemVer with minor and patch components marked as present.

func ParseSemVer

func ParseSemVer(input string, allowSuffix bool) (SemVer, error)

ParseSemVer parses input into a SemVer. An optional v prefix is accepted and a suffix is only allowed when allowSuffix is true.

func (SemVer) Compare

func (s SemVer) Compare(b SemVer) int

Compare compares semantic-version precedence. Prefixes, missing zero components and build metadata do not affect precedence.

func (SemVer) Equal

func (s SemVer) Equal(b SemVer) bool

Equal compares parsed identity, ignoring the optional v prefix.

func (SemVer) HigherThan

func (s SemVer) HigherThan(b SemVer) bool

HigherThan reports whether s has higher precedence than b.

func (SemVer) MajorString

func (s SemVer) MajorString() string

MajorString returns the major component, with the v prefix when present and no minor or patch components.

func (*SemVer) SetMajorMinorOnly

func (s *SemVer) SetMajorMinorOnly()

SetMajorMinorOnly truncates the version to its major and minor components, clearing patch and suffix.

func (*SemVer) SetMajorOnly

func (s *SemVer) SetMajorOnly()

SetMajorOnly truncates the version to its major component, clearing minor, patch and suffix.

func (SemVer) String

func (s SemVer) String() string

String returns the canonical string form of the version, including the v prefix and any suffix.