Annotation to mark a class as abstract. An abstract class may have formal members, but may not be directly instantiated. An enumerated class must be abstract.

Annotation to mark a member of a type as refining a member of a supertype.

Annotation to specify a list of aliases that tools such as auto-completion and quick-fixes should consider, to help users find a declaration using its aliases.

Annotation to mark a class as an annotation class, or a top-level function as an annotation constructor.

Annotation to document the authors of an API.

Annotation to mark a member whose implementation may be refined by subtypes. Non-default declarations may not be refined.

Annotation to mark program elements which should not be used anymore.

Annotation to specify API documentation of a program element. The doc annotation need not be explicitly specified, since a string literal at the beginning of a declaration is implicitly considered an argument to doc().

"Something awesome"
void hello() => print("hello");

Is an abbreviation for:

doc ("Something awesome")
void hello() => print("hello");

Annotation to mark a class as final. A final class may not be extended. Marking a class as final affects disjoint type analysis.

Annotation to mark a member whose implementation must be provided by subtypes.

Annotation to disable definite initialization analysis for an attribute of a class, or for a toplevel value, or to specify that an attribute of a class should be initialized lazily.

• In the case of a class attribute, the attribute may have no initializer and may be left unassigned by the class initializer.
• In the case of a toplevel value, the value may have no initializer.

If a late value does have an initializer, the initializer will be executed lazily the first time the value is evaluated, if the value has not already been assigned.

A late value may be assigned by any code to which it is visible, but repeated assignment produces an InitializationError.

Evaluation of a late value with no initializer cannot be guaranteed sound by the compiler, and so evaluation of a late value with no initializer before it has been assigned produces an InitializationError.

class Lately() {

    shared interface Calculator {
        shared formal Float calculatePi();
    }

    //an uninitialized attribute
    late Calculator calculator;

    //a lazy attribute
    shared late Float pi = calculator.calculatePi();

    shared void init(Calculator calculator) {
        //initialize the attribute
        this.calculator = calculator;
    }

}

Annotation to specify the URL of the license of a module or package.

Annotation to mark a module, import, or declaration as platform-native.

For example, this code defines a native function in a cross-platform module:

import java.lang { System }

native void hello();

native ("jvm") void hello() {
    System.out.println("hello");
}

native ("js") void hello() {
    dynamic {
        console.log("hello");
    }
}

Annotation to specify that a module can be executed even if the annotated dependency is not available.

optional import org.some.service.provider "1.2.3";

Annotation to restrict the visibility of a declaration or package to a given list of modules. If no modules are specified, a restricted declaration is only visible within the package in which it is defined.

Annotation to mark an interface, class, or constructor as sealed. A sealed interface may not be satisfied outside of the module in which it is defined. A sealed class may not be extended or instantiated outside of the module in which it is defined. A sealed constructor may not be invoked outside of the module in which it is defined.

Annotation to specify references to other program elements related to the annotated API.

Annotation to specify that a class is serializable.

A serializable class may have instances that cannot be serialized if those instances have reachable references to instances of non-serializable classes.

Annotation marking a class as implementing a service. The class must be a non-abstract, shared, toplevel class.

For example, if Manager is an interface, this code declares an implementation of Manager:

service (`Manager`)
shared class DefautManager() satisfies Manager {}

Service implementations can be found at runtime using Module.findServiceProviders().

{Manager*} managers = `module`.findServiceProviders(`Manager`);
assert (exists manager = managers.first);

Annotation to mark a declaration as shared. A shared declaration is visible outside the block of code in which it is declared.

Annotation to indicate at which moment the annotated declaration was added to the module.

Annotation to hint to the compiler that, if possible:

• an Integer type should be represented using a 32-bit signed integer,
• a Float type should be represented using 32-bit IEEE float, or
• a Character type should be represented as a single 16-bit code point in the Basic Multilingual Plane.

The compiler is permitted to ignore this hint.

small Integer zero = 0;

Annotation to mark a member of a toplevel class as static. A static member does not have access to any current instance of the class, and must occur before all constructor declarations and non-static member declarations in the body of the class.

For example:

class Hello {
    shared static void hello() => print("hello");
    shared new() {}
}

A static member may be invoked or evaluated without any receiving instance of the class, by qualifying the member by a reference to the class itself.

shared void run() => Hello.hello();

The type parameters of a generic class are in scope at the declaration of a static member.

class Box<Element> {
    shared static Box<Element>[2] pair(Element x, Element y)
           => [create(x), create(y)];
    shared new create(Element element) {}
}

Box<Float>[2] boxes = Box.pair(1.0, 2.0);

Annotation to suppress compilation warnings of the specified types when typechecking the annotated program element.

Annotation to categorize an API by tag.

Annotation to document the exception types thrown by a function, value, class, or constructor.

throws(`class Exception`)
void die() { throw; }

Annotation to mark a value as variable. A variable value may be assigned multiple times.

The annotation class for the abstract() annotation.

The annotation class for the actual() annotation.

The annotation class for the aliased() annotation.

The annotation class for the annotation() meta-annotation.

The annotation class for the by() annotation.

The annotation class for the default() annotation.

The annotation class for the deprecated() annotation.

The annotation class for the doc() annotation.

The annotation class for the final() annotation.

The annotation class for the formal() annotation.

The annotation class for the late() annotation.

