\chapter Built-in Types and Objects

\QS provides a variety of types and built-in objects. The types
covered in the following sections are built in to the \QS interpreter.
\QS also provides every \Class QObject subclass in the \QT library,
which includes, for example, every \QT GUI widget.

The built-in types include \l Array, \l Boolean, \l ByteArray, \l
Color, \l Date, \l Font, \l{Function type} \l Number, \l Object, \l
Pixmap, \l Point, \l Rect, \l RegExp, \l Size and \l String.

The built-in objects include \l Math, \l Qt and \l System. 

\section1 Built-in Types

These may be considered to be \QS's 'native' datatypes. Because \Q
uses \QT, the hundreds of classes that \QT provides are also directly
available to \Q programmers. All the types are documented in the \link
library.book Library Reference\endlink.

\section2 Array

An \Class Array is a datatype which contains an ordered list of
elements. The elements may be any \QS object. Multi-dimensional arrays
are achieved by setting array elements to be arrays themselves.

Arrays can be extended dynamically simply by creating elements at
non-existent index positions. Elements can also be added using \l
push(), \l unshift() and \l splice(). Arrays can be concatenated
together using \l concat(). Elements can be extracted using \l pop(),
\l shift() and \l slice(). Elements can be deleted using \l splice().
Arrays can be turned into strings using \l join() or
\l{Array::toString()}. Use \l reverse() to reverse the elements in an
array, and \l sort() to sort the elements. The \l sort() function can
be passed a comparison function for customized sort orders.

In general, operations that copy array elements perform a deep copy on
elements that are \l Number or \l String objects, and a shallow copy
on other objects.

\section3 Array Construction

Arrays may be constructed from array literals or using the \l{new
operator}:
\code
    var mammals = [ "human", "dolphin", "elephant", "monkey" ];
    var plants = new Array( "flower", "tree", "shrub" );
    var things;
    for ( i = 0; i < mammals.length; i++ ) {
	things[i] = new Array( 2 );
	things[i][0] = mammals[i];
	things[i][1] = plants[i];
    }
\endcode

Arrays can be initialized with a size, but with all elements
undefined:
\code
    var a = new Array( 9 ); // 10 elements
\endcode

\section3 Array Access

\Class Array elements are accessed via their indices.

Example:
\code
    var m2 = mammals[2];
    mammals[2] = "gorilla";
    var thing = things[2][1]
\endcode
The first statement retrieves the value of the third element of the \c
mammals array and assigns it to \c m2, which now contains "monkey".
The second statement replaces the third element of the \c mammals
array with the value "gorilla". The third statement retrieves the
second element of the third element's array from the \c things array
and assigns it to \c thing, which now contains "shrub".

\section3 Array Properties

Arrays have a single property, \Func length, that holds the number of
elements in the array.

\section3 Array Functions

\section4 concat()

\c{concat( array1, array2, optArray3, ... optArrayN )}

\code
    var x = new Array( "a", "b", "c" );
    var y = concat( a, [ "d", "e" ], [ 90, 100 ] );
    // y == [ "a", "b", "c", "d", "e", 90, 100 ]
\endcode
Concatenates any number of arrays together in the order given, and
returns a single array.

\section4 join()

\c{join( optSeparator )}

\code
    var x = new Array( "a", "b", "c" );
    var y = x.join();         // y == "a,b,c"
    var z = x.join( " * " );  // y == "a * b * c"
\endcode
Joins all the elements of an array together, separated by commas, or
the specified \e optSeparator.

\section4 pop()

\c{pop()}

\code
    var x = new Array( "a", "b", "c" );
    var y = x.pop(); // y == "c"  x == [ "a", "b" ]
\endcode
Pops the top-most (right-most) element off the array and returns this
element.

See also \l push(), \l shift() and \l unshift().

\section4 push()

\c{push( element1, optElement2, ... optElementN )}

\code
    var x = new Array( "a", "b", "c" );
    x.push( 121 ); // x == [ "a", "b", "c", 121 ]
\endcode
Pushes the given item(s) onto the top (right) end of the array.

See also \l push(), \l shift() and \l unshift().

\section4 reverse()

\c{reverse()}

\code
    var x = new Array( "a", "b", "c", "d" );
    x.reverse(); // x == [ "d", "c", "b", "a" ]
\endcode
Reverses the elements in the array.

\section4 shift()

\c{shift()}

