Returns the absolute value of number xx (removes the sign).

Returns the ASCII code of the first character of xx. If xx is not a string, it is converted into one using the one-argument `Str' function. If xx is EMPTY or an empty string, the result is EMPTY.

Returns the arc-tangent of xx resp. xx/yy. The result is an angle in the range 0 to 360°. A heading angle is usually calculated as

  Heading$ = ATan(Waypoint.DX, Waypoint.DY)

This form is safer then

  Heading$ = ATan(Waypoint.DX / Waypoint.DY)

because it gets the quadrant right and handles the case where `Waypoint.DY' is zero correctly.

Creates an atom for the string str, and returns it. An atom is an integer number, which can later be used (with AtomStr(n)) to get back the string. Calling `Atom' again with the same string will yield the same value. See also the section on the User Interface for more information.

The empty string "" always maps to the atom 0.

Returns the string associated with atom n. n is an integer number. If there is no atom associated with n, returns the empty string "".

After doing `x := Atom("foo")', `AtomStr(x)' will return "foo".

Returns the bitwise AND of all its arguments, which must all be integers. Up to six arguments can be specified. If any argument is EMPTY, the result is EMPTY.

Returns the bitwise NOT of its argument. If the argument is EMPTY, the result is empty.

Returns the bitwise OR of all its arguments, which must all be integers. Up to six arguments can be specified. If any argument is EMPTY, the result is EMPTY.

Returns the bitwise XOR of all its arguments, which must all be integers. Up to six arguments can be specified. If any argument is EMPTY, the result is EMPTY.

Add the cargo amounts a, b, and c. Returns a cargo amount. This function can be called with two to six arguments.

  CAdd("100s", "10$")   = "100S 10$"
  CAdd("100tdm", "54$") = "100T 100D 100M 54$"

If any argument is EMPTY, returns EMPTY. (Until 1.1.19: ignores EMPTY arguments.)

Note that, if the cargo strings are well-formed, simply concatenating them by means of the # operator has a similar effect: In the second example above, concatenating both arguments would yield "100tdm54$" which is less readable than the result of `CAdd', but has the same effect when used later on.

Returns `True' if the cargo amount a is enough to satisfy a request for b. For example, if you have 135 kt Tritanium and need 95 kt, you'd use

  CCompare("135t", "95t")

to check that your storage contains enough to satisfy your need. Supply sale is taken into account automatically:

  CCompare("100s 11$", "111$") = True

`CCompare' is roughly identical to calling `CSub()' and then testing the result for negative amounts. Note that `CCompare' alone will not suffice to test if a cargo transfer will succeed. Cargo sets do not specify torpedo types, so `CCompare' will not check them. A cargo transfer between two ships with mismatching types will of course fail.

Divide the cargo amount a by b.

If b is an integer, this divides the cargo into that many equal pieces (by dividing each component), and returns that amount. For example,

  CDiv("200T 54D", 5) = "40T 10D"

If b is a cargo amount, this returns the number of times b fits into a. Supply sale is taken into account. For example,

  CDiv(Cargo.Str, Torpedo(10).Cost.Str)

returns how many Mark 8 torpedoes can be built from this ship's cargo.

The first parameter is a cargo set, t is a string containing a cargo type. This function extracts the amount of cargo of that type:

  CExtract("100n 200t 300d", "t") = 200

If the second parameter contains multiple letters, returns the sum of the specified types:

  CExtract("100n 200t 300d", "tdm") = 500

This function is dual to CRemove(): `CExtract' extracts the amount of a specified type, `CRemove' returns what remains after removing that cargo.