The annotation class for the license() annotation.

The annotation class for the native() annotation.

The annotation class for the optional() annotation.

The annotation class for the restricted() annotation.

The annotation class for the sealed() annotation.

The annotation class for the see() annotation.

The annotation class for the serializable() annotation.

The annotation class for the service() annotation.

The annotation class for the shared() annotation.

The annotation class for the since() annotation.

The annotation class for the small() annotation.

The annotation class for the static() annotation.

The annotation class for the suppressWarnings() annotation.

The annotation class for the tagged() annotation.

The annotation class for the throws() annotation.

The annotation class for the variable() annotation.

A sequence with no elements, abbreviated []. The unique instance of the type [].

An iterator that returns no elements.

An immutable Map with no entries.

An immutable Set with no elements.

The value is exactly equal to the given value.

A value representing falsity in Boolean logic.

A value that indicates that an Iterator is exhausted and has no more values to return.

An instance of Float representing positive infinity, ∞, the result of dividing a positive number by zero. Negative infinity, -∞, the result of dividing a negative number by zero, is the additive inverse -infinity.

Note that any floating-point computation that results in a positive value too large to be represented as a Float is “rounded up” to infinity. Likewise, any floating-point computation that yields a negative value whose magnitude is too large to be represented as a Float is “rounded down” to -infinity.

Contains information about the Ceylon language version.

The value is larger than the given value.

A value getter of type Nothing. The expression nothing is formally assignable to any type, but produces an exception when evaluated.

(This is most useful for tool-generated implementations of formal members.)

The null value.

Represents the operating system on which the current process is running.

Represents the current process (instance of the virtual machine).

Represents the machine and virtual machine on which the current process is executing.

Holds information about runtime name, version and about inherent limitations like minimum/maximum values that can be represented by the runtime.

The value is smaller than the given value.

Represents the system on which the current process is executing.

Holds information about system time and locale.

A value representing truth in Boolean logic.

Returns a function which is the logical conjunction of the given predicate functions.

Determines if any one of the given boolean values (usually a comprehension) is true.

Boolean anyNegative = any { for (x in xs) x<0.0 };

If there are no boolean values, return false.

Given two streams, return true if some pair of elements in the given streams satisfies the given binary predicate function, or false otherwise. If one of the streams is longer than the other, simply ignore additional elements of the longer stream with no pair in the other stream. If either stream is empty, return false.

For any given streams xs and ys, and predicate function p, anyPair() may be defined in terms of Iterable.any(), zipPairs(), and unflatten():

anyPair(p, xs, ys) == zipPairs(xs, ys).any(unflatten(p))

Applies an arbitrary Callable to the given arguments. The arguments must be packaged into a Tuple whose type is compatible with the Callable type.

For example, given the following argument tuple:

 [Boolean(Character), Boolean, Boolean] tuple
     = [Character.whitespace, true, false];

We can apply String.split() to the arguments given in tuple as follows:

String string = ... ;
{String*} strings = apply(string.split, tuple);

Application may be abbreviated using the spread operator:

String string = ... ;
{String*} strings = string.split(*tuple)

In practice, this behaves as if the Callable were called with the elements of the tuple as its arguments. The examples above are both equivalent to:

string.split(Character.whitespace, true, false)

Create an array of the specified size, populating every index with the given element. The specified size must be no larger than runtime.maxArraySize. If size<=0, the new array will have no elements.

Produces a comparator function which orders elements in decreasing order according to the Comparable value returned by the given comparable() function.

 "Hello World!".sort(byDecreasing(Character.lowercased))

This function is intended for use with Iterable.sort() and Iterable.max().

Produces a comparator function which orders elements in increasing order according to the Comparable value returned by the given comparable() function.

 "Hello World!".sort(byIncreasing(Character.lowercased))

This function is intended for use with Iterable.sort() and Iterable.max().

A comparator for Entrys which compares their items according to the given comparing() function.

value sortedEntries = map.sort(byItem(byIncreasing(String.lowercased)));

This function is intended for use with Iterable.sort() and Iterable.max().

A comparator for Entrys which compares their keys according to the given comparing() function.

value sortedEntries = map.sort(byKey(byIncreasing(String.lowercased)));

This function is intended for use with Iterable.sort() and Iterable.max().

Return the name of the concrete class of the given object, in a format native to the virtual machine. For example, className(0) evaluates to:

• "ceylon.language.Integer" on the Java Virtual Machine, and to
• "ceylon.language::Integer" on a JavaScript VM.

To obtain a platform-independent class name, use the type() function to obtain a metamodel object, for example:

type(1).declaration.qualifiedName

evaluates to "ceylon.language::Integer" on every platform.

Compares corresponding elements of the given streams using the given comparison function. Two elements are considered corresponding if they occupy the same position in their respective streams. Returns:

• the result of the given comparison for the earliest pair of corresponding elements whose comparison does not evaluate to equal, or, otherwise, if every comparison of corresponding pairs of elements produces equal,
• smaller, if the first stream produces fewer elements than the second stream,
• larger, if the first stream produces more elements than the second stream, or
• equal if the two streams produce the same number of elements.

If both streams are empty, return equal.

For example:

compareCorresponding({ 1, 2, 2, 5 }, 1:4,
       (Integer i, Integer j) => i<=>j)

and:

