`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

Object: The common supertype of every other class

Primitive types

About primitive types: The shared properties of primitive types
Int: The integer type
Str: The string type
Float: The floating-point number type
Boolean: The Boolean type
Type: The type of types
Function: The type of functions and bound methods
Constant: The symbolic constant type
Pair: A pair of values
Range: A range of integer values

Collection types

Array: A resizable array of values
Tuple: A fixed-length, immutable sequence of values
Map: A map of key-value pairs implemented as a hash table

Functions

Print(...)

Write the arguments to the 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.

Print(2, "and", [2, 3]) -- Display "2 and [2, 3]" (without quotes)

Write(...)

Write the arguments to the StdOut stream. This is a shorthand for io::StdOut.write.

WriteLn(...)

Write the arguments to the StdOut stream, followed by a line break. This is a shorthand for io::StdOut.writeLn.

ReadLn() as Str

Read a line from StdIn, and return the line without the line ending. This is a shorthand for io::StdIn.readLn.

Repr(object) as Str

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:

Repr(3)            -- "3"
Repr('foo' + LF)   -- "'foo\u000a'"
Repr([nil, True])  -- "[nil, True]"

TypeName(object) as Str

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:

TypeName(1)       -- "Int"
TypeName(StdIn)   -- "io::TextStream"

See also: reflect::TypeOf

Chr(n as Int) as Str

Return a single-character string with character code n. The valid range of values for n is from 0 to 65535, inclusive.

Ord(ch as Str) as Int

Return the character code of a single-character string. The return value is an integer in the range from 0 to 65535, inclusive.

Abs(x as Int) as Int

Abs(x as Float) as Float

Return the absolute value of an integer or a float.

Min(x, y)

Return the minimum of two objects.

Max(x, y): Return the maximum of two objects.

Sort(sequence[, func])

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.

Reversed<T>(iterable as Iterable<T>) as Array<T>

Return an array that has all the items in the iterable in reverse order. Examples:

Reversed([2, 3, 4])   -- [4, 3, 2]
Reversed(0 to 3)      -- [2, 1, 0]
Reversed("foo")       -- ["o", "o", "f"]

Hash(object) as Int

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.

Exit([value as Int])

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.

Constants

This module also defines boolean constants:

True: The boolean true value.
False: The boolean false value.

A few string constants are provided as well:

Tab: The tab character (code 9).
Newline: The platform specific line break string. On Unix-like operating systems it is LF and on Windows CR + LF.
LF: The line feed character (code 10).
CR: The carriage return character (code 13).

Interfaces

Sequence: A sequence of values
Iterable: An object that supports iteration
Iterator: An iterator object
Comparable: An object that supports comparisons using < and >
Addable: An object that supports addition
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]): 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.
class ValueError([message as Str]): 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.
class TypeError([message as Str]): Raised when the inputs of an operation or a function have unsupported types. Note that MemberError will be often raised in similar situations.
class MemberError([message as Str]): Raised when an object does not have a requested member or the member being assigned to cannot be modified.
class ArithmeticError([message as Str]): Raised when an arithmetic operation or function receives invalid inputs. A typical example is division by zero.
class IndexError([message as Str]): Raised when the index of a sequence object such as an array is out of bounds or otherwise invalid.
class KeyError([message as Str]): Raised when a key of a mapping object is not present or is otherwise invalid.
class CastError([message as Str]): Raised when a cast operation fails.
class ResourceError([message as Str]): Raised when a resource is exhausted. This exception can be triggered by lack of disk space or by too many open files, for example.
class MemoryError([message as Str]): 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.
class RuntimeError([message as Str]): Raised when there is a run-time error during execution that does not have a more specific exception class.
class InterruptException([message as Str]): Raised when the user interrupts the program by pressing Ctrl+C.

`ExitException`

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

`IoError`

class IoError([message as Str[, error as Constant]])
class IoError([message as Str[, error as Int]]): Raised as a response to an operating system error. This exception can be raised by several modules such as io and 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 also: The errno module defines symbolic constants that can be used to represent errors, and provides conversions between them and integer errno values.

IoError also has the following member constants:

code as Constant: 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 errno module; failing that, or if the error argument was not present, the value is nil.
errno as Int: 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 errno module; failing that, or if the error argument was not present, the value is 0.

std: Basic services