@head @module std @title std: Basic services

This module defines several basic types, constants and utility functions. The types include the primitive types, basic collection types and several exception types. The std module is the only module that is always imported without an explicit import definition, and its services are used by practically every Alore program.

Object type

@link std_object.html
The common supertype of every other class

Primitive types

@link std_about_primitive.html
The shared properties of primitive types
@link std_int.html
The integer type
@link std_str.html
The string type
@link std_float.html
The floating-point number type
@link std_boolean.html
The Boolean type
@link std_type.html
The type of types
@link std_function.html
The type of functions and bound methods
@link std_constant.html
The symbolic constant type
@link std_pair.html
A pair of values
@link std_range.html
A range of integer values

Collection types

@link std_array.html
A resizable array of values
@link std_tuple.html
A fixed-length, immutable sequence of values
@link std_map.html
A map of key-value pairs implemented as a hash table

Functions

@fun Print(...) @desc Write the arguments to the @ref{StdOut} stream, separated by spaces and followed by a line break. Flush the stream afterwards. Print is aimed at displaying debugging and diagnostics output, and Alore implementations may allow redirecting the output of Print to a log file or an IDE window, for example. Consider using WriteLn or Write for displaying normal program output. @example Print(2, "and", [2, 3]) -- Display "2 and [2, 3]" (without quotes) @end @end @fun Write(...) @desc Write the arguments to the @ref{StdOut} stream. This is a shorthand for io::StdOut.write. @end @fun WriteLn(...) @desc Write the arguments to the @ref{StdOut} stream, followed by a line break. This is a shorthand for io::StdOut.writeLn. @end @fun ReadLn() as Str @desc Read a line from @ref{StdIn}, and return the line without the line ending. This is a shorthand for io::StdIn.readLn. @end @fun Repr(object) as Str @desc Return a representation of the argument as a string. This is similar to the Str constructor, but this function may return more detailed information. Repr works with objects of all types. First try to return the result of calling the _repr method without arguments. If that fails, return the result of the _str method. If even that fails, return a generic representation of the argument that indicates the type of the object. Examples: @example Repr(3) -- "3" Repr('foo' + LF) -- "'foo\u000a'" Repr([nil, True]) -- "[nil, True]" @end @end @fun TypeName(object) as Str @desc Return the class name of the argument. Do not include module prefix for std module classes. Return the fully qualified name for other classes. Return "nil" if the argument is nil. Examples: @example TypeName(1) -- "Int" TypeName(StdIn) -- "io::TextStream" @end @see @ref{reflect::TypeOf} @end @end @fun Chr(n as Int) as Str @desc Return a single-character string with character code n. The valid range of values for n is from 0 to 65535, inclusive. @end @fun Ord(ch as Str) as Int @desc Return the character code of a single-character string. The return value is an integer in the range from 0 to 65535, inclusive. @end @fun Abs(x as Int) as Int @fun Abs(x as Float) as Float @desc Return the absolute value of an integer or a float. @end @fun Min(x, y) @desc Return the minimum of two objects. @end @fun Max(x, y) @desc Return the maximum of two objects. @end @fun Sort(sequence[, func]) @desc Return an array that has the items of a sequence sorted in ascending order (by default). The optional argument specifies a function that can be used for evaluating the order of two items. The function must accept 2 arguments and return a boolean indicating whether the first argument should appear earlier than the second argument in the sorted sequence. @end @fun Reversed(iterable as Iterable) as Array @desc Return an array that has all the items in the iterable in reverse order. Examples: @example Reversed([2, 3, 4]) -- [4, 3, 2] Reversed(0 to 3) -- [2, 1, 0] Reversed("foo") -- ["o", "o", "f"] @end @end @fun Hash(object) as Int @desc Return the hash value of an object as an integer. If the object has the _hash() method, return the result of calling that method with no arguments. This method should return an integer, and all instances that compare equal should receive the same hash value. If the object does not have this method, calculate the hash value based on the identity of the object.