compareCorresponding({ 1, 2, 3 }, 1:4,
       (Integer i, Integer j) => i<=>j)

both evaluate to smaller.

A single comparator function which delegates to each of the given comparator functions in turn, returning the first result of smaller or larger if any, or returning equal otherwise.

Consider the following type:

class Person(shared Integer age, shared String name) {}

A stream of Persons may be sorted by age, breaking ties by name, like this:

people.sort(comparing(byDecreasing(Person.age), byIncreasing(Person.name)))

If no comparators are given, the resulting comparator always returns equal.

This function is intended for use with Iterable.sort() and Iterable.max().

Given a function with return type Y, and a second function with a single parameter also of type Y, return the composition of the two functions. The first function may have any number of parameters.

For any such functions f() and g(),

compose(g,f)(*args)==g(f(*args))

for every possible argument tuple args of f().

Given zero or more argument streams, return a new sequence containing all elements of every given stream. The elements of the resulting stream are ordered first according to the stream in which they occur, and then according to where they occur in that stream. If there are no arguments, or if none of the argument streams contain any elements, return the empty sequence.

For example, the expression

concatenate(1..3, [0.0], {"hello", "world"})

results in the sequence [1, 2, 3, 0.0, "hello", "world"] which has the type [Integer|Float|String*].

To concatentate Strings, use String.sum(). When a lazy stream is desired, use expand().

Compares corresponding elements of the given streams using the given binary predicate function. Two elements are considered corresponding if they occupy the same position in their respective streams. Returns true if and only if:

• the two streams have the same number of elements, and
• if the predicate is satisfied for every pair of corresponding elements.

Returns false otherwise. If both streams are empty, return true.

For example:

corresponding({ 1, 2, 3, 4 }, 1:4)

and:

corresponding({ 1, 2, 3, 4 }, "1234", 
       (Integer i, Character c) => i.string==c.string)

both evaluate to true.

A count of the number of true items in the given values.

Integer negatives = count { for (x in xs) x<0.0 };

Curries a function, returning a function with two parameter lists, given a function with at least one parameter. The first parameter list of the returned function has just the first parameter of the original function, and the second parameter list has the remaining parameters.

That is, if fun has type W(X,Y,Z) then curry(fun) has type W(Y,Z)(X).

A comparator function which orders elements in decreasing natural order.

   "Hello World!".sort(decreasing)

This function is intended for use with Iterable.sort() and Iterable.max().

A comparator function which orders entries by decreasing natural order of their items.

This function is intended for use with Iterable.sort() and Iterable.max().

A comparator function which orders entries by decreasing natural order of their keys.

This function is intended for use with Iterable.sort() and Iterable.max().

A singleton Tuple with the given element if the given element is non-null, or the empty sequence otherwise. This operation transforms an optional type T? to a sequence type []|[T] allowing optional values to be the subject of operations defined for streams.

For example, flat mapping emptyOrSingleton() reproduces the behavior of Iterable.coalesced. The expression

{ "1.23", "foo", "5.67", "-1", "" }
        .map(parseFloat)
        .flatMap(emptyOrSingleton)

produces the stream:

{ 1.23, 5.67, -1.0 }

Determines if every one of the given boolean values (usually a comprehension) is true.

Boolean allPositive = every { for (x in xs) x>0.0 };

If there are no boolean values, return true.

Given two streams, return true if every pair of elements in the given streams satisfies the given binary predicate function, or false otherwise. If one of the streams is longer than the other, simply ignore additional elements of the longer stream with no pair in the other stream. If either stream is empty, return true.

For any given streams xs and ys, and predicate function p, everyPair() may be defined in terms of Iterable.every(), zipPairs(), and unflatten():

everyPair(p, xs, ys) == zipPairs(xs, ys).every(unflatten(p))

Given a stream whose elements are also streams, return a new stream with all elements of every nested stream. If there are no nested streams, or if all of the nested streams are empty, return an empty stream.

For example, the expression

expand { 1..3, {5}, "hi" }

results in the stream { 1, 2, 3, 5, 'h', 'i' } which has the type {Integer|Character*}.

Given two streams, return the first pair of elements in the given streams that satisfies the given binary predicate function, or null if no pair of elements satisfies the predicate. If one of the streams is longer than the other, simply ignore additional elements of the longer stream with no pair in the other stream.

For any given streams xs and ys, and predicate function p, findPair() may be defined in terms of Iterable.find(), zipPairs(), and unflatten():

findPair(p, xs, ys) == zipPairs(xs, ys).find(unflatten(p))

Given a function with a single parameter of tuple type [P1, P2, ..., Pn], return a function with multiple parameters of type P1, P2, …, Pn.

That is, if fun has type W([X,Y,Z]) then flatten(fun) has type W(X,Y,Z).

In the case of a function whose parameter type is a sequence type or unterminated tuple type, the returned function is variadic:

• if the given function accepts [S*], the returned function has a single variadic parameter of type S*,
• if the given function accepts [S+], the returned function has a single variadic parameter of type S+,
• if the given function accepts [P1, P2, ..., Pn, S*], the returned function has multiple parameters with types P1, P2, …, Pn, S*, or
• if the given function accepts [P1, P2, ..., Pn, S+], the returned function has multiple parameters with types P1, P2, …, Pn, S+.

