Source Code

The Ceylon language module containing the core types referred to in the language specification.

By: Gavin King, Tom Bentley, Tako Schotanus, Stephane Epardaud, Enrique Zamudio
License: http://www.apache.org/licenses/LICENSE-2.0.html
Packages
ceylon.language

The Ceylon language package.

ceylon.language.meta

The Ceylon metamodel base package.

ceylon.language.meta.declaration

The Ceylon metamodel open type and declaration package.

ceylon.language.meta.model

The Ceylon metamodel closed type and model package.

The Ceylon language package.

By: Gavin King, Tom Bentley, Tako Schotanus, Stephane Epardaud, Enrique Zamudio
Annotations
abstractSource Code
shared AbstractAnnotation abstract()

Annotation to mark a class as abstract. An abstract class may not be directly instantiated. An abstract class may have enumerated cases.

actualSource Code
shared ActualAnnotation actual()

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

annotationSource Code
shared AnnotationAnnotation annotation()

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

See also: Annotation
bySource Code

Annotation to specify API authors.

Parameters:
  • authors

    The authors, in Markdown syntax, of the annotated element

defaultSource Code
shared DefaultAnnotation default()

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

deprecatedSource Code
shared DeprecationAnnotation deprecated(String reason = "")

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

Parameters:
  • reason = ""

    A description, in Markdown syntax, of why the element is deprecated, and what replacements are available.

docSource Code
shared DocAnnotation doc(String description)

Annotation to specify API documentation of a program element.

Parameters:
  • description

    Documentation, in Markdown syntax, about the annotated element

finalSource Code
shared FinalAnnotation final()

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

formalSource Code
shared FormalAnnotation formal()

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

lateSource Code
shared LateAnnotation late()

Annotation to disable definite initialization analysis for a reference.

licenseSource Code
shared LicenseAnnotation license(String description)

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

Parameters:
  • description

    The name, text, or URL of the license.

nativeSource Code
shared NativeAnnotation native()

Annotation to mark a member whose implementation is defined in platform-native code.

optionalSource Code
shared OptionalImportAnnotation optional()

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

seeSource Code

Annotation to specify API references to other related program elements.

Parameters:
  • programElements

    The program elements being referred to.

sharedSource Code
shared SharedAnnotation shared()

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

taggedSource Code

Annotation to categorize the API by tag.

Parameters:
  • tags

    The tags, in plain text.

throwsSource Code
shared ThrownExceptionAnnotation throws(Declaration type, String when = "")

Annotation to mark a program element that throws an exception.

Parameters:
  • type

    The Exception type that this thrown.

  • when = ""

    A description, in Markdown syntax, of the circumstances that cause this exception to be thrown.

variableSource Code
shared VariableAnnotation variable()

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

AbstractAnnotationSource Code

The annotation class for abstract.

ActualAnnotationSource Code

The annotation class for actual.

AnnotationAnnotationSource Code

The annotation class for annotation.

AuthorsAnnotationSource Code

The annotation class for by.

DefaultAnnotationSource Code

The annotation class for default.

DeprecationAnnotationSource Code

The annotation class for deprecated.

DocAnnotationSource Code

The annotation class for the doc annotation.

FinalAnnotationSource Code

The annotation class for final.

FormalAnnotationSource Code

The annotation class for formal.

LateAnnotationSource Code

The annotation class for late.

LicenseAnnotationSource Code

The annotation class for license.

NativeAnnotationSource Code

The annotation class for native.

OptionalImportAnnotationSource Code

The annotation class for optional.

SeeAnnotationSource Code

The annotation class for see.

SharedAnnotationSource Code

The annotation class for shared.

TagsAnnotationSource Code

The annotation class for tagged.

ThrownExceptionAnnotationSource Code

The annotation class for throws.

VariableAnnotationSource Code

The annotation class for variable.

Values
emptySource Code
shared empty empty

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

emptyIteratorSource Code
shared emptyIterator emptyIterator

An iterator that returns no elements.

emptyMapSource Code
shared emptyMap emptyMap

A Map with no entries.

emptySetSource Code
shared emptySet emptySet

A Set with no elements.

equalSource Code
shared equal equal

The value is exactly equal to the given value.

falseSource Code
shared false false

A value representing falsity in Boolean logic.

finishedSource Code
shared finished finished

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

