Protocols · Library

The six protocols of the standard library: what each one requires, what it provides, and who conforms.

Equatable

Anything that can be compared for equality.

Declaration

protocol Equatable {
	is(_ other: Self) -> Boolean
	isNot(_ other: Self) -> Boolean
}

Requires

is(_ other: Self) -> Boolean

Answers whether both values are equal.

NameTypeDescription

_Selfthe value to compare with

Returns true when the values are equal.

Example

expect "Ada"::is("Ada")
expect [1, 2]::is([2, 1])::negate()

Provides

isNot(_ other: Self) -> Boolean

Answers whether the values differ.

NameTypeDescription

_Selfthe value to compare with

Returns true when the values differ.

Example

expect "Ada"::isNot("Grace")
expect 3::isNot(3)::negate()

Every choice has is and isNot without declaring Equatable. Two of its values are equal when they are the same case with equal payloads.

Conforming Algebraic, Boolean, Dictionary where KeyType is Equatable, ValueType is Equatable, HttpMethod, Redirects, HttpFailure, Division, Integer, SortOrder, List where ItemType is Equatable, Number, Optional where ItemType is Equatable, Ordering, NumberFormat, Rounding, SignStyle, Rational, Record, Result where ValueType is Equatable, FailureType is Equatable, Side, CaseSensitivity, NormalizationForm, String, Stream, Transcendental

Required by Dictionary.of(_:), Dictionary.of(_:valuedBy:), Dictionary::is(_:), Dictionary::hasKey(_:), Dictionary::hasValue(_:), Dictionary::value(at:), Dictionary::value(at:defaultingTo:), Dictionary::set(_:to:), Dictionary::update(at:with:), Dictionary::update(at:defaultingTo:with:), Dictionary::remove(at:), Dictionary::remove(atEvery:), Dictionary::merge(with:), Dictionary::merge(with:choosing:), GroupedList::group(on:), GroupedList::tally(), GroupedList::index(on:), GroupedNonEmptyList::group(on:), GroupedNonEmptyList::tally(), GroupedNonEmptyList::index(on:), List::is(_:), List::contains(_:), List::contains(everyItemOf:), List::doesNotContain(_:), List::hasDuplicates(), List::hasDuplicates(on:), List::starts(with:), List::doesNotStart(with:), List::ends(with:), List::doesNotEnd(with:), List::firstIndex(of:), List::firstIndex(of:defaultingTo:), List::lastIndex(of:), List::lastIndex(of:defaultingTo:), List::everyIndex(of:), List::removeEvery(_:), List::removeEvery(contentsOf:), List::everyItem(alsoIn:), List::count(of:), List::split(on:), List::removeDuplicates(), List::removeDuplicates(on:), NonEmptyList::removeDuplicates(), NonEmptyList::removeDuplicates(on:), Optional::is(_:), Optional::isNot(_:), Result::is(_:), Result::isNot(_:)

Printable

Anything that can represent itself as a String.

Declaration

protocol Printable {
	toString() -> String
}

Requires

toString() -> String

Answers the value as a String.

Returns the String representation of the value.

Example

expect 42::toString()::is("42")
expect [1, 2]::toString()::is("[1, 2]")

A choice whose cases carry no payload prints its case name once a namespace declares is Printable for it. The namespace body can stay empty: namespace Side for Side is Equatable, is Printable {}.

An interpolation hole in a String needs a Printable value. Any other value is interpolation-not-printable.

Conforming Algebraic, Boolean, Dictionary where KeyType is Printable, ValueType is Printable, HttpMethod, Redirects, HttpFailure, Division, Integer, SortOrder, List where ItemType is Printable, Number, Optional where ItemType is Printable, Ordering, NumberFormat, Rounding, SignStyle, Rational, Record, Result where ValueType is Printable, FailureType is Printable, Side, CaseSensitivity, NormalizationForm, String, Stream, Transcendental

Required by Dictionary::toString(), List::toString(), List::join(with:), Optional::toString(), Result::toString(), Terminal.print(_:to:)

Comparable

Anything with a total order among its values.

Declaration

protocol Comparable {
	compare(to other: Self) -> Ordering
	isLessThan(_ other: Self) -> Boolean
	isLessThanOrEqualTo(_ other: Self) -> Boolean
	isGreaterThan(_ other: Self) -> Boolean
	isGreaterThanOrEqualTo(_ other: Self) -> Boolean
}

Requires

compare(to other: Self) -> Ordering

Orders the value against another one of the same Type.

NameTypeDescription

toSelfthe value to compare with

Returns Ordering#Less, Ordering#Equal or Ordering#Greater.

Example

