S-Lang Run-Time Library Reference: Version 2.0.4: Miscellaneous Functions

Next Previous Contents

## 22. Miscellaneous Functions

## 22.1 _auto_declare

Synopsis

  Set automatic variable declaration mode

Usage

  `Integer_Type _auto_declare`

Description

  The `_auto_declare` variable may be used to have undefined variable implicitly declared. If set to zero, any variable must be declared with a `variable` declaration before it can be used. If set to one, then any undeclared variable will be declared as a `static` variable.

  The `_auto_declare` variable is local to each compilation unit and setting its value in one unit has no effect upon its value in other units. The value of this variable has no effect upon the variables in a function.

Example

  The following code will not compile if `X` not been declared:

  > `

  >         X = 1;

  > `

  However,

  > `

  >         _auto_declare = 1;   % declare variables as static.
  >         X = 1;

  > `

  is equivalent to

  > `

  >         static variable X = 1;

  > `

Notes

  This variable should be used sparingly and is intended primarily for interactive applications where one types S-Lang commands at a prompt.

## 22.2 __class_id

Synopsis

  Return the class-id of a specified type

Usage

  `Int_Type __class_id (DataType_Type type)`

Description

  This function returns the internal class-id of a specified data type.

See Also

  `typeof, _typeof, __class_type, __datatype`

## 22.3 __class_type

Synopsis

  Return the class-type of a specified type

Usage

  `Int_Type __class_type (DataType_Type type))`

Description

  Internally S-Lang objects are classified according to four types: scalar, vector, pointer, and memory managed types. For example, an integer is implemented as a scalar, a complex number as a vector, and a string is represented as a pointer. The `__class_type` function returns an integer representing the class-type associated with the specified data type. Specifically, it returns:

  > `

  >            0    memory-managed
  >            1    scalar
  >            2    vector
  >            3    pointer

  > `

See Also

  `typeof, _typeof, __class_id, __datatype`

## 22.4 current_namespace

Synopsis

  Get the name of the current namespace

Usage

  `String_Type current_namespace ()`

Description

  The `current_namespace` function returns the name of the static namespace associated with the compilation unit. If there is no such namespace associated with the compilation unit, then the empty string `""` will be returned.

See Also

  `implements, use_namespace, import, evalfile`

## 22.5 _eqs

Synopsis

  Test for equality of two objects

Usage

  `Int_Type _eqs (a, b)`

Description

  This function tests its two arguments for equality and returns 1 if they are equal or 0 otherwise. What it means to be equal depends upon the data types of the objects being compared. If the types are numeric, they are regarded as equal if their numerical values are equal. If they are arrays, then they are equal if they have the same shape with equal elements. If they are structures, then they are equal if they contain identical fields, and the corresponding values are equal.

Example
  _

  eqs (1, 1) ===> 1 _eqs (1, 1.0) ===> 1 _eqs ("a", 1) ===> 0 _eqs ([1,2], [1.0,2.0]) ===> 1

See Also

  `typeof, _eqs, __get_reference, __is_callable`

Notes

  For testing sameness, use `__is_same`.

## 22.6 getenv

Synopsis

  Get the value of an environment variable

Usage

  `String_Type getenv(String_Type var)`

Description

  The `getenv` function returns a string that represents the value of an environment variable `var`. It will return `NULL` if there is no environment variable whose name is given by `var`.

Example

  > `

  >         if (NULL != getenv ("USE_COLOR"))
  >           {
  >             set_color ("normal", "white", "blue");
  >             set_color ("status", "black", "gray");
  >             USE_ANSI_COLORS = 1;
  >           }

  > `

See Also

  `putenv, strlen, is_defined`

## 22.7 __get_reference

Synopsis

  Get a reference to a global object

Usage

  `Ref_Type __get_reference (String_Type nm)`

Description

  This function returns a reference to a global variable or function whose name is specified by `nm`. If no such object exists, it returns `NULL`, otherwise it returns a reference.

Example

  Consider the function:

  > `

  >         define runhooks (hook)
  >         {
  >            variable f;
  >            f = __get_reference (hook);
  >            if (f != NULL)
  >              @f ();
  >         }

  > `

  This function could be called from another S-Lang function to allow customization of that function, e.g., if the function represents a jed editor mode, the hook could be called to setup keybindings for the mode.
See Also

  `is_defined, typeof, eval, autoload, __is_initialized, __uninitialize`

## 22.8 implements

Synopsis

  Create a new static namespace

Usage

  `implements (String_Type name)`

Description

  The `implements` function may be used to create a new static namespace and have it associated with the current compilation unit. If a namespace with the specified name already exists, a `NamespaceError` exception will be thrown.

  In addition to creating a new static namespace and associating it with the compilation unit, the function will also create a new private namespace. As a result, any symbols in the previous private namespace will be no longer be accessable. For this reason, it is recommended that this function should be used before any private symbols have been created.

