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.IsValid())  // true
fmt.Println(version.String())   // v1.2.3-rc.1

Valid, IsValid and IsInvalid distinguish a successfully parsed zero version from an invalid result. Invalid is the canonical invalid value and can be used instead of SemVer{}. ParseSemVer and NewEmptySemVer return valid values on success. Set Valid: true when constructing a valid SemVer with a struct literal.

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 validity, parsed components, component presence and the 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) IsInvalid() bool
  • func (s SemVer) IsValid() bool
  • func (s SemVer) MajorString() string
  • func (s *SemVer) SetMajorMinorOnly()
  • func (s *SemVer) SetMajorOnly()
  • func (s SemVer) String() string

Variables

var (
	// Invalid is the canonical invalid SemVer value.
	Invalid SemVer

	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
	Valid    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 validity and 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) IsInvalid

func (s SemVer) IsInvalid() bool

IsInvalid reports whether s does not represent a successfully parsed or constructed version.

func (SemVer) IsValid

func (s SemVer) IsValid() bool

IsValid reports whether s was produced by a successful parse or constructor.

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.