expect 3::compare(to 5)::is(#Less)
expect "pear"::compare(to "apple")::is(#Greater)

Provides

isLessThan(_ other: Self) -> Boolean

Answers whether the value is strictly below another.

NameTypeDescription

_Selfthe value to compare with

Returns true when the value is below the given one.

Example

expect 3::isLessThan(5)
expect 5::isLessThan(5)::negate()

isLessThanOrEqualTo(_ other: Self) -> Boolean

Answers whether the value is below another, or equal to it.

NameTypeDescription

_Selfthe value to compare with

Returns true when the value is below the given one or equal to it.

Example

expect 3::isLessThanOrEqualTo(5)
expect 5::isLessThanOrEqualTo(5)

isGreaterThan(_ other: Self) -> Boolean

Answers whether the value is strictly above another.

NameTypeDescription

_Selfthe value to compare with

Returns true when the value is above the given one.

Example

expect "pear"::isGreaterThan("apple")
expect "pear"::isGreaterThan("pear")::negate()

isGreaterThanOrEqualTo(_ other: Self) -> Boolean

Answers whether the value is above another, or equal to it.

NameTypeDescription

_Selfthe value to compare with

Returns true when the value is above the given one or equal to it.

Example

expect 5::isGreaterThanOrEqualTo(3)
expect 5::isGreaterThanOrEqualTo(5)

Conforming Algebraic (through Orderable), Boolean, Integer (through Orderable), List where ItemType is Comparable, Number (through Orderable), Rational (through Orderable), String

Required by Dictionary::sort(in:), Dictionary::sort(on:in:), NonEmptyDictionary::sort(in:), NonEmptyDictionary::sort(on:in:), List::compare(to:), List::isSorted(in:), List::sort(in:), List::sort(on:in:), List::lowestItem(on:), List::lowestItem(on:defaultingTo:), List::lowestItem(), List::lowestItem(defaultingTo:), List::highestItem(on:), List::highestItem(on:defaultingTo:), List::highestItem(), List::highestItem(defaultingTo:), NonEmptyList::sort(in:), NonEmptyList::sort(on:in:), NonEmptyList::lowestItem(on:), NonEmptyList::lowestItem(), NonEmptyList::highestItem(on:), NonEmptyList::highestItem()

Orderable

Anything on a line, where a value can be between two others or pulled into a range.

Declaration

protocol Orderable is Comparable {
	isBetween(_ lower: Self, and upper: Self) -> Boolean
	clamp(between lowest: Self, and highest: Self) -> Self
}

Extends Comparable: a type that conforms to Orderable conforms to it too, and gets what it provides.

Provides

isBetween(_ lower: Self, and upper: Self) -> Boolean

Answers whether the value lies between the two given ones, both included.

The two bounds name the same range in either order: 7::isBetween(10, and 1) is true, and 15::isBetween(10, and 1) is false.

NameTypeDescription

_Selfone bound of the range, included

andSelfthe other bound of the range, included

Returns true when the value is within the bounds.

Example

expect 7::isBetween(1, and 10)
expect 7::isBetween(10, and 1)
expect 15::isBetween(10, and 1)::negate()

clamp(between lowest: Self, and highest: Self) -> Self

Answers the value, pulled into the given bounds.

The answer is the lower bound when the value is below it. It is the upper bound when the value is above it, and the value itself otherwise. The two bounds name the same range in either order: 7::clamp(between 10, and 1) is 7, and 15::clamp(between 10, and 1) is 10.

NameTypeDescription

betweenSelfone bound of the range

andSelfthe other bound of the range

Returns the clamped value.

Example

expect 7::clamp(between 1, and 10)::is(7)
expect 15::clamp(between 1, and 10)::is(10)
expect -4::clamp(between 10, and 1)::is(1)

Conforming Algebraic, Integer, Number, Rational

Enumerable

Anything whose values can be listed, from a Choice whose Cases carry no payload.

Declaration

protocol Enumerable {
	static cases() -> NonEmptyList<Self>
}

Requires

static cases() -> NonEmptyList<Self>

Answers every value of the Type.

The values stand in the order the Cases are declared in. A Choice has at least one Case, so the answer certainly holds one.

Returns every Case of the Choice, in declaration order.

Every choice whose cases carry no payload has the static cases() without declaring Enumerable. It returns the cases in the order they are declared: Side.cases() is [Start, End, BothEnds].

Derived for Division, NumberFormat, Rounding, SignStyle, Side, CaseSensitivity, NormalizationForm, SortOrder, Ordering, Stream, HttpMethod, Redirects

Generatable

Anything a property test can build values of.

A Namespace that declares this conformance replaces the generator a property test derives from the Type. The derived generator also makes a failing value smaller, and a conformance answers shrink for that instead. The provided shrink answers no candidates, so a Namespace that writes none of its own has its counterexamples reported as they were drawn.

Declaration

protocol Generatable {
	static generate(from source: Randomness) -> Self
	shrink() -> List<Self>
}

Requires

static generate(from source: Randomness) -> Self

Answers a value of the conforming Type, built from a source of randomness.

A property test derives a generator from the Type where a Namespace declares no conformance. Declaring one replaces that generator, for a Type whose values carry an invariant the derived one can not know about.

NameTypeDescription

fromRandomnessthe source to draw from.

Returns a value of the conforming Type.

Provides shrink, with its own entry below.

No namespace in the standard library conforms to it.

shrink

provided by Generatable

shrink() -> List<Self>

Answers the smaller values a failing one can be reported as.

A property test that fails asks its counterexample for these candidates, and reports the first one that fails as well. It asks that value for its own, so a body answering one step smaller each time reports the smallest value the property fails on. The runner tries the candidates in the order the List holds them, and skips one that is the failing value itself. The body here answers no candidates, so a Namespace that writes none of its own reports the value the source drew.

Returns the smaller values, smallest first.