Given two streams, return the result of applying the given accumulating function to each pair of elements of the given streams in turn. If one of the streams is longer than the other, simply ignore additional elements of the longer stream with no pair in the other stream.

For any given streams xs and ys, initial value z, and combining function f, foldPairs() may be defined in terms of Iterable.fold(), zipPairs(), and unflatten():

foldPairs(z, f, xs, ys) == zipPairs(xs, ys).fold(z)(unflatten(f))

A function that returns the result of applying the given function to the item of a given Entry, discarding its key.

Map<String,List<Item>> map = ... ;
{Item?*} topItems = map.map(forItem(List<Item>.first));

A function that returns the result of applying the given function to the key of a given Entry, discarding its item.

Map<String,List<Item>> map = ... ;
{String*} uppercaseKeys = map.map(forKey(String.uppercased));

The string decimal representation of the given floating point number. If the given number is negative, the string representation will begin with -. The whole part and fractional parts of the number are separated by a . decimal point. Digits consist of decimal digits 0 to 9.

The number of decimal places following the decimal point is controlled by the parameters minDecimalPlaces and maxDecimalPlaces, which default to 1 and 9 respectively, so that by default the string representation always contains a decimal point, and never contains more than nine decimal places. The decimal representation is rounded so that the number of decimal places never exceeds the specified maximum.

For example:

• formatFloat(1234.1234) is "1234.1234"
• formatFloat(0.1234) is "0.1234"
• formatFloat(1234.0) is "1234.0"
• formatFloat(1234.0,0) is "1234"
• formatFloat(1234.1234,6) is "1234.123400"
• formatFloat(1234.1234,0,2) is "1234.12"
• formatFloat(1234.123456,0,5) is "1234.12346"
• formatFloat(0.0001,2,2) is "0.00"
• formatFloat(0.0001,0,2) is "0"

Finally:

• formatFloat(-0.0) is "0.0",
• formatFloat(0.0/0) is "NaN",
• formatFloat(1.0/0) is "Infinity", and
• formatFloat(-1.0/0) is "-Infinity".

This function never produces a representation involving scientific notation.

The string representation of the given integer in the base given by radix. If the given integer is negative, the string representation will begin with -. Digits consist of decimal digits 0 to 9, together with and lowercase letters a to z for bases greater than 10.

For example:

• formatInteger(-46) is "-46"
• formatInteger(9,2) is "1001"
• formatInteger(10,8) is "12"
• formatInteger(511,16) is "1ff"
• formatInteger(512,32) is "g0"

Determine if the arguments are identical(). Equivalent to x===y. Only instances of Identifiable have well-defined identity.

The identity function that always returns its argument.

Return the system-defined identity hash value of the given value. This hash value is consistent with identity equality.

A comparator function which orders elements in increasing natural order.

   "Hello World!".sort(increasing)

This function is intended for use with Iterable.sort() and Iterable.max().

A comparator function which orders entries by increasing natural order of their items.

This function is intended for use with Iterable.sort() and Iterable.max().

A comparator function which orders entries by increasing natural order of their keys.

This function is intended for use with Iterable.sort() and Iterable.max().

Given one or more argument streams, return a stream containing elements of the given streams. The elements are ordered first according to their position in the argument stream, and then according to the stream in which they occur. The resulting stream contains exactly the same number of elements from each stream.

For example, the expression

interleave(1..5, "-+".cycled)

results in the stream { 1, '-', 2, '+', 3, '-', 4, '+', 5, '-' }.

Given two Comparable values, return largest of the two.

If exactly one of the given values violates the reflexivity requirement of Object.equals() such that x!=x, then the other value is returned. In particular, if exactly one is an undefined Float (Float.undefined), it is not returned.

On the JVM platform, for arguments of type Integer or Float, prefer Integer.largest() or Float.largest() in performance-sensitive code.

Produces the stream that results from repeated application of the given function to the given first element of the stream, until the function first returns finished. If the given function never returns finished, the resulting stream is infinite.

For example:

loop(0)(2.plus).takeWhile(10.largerThan)

produces the stream { 0, 2, 4, 6, 8 }.

Create a new immutable Map containing every Entry produced by the given stream, resolving items with duplicate keys according to the given function.

For example:

map { 1->"hello", 2->"goodbye" }

produces the map { 1->"hello", 2->"goodbye" }.

This is an eager operation and the resulting map does not reflect changes to the given stream.

Given two streams, form a new stream by applying a binary mapping function to pairs of elements in the given streams. If one of the streams is longer than the other, simply ignore additional elements of the longer stream with no pair in the other stream. The length of the resulting stream is the length of the shorter of the two given streams.

For any given streams xs and ys, and mapping function f, mapPairs() may be defined in terms of Iterable.map(), zipPairs(), and unflatten():

mapPairs(f, xs, ys) == zipPairs(xs, ys).map(unflatten(f))

For example the expression

mapPairs((Float x, Float y) => (x^2+y^2)^0.5, 
        {3.0, 5.0, 6.0, 9.0}, {4.0, 12.0, 8.0, 12.0})

evaluates to the stream { 5.0, 13.0, 10.0, 15.0 }.

Given a stream of Comparable values, return the largest value in the stream, or null if the stream is empty.

For any nonempty stream it, max(it) evaluates to the first element of it such that for every element e of it, max(it) >= e.