See also: Iterator
infinitySource Code
shared Float infinity= 1.0/0.0

An instance of Float representing positive infinity ∞.

languageSource Code
shared language language

Contains information about the language

largerSource Code
shared larger larger

The value is larger than the given value.

nothingSource Code
shared Nothing nothing

A value that is assignable to any type, but that results in an exception when evaluated. This is most useful for generating members in an IDE.

nullSource Code
shared null null

The null value.

By: Gavin
operatingSystemSource Code
shared operatingSystem operatingSystem

Operating System on which the current process is running.

processSource Code
shared process process

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

By: Gavin, Tako
runtimeSource Code
shared runtime runtime

Machine (Virtual or not) on which the current process is running.

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

smallerSource Code
shared smaller smaller

The value is smaller than the given value.

systemSource Code
shared system system

Represents the system on which the current process is running.

Holds information about system time and locale.

trueSource Code
shared true true

A value representing truth in Boolean logic.

Functions
anySource Code

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

See also: every
applySource Code
shared Return apply<Return, Args>(Callable<Return,Args> f, Args args)

Applies an arbitrary Callable to the specified arguments. The arguments are taken packaged in a tuple whose type is compatible with the Callable arguments tuple.

In practice, this behaves as if the Callable were called with the elements of the tuple used as its arguments.

See also: unflatten
arrayOfSizeSource Code
shared Array<Element> arrayOfSize<Element>(Integer size, Element element)

Create an array of the specified size, populating every index with the given element. If the specified size is smaller than 1, return an empty array of the given element type.

Parameters:
  • size

    The size of the resulting array. If the size is non-positive, an empty array will be created.

  • element

    The element value with which to populate the array. All elements of the resulting array will have the same value.

byDecreasingSource Code
shared Comparison byDecreasing<Element, Value>(Value comparable(Element e))(Element x, Element y)
given Value satisfies Comparable<Value>

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

See also: byIncreasing
byIncreasingSource Code
shared Comparison byIncreasing<Element, Value>(Value comparable(Element e))(Element x, Element y)
given Value satisfies Comparable<Value>

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

See also: byDecreasing
byItemSource Code
shared Comparison byItem<Item>(Comparison comparing(Item x, Item y))(Object->Item x, Object->Item y)
given Item satisfies Object

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

See also: byKey
byKeySource Code

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

See also: byItem
classNameSource Code
shared String className(Object obj)

Return the name of the concrete class of the given object, in a format native to the virtual machine.

coalesceSource Code

Return a sequence containing the given values which are not null. If there are no values which are not null, return an empty sequence.

Parameters:
  • values

    The values, some of which may be null.

composeSource Code

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().

See also: curry, uncurry
concatenateSource Code

Given a list of iterable objects, return a new sequence of all elements of the all given objects. If there are no arguments, or if none of the arguments contains any elements, return the empty sequence.

Parameters:
  • iterables

    The iterable objects to concatenate.

See also: SequenceBuilder
countSource Code

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

currySource Code
shared Callable<Return,Rest> curry<Return, Argument, First, Rest>(Callable<Return,Tuple<Argument,First,Rest>> f)(First first)
given First satisfies Argument

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).

See also: uncurry, compose
emptyOrSingletonSource Code
shared Element[] emptyOrSingleton<Element>(Element? element)
given Element satisfies Object

A Singleton if the given element is non-null, otherwise Empty.

See also: Singleton, Empty
entriesSource Code

Given a stream of items, produce a stream of entries. For each non-null item produced by the given stream of items, the resulting stream contains an Entry of form key->item where key is the index at which the item occurs in the stream of items.

equalToSource Code
shared Boolean equalTo<Element>(Element val)(Element element)
given Element satisfies Object

Returns a partial function that will compare an element to any other element and returns true if they're equal. This is useful in conjunction with methods that receive a predicate function.

everySource Code

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

See also: any
firstSource Code
shared Absent|Value first<Value, Absent>(Iterable<Value,Absent> values)
given Absent satisfies Null

The first of the given values (usually a comprehension), if any.

flattenSource Code
shared Callable<Return,Args> flatten<Return, Args>(Return tupleFunction(Args tuple))

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).

See also: unflatten
forItemSource Code
shared Result forItem<Item, Result>(Result resulting(Item item))(Object->Item entry)
given Item satisfies Object

A function that returns the result of the given resulting() function on the item of a given Entry.