\code
    var x = new Array( "a", "b", "c" );
    var y = x.shift(); // y == "a"  x == [ "b", "c" ]
\endcode
Shifts the bottom-most (left-most) element off the array and returns
this element.

See also \l push(), \l shift() and \l unshift().

\section4 slice()

\c{slice( startIndex, optEndIndex )}

\code
    var x = new Array( "a", "b", "c", "d" );
    var y = x.slice( 1, 3 ); // y == [ "b", "c" ]
    var z = x.slice( 2 );    // z == [ "c", "d" ]
\endcode
Copies a slice of the array from the element with the given starting
index, \e startIndex, to the element before the element with the given
ending index, \e optEndIndex. If no ending index is given, all
elements from the starting index onward are sliced.

\section4 sort()

\c{sort( optComparisonFunction )}

\code
    var x = new Array( "d", "x", "a", "c" );
    x.sort(); // x == [ "a", "c", "d", "x" ]
\endcode
Sorts the elements in the array using string comparison. For
customized sorting, pass the \Func sort() function a comparison
function, \e optComparisonFunction, that has the following signature
and behavior:
\code
    function comparisonFunction( a, b ) // signature
\endcode
The function must return an integer as follows:
\list
\i -1 if a \< b
\i  0 if a == b
\i  1 if a \> b
\endlist

Example:
\code
    function numerically( a, b ) { return a < b ? -1 : a > b ? 1 : 0; }
    var x = new Array( 8, 90, 1, 4, 843, 221 );
    x.sort( numerically ); // x == [ 1, 4, 8, 90, 221, 843 ]
\endcode

\section4 splice()

\c{splice( startIndex, replacementCount, optElement1, ... optElementN )}

\code
    var x = new Array( "a", "b", "c", "d" );

    // 2nd argument 0, plus new elements   ==> insertion
    x.splice( 1, 0, "X", "Y" );
    // x == [ "a", "X", "Y", "b", "c", "d" ]

    // 2nd argument > 0, and no elements   ==> deletion
    x.splice( 2, 1 );
    // x == [ "a", "X", "b", "c", "d" ]

    // 2nd argument > 0, plus new elements ==> replacement
    x.splice( 3, 2, "Z" );
    // x == [ "a", "X", "b", "Z" ]
\endcode
Splices elements into the array and out of the array. The first
argument, \e startIndex, is the start index. The second argument, \e
replacementCount, is the number of elements that are to be replaced.
Make the second argument 0 if you are simply inserting elements. The
remaining arguments are the elements to be inserted; there can be no
elements if you are simply deleting a part of the array, i.e. if the
second argument is \> 0.

\section4 toString()

\c{toString()}

\code
    var x = new Array( "a", "b", "c" );
    var y = x.toString();  // y == "a,b,c"
    var z = x.join();      // y == "a,b,c"
\endcode
Joins all the elements of an array together, separated by commas. This
function is used when the array is used in the context of a string
concatenation or is used as a text value, e.g. for printing. Use \l
join() if you want to use your own separator.

\section4 unshift()

\c{unshift( expression, optExpression1, ... opExpressionN )}

\code
    var x = new Array( "a", "b", "c" );
    x.unshift( 121 ); // x == [ 121, "a", "b", "c" ]
\endcode
Unshifts the given item(s) onto the bottom (left) end of the array.

See also \l push(), \l shift() and \l unshift().

\section2 Boolean

\ECMA provides a \Class Boolean data type. In general, creating objects
of this type is not recommended since the behavior will probably not
be what you would expect.

Instead, use the boolean constants \c true and \c false as required.
Any expression can be evaluated in a boolean context, e.g. in an \l if
statement. If the expression's value is \c 0, \c null, \c false, \l
NaN, \l undefined or the empty string \c "", the expression is \c
false; otherwise the expression is \c true.

\section2 ByteArray

A \Class ByteArray is an array optimized for storing raw bytes. See
the \link library.book Library Reference\endlink for details.

\QTDOC QByteArray.

\section2 Color

A \Class Color object represents a color. See the \link library.book
Library Reference\endlink for details.

\QTDOC QColor.

\section2 Date

Instances of the \Class Date class are used to store and maniupulate
dates and times.

A variety of get functions are provided to obtain the date, time or
relevant parts, for example, \l getDate(), \l getDay(), \l
getFullYear(), \l getHours(), \l getMilliseconds(), \l getMinutes(),
\l getMonth(), \l getSeconds(), \l getTime(), \l getTimezoneOffset(),
\l getUTCDate(), \l getUTCDay(), \l getUTCFullYear(), \l
getUTCHours(), \l getUTCMilliseconds(), \l getUTCMinutes(), \l
getUTCMonth(), \l getUTCSeconds() and \l UTC().