Any value x which violates the reflexivity requirement of Object.equals() such that x!=x is skipped, unless it is the last element in the stream. Thus, for a stream of Floats, max() will not return an undefined value unless every element of the stream is undefined.

Note that Iterable.max() may be used to find the largest value in any stream, as determined by a given comparator function.

Produces a Range of adjacent Enumerable values generated by a first element, and a strictly positive size, or returns the empty sequence if size <= 0. The range includes all values whose offset from first is non-negative and less than the size.

More precisely, if x and first are of Enumerable type X, and size is an integer, then x in first:size if and only if 0 <= x.offset(first) < size.

The measure operator : is an abbreviation for measure():

for (i in start:size) { ... }
for (char in '0':10) { ... }

The measure operator accepts the first index and size of the range:

0:5     // [0, 1, 2, 3, 4]

If the size is nonpositive, the range is empty:

0:0     // []
5:0     // []
0:-5    // []

Given a stream of Comparable values, return the smallest value in the stream, or null if the stream is empty.

For any nonempty stream it, min(it) evaluates to the first element of it such that for every element e of it, min(it) <= e.

Any value x which violates the reflexivity requirement of Object.equals() such that x!=x is skipped, unless it is the last element in the stream. Thus, for a stream of Floats, min() will not return an undefined value unless every element of the stream is undefined.

A void function that does nothing.

Returns a function which is the logical negation of the given predicate function.

Returns a function which is the logical disjunction of the given predicate functions.

The Boolean value of the given string representation of a boolean value, or null if the string does not represent a boolean value.

Recognized values are "true", "false".

The Float value of the given string representation of a decimal floating point number, or null if the string does not represent a decimal floating point number.

If the given string representation contains more digits than can be represented by a Float, then the least significant digits are ignored.

The syntax accepted by this method is the same as the syntax for a Float literal in the Ceylon language except that it may optionally begin with a sign character (+ or -) and may not contain grouping underscore characters. That is, an optional sign character, followed by a string of decimal digits, followed by an optional decimal point and string of decimal digits, followed by an optional decimal exponent, for example e+10 or E-5, or SI magnitude, k, M, G, T, P, m, u, n, p, or f.

Float: Sign? Digits ('.' Digits)? (Magnitude|Exponent)
Sign: '+' | '-'
Magnitude: 'k' | 'M' | 'G' | 'T' | 'P' | 'm' | 'u' | 'n' | 'p' | 'f'
Exponent: ('e'|'E') Sign? Digits
Digits: ('0'..'9')+

The Integer value of the given string representation of an integer value in the base given by radix, or null if the string does not represent an integer in that base, or if the mathematical integer it represents is too large in magnitude to be represented by an instance of the class Integer.

The syntax accepted by this function depends upon the given base:

• For base 10, the accepted syntax is the same as the syntax for an Integer literal in the Ceylon language except that it may optionally begin with a sign character (+ or -) and may not contain grouping underscore characters. That is, an optional sign character, followed be a string of decimal digits, followed by an optional SI magnitude: k, M, G, T, or P.
• For other bases, the accepted syntax is an optional sign character, followed by a string of digits of the given base.

The given radix specifies the base of the string representation. The list of available digits starts from 0 to 9, followed by a to z. When parsing in a specific base, the first radix digits from the available digits list is used. This function is not case sensitive; a and A both correspond to the digit a whose decimal value is 10.

Integer: Base10 | BaseN
Base10: Sign? Base10Digits Magnitude
BaseN: Sign? BaseNDigits
Sign: '+' | '-'
Magnitude: 'k' | 'M' | 'G' | 'T' | 'P'
Base10Digits: ('0'..'9')+
BaseNDigits: ('0'..'9'|'a'..'z'|'A'..'Z')+

Add the given Summable values.

(1..100).by(2).fold(0)(plus<Integer>)

Print a line to the standard output of the virtual machine process, printing the given value's string, or <null> if the value is null.

This function is a shortcut for:

process.writeLine(line?.string else "<null>")

and is intended mainly for debugging purposes.

Print multiple values to the standard output of the virtual machine process as a single line of text, separated by a given character sequence.

Print the stack trace of the given Exception using the given function, or to standard error if no function is specified.

Given a nonempty stream of Numeric values, return the product of the values.

{Float+} values = ... ;
Float result = product(values);

For the case of a possibly-empty stream, form a nonempty stream starting with the unit element (the multiplicative identity).

{Float*} values = ... ;
Float result = product { 1.0, *values };

For the case of a stream of Integers or Floats, prefer Integer.product() or Float.product().

A nonempty sequence of the given elements, or null if the given stream is empty. A non-null, but possibly empty, sequence may be obtained using the else operator:

[Element*] sequenceOfElements = sequence(elements) else [];

Create a new immutable Set containing every element produced by the given stream, resolving items with duplicate keys according to the given function.

For example:

set { 0, 1, 1, 2, 3, 3, 3 }

produces the set { 0, 1, 2, 3 }.

This is an eager operation and the resulting set does not reflect changes to the given stream.

Given a function with two parameter lists, return a function with the order of the argument lists reversed. The parameter lists may have any number of parameters.

That is, if fun has type W(A,B)(X,Y,Z) then shuffle(fun) has type W(X,Y,Z)(A,B).

This function is often used in conjunction with curry().

Given two Comparable values, return smallest of the two.