See also: forKey
forKeySource Code
shared Result forKey<Key, Result>(Result resulting(Key key))(Key->Object entry)
given Key satisfies Object

A function that returns the result of the given resulting() function on the key of a given Entry.

See also: forItem
formatIntegerSource Code
shared String formatInteger(Integer integer, Integer radix = ...)

The string representation of integer in the radix base. radix must be between minRadix and maxRadix included.

If integer is negative, returned string will start by character -

Parameters:
  • radix = 10
Throws:
greaterThanSource Code
shared Boolean greaterThan<Element>(Element val)(Element element)
given Element satisfies Comparable<Element>

Returns a partial function that will compare an element to any other element and returns true if the compared element is greater than its element. This is useful in conjunction with methods that receive a predicate function.

identicalSource Code
shared Boolean identical(Identifiable x, Identifiable y)

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

Parameters:
  • x

    An object with well-defined identity.

  • y

    A second object with well-defined identity.

See also: identityHash
identityHashSource Code
shared Integer identityHash(Identifiable x)

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

See also: identical
largestSource Code
shared Element largest<Element>(Element x, Element y)
given Element satisfies Comparable<Element>

Given two Comparable values, return largest of the two.

See also: Comparable, smallest, max
lessThanSource Code
shared Boolean lessThan<Element>(Element val)(Element element)
given Element satisfies Comparable<Element>

Returns a partial function that will compare an element to any other element and returns true if the compared element is less than its element. This is useful in conjunction with methods that receive a predicate function.

mapPairsSource Code
shared {Result*} mapPairs<Result, FirstArgument, SecondArgument>(Result collecting(FirstArgument firstArg, SecondArgument secondArg), {FirstArgument*} firstArguments, {SecondArgument*} secondArguments)

Given two streams, form a new stream by applying a function to the arguments in the given streams. The length of the resulting stream is the length of the shorter of the two given streams.

Thus:

mapPairs(xs,ys,fun)[i]==fun(xs[i],ys[i])

for every 0<=i<min({xs.size,ys.size}).

maxSource Code
shared Absent|Value max<Value, Absent>(Iterable<Value,Absent> values)
given Value satisfies Comparable<Value>
given Absent satisfies Null

Given a nonempty stream of Comparable values, return the largest value in the stream.

See also: Comparable, min, largest
minSource Code
shared Absent|Value min<Value, Absent>(Iterable<Value,Absent> values)
given Value satisfies Comparable<Value>
given Absent satisfies Null

Given a nonempty stream of Comparable values, return the smallest value in the stream.

See also: Comparable, max, smallest
parseBooleanSource Code

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”.

parseFloatSource Code

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

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 -).

parseIntegerSource Code

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

The syntax accepted by this function 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 -).

A radix can be given in input to specify what is the base to take in consideration for the parsing. radix has to be between minRadix and maxRadix included. 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 can be used. This function is not case sensitive; a and A both correspond to the a digit which decimal value is 10.

_ character can be used to separate groups of digits for bases 2, 10 and 16 as for Integer literal in the Ceylon language. For any other bases, no grouping is supported.

Parameters:
  • radix = 10
Throws:
plusSource Code
shared Value plus<Value>(Value x, Value y)
given Value satisfies Summable<Value>

Add the given Summable values.

See also: times, sum
printSource Code
shared void print(Anything val)

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 method is a shortcut for:

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

and is intended mainly for debugging purposes.

By: Gavin
printAllSource Code

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

Parameters:
  • separator = ", "

    A character sequence to use to separate the values

By: Gavin
printStackTraceSource Code
shared void printStackTrace(Exception exception, void write(String string) = ...)

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

Parameters:
  • write = process.writeError(string)

    A function that prints the given string. Defaults to process.writeError().

productSource Code
shared Value product<Value>({Value+} values)
given Value satisfies Numeric<Value>

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

See also: sum
shuffleSource Code
shared Callable<Callable<Result,FirstArgs>,SecondArgs> shuffle<Result, FirstArgs, SecondArgs>(Callable<Callable<Result,SecondArgs>,FirstArgs> f)

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().

See also: curry
smallestSource Code
shared Element smallest<Element>(Element x, Element y)
given Element satisfies Comparable<Element>

Given two Comparable values, return smallest of the two.

See also: Comparable, largest, min
sortSource Code