A complementary set of functions are also provided, including \l
setDate(), \l setFullYear(), \l setHours(), \l setMilliseconds(), \l
setMinutes(), \l setMonth(), \l setSeconds(), \l setTime(), \l
setUTCDate(), \l setUTCFullYear(), \l setUTCHours(), \l
setUTCMilliseconds(), \l setUTCMinutes(), \l setUTCMonth() and \l
setUTCSeconds().

The functions operate using local time, unless they have \c UTC in
their name in which case they use UTC (Universal
Coordinated Time, also known as GMT, Greenwich Mean Time).

Conversion between Date objects to and from strings are provided by \l
parse(), \l{Date::toString()}, \l toLocaleString() and \l
toUTCString().

Elapsed time (in milliseconds) can be obtained by subtracting one date
from another.

\section3 Date Construction

\code
Date()
Date( milliseconds )
Date( year, month, day, optHour, optMinutes, optSeconds )
\endcode
\PP
\code
    var today = new Date();
    var d = new Date( 1234567 );
    var date = new Date( 1994, 4, 21 );
    var moment = new Date( 1968, 5, 11, 23, 55, 30 );
    var gmt = new Date( Date.UTC( 1975, 12, 25, 22, 30 ) );
\endcode
Dates can be constructed with no arguments, in which case the value is
the date and time at the moment of construction using local time. Use
the static \l UTC() function to create a date using UTC time. A single
integer argument is taken as the number of milliseconds since midnight
on the 1st January 1970.

\section3 Date Functions

\section4 getDate()

\c{getDate()}

\code
    var d = new Date( 1975, 12, 25 );
    var x = d.getDate();  // x == 25
\endcode
Returns the day of the month using local time. The value is always in
the range 1..31.

\section4 getDay()

\c{getDate()}

\code
    var d = new Date( 1975, 12, 25, 22, 30, 15 );
    var x = d.getDay();  // x == 0
\endcode
Returns the day of the week using local time. The value is always in
the range 0..6, with the week considered to begin on Sunday.

Example:
\code
    var IndexToDay = [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ];
    var d = new Date( 1975, 12, 28 );
    System.println( IndexToDay[ d.getDay() ] ); // Prints "Wed"
\endcode

\section4 getFullYear()

\c{getFullYear()}

\code
    var d = new Date( 1975, 12, 25 );
    var x = d.getFullYear();  // x == 1975
\endcode
Returns the year using local time.

\section4 getHours()

\c{getHours()}

\code
    var d = new Date( 1975, 12, 25, 22 );
    var x = d.getHours();  // x == 22
\endcode
Returns the hour using local time. The value is always in the range
0..23.

\section4 getMilliseconds()

\c{getMilliseconds()}

\code
    var d = new Date( 1975, 12, 25, 22 );
    var x = d.getMilliseconds();  // x == 0
\endcode
Returns the milliseconds component of the date using local time. The
value is always in the range 0..999. In the example, \c x is 0,
because no milliseconds were specified, and the default for
unspecified components of the time is 0.

\section4 getMinutes()