If exactly one of the given values violates the reflexivity requirement of Object.equals() such that x!=x, then the other value is returned. In particular, if exactly one is an undefined Float (Float.undefined), it is not returned.

On the JVM platform, for arguments of type Integer or Float, prefer Integer.smallest() or Float.smallest() in performance-sensitive code.

Sort the given elements according to their natural order, returning a new sequence.

Note that Iterable.sort() may be used to sort any stream according to a given comparator function.

Produces a Range of adjacent Enumerable values generated by two endpoints: first and last. The range includes both endpoints, and all values falling between the endpoints.

• For a recursive enumerable type, a value falls between the endpoints if its offset from first is less than the offset of last from first.
• For a linear enumerable type, a value falls between the endpoints if the sign of its offset from first is the same as the sign of the offset of last from first and the sign of its offset from last is the opposite of the sign of the offset of last from first.

More precisely, if x, first, and last are of Enumerable type X, then x in first..last if and only if:

• X is recursive and x.offset(first)<last.offset(first), or
• X is linear and x.offsetSign(first)==last.offsetSign(first) and x.offsetSign(last)==-last.offsetSign(first).

For a linear enumerable type, a range is either increasing or decreasing:

• in an increasing range, a value occurs before its successor and after its predecessor, but
• in a decreasing range, a value occurs after its successor and before its predecessor.

The direction of the range depends upon the sign of the offset of last from first:

• if last.offsetSign(first)>=0 the range is increasing, but
• if last.offsetSign(first)<0, the range is decreasing.

A range for a recursive enumerable type is always increasing.

The span operator .. is an abbreviation for span():

for (i in min..max) { ... }
if (char in 'A'..'Z') { ... }

The span operator accepts the first and last values of the range. It may produce an increasing range:

0..5    // [0, 1, 2, 3, 4, 5]
0..0    // [0]

Or it may produce a decreasing range:

5..0    // [5, 4, 3, 2, 1, 0]
0..-5   // [0, -1, -2, -3, -4, -5]

Given a nonempty stream of Summable values, return the sum of the values.

{Float+} values = ... ;
Float total = sum(values);

For the case of a possibly-empty stream, form a nonempty stream starting with the zero element (the additive identity).

{Float*} values = ... ;
Float total = sum { 0.0, *values };

For the case of a stream of Integers, Floats, or Strings, prefer Integer.sum(), Float.sum(), or String.sum().

Multiply the given Numeric values.

(1..100).by(2).fold(1)(times<Integer>)

Uncurries a function, returning a function with one parameter list, given a function with two parameter lists, where the first parameter list has exactly one parameter. The parameter list of the returned function has the parameter of the first parameter list of the original function, followed by all parameters of the second parameter list.

That is, if fun has type W(Y,Z)(X) then uncurry(fun) has type W(X,Y,Z).

Given a function with parameter types P1, P2, …, Pn, return a function with a single parameter of tuple type [P1, P2, ..., Pn].

That is, if fun has type W(X,Y,Z) then unflatten(fun) has type W([X,Y,Z]).

In the case of a variadic function, the returned function has a single parameter whose type is a sequence type or unterminated tuple type:

• if the given function has a single variadic parameter of type S*, the returned function accepts [S*],
• if the given function has a single variadic parameter of type S+, the returned function accepts [S+],
• if the given function has multiple parameters with types P1, P2, …, Pn, S*, the returned function accepts [P1, P2, ..., Pn, S*], or
• if the given function has multiple parameters with types P1, P2, …, Pn, S+, the returned function accepts [P1, P2, ..., Pn, S+].

Given a stream of tuples, return two streams. The first stream produces the first elements of the given tuples, and the second stream produces the remaining elements of the given tuples.

Thus:

tuples[i] == [unzip(tuples)[0][i], 
             *unzip(tuples)[1][i]]

Given a stream of entries, return two streams. The first stream produces the keys of the given entries, and the second stream produces the items of the given entries.

Thus:

entries[i] == unzipEntries(entries)[0][i] 
           -> unzipEntries(entries)[1][i]

Given a stream of pairs, return two streams. The first stream produces the first elements of the given pairs, and the second stream produces the second elements of the given pairs.

Thus:

pairs[i] == [unzipPairs(pairs)[0][i], 
             unzipPairs(pairs)[1][i]]

Given a stream of values, and a stream of tuples, produce a new stream of tuples formed by prepending the values in the first stream to the tuples in the second stream. The length of the resulting stream is the length of the shorter of the two given streams.

Thus:

zip(heads, tails)[i] == [heads[i], *tails[i]]

for every 0<=i<smallest(heads.size,tails.size).

Given two streams, form a new stream consisting of all entries where, for any given index in the resulting stream, the key of the entry is the element occurring at the same index in the first stream, and the item is the element occurring at the same index in the second stream. The length of the resulting stream is the length of the shorter of the two given streams.

Thus:

zipEntries(keys, items)[i] == keys[i] -> items[i]

for every 0<=i<smallest(keys.size,items.size).

Given two streams, form a new stream consisting of all pairs where, for any given index in the resulting stream, the first element of the pair is the element occurring at the same index in the first stream, and the second element of the pair is the element occurring at the same index in the second stream. The length of the resulting stream is the length of the shorter of the two given streams.

Thus:

zipPairs(xs, ys)[i] == [xs[i], ys[i]]