Sort the given elements, returning a new sequence.

See also: Comparable
sumSource Code
shared Value sum<Value>({Value+} values)
given Value satisfies Summable<Value>

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

See also: product
suppressedExceptionsSource Code

Returns the exceptions that were suppressed (if any) during the handling of the given exception.

timesSource Code
shared Value times<Value>(Value x, Value y)
given Value satisfies Numeric<Value>

Multiply the given Numeric values.

See also: plus, product
uncurrySource Code
shared Callable<Return,Tuple<Argument,First,Rest>> uncurry<Return, Argument, First, Rest>(Callable<Return,Rest> f(First first))
given First satisfies Argument

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).

See also: curry, compose
unflattenSource Code
shared Return unflatten<Return, Args>(Callable<Return,Args> flatFunction)(Args args)

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]).

See also: flatten
unzipSource Code

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:

unzip(tuples)[i]==[tuples[i].first,*tuples[i].rest]
unzipEntriesSource Code

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:

unzipEntries(entries)[i]==[entries[i].key,entries[i].item]
unzipPairsSource Code

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:

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

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<min({heads.size,tails.size}).

zipEntriesSource Code

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<min({keys.size,items.size}).

zipPairsSource Code

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<min({xs.size,ys.size}).

Interfaces
AnnotatedSource Code
shared Annotated

A program element that can be annotated.

AnnotationSource Code
shared Annotation

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 ceylon.language.meta.declaration::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 ceylon.language.meta.declaration::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.

An annotation class can have multiple annotation constructors.

BinarySource Code
shared Binary<Other>

Abstraction of numeric types like Integer that may be represented as a sequence of bits, and may be the subject of bitwise operations.

CallableSource Code
shared Callable<out Return,in Arguments>

A reference to a function. The type arguments encode the function return type and parameter types. The parameter types are typically represented as a tuple type. For example, the type of the function reference plus<Float> is:

Callable<Float,[Float,Float]>

which we usually abbreviate Float(Float,Float). 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);

This interface may not be implemented by user code.

CategorySource Code
shared Category

Abstract supertype of objects that contain other values, called elements, where it is possible to efficiently determine if a given value is an element. Category does not satisfy Container, because it is conceptually possible to have a Category whose emptiness cannot be computed.

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

if ("hello" in "hello world") { ... }
if (69 in 0..100) { ... }
if (key->value in { for (n in 0..100) n.string->n**2 }) { ... }

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.

CloneableSource Code
shared Cloneable<out Clone>

Abstract supertype of objects whose value can be cloned.

CloseableSource Code
shared Closeable

Abstract supertype of types which may appear as the expression type of a resource expression in a try statement.

CollectionSource Code
shared Collection<out Element>

Represents an iterable collection of elements of finite size. Collection is the abstract supertype of List, Map, and Set.

A Collection forms a Category of its elements.

All Collections are Cloneable. 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 an immutable collection containing references to the same elements, with the same structure as the original collection—that is, it should produce an immutable shallow copy of the collection.

ComparableSource Code
shared Comparable<in Other>

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 <, >, <=, >=, and <=>.

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
ConstrainedAnnotationSource Code
shared ConstrainedAnnotation<out Value = Annotation,out Values = Anything,in ProgramElement = Nothing>

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

This interface should not be satisfied directly. Instead either OptionalAnnotation or SequencedAnnotation should be satisfied.

CorrespondenceSource Code
shared Correspondence<in Key,out Item>

Abstract supertype of objects which associate values with keys. Correspondence does not satisfy Category, since in some cases—List, for example—it is convenient to consider the subtype a Category of its values, 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 is no item for the given key.

EmptySource Code
shared Empty

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, e has type [] and refers to the value []:

[] none = [];

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

EnumerableSource Code
shared Enumerable<out Other>

Abstraction of ordinal types whose instances can be mapped to the integers or to a range of integers.

ExponentiableSource Code
shared Exponentiable<This,Other>

Abstraction of numeric types that may be raised to a power x^p. Note that the type of the exponent may be different to the numeric type which may be exponentiated.

IdentifiableSource Code

The abstract supertype of all types with a well-defined notion of identity. Values of type Identifiable may be compared using the === operator to determine if they are references to the same object instance. For the sake of convenience, this interface defines a default implementation of value equality equivalent to identity. Of course, subtypes are encouraged to refine this implementation.