xx is a string. This function retrieves the named parameter from the host configuration. Valid values for xx are all the PConfig keys PCC handles (even if you don't play with PHost). PCC handles all PConfig keys that directly map to HConfig entries, plus many more (but not all). Values which are used only in PHost yield EMPTY when the game is not hosted with PHost.

Some configuration items are indexed by player. For those, you can pass a second parameter, a player number. If you don't specify a player number, you get "your" value:

  Cfg("AllowHiss")
  Cfg("ColonistTaxRate")
  Cfg("ColonistTaxRate", 2)

give, in this order: `True' or `False' depending on whether the "Hisssss" mission is supported, your colonist tax collection rate (default: 200 for Feds, 100 for others), and the colonist tax collection rate for player 2.

See also: Possible Arguments to `Cfg'

Return the character whose ASCII code is xx.

Multiply the cargo amount a with the integer n. Returns a cargo amount. For example, to compute the cost of 15 type-10 torpedoes, use

  CMul(Torpedo(10).Cost.Str, 15)

Returns the cosine of the specified angle, a floating-point value between -1 and 1. The angle is specified in degrees. This function can be applied like this:

  % way = traveled distance
  Y_DISTANCE = WAY * Cos(HEADING$)

See also: Compass

Count the number of objects in the given set that satisfy the condition p. Sets are the same as for the `ForEach' command.

For example,

  Count(Beam,Kill>50)

yields the number of beams with a kill power over 50.

  Count(Ship,Hull$=105)

will produce the same result as

  CountShips(Hull$=105)

If the condition is omitted, all objects are counted. For example,

  Count(Beam)

will return 10.

Count the planets that satisfy the condition p. For example,

  CountPlanets(Mined.N > 1000)

yields the number of planets with more than 1000 kt Neutronium.

Count the ships that satisfy the condition p. For example,

  CountShips(Hull$=105)

yields the number of Merlin ships you have.

The first parameter is a cargo set, t is a string containing a cargo type. This function returns a cargo set with the specified type removed:

  CRemove("100n 200t 300d", "t") = "300D 100N"

You can remove multiple types by specifying multiple letters:

  CRemove("100n 200t 300d", "tdm") = "100N"

This function is dual to CExtract().

Subtract the cargo amounts b and c from a. Returns a cargo amount. This function can be called with two to six arguments. Supply sale is taken into account if needed.

  CSub("100s", "10$")   = "90S"
  CSub("100t", "10t$")  = "90T -10$"

If any argument is EMPTY, returns EMPTY. (Until 1.1.19: ignores EMPTY arguments.)

As shown in the second example, if you subtract more than you have, you get a negative amount.

Computes the distance between points (x1,y1) and (x2,y2). If a wrapped map is being used, the shortest possible distance is reported. For example,

 Distance(0,0,10,10)

yields 14.14.

Instead of an (x,y) pair, you can also specify an object:

 Distance(Ship(10), Planet(3))

will return the distance between ship #10 and planet #3. These forms can be mixed, so

 Distance(Ship(10), 1000, 1200)

returns the distance between ship #10 and the point (1000,1200). All object types that have a `Loc.X' and `Loc.Y' property can be used.

Find the first object in the given set that satisfy the condition p. Sets are the same as for the `ForEach' command.

For example,

  Find(Beam,Kill>50,Name)

yields the name of the first beam with a kill power over 50.

  Find(Ship,Hull$=105,Id)

will produce the same result as

  FindShip(Hull$=105)

Returns the Id number of the first planet that satisfies the condition p. If there's no such planet, returns EMPTY. For examples, see FindShip(p).

Returns the Id number of the first ship that satisfies the condition p. If there is no such ship, returns EMPTY. This can be used for iteration through objects. For example, to iterate through all Merlin ships, you can do

 Local sid = 0
 Do While (sid := FindShip(Hull$=105 And Id>sid))
   % do something with Ship(sid)
 Loop

(note the `Id>sid' to find the respective next ship in each step). You could also use

 ForEach Ship Do
   If Hull$=105 Then
     % do something
   EndIf
 Next

instead. The `FindShip' function can also be used to test whether you have a ship that satisfies the condition:

 If FindShip(Hull$=105) Then
   % ...
 EndIf

Assuming that str is a string containing multiple fields, separated by delim, this function returns the first field. For example,

  First(",", "cln,-57,Clone a ship")

returns "cln". If the string does not contain the delimiter, it is returned as-is:

  First(",", "huh?")

returns "huh?".

This function is dual to `Rest', which returns the rest of the string.

fd is an open file handle. This function returns the current file pointer of that file.

See also: File I/O, Seek

Returns a free file handle. If there is no free file handle, fails with an error message. Note that this will return the same value again and again until you call `Open' or `Close'.

See File I/O for an example.

Note that this is a function without parameters; the pair of parentheses is required.

fd is an open file handle. This function returns the size in bytes of the associated file.

See also: File I/O, Seek

Extracts the specified quantity from the data block given as parameter. pos is the index into the block, 0 meaning the first byte. These functions are used for binary file I/O.

See also: File I/O, Get, SetByte, GetStr

Get directory name component of the given path name. For example,

GetDirectoryName('c:\games\one\player1.rst')

will return 'c:\games\one\'.

Get file name component of the given path name. For example,

GetFileName('c:\autoexec.bat')

will return 'autoexec.bat'.

Extracts a `BASIC string' from the specified data block. pos is the index into the block, starting with 0 for the first byte. len is the maximum length of the string.

See also: File I/O, Get

The condition operator. If the condition evaluates to TRUE (non-zero, non-empty), it yields the value of THEN, otherwise ELSE. Only the needed arguments are evaluated. If the ELSE argument is not specified, it is treated as EMPTY.

Locates the first occurrence of string sub in string str. It returns the position of that string as an integer. If there is no match, returns 0. Search ignores case by default. To distinguish upper-case and lower-case letters, use the `StrCase' function.

  InStr("frob","o") = 3
  InStr("frob","x") = 0

Convert the floating-point number xx to an integer by discarding fractional digits.

  Int(2.5)  = 2
  Int(-2.1) = -2

See also: Round(xx)

Returns TRUE if and only if xx is EMPTY.

Returns TRUE if and only if xx is a number (i.e. integer or real).

Returns true if fc is a special friendly code (such as "lfm", "mkt" etc.), false if it is not.

Returns TRUE if and only if xx is a string.

Returns the binding of the specified key in the keymap. If the keymap does not exist or the key is not bound, returns EMPTY. Otherwise, it will return the numeric command associated with the key. If the key is not defined directly in the specified keymap, its parent keymaps will automatically be consulted.

If the key is bound to a user-defined command, the return value will be an atom. You can retrieve the command using AtomStr(). For example, after

  Bind ControlScreen "f7" := "UI.Search"

`AtomStr(Key(ControlScreen,"f7"))' will return "UI.Search".

If the key is bound to a PCC-internal command, `AtomStr()' will return the empty string. This is, however, useful to rebind keys:

  Bind ShipScreen "p" := Key(ShipScreen, "shift-f2")

will bind "p" to the same function as Shift-F2. Note however that these command numbers are not interchangeable, you cannot copy an internal command from one keymap to another one.

Returns the first n characters from string xx.

  Left("foobar",3) = "foo"

Returns the length in characters of the string xx. If xx is not a string, it is converted using the one-argument `Str' function.

Build a file name. Concatenates its parameters, inserting directory separators inbetween if required. For example,

MakeFileName('c:\a', 'b', 'file.txt')

will produce 'c:\a\b\file.txt' in PCC 1.x.

Accepts one to six arguments: returns the maximum of them. The comparison is done using the `>' operator. EMPTY values are ignored. If all arguments are EMPTY, returns EMPTY. To compute the maximum of more than six values, use nested `Max's, as in `Max(a,b,Max(c,d))'

Returns l characters from position p in string xx. If the parameter l is not specified, returns all characters from position p onwards. p counts from 1.

  Mid("foobar",3,2) = "ob"
  Mid("foobar",3) = "obar"

Accepts one to six arguments: returns the minimum of them. The comparison is done using the `<' operator. EMPTY values are ignored. If all arguments are EMPTY, returns EMPTY. To compute the minimum of more than six values, use nested `Min's, as in `Min(a,b,Min(c,d))'

Returns the Id number of the planet at position (x,y). When g is true (nonzero, nonempty), returns the planet whose gravity wells are in effect at that place; when g is false or not specified at all, returns only exact matches. If there is no such planet, it returns zero.

For example,

  Local x = Planet(10).Loc.x, y = Planet(10).Loc.y
  Print PlanetAt(x, y)

should print 10 in any starchart worth its salt.

This is better than `FindPlanet(Loc.x = x And Loc.y = y)' because it knows about the wrapping rules. And about the warp wells of course.

Returns the name of the specified planet. Yields EMPTY if the Id is out of range.

Note that this is the same value as `Planet(id).Name', which you should prefer for new code. This function predates the `Planet(id)...' syntax.

Random numbers: a and b must be integers between 0 and 32767, inclusive. The generated random numbers are integers between a and b, where a is a possible result, b is not. The one-argument form RANDOM(b) is equivalent to RANDOM(0,b).

  Random(0,10)  random numbers between 0 and 9
  Random(10)    ditto
  Random(10,0)  random numbers between 10 and 1

Note that this function has always been documented as above, but PCC below 1.1.18 erroneously implemented RANDOM(b) as RANDOM(b,0), i.e. generating random numbers between b and 1. For portability, always use the two-argument form.

Returns a random friendly code. This is same function as on the Friendly Code dialog. The generated code will never contain a character twice, and will not have a special meaning (in particular, it will not be completely numeric).

Assuming that str is a string containing multiple fields, separated by delim, this function returns everything except for the first field. For example,

  Rest(",", "cln,-57,Clone a ship")

returns "-57,Clone a ship". If the string does not contain the delimiter, this function returns EMPTY.

This function is dual to `First', which returns the first field.

Example:

  s := "apples,bacon,eggs"
  Do
    Print First(",", s)
  Loop Until IsEmpty(s := Rest(",", s))

will print three lines:

  apples
  bacon
  eggs

Returns the last n characters from string xx.

  Right("foobar",3) = "bar"

Convert the floating-point number xx to an integer by rounding according to the usual rules.

  Round(2.1) = 2
  Round(2.6) = 3

See also: Int(xx)

Returns the name of the specified ship. Yields EMPTY if the Id is out of range, "Ship #xx" if the name is not known.

Note that this is a similar value as `Ship(id).Name', which you should prefer for new code. This function predates the `Ship(id)...' syntax.

Returns the sine of the specified angle, a floating-point value between -1 and 1. The angle is specified in degrees. This function can be applied like this:

  % way = traveled distance
  X_DISTANCE = WAY * Sin(HEADING$)

See also: Compass

Returns the square root of the number xx. This function can be used to compute distances:

  DISTANCE = Sqr(X_DISTANCE^2 + Y_DISTANCE^2)

where X_DISTANCE and Y_DISTANCE are the X/Y coordinate differences.

Convert the number xx into a string. When used with one argument, performs the same operation as the `&' operator (real numbers are only shown with 2 digits or less). With two arguments, ww (an integer) specifies the number of digits after the period.

Evaluates the specified expression, and returns its value. During evaluation of expr, upper-case and lower-case will be distinguished. By default, PCC ignores case.

  StrCase("A" = "a") = False
  ("A" = "a") = True

Currently, `StrCase' affects the comparison operators and the `InStr' function. Nonetheless, the expression can contain all possible operators:

  StrCase(Ground.M / Density.M)

is not quite useful, but allowed.

xx is a positive integer. The result is the string ss (or the space character, if ss is not specified) repeated xx times.

Returns the tangent of the specified angle, a floating-point value. The angle is specified in degrees. May yield a division error if the angle is 90° or 270°

xx is a string. `Trim' removes leading and trailing spaces, `LTrim' removes leading (left) ones, `RTrim' removes trailing (right) ones.

  Trim("  foo ")  = "foo"
  LTrim("  foo ") = "foo "
  RTrim("  foo ") = "  foo"

Each player can build only a certain set of ship hulls. This function can be used to access this set. If n is a number between 1 and 20, and p is a player number, this function returns the n-th hull player p can build, as an index for the `Hull()' context. On the ship build screen, this will be the n-th line in the selection list. When p is omitted, it defaults to your player number.

Example:

 Truehull(1, 2)

returns the first Lizard hull, 15.

 Hull(Truehull(1, 2)).Name

returns its name: "SMALL DEEP SPACE FREIGHTER".

If the player can build less than 20 hulls, some entries will be zero. E.g., `Truehull(20, 6)' will return 0 because the Cyborg can not build 20 hulls. If either parameter is out of range, this also returns 0.

xx is a string. `Val' attempts to convert it into its numeric equivalent, or returns EMPTY if it is not a number.

  IsEmpty(Val(FCode))

can be used to test for non-numeric FCodes: if the friendly code is numeric, `Val' returns a number, and `IsEmpty' yields TRUE.

If the expression xx is zero or an empty string, the result is EMPTY, otherwise it is xx. This function can be used as

  Z(Cargo.Money) # " mc"

This expression gives a text like "10 mc" if the ship has money aboard, or disappears (EMPTY) if it hasn't.