for every 0<=i<smallest(xs.size,ys.size).

A program element that can be annotated.

The supertype of all annotation classes.

Annotation classes

An annotation class must satisfy Annotation, OptionalAnnotation, or SequencedAnnotation and must be annotated final annotation. For example:

"An annotation class."
final annotation class Example(shared String description) 
      satisfies Annotation {}

Annotation classes which satisfy Annotation directly may be applied to any program element that supports annotations (see Annotated). In practice, annotation classes often satisfy OptionalAnnotation or SequencedAnnotation in order to prevent annotations being applied to inappropriate program elements.

Each initializer parameter of an annotation class must have one of the following types:

• Integer, Float, Character, or String,
• an enumerated type whose cases are all anonymous classes, such as Boolean,
• a subtype of Declaration
• an annotation class,
• {T*} or [T*] where T is a legal annotation parameter type, or
• any tuple type whose element types are legal annotation parameter types.

An initializer parameter of an annotation class may be variadic or defaulted.

Annotation constructors

An annotation constructor is simply a top level function, annotated with annotation whose return type is an annotation class type. For example:

"An annotation constructor."
annotation Example example(String description="") 
    => Example(description);

Each parameter of an annotation constructor must have one of the following types:

• Integer, Float, Character, or String,
• an enumerated type whose cases are all anonymous classes, such as Boolean,
• a subtype of Declaration,
• an annotation type,
• {T*} or [T*] where T is a legal annotation constructor parameter type, or
• any tuple type whose element types are legal annotation constructor parameter types.

A parameter of an annotation constructor may be variadic or defaulted.

The constructor must simply instantiate and return the annotation class, and there are strict rules about the arguments to the instantiation.

A given annotation class can have multiple annotation constructors.

Abstraction of types that are conceptually a sequence of bits, and may be the subject of bitwise operations. A bit is a Boolean value. Bits are indexed from right to left, where 0 is the index of the least significant bit.

A reference to a function. The type arguments encode the Return of the function along with its Arguments. The parameter types are represented by a tuple type. Functions declared void are considered to have the return type Anything.

For example, the type of the anonymous function (Float x, Integer y) => x^y+1 is:

Callable<Float, [Float,Integer]>

which we usually abbreviate to Float(Float,Integer).

Likewise, the type of the function reference plus<Float> to the function plus() is:

Callable<Float, [Float,Float]>

which we abbreviate as Float(Float,Float).

A variadic function is represented using an unterminated tuple type. For example, the type of the function reference concatenate<Object> to the function concatenate() is:

Callable<Object[], [{Object*}*]>

which we usually abbreviate Object({Object*}*).

A function with defaulted parameters is represented using a union type. For example, the type of the method reference process.writeLine to the method process.writeLine() is:

Callable<Anything, [String]|[]>

which we usually abbreviate Anything(String=).

Finally, any type of form Callable<X,Y> may be abbreviated to X(*Y).

Any instance of Callable may be invoked by supplying a positional argument list:

Float(Float,Float) add = plus<Float>;
value four = add(2.0, 2.0);

or by supplying a tuple containing the arguments:

Float(Float,Float) add = plus<Float>;
[Float,Float] twoAndTwo = [2.0, 2.0];
value four = add(*twoAndTwo);

The type of the tuple must be assignable to the type argument of Arguments.

There is no reasonable and computationally decidable definition of value equality for a function reference. Therefore, the equals() method of an instance of Callable always returns false, and x==y always evaluates to false for any two function references x and y.

This interface may not be implemented by user-written code.

Abstract supertype of objects that contain other values, called elements, where it is possible to efficiently determine if a given value is an element. A Category may not be finite, and its elements may not even be countable. Thus, unlike streams, the elements of a generic Category are not iterable.

Category models a mathematical set, but is distinct from the Set collection type which represents finite sets.

The in operator may be used to determine if a value belongs to a Category:

if (69 in 0..100) { ... }
assert (key->item in { for (n in 0..100) n.string->n**2 });

An object may be a Category of two different disjoint element types. For example, String is a Category of its Characters and of its substrings.

if ("hello" in "hello world") { ... }
assert ('.' in string);

Every meaningful Category is formed from elements with some equivalence relation. Ordinarily, that equivalence relation is value equality. Thus, ordinarily, x==y implies that x in cat == y in cat. But this contract is not required since it is possible to form a meaningful Category using a different equivalence relation. For example, an IdentitySet is a meaningful Category, where the equivalence relation is identity equality.

Since Null is not considered to have any meaningful equivalence relation, a Category may not contain the null value.

Note that even though Category<Element> is declared contravariant in its Element, most types that inherit Category are covariant in their element type, and therefore satisfy Category<Object>, resulting in some loss of typesafety. For such types, Category.contains() should return false for any value that is not an instance of the element type. For example, String is a Category<Object>, not a Category<Character|String>, and x in string evaluates to false for every x that is not a String or Character.

An iterable collection of elements of finite Iterable.size, with a well-defined notion of value equality. Collection is the abstract supertype of List, Map, and Set.

A Collection forms a Category of its elements, and is Iterable. The elements of a collection are not necessarily distinct when compared using Object.equals().

A Collection may be cloned. If a collection is immutable, it is acceptable that clone() produce a reference to the collection itself. If a collection is mutable, clone() should produce a collection containing references to the same elements, with the same structure as the original collection—that is, it should produce a shallow copy of the collection.