IntegralSource Code
shared Integral<Other>

Abstraction of integral numeric types. That is, types with no fractional part, including Integer. The division operation for integral numeric types results in a remainder. Therefore, integral numeric types have an operation to determine the remainder of any division operation.

InvertableSource Code
shared Invertable<out Inverse>

Abstraction of types which support a unary additive inversion operation -x. For a numeric type, this should return the negative of the argument value.

Implementations which also satisfy Summable should respect the following constraint:

  • x + -x == 0
IterableSource Code
shared Iterable<out Element,out Absent = Null>

Abstract supertype of categories whose elements may be iterated. An iterable category need not be finite, but its elements must at least be countable. There may not be a well-defined iteration order, and so the order of iterated elements may not be stable.

The type Iterable<Element,Null>, usually abbreviated {Element*} represents a possibly-empty iterable container. The type Iterable<Element,Nothing>, usually abbreviated {Element+} represents a nonempty iterable container.

An instance of Iterable may be constructed by surrounding a value list in braces:

{String+} words = { "hello", "world" };

An instance of Iterable may be iterated using a for loop:

for (c in "hello world") { ... }

Iterable and its subtypes define various operations that return other iterable objects. Such operations come in two flavors:

  • Lazy operations return a view of the receiving iterable object. If the underlying iterable object is mutable, then changes to the underlying object will be reflected in the resulting view. Lazy operations are usually efficient, avoiding memory allocation or iteration of the receiving iterable object.
  • Eager operations return an immutable object. If the receiving iterable object is mutable, changes to this object will not be reflected in the resulting immutable object. Eager operations are often expensive, involving memory allocation and iteration of the receiving iterable object.

Lazy operations are preferred, because they can be efficiently chained. For example:

string.filter((Character c) => c.letter)
      .map((Character c) => c.uppercased)

is much less expensive than:

string.select((Character c) => c.letter)
      .collect((Character c) => c.uppercased)

Furthermore, it is always easy to produce a new immutable iterable object given the view produced by a lazy operation. For example:

[ *string.filter((Character c) => c.letter)
      .map((Character c) => c.uppercased) ]

Lazy operations normally return an instance of Iterable or Map.

However, there are certain scenarios where an eager operation is more useful, more convenient, or no more expensive than a lazy operation, including:

  • sorting operations, which are eager by nature,
  • operations which preserve emptiness/nonemptiness of the receiving iterable object.

Eager operations normally return a sequence.

IteratorSource Code
shared Iterator<out Element>

Produces elements of an Iterable object. Classes that implement this interface should be immutable.

ListSource Code
shared List<out Element>

Represents a collection in which every element has a unique non-negative integer index.

A List is a Collection of its elements, and a Correspondence from indices to elements.

Direct access to a list element by index produces a value of optional type. The following idiom may be used instead of upfront bounds-checking, as long as the list element type is a non-null type:

value char = "hello world"[index];
if (exists char) { /*do something*/ }
else { /*out of bounds*/ }

To iterate the indexes of a List, use the following idiom:

for (i->char in "hello world".indexed) { ... }
MapSource Code
shared Map<out Key,out Item>

Represents a collection which maps keys to items, where a key can map to at most one item. Each such mapping may be represented by an Entry.

A Map is a Collection of its Entrys, and a Correspondence from keys to items.

The presence of an entry in a map may be tested using the in operator:

if ("lang"->"en_AU" in settings) { ... }

The entries of the map may be iterated using for:

for (key->item in settings) { ... }

The item for a key may be obtained using the item operator:

String lang = settings["lang"] else "en_US";
NumberSource Code
shared Number

Abstraction of numbers. Binary numeric operations are defined the interface Numeric. This type defines operations which can be expressed without reference to the self type Other of Numeric.

NumericSource Code
shared Numeric<Other>

Abstraction of numeric types with addition, x + y, subtraction, x - y, multiplication, x * y, and division, x / y, along with additive inverse -x.

In general, a numeric type need not define a total order. For example, complex numbers do not have a total order. Numeric types with a total order also satisfy Scalar.

OptionalAnnotationSource Code
shared OptionalAnnotation<out Value,in ProgramElement = Annotated>

An annotation that may occur at most once at a single program element and only on certain program elements.