The main purpose of the hash value is to spread different objects in different slots of a hash table most of the time, and to collect equal objects in the same slots. Therefore, even though technically all objects of a certain type could have the same hash value, this would result in a dramatic slowdown of certain operations. Due to efficiency reasons, the optimal maximum magnitude of hash values is typically about 2**29. @end @fun Exit([value as Int]) @desc Exit the program. The optional argument specifies an integer return value to the operating system. The function is implemented by raising an ExitException. It can be caught using a try statement to prevent the program from exiting. @end

Constants

This module also defines boolean constants: @var True @desc The boolean true value. @end @var False @desc The boolean false value. @end

A few string constants are provided as well: @var Tab @desc The tab character (code 9). @end @var Newline @desc The platform specific line break string. On Unix-like operating systems it is LF and on Windows CR + LF. @end @var LF @desc The line feed character (code 10). @end @var CR @desc The carriage return character (code 13). @end

Interfaces

@href{Sequence}
A sequence of values
@href{Iterable}
An object that supports iteration
@href{Iterator}
An iterator object
@href{Comparable}
An object that supports comparisons using < and >
@href{Addable}
An object that supports addition
@href{Multipliable}
An object that supports multiplication

Exceptions

The exception classes in the std module form this inheritance hierarchy:

  • Exception
    • ValueError
      • TypeError
      • MemberError
      • ArithmeticError
      • IndexError
      • KeyError
      • CastError
    • ResourceError
      • MemoryError
    • RuntimeError
    • InterruptException
    • ExitException
    • IoError

Simple exceptions

These exception classes have similar functionality inherited from Exception: @class Exception([message as Str]) @desc The base class of all exceptions. Exception has a single member, message, that contains the error message argument given to the constructor, or nil if the message argument was omitted or if it was nil. @end @class ValueError([message as Str]) @desc Raised when the input values of an operation or a function have invalid types or values. Typically, ValueError signifies a programming error, but it can be caught to recover from these situations. The several subclasses of ValueError indicate more specific conditions. @end @class TypeError([message as Str]) @desc Raised when the inputs of an operation or a function have unsupported types. Note that MemberError will be often raised in similar situations. @end @class MemberError([message as Str]) @desc Raised when an object does not have a requested member or the member being assigned to cannot be modified. @end @class ArithmeticError([message as Str]) @desc Raised when an arithmetic operation or function receives invalid inputs. A typical example is division by zero. @end @class IndexError([message as Str]) @desc Raised when the index of a sequence object such as an array is out of bounds or otherwise invalid. @end @class KeyError([message as Str]) @desc Raised when a key of a mapping object is not present or is otherwise invalid. @end @class CastError([message as Str]) @desc Raised when a cast operation fails. @end @class ResourceError([message as Str]) @desc Raised when a resource is exhausted. This exception can be triggered by lack of disk space or by too many open files, for example. @end @class MemoryError([message as Str]) @desc Raised when a memory allocation request cannot be fulfilled. This exception may also be raised if only a specific kind of memory pool is exhausted, even though there might be memory available for other purposes. @end @class RuntimeError([message as Str]) @desc Raised when there is a run-time error during execution that does not have a more specific exception class. @end @class InterruptException([message as Str]) @desc Raised when the user interrupts the program by pressing Ctrl+C. @end

ExitException

@class ExitException(code as Int) @desc Raised by the std::Exit function. The argument specifies the integer return value reported to the operating system. @end

IoError

@class IoError([message as Str[, error as Constant]]) @class IoError([message as Str[, error as Int]]) @desc Raised as a response to an operating system error. This exception can be raised by several modules such as @ref{io} and @ref{os}. Typical reasons for raising an IoError include a missing file or directory, insufficient access rights to a resource and insufficient free space on a device. The optional error argument describes the reason for the error. It can be an integer errno value or a symbolic constant. @see The @ref{errno} module defines symbolic constants that can be used to represent errors, and provides conversions between them and integer errno values. @end @end

IoError also has the following member constants: @var code as Constant @desc The symbolic constant representing the error. If an integer value was passed to the constructor, IoError tries to map the integer to a symbolic constant using the @ref{errno} module; failing that, or if the error argument was not present, the value is nil. @end @var errno as Int @desc The integer errno value representing the error. If a symbolic constant was passed to the constructor, IoError tries to map the constant to an integer value using the @ref{errno} module; failing that, or if the error argument was not present, the value is 0. @end @end-class