\c{getMinutes()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var x = d.getMinutes();  // x == 30
\endcode
Returns the minutes component of the date using local time. The
value is always in the range 0..59.

\section4 getMonth()

\c{getMonth()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var x = d.getMonth();  // x == 11
\endcode
Returns the months component of the date using local time. The
value is always in the range 0..11.

Example:
\code
    var IndexToMonth = [ "Jan", "Feb", "Mar", "Apr", "May", "Jun",
                         "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" ];
    var d = new Date( 1975, 12, 25 );
    System.println( IndexToMonth[ d.getMonth() ] ); // Prints "Dec"
\endcode

\section4 getSeconds()

\c{getSeconds()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var x = d.getSeconds();  // x == 0
\endcode
Returns the seconds component of the date using local time. The
value is always in the range 0..59. In the example \c x is 0 because
no seconds were specified, and the default for unspecified
components of the time is 0.

\section4 getTime()

\c{getTime()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var x = d.getTime();  // x == 1.91457e+11
\endcode
Returns the number of milliseconds since midnight on the 1st January
1970 using local time.

\section4 getTimezoneOffset()

\c{getTimezoneOffset()}

\code
    var d = new Date();
    var x = d.getTimezoneOffset();
\endcode
Returns the difference in minutes between local time and GMT
(Greenwich Mean Time -- also known as UTC, Universal Coordinated
Time). This value may be positive or negative, and accounts for
daylight savings.

\section4 getUTCDate()

\c{getUTCDate()}

\code
    var d = new Date( 1975, 12, 25 );
    var x = d.getUTCDate();  // x == 25
\endcode
Returns the day of the month using UTC. The value is always in the
range 1..31.

\section4 getUTCDay()

\c{getUTCDate()}

\code
    var d = new Date( 1975, 12, 25, 22, 30, 15 );
    var x = d.getUTCDay();  // x == 0
\endcode
Returns the day of the week using UTC. The value is always in
the range 0..6, with the week considered to begin on Sunday.

Example:
\code
    var IndexToDay = [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ];
    var d = new Date( 1975, 12, 28 );
    System.println( IndexToDay[ d.getUTCDay() ] ); // Prints "Wed"
\endcode

\section4 getUTCFullYear()

\c{getUTCFullYear()}

\code
    var d = new Date( 1975, 12, 25 );
    var x = d.getUTCFullYear();  // x == 1975
\endcode
Returns the year using UTC.

\section4 getUTCHours()

\c{getUTCHours()}

\code
    var d = new Date( 1975, 12, 25, 22 );
    var x = d.getUTCHours();  // x == 22
\endcode
Returns the hour using UTC. The value is always in the range
0..23.

\section4 getUTCMilliseconds()

\c{getUTCMilliseconds()}

\code
    var d = new Date( 1975, 12, 25, 22 );
    var x = d.getUTCMilliseconds();  // x == 0
\endcode
Returns the milliseconds component of the date using UTC. The
value is always in the range 0..999. In the example \c x is 0 because
no milliseconds were specified, and the default for unspecified
components of the time is 0.

\section4 getUTCMinutes()

\c{getUTCMinutes()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var x = d.getUTCMinutes();  // x == 30
\endcode
Returns the minutes component of the date using UTC. The
value is always in the range 0..59.

\section4 getUTCMonth()

\c{getUTCMonth()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var x = d.getUTCMonth();  // x == 11
\endcode
Returns the months component of the date using UTC. The value is
always in the range 0..11.

Example:
\code
    var IndexToMonth = [ "Jan", "Feb", "Mar", "Apr", "May", "Jun",
                         "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" ];
    var d = new Date( 1975, 12, 25 );
    System.println( IndexToMonth[ d.getUTCMonth() ] ); // Prints "Dec"
\endcode

\section4 getUTCSeconds()

\c{getUTCSeconds()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var x = d.getUTCSeconds();  // x == 0
\endcode
Returns the seconds component of the date using UTC. The
value is always in the range 0..59. In the example \c x is 0 because
no seconds were specified, and the default for unspecified
components of the time is 0.

\section4 parse()

\c{parse( dateString )}

\code
    var d = new Date( Date.parse( "Sun Jan 25 22:30:00 1976 GMT+0000" ) );
    d = Date.parse( "Sun, Jan 25 1976 22:30:00 GMT+0000" );
    d = Date.parse( "Sun Jan 25 1976" );
\endcode
This is a static function that parses a string, \e dateString, which
represents a particular date and time. It returns the number of
milliseconds since midnight on the 1st January 1970. The string should
use IETF standard date format.

The day may optionally be followed by a comma.

The time element may precede or follow the year, or may be omitted
entirely. The time element consists of the hour using two digits,
followed by a colon followed by the minutes using two digits. This may
optionally be followed by a colon followed by the seconds using two
digits.

The time zone offset is specified at the end in the form: "GMT"
followed by "+" or "-", followed by the number of hours using two
digits, followed by the number of minutes using two digits. If the
time zone offset is not specified, local time is assumed.

See also \l{Date::toString()}.

\section4 setDate()

\c{setDate( dayOfTheMonth )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setDate( 30 );  // d == 1975-12-30 22:30
\endcode
Sets the day of the month to the specified \e dayOfTheMonth in local
time.

\section4 setFullYear()

\c{setFullYear( year, optMonth, optDayOfTheMonth )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setFullYear( 1980 );         // d == 1980-12-30 22:30
    d.setFullYear( 1980, 11, 2 );  // d == 1980-12-02 22:30
\endcode
Sets the year to the specified \e year in local time. If the month, \e
optMonth is specified, it must be in the range 0..11. If the \e
optDayOfTheMonth is specified it must be in the range 1..31.

\section4 setHours()

\c{setHours( hour, optMinutes, optSeconds, optMilliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setHours( 10 );  // d == 1980-12-30 10:30
\endcode
Sets the \e hour to the specified hour, which must be in the range
0..23, in local time. The minutes, seconds and milliseconds past the
hour (\e optMinutes, \e optSeconds and \e optMilliseconds) may also be
specified.

\section4 setMilliseconds()

\c{setMilliseconds( milliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setMilliseconds( 998 );  // d == 1980-12-30 10:30:00:998
\endcode
Sets the \e milliseconds component of the date to the specified value
in local time.

\section4 setMinutes()

\c{setMinutes( minutes, optSeconds, optMilliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setMinutes( 15 );  // d == 1980-12-30 10:15
\endcode
Sets the \e minutes to the specified minutes, which must be in the
range 0..59, in local time. The seconds and milliseconds past the
minute (\e optSeconds and \e optMilliseconds) may also be specified.

\section4 setMonth()

\c{setMonth( month, optDayOfTheMonth )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setMonth( 0, 11 );  // d == 1980-01-11 22:30
\endcode
Sets the \e month to the specified month, which must be in the range
0..11, in local time. The day of the month (\e optDayOfTheMonth) may
also be specified.

\section4 setSeconds()

\c{setSeconds( seconds, optMilliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setSeconds( 25 );  // d == 1980-12-30 22:30:25
\endcode
Sets the \e seconds to the specified seconds, which must be in the
range 0..59, in local time. The milliseconds past the minute (\e
optMilliseconds) may also be specified.

\section4 setTime()

\c{setTime( milliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var duplicate = new Date();
    duplicate.setTime( d.getTime() );
\endcode
Sets the date and time to the local date and time given in terms of
\e milliseconds since midnight on the 1st January 1970.

\section4 setUTCDate()

\c{setUTCDate( dayOfTheMonth )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setUTCDate( 30 );  // d == 1975-12-30 22:30
\endcode
Sets the day of the month (\e dayOfTheMonth) to the specified date in
UTC.

\section4 setUTCFullYear()

\c{setUTCFullYear( year, optMonth, optDayOfTheMonth )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setUTCFullYear( 1980 );         // d == 1980-12-30 22:30
    d.setUTCFullYear( 1980, 11, 2 );  // d == 1980-12-02 22:30
\endcode
Sets the \e year to the specified year in UTC. If the month is
specified (\e optMonth), it must be in the range 0..11. If the day of
the month is specified (\e optDayOfTheMonth), it must be in the range
1..31.

\section4 setUTCHours()

\c{setUTCHours( hour, optMinutes, optSeconds, optMilliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setUTCHours( 10 );  // d == 1980-12-30 10:30
\endcode
Sets the \e hour to the specified hour, which must be in the range
0..23, in UTC. The minutes, seconds and milliseconds past the hour (\e
optMinutes, \e optSeconds and \e optMilliseconds) may also be
specified.

\section4 setUTCMilliseconds()

\c{setUTCMilliseconds( milliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setUTCMilliseconds( 998 );  // d == 1980-12-30 10:30:00:998
\endcode
Sets the \e milliseconds component of the date to the specified value
in UTC.

\section4 setUTCMinutes()

\c{setUTCMinutes( minutes, optSeconds, optMilliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setUTCMinutes( 15 );  // d == 1980-12-30 10:15
\endcode
Sets the \e minutes to the specified minutes, which must be in the
range 0..59, in UTC. The seconds and milliseconds past the minute (\e
optSeconds and \e optMilliseconds) may also be specified.

\section4 setUTCMonth()

\c{setUTCMonth( month, optDayOfTheMonth )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setUTCMonth( 0, 11 );  // d == 1980-01-11 22:30
\endcode
Sets the month to the specified \e month, which must be in the range
0..11, in local time. The day of the month (\e optDayOfTheMonth) may
also be specified.

\section4 setUTCSeconds()

\c{setUTCSeconds( seconds, optMilliseconds )}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    d.setUTCSeconds( 25 );  // d == 1980-12-30 22:30:25
\endcode
Sets the seconds to the specified \e seconds, which must be in the
range 0..59, in UTC. The milliseconds past the minute (\e
optMilliseconds) may also be specified.

\section4 toLocaleString()

\c{toLocaleString()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var s = d.toLocaleString(); // s == "Wed Dec 25 22:30:00 1975"
\endcode
Converts the date into a string using the local date format. Depending
on the underlying compiler library and the operating system, the
string may have a two digit year. Some local date formats may produce
strings like "03/05/65": this would be the 3rd May in Europe and the
5th March in North America.

\section4 toString()

\c{toString()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var s = d.toString(); // s == "Wed Dec 25 22:30:00 1975 GMT+0000"
\endcode
Converts the date into a string. This function produces the same
output as \l toLocaleString().

\section4 toUTCString()

\c{toUTCString()}

\code
    var d = new Date( 1975, 12, 25, 22, 30 );
    var s = d.toUTCString(); // s == "Wed Dec 25 22:30:00 1975 GMT+0000"
\endcode
Converts the date into a string using the IETF UTC format.

\section4 UTC()

\c{UTC( year, month, day, optHour, optMinutes, optSeconds, optMilliseconds )}

\code
    var d = new Date( Date.UTC( 1975, 12, 25, 22, 30 ) );
\endcode
Returns the number of milliseconds since midnight on the 1st January
1970 using UTC. The \e year, \e month and \e day must be specified.
The time components, \e optHour, \e optMinutes, \e optSeconds and \e
optMilliseconds, are optional. If you want to specify minutes you must
also specify the hour, since you can only skip time components from
the right.

\section2 Font

A \Class Font object represents a font. See the \link library.book
Library Reference\endlink for details.

\QTDOC QFont.

\section2 Function type

Functions are normally defined in the application's source code. In
some situations it is desirable to create functions at run time.

\code
    var min = new Function( "x", "y", "return x < y ? x : y;" );
    var m = min( 68, 9 ); // m == 9
\endcode
The first arguments are the names of the parameters; the last argument
is a string which contains the function's definition.

Variable numbers of arguments are also supported, using the \l
arguments array, for example:
\code
    max = new Function(
	  "var max = 0;"
	+ "for ( var i = 0; i < arguments.length; i++ ) {"
	+ "   if ( arguments[ i ] > max ) max = arguments[ i ];"
	+ "}"
	+ "return max;"
	);
    System.println( max( 50, 16, 24, 99, 1, 97 ) ); // Prints 99
\endcode

See also \l function and \l{function operator}.

\section2 Number

A \Class Number is a datatype that represents a number. In most
situtations, programmers will use numeric literals like 3.142 directly
in code. The \Class Number datatype is useful for obtaining system
limits, e.g. \c MIN_VALUE and \c MAX_VALUE, and for performing number
to string conversions with \l toExponential(), \l toFixed(), \l
toPrecision() and \l{Number::toString()}.

\section3 Number Construction

Numbers are not normally constructed, but instead created by simple
assignment, e.g.
\code
    var x = 3.142;
\endcode

\section3 Number Properties

\code
    System.println( Number.MAX_VALUE );
    System.println( Number.MIN_VALUE );
\endcode
The maximum and minimum values are floating point values.

A numeric variable may hold a non-numeric value, in which case \l
isNaN() returns \c true. The result of an arithmetic expression may
exceed the maximum or minimum representable values in which case the
value of the expression will be \l Infinity, and \l isFinite() will
return \c false.

\section3 Number Functions

\section4 toExponential()

\c{toExponential( optDecimals )}

\code
    var x = 999.8765;
    System.println( x.toExponential() );    // Prints: 9.998765e+1
    System.println( x.toExponential( 1 ) ); // Prints: 9.9e+1
\endcode
This function returns a string representation of the number using
scientific (exponential) notation. If \e optDecimals is given, it
specifies the number of decimal places to use in the resultant string.

\section4 toFixed()

\c{toFixed( optDecimals )}

\code
    var x = 999.8765;
    System.println( x.toFixed() );    // Prints: 999
    System.println( x.toFixed( 1 ) ); // Prints: 999.9
\endcode
This function returns a string representation of the number using a
fixed number of decimal places. The default number of places is zero;
the number of decimal places to use may be given as \e optDecimals.
The number is rounded if necessary.

\section4 toPrecision()

\c{toPrecision( optSignificanDigits )}

\code
    var x = 999.8765;
    System.println( x.toPrecision() );    // Prints: 999.8765
    System.println( x.toPrecision( 1 ) ); // Prints: 999.9
\endcode
This function returns a string representation of the number using
a fixed number of decimal places or using scientific notation. By
default all digits are used, but by specifying the number of
significant digits (\e optSignificanDigits) to be less than the number
available, rounding will occur.

\section4 toString()

\c{toString()}

\code
    var x = 999.8765;
    System.println( x.toString() ); // Prints: 999.8765
\endcode
This function returns a string representation of the number. It is the
same as using \l toPrecision() with no argument.

\section2 Object

An \Class Object is the base type for all \QS objects.

\Class Object provides a \Func toString() function which is usually
overridden by subclasses.

\section2 Pixmap

A \Class Pixmap object represents a pixmap. See the \link library.book
Library Reference\endlink for details.

\QTDOC QPixmap.

\section2 Point

A \Class Point object represents a point. See the \link library.book
Library Reference\endlink for details.

\QTDOC QPoint.

\section2 Rect

A \Class Rect object represents a rect. See the \link library.book
Library Reference\endlink for details.

\QTDOC QRect.

\section2 RegExp

A \Class RegExp is a pattern that matches strings. \QS's \Class RegExp
class uses the \QT QRegExp class's functions and syntax; see the \link
library.book Library Reference\endlink for details.

\QTDOC QRegExp.

\section2 Size

A \Class Size object represents a size. See the \link library.book
Library Reference\endlink for details.

\QTDOC QSize.

\section2 String

A \Class String is a sequence of zero or more Unicode characters.
\QS's \Class String class uses the \QT QString class's functions and
syntax; see the \link library.book Library Reference\endlink for
details.

\QTDOC QString.

See also the \l{+ string operator} and \l{+= string operator}.


\section1 Built-in Objects

The built-in \l Math object provides functions that include, \l abs(),
\l acos() and \l cos(), \l asin() and \l sin(), \l atan(), \l atan2()
and \l tan(), \l ceil(), \l floor() and \l round(), \l exp() and \l
log(), \l max() and \l min(), \l pow() and \l sqrt(), \l random(), and
\l round().

The built-in \l Qt object provides \Q's named constants.

The built-in \l System object provides functions including, \l
getenv(), \l setenv(), \l unsetenv(), \l print() and \l println().

\omit The built-in objects include \l Math, \l Qt and \l System. \endomit

\section2 Math

The \Class Math object always exists in a \QS program. Use the \Class
Math object to access mathematical constants and functions, e.g.
\code
    with ( Math ) {
	var x = PI * 2;
	var angle = 1.3;
	var y = x * sin( angle );
    }
\endcode
The \Class Math object supports all the common mathematical functions,
for example, \l abs(), \l acos() and \l cos(), \l asin() and \l sin(),
\l atan(), \l atan2() and \l tan(), \l ceil(), \l floor() and \l
round(), \l exp() and \l log(), \l max() and \l min(), \l pow() and \l
sqrt(), \l random(), and \l round().

See also, \l{+ operator}, \l{++ operator}, \l{- operator}, \l{--
operator}, \l{* operator}, \l{/ operator}, \l{% operator}, \l{-=
operator}, \l{+= operator}, \l{*= operator}, \l{/= operator} and \l{%=
operator}.

\section3 Math Properties

All the \Class Math properties are read-only constants.

\list
\i E -- Euler's constant. The base for natural logarithms.
\i LN2 -- Natural logarithm of 2.
\i LN10 -- Natural logarithm of 10.
\i LOG2E -- Base 2 logarithm of E.
\i LOG10E -- Base 10 logarithm of E.
\i PI -- Pi.
\i SQRT1_2 -- Square root of 1/2.
\i SQRT2 -- Square root of 2.
\endlist

\section3 Math Functions

\section4 abs()

\c{abs( number )}

\code
    var x = -99;
    var y = 99;
    with ( Math ) {
	x = abs( x );
	y = abs( y );
    }
    if ( x == y ) System.println( "equal" );
\endcode
Returns the absolute value of the given \e number. The equivalent of
\code
    x = x < 0 ? -x : x;
\endcode

\section4 acos()

\c{acos( number )}

Returns the arccosine of the given \e number in radians between 0 and
\c Math.PI. If the number is out of range, returns \l NaN.

See also \l cos().

\section4 asin()

\c{asin( number )}

Returns the arcsine of the given \e number in radians between
\c{-Math.PI/2} and \c{Math.PI/2}. If the number is out of range,
returns \l NaN.

See also \l sin().

\section4 atan()

\c{atan( number )}

Returns the arctangent of the given \e number in radians between
\c{-Math.PI/2} and \c{Math.PI/2}. If the number is out of range,
returns \l NaN.

See also \l tan() and \l atan2().

\section4 atan2()

\c{atan2( yCoord, xCoord )}

Returns the counterclockwise angle in radians between the positive
x-axis and the point at (\e xCoord, \e yCoord). The value returned is
always between \c{-Math.PI} and \c{Math.PI}.

Example:
\code
    function polar( x, y )
    {
	return Math.atan2( y, x );
    }
\endcode

See also \l tan() and \l atan().

\section4 ceil()

\c{ceil( number )}

If the \e number is an integer, it returns the \e number. If the \e
number is a floating point value, it returns the smallest integer
greater than the \e number.

Example:
\code
    var x = 913.41;
    x = Math.ceil( x ); // x == 914
    var y = -33.97;
    y = Math.ceil( y ); // y == 33
\endcode

See also \l floor() and \l round().

\section4 cos()

\c{cos( number )}

Returns the cosine of the given \e number. The value will be in the
range -1..1.

See also \l acos().

\section4 exp()

\c{exp( number )}

Returns \c{Math.E} raised to the power of the given \e number.

See also \l log().

\section4 floor()

\c{floor( number )}

If the \e number is an integer, it returns the \e number. If the \e
number is a floating point value, it returns the greatest integer less
than the \e number.

See also \l ceil() and \l round().

\section4 log()

\c{log( number )}

If the \e number is \> 0, it returns the natural logarithm of the
given \e number. If the \e number is 0, it returns \c Infinity. If the
\e number is \< 0, it returns \l NaN.

See also \l exp().

\section4 max()

\c{max( number1, number2 )}

Returns the largest of \e number1 and \e number2.

See also \l min().

\section4 min()

\c{min( number1, number2 )}

Returns the smallest of \e number1 and \e number2.

See also \l max().

\section4 pow()

\c{pow( number, power )}

Returns the value of the \e number raised to the \e power.

See also \l sqrt().

\section4 random()

\c{random()}

Returns a pseudo-random floating point number between 0 and 1. Pseudo
random numbers are not truly random, but are often adequate for many
applications, for example, games and simulations.

\section4 round()

\c{round( number )}

Returns the \e number rounded to the nearest integer. If the
fractional part of the \e number is \>= 0.5, the \e number is rounded
up; otherwise it is rounded down.

See also \l ceil() and \l floor().

\section4 sin()

\c{sin( number )}

Returns the sine of the given \e number. The value will be in the
range -1..1.

See also \l asin().

\section4 sqrt()

\c{sqrt( number )}

If the \e number is \>= 0, it returns the square root. If the \e
number is \< 0, it returns \l NaN.

See also \l pow().

\section4 tan()

\c{tan( number )}

Returns the tangent of the given \e number.

See also \l atan() and \l atan2().

\section2 Qt

The \Class Qt object always exists in a \QS program. This object is
used to provide names for all the constants used in \QS applications:

###

\section2 System

The \Class System object always exists in a \QS program. Use the
\Class System object to access and manipulate environment variables,
e.g. with \l getenv(), \l setenv() and \l unsetenv(), and to print
text to the console with \l print() and \l println().

\section3 System Functions

\section4 getenv()

\c{getenv( environmentVariable )}

Returns the string stored in the given \e environmentVariable.

Example:
\code
    var q = System.getenv( "QTDIR" ); // q == /usr/local/qt
\endcode

See also \l setenv() and \l unsetenv().

\section4 print()

\c{print( expression )}

Prints the \e expression (applying \Func toString() if necessary) to the
console (\c stdout).

\section4 println()

\c{print( expression )}

Prints the \e expression (applying \Func toString() if necessary) to
the console (\c stdout), followed by a newline.

See also \l debug().

\section4 setenv()

\c{setenv( environmentVariable, value )}

Sets the \e environmentVariable to the \e value. If the \e
environmentVariable does not exist it is created. The environment is
only changed within the context of the \Q process for the duration of
the process.

See also \l getenv() and \l unsetenv().

\section4 unsetenv()

\c{unsetenv( environmentVariable )}

Removes the \e environmentVariable from the \Q process's environment.
The environment is only changed within the context of the \Q process
for the duration of the process.

See also \l getenv() and \l setenv().