An optional annotation is declared simply by having the annotation class satisfy OptionalAnnotation instead of Annotation. For example the following would only be allowed on class declarations:

final annotation class ExampleClass() 
        satisfies OptionalAnnotation<Example, ClassDeclaration> {}

At runtime a ceylon.language.meta.declaration::Declaration instance can be queried for its OptionalAnnotations of a certain type using ceylon.language.meta::annotations or ceylon.language.meta::optionalAnnotation.

OrdinalSource Code
shared Ordinal<out Other>

Abstraction of ordinal types, that is, types with successor and predecessor operations, including Integer and other Integral numeric types. Character is also considered an ordinal type. Ordinal types may be used to generate a Range.

RangedSource Code
shared Ranged<in Index,out Span>

Abstract supertype of ranged objects which map a range of Comparable keys to ranges of values. The type parameter Span abstracts the type of the resulting range.

A span may be obtained from an instance of Ranged using the span operator:

print("hello world"[0..5])
ScalableSource Code
shared Scalable<in Scale,out Value>

Abstract supertype of types that support scaling by a numeric factor s ** x. Examples of such types include vectors and matrices.

Implementations should generally respect the following constraints, where relevant:

  • x == 1**x

Implementations of Scalable are encouraged to also satisfy Invertable, in which case, the following identity should be respected:

  • -x == -1**x

Implementations of Scalable usually also satisfy Summable, in which case, the following identity should be respected:

  • x+x == 2**x
ScalarSource Code
shared Scalar<Other>

Abstraction of numeric types representing scalar values with a total order, including the built-in numeric types Integer and Float.

SequenceSource Code
shared Sequence<out Element>

A nonempty, immutable sequence of values. The type Sequence<Element>, may be abbreviated [Element+].

Given a possibly-empty sequence of type [Element*], the if (nonempty ...) construct, or, alternatively, the assert (nonempty ...) construct, may be used to narrow to a nonempty sequence type:

[Integer*] nums = ... ;
if (nonempty nums) {
    Integer first = nums.first;
    Integer max = max(nums);
    [Integer+] squares = nums.collect((Integer i) => i**2));
    [Integer+] sorted = nums.sort(byIncreasing((Integer i) => i));
}

Operations like first, max(), collect(), and sort(), which polymorphically produce a nonempty or non-null output when given a nonempty input are called emptiness-preserving.

SequencedAnnotationSource Code
shared SequencedAnnotation<out Value,in ProgramElement = Annotated>

An annotation that may occur multiple times at a single program element, and only on certain program elemenets.

A sequenced annotation is declared simply by having the annotation class satisfy SequencedAnnotation instead of Annotation. For example the following would only be allowed on class declarations, functions or methods:

alias ExecutableDeclaration 
       => ClassOrInterfaceDeclaration|FunctionDeclaration
"Documents a pattern that the annotated element is particpating in"
final annotation class Pattern(String name) 
        satisfies SequencedAnnotation<Pattern, ExecutableDeclaration> {
}

At runtime a ceylon.language.meta.declaration::Declaration instance can be queried for its SequencedAnnotations of a certain type using ceylon.language.meta::annotations or ceylon.language.meta::sequencedAnnotations.

SequentialSource Code
shared Sequential<out Element>

A possibly-empty, immutable sequence of values. The type Sequential<Element> may be abbreviated [Element*] or Element[].

Sequential has two enumerated subtypes:

  • Empty, abbreviated [], represents an empty sequence, and
  • Sequence<Element>, abbreviated [Element+] represents a non-empty sequence, and has the very important subclass Tuple.
SetSource Code
shared Set<out Element>

A collection of unique elements.

A Set is a Collection of its elements.

Sets may be the subject of the binary union, intersection, and complement operators |, &, and ~.

SummableSource Code
shared Summable<Other>

Abstraction of types which support a binary addition operator x + y. For numeric types, this is just familiar numeric addition. For String, it is string concatenation.

In general, the addition operation should be a binary associative operation.

Classes
AnythingSource Code
shared abstract Anything

The abstract supertype of all types. A value of type Anything may be a definite value of type Object, or it may be the null value. A method declared void is considered to have the return type Anything.

Note that the type Nothing, representing the intersection of all types, is a subtype of all types.

ArraySource Code
shared Array<Element>

A fixed-size array of elements. An array may have zero size (an empty array). Arrays are mutable. Any element of an array may be set to a new value.