Example

  Suppose that some file `t.sl` contains:

  > `

  >          implements ("My");
  >          define message (x)
  >          {
  >             Global->message ("My's message: $x"$);
  >          }
  >          message ("hello");

  > `

  will produce `"My's message: hello"`. This `message` function may be accessed from outside the namespace via:

  > `

  >         My->message ("hi");

  > `

Notes

  Since `message` is an intrinsic function, it is public and may not be redefined in the public namespace.

  The `implements` function should rarely be used. It is preferable to allow a static namespace to be associated with a compilation unit using, e.g., `evalfile`.

See Also

  `use_namespace, current_namespace, import`

## 22.9 __is_callable

Synopsis

  Determine whether or not an object is callable

Usage

  `Int_Type __is_callable (obj)`

Description

  This function may be used to determine if an object is callable. It returns 1 if the argument is callable, or zero otherwise.

Example
  __

  is_callable (7) ==> 0 __is_callable (&sin) ==> 1

See Also

  `__is_numeric, is_defined`

## 22.10 __is_numeric

Synopsis

  Determine whether or not an object is a numeric type

Usage

  `Int_Type __is_numeric (obj)`

Description

  This function may be used to determine if an object represents a numeric type. It returns `1` if the argument is numeric, or zero otherwise. If the argument is an array, then the array type will be used for the test.

Example
  __

  is_numeric ("foo"); ==> 0 __is_numeric ("0"); ==> 0 __is_numeric (0); ==> 1 __is_numeric (PI); ==> 1 __is_numeric ([1,2]); ==> 1 __is_numeric ({1,2}); ==> 0

See Also

  `typeof`

## 22.11 __is_same

Synopsis

  Test for sameness of two objects

Usage

  `Int_Type __is_same (a, b)`

Description

  This function tests its two arguments for sameness and returns 1 if they are the same, or 0 otherwise. To be the same, the data type of the arguments must match and the values of the objects must reference the same underlying object.

Example
  __

  is_same (1, 1) ===> 1 __is_same (1, 1.0) ===> 0 __is_same ("a", 1) ===> 0 __is_same ([1,2], [1,2]) ===> 0

See Also

  `typeof, _eqs, __get_reference, __is_callable`

Notes

  For testing equality, use `_eqs`.

## 22.12 putenv

Synopsis

  Add or change an environment variable

Usage

  `putenv (String_Type s)`

Description

  This functions adds string `s` to the environment. Typically, `s` should of the form `"name=value"`. The function throws an `OSError` upon failure.

Notes

  This function may not be available on all systems.

See Also

  `getenv, sprintf`

## 22.13 _slang_install_prefix

Synopsis

  S-Lang's installation prefix

Usage

  `String_Type _slang_install_prefix`

Description

  The value of this variable is set at the S-Lang library's compilation time. On Unix systems, the value corresponds to the value of the `prefix` variable in the Makefile. For normal installations, the library itself will be located in the `lib` subdirectory of the `prefix` directory.

Notes

  The value of this variable may or may not have anything to do with where the slang library is located. As such, it should be regarded as a hint. A standard installation will have the `slsh` library files located in the `share/slsh` subdirectory of the installation prefix.

See Also

  `_slang_doc_dir`

## 22.14 _slang_utf8_ok

Synopsis

  Test if the interpreter running in UTF-8 mode

Usage

  `Int_Type _slang_utf8_ok`

Description

  If the value of this variable is non-zero, then the interpreter is running in UTF-8 mode. In this mode, characters in strings are interpreted as variable length byte sequences according to the semantics of the UTF-8 encoding.

Notes

  When running in UTF-8 mode, one must be careful not to confuse a character with a byte. For example, in this mode the `strlen` function returns the number of characters in a string which may be different than the number of bytes. The latter information may be obtained by the `strbytelen` function.

See Also

  `strbytelen, strlen, strcharlen`

## 22.15 __uninitialize

Synopsis

  Uninitialize a variable

Usage

  `__uninitialize (Ref_Type x)`

Description

  The `__uninitialize` function may be used to uninitialize the variable referenced by the parameter `x`.

Example

  The following two lines are equivalent:

  > `

  >          () = __tmp(z);
  >          __uninitialize (&z);

  > `

See Also

  `__tmp, __is_initialized`

## 22.16 use_namespace

Synopsis

  Change to another namespace

Usage

  `use_namespace (String_Type name)`

Description

  The `use_namespace` function changes the current static namespace to the one specified by the parameter. If the specified namespace does not exist, a `NamespaceError` exception will be generated.

See Also

  `implements, current_namespace, import`

Next Previous Contents