All Collections are required to support a well-defined notion of value equality, but the definition of equality depends upon the kind of collection. Equality for Maps and Sets has a quite different definition to equality for Lists. Instances of two different kinds of collection are never equal—for example, a Map is never equal to a List.

The general contract for values whose magnitude can be compared. Comparable imposes a total ordering upon instances of any type that satisfies the interface.

If a type T satisfies Comparable<T>, then instances of T may be compared using the comparison operators <, >, <=, >=.

assert (x>=0.0);

A ternary comparison is useful for asserting lower and upper bounds.

assert (0.0<=x<1.0);

Finally, the compare operator <=> may be used to produce an instance of Comparison.

switch (x<=>y)
case (equal) {
    print("same same");
}
case (smaller) {
    print("x smaller");
}
case (larger) {
    print("y smaller");
}

The total order of a type must be consistent with the definition of equality for the type. That is, there are three mutually exclusive possibilities:

• x<y,
• x>y, or
• x==y

(These possibilities are expressed by the enumerated instances smaller, larger, and equal of Comparison.)

The order imposed by Comparable is sometimes called the natural order of a type, to reflect the fact that any function of type Comparison(T,T) might determine a different order. Thus, some order-related operations come in two flavors: a flavor that depends upon the natural order, and a flavor which accepts an arbitrary comparator function. Examples are:

• sort() vs Iterable.sort() and
• max() vs Iterable.max().

An annotation constrained to appear only on certain program elements, and only with certain values.

This interface should never be satisfied directly by any annotation type. Instead, either OptionalAnnotation or SequencedAnnotation should be satisfied by the annotation type.

The type parameters encode information about the annotation type and its constraints:

• Value represents the type of the annotation itself,
• ProgramElement represents a constraint on the
  reference expression type of the annotated program element, for example, ClassDeclaration or Module, where Annotated means there is no constraint, and
• Type is a constraint on the metamodel type of the annotated program element, for example, Function<Float,[Float,Float]> (ceylon.language.meta.model::Function), where Anything means there is no constraint, and that the program element need not have a metamodel type.

Abstract supertype of objects which associate values with keys. A Correspondence<Key,Item> may be a viewed as a partial function from domain Key to range Item, where some Keys have no Item.

Correspondence does not satisfy Category, since in some cases—List, for example—it is convenient to consider the subtype a Category of its indexed items, and in other cases—Map, for example—it is convenient to treat the subtype as a Category of its entries.

The item corresponding to a given key may be obtained from a Correspondence using the item operator:

value bg = settings["backgroundColor"] else white;

The get() operation and item operator result in an optional type, to reflect the possibility that there may be no item for the given key.

A Correspondence that supports mutation of its constituent key/item associations. Items may be mutated via the assignment and item operators:

array[i] = i^2;

Every CorrespondenceMutator is either:

• a KeyedCorrespondenceMutator, which allows the creation of new key/item associations, or
• an IndexedCorrespondenceMutator, which only allows mutation of items associated with a given range of integer indexes.

Most CorrespondenceMutators are also instances of Correspondence.

Abstract supertype of resources which are created at the beginning of a try statement and destroyed when the statement completes. Unlike an Obtainable resource, a single instance of Destroyable may not be reused between multiple try statements or multiple executions of the same try statement.

try (tx = Transaction()) {
    ...
}

• The resource is instantiated before the body of the try statement is executed, and
• Destroyable.destroy() is called when execution of the body of the try statement ends, even if an exception propagates out of the body of the try.

A sequence with no elements. The type Empty may be abbreviated [], and an instance is produced by the expression []. That is, in the following expression, none has type [] and refers to the value []:

[] none = [];

(Whether the syntax [] refers to the type or the value depends upon how it occurs grammatically.)

Abstraction of ordinal types whose values may be used as endpoints of a span() or measure().

An Enumerable type is characterized by each element having well-defined offset and Enumerable.neighbour() functions. Given an instance x of an enumerable type X:

• for any integer-valued offset, there is a unique neighbour y of X with that offset, and
• if y is an instance of X, then there is a well-defined integer-valued offset of x from y.

The offset function must satisfy:

• x.offset(x) == 0, and
• x.successor.offset(x) == 1 if x!=x.successor.

The neighbour function must satisfy:

• x.neighbour(0) == x,
• x.neighbour(n-1) == x.neighbour(n).predecessor, and
• x.neighbour(n+1) == x.neighbour(n).successor.

Of course, it follows that:

• x.neighbour(-1) == x.predecessor, and
• x.neighbour(1) == x.successor.

An enumerable type may be linear or recursive. If X is a linear enumerable type, then the offset function satisfies:

• x.predecessor.offset(x) == -1 if x!=x.predecessor,
• x.offset(y) == -y.offset(x) for any instance y of X, and
• x.offset(y) == x.offset(z) + z.offset(y).

Otherwise, X is a recursive enumerable type with a finite list of enumerated instances of size count, and its offset and neighbour functions must satisfy:

• x.neighbour(count)==x,
• x.offset(y) >= 0 for any instance y of X, and
• x.predecessor.offset(x) == count - 1.

A range of values of an enumerable type may be specified using:

• the span operator, written first..last, or
• the segment operator, written first:length.