This class is provided primarily to support interoperation with Java, and for some performance-critical low-level programming tasks.

ArraySequenceSource Code
shared ArraySequence<out Element>

An immutable Sequence implemented using the platform's native array type. Where possible copying of the underlying array is avoided. Direct use of this type is discouraged.

BasicSource Code
shared abstract Basic

The default superclass when no superclass is explicitly specified using extends. For the sake of convenience, this class inherits a default definition of value equality from Identifiable.

BooleanSource Code
shared abstract Boolean

A type capable of representing the values true and false of Boolean logic.

CharacterSource Code
shared Character

A 32-bit Unicode character.

ComparisonSource Code
shared abstract Comparison

The result of a comparison between two Comparable objects.

EntrySource Code
shared Entry<out Key,out Item>

A pair containing a key and an associated value called the item. Used primarily to represent the elements of a Map. The type Entry<Key,Item> may be abbreviated Key->Item. An instance of Entry may be constructed using the -> operator:

String->Person entry = person.name->person;
FinishedSource Code
shared abstract Finished

The type of the value that indicates that an Iterator is exhausted and has no more values to return.

FloatSource Code
shared Float

An IEEE 754 64-bit floating point number. A Float is capable of approximately representing numeric values between 2-1022 and (2-2-52)×21023, along with the special values infinity and -infinity, and undefined values (Not a Number). Zero is represented by distinct instances +0, -0, but these instances are equal. An undefined value is not equal to any other value, not even to itself.

IntegerSource Code
shared Integer

A 64-bit integer, or the closest approximation to a 64-bit integer provided by the underlying platform.

  • For the JVM runtime, integer values between -263 and 263-1 may be represented without overflow.
  • For the JavaScript runtime, integer values with a magnitude no greater than 253 may be represented without loss of precision.

Overflow or loss of precision occurs silently (with no exception raised).

LazyListSource Code
shared LazyList<out Element>

An implementation of List that wraps an Iterable of elements. All operations on this List are performed on the Iterable.

LazyMapSource Code
shared LazyMap<out Key,out Item>

A Map implementation that wraps an Iterable of entries. All operations, such as lookups, size, etc. are performed on the Iterable.

LazySetSource Code
shared LazySet<out Element>

An implementation of Set that wraps an Iterable of elements. All operations on this Set are performed on the Iterable.

NullSource Code
shared abstract Null

The type of the null value. Any union type of form Null|T is considered an optional type, whose values include null. Any type of this form may be written as T? for convenience.

The if (exists ... ) construct, or, alternatively, the assert (exists ...) construct, may be used to narrow an optional type to a definite type, that is, a subtype of Object:

String? firstArg = process.arguments.first;
if (exists firstArg) {
    print("hello " + firstArg);
}

The else operator evaluates its second operand if and only if its first operand is null:

String name = process.arguments.first else "world";

The then operator evaluates its second operand when its first operand evaluates to true, and to null otherwise:

Float? diff = x>=y then x-y;
ObjectSource Code
shared abstract Object

The abstract supertype of all types representing definite values. Any two Objects may be compared for value equality using the == and != operators:

true==false
1=="hello world"
"hello"+" "+"world"=="hello world"
Singleton("hello world")=={ "hello world" }

However, since Null is not a subtype of Object, the value null cannot be compared to any other value using ==. Thus, value equality is not defined for optional types. This neatly voids the problem of deciding the value of the expression null==null, which is simply illegal.

RangeSource Code
shared Range<Element>

Represents the range of totally ordered, ordinal values generated by two endpoints of type Ordinal and Comparable. If the first value is smaller than the last value, the range is increasing. If the first value is larger than the last value, the range is decreasing. If the two values are equal, the range contains exactly one element. The range is always nonempty, containing at least one value.

A range may be produced using the .. operator:

for (i in min..max) { ... }
if (char in 'A'..'Z') { ... }
SequenceAppenderSource Code
shared SequenceAppender<Element>

This class is used for constructing a new nonempty sequence by incrementally appending elements to an existing nonempty sequence. The existing sequence is not modified, since Sequences are immutable. This class is mutable but threadsafe.

SequenceBuilderSource Code
shared SequenceBuilder<Element>

Since sequences are immutable, this class is used for constructing a new sequence by incrementally appending elements to the empty sequence. This class is mutable but threadsafe.

SingletonSource Code
shared Singleton<out Element>

A sequence with exactly one element, which may be null.

StringSource Code
shared String

A string of characters. Each character in the string is a 32-bit Unicode character. The internal UTF-16 encoding is hidden from clients.

A string is a Category of its Characters, and of its substrings:

'w' in greeting 
"hello" in greeting

Strings are summable:

String greeting = "hello" + " " + "world";

They are efficiently iterable:

for (char in "hello world") { ... }

They are Lists of Characters:

value char = "hello world"[5];

They are ranged:

String who = "hello world"[6...];

Note that since string[index] evaluates to the optional type Character?, it is often more convenient to write string[index..index], which evaluates to a String containing a single character, or to the empty string "" if index refers to a position outside the string.

It is easy to use comprehensions to transform strings:

String { for (s in "hello world") if (s.letter) s.uppercased }

Since a String has an underlying UTF-16 encoding, certain operations are expensive, requiring iteration of the characters of the string. In particular, size requires iteration of the whole string, and get(), span(), and segment() require iteration from the beginning of the string to the given index.

StringBuilderSource Code

Since strings are immutable, this class is used for constructing a string by incrementally appending characters to the empty string. This class is mutable but threadsafe.

TupleSource Code
shared Tuple<out Element,out First,out Rest = []>

A tuple is a typed linked list. Each instance of Tuple represents the value and type of a single link. The attributes first and rest allow us to retrieve a value form the list without losing its static type information.

value point = Tuple(0.0, Tuple(0.0, Tuple("origin")));
Float x = point.first;
Float y = point.rest.first;
String label = point.rest.rest.first;

Usually, we abbreviate code involving tuples.

[Float,Float,String] point = [0.0, 0.0, "origin"];
Float x = point[0];
Float y = point[1];
String label = point[2];

A list of types enclosed in brackets is an abbreviated tuple type. An instance of Tuple may be constructed by surrounding a value list in brackets:

[String,String] words = ["hello", "world"];

The index operator with a literal integer argument is a shortcut for a chain of evaluations of rest and first. For example, point[1] means point.rest.first.

A terminated tuple type is a tuple where the type of the last link in the chain is Empty. An unterminated tuple type is a tuple where the type of the last link in the chain is Sequence or Sequential. Thus, a terminated tuple type has a length that is known statically. For an unterminated tuple type only a lower bound on its length is known statically.

Here, point is an unterminated tuple:

String[] labels = ... ;
[Float,Float,String*] point = [0.0, 0.0, *labels];
Float x = point[0];
Float y = point[1];
String? firstLabel = point[2];
String[] allLabels = point[2...];
emptySource Code
shared empty

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

emptyIteratorSource Code

An iterator that returns no elements.

emptyMapSource Code
shared emptyMap

A Map with no entries.

emptySetSource Code
shared emptySet

A Set with no elements.

equalSource Code
shared equal

The value is exactly equal to the given value.

falseSource Code
shared false

A value representing falsity in Boolean logic.

finishedSource Code
shared finished

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

languageSource Code
shared language

Contains information about the language

largerSource Code
shared larger

The value is larger than the given value.

nullSource Code
shared null

The null value.

operatingSystemSource Code

Operating System on which the current process is running.

processSource Code
shared process

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

runtimeSource Code
shared runtime

Machine (Virtual or not) on which the current process is running.

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

smallerSource Code
shared smaller

The value is smaller than the given value.

systemSource Code
shared system

Represents the system on which the current process is running.

Holds information about system time and locale.

trueSource Code
shared true

A value representing truth in Boolean logic.

Exceptions
AssertionExceptionSource Code

An exception that occurs when an assertion fails, that is, when a condition in an assert statement evaluates to false at runtime.

ExceptionSource Code
shared Exception

The supertype of all exceptions. A subclass represents a more specific kind of problem, and may define additional attributes which propagate information about problems of that kind.

InitializationExceptionSource Code

Thrown when a problem was detected with value initialization.

Possible problems include:

  • when a value could not be initialized due to recursive access during initialization,
  • an attempt to use a late value before it was initialized,
  • an attempt to assign to a late but non-variable value after it was initialized.
NegativeNumberExceptionSource Code

Thrown when a negative number is not allowed.

OverflowExceptionSource Code

Thrown when a mathematical operation caused a number to overflow from its bounds.