Next Previous Contents

26. Miscellaneous Functions

26.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.

26.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

26.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

26.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

26.5 __datatype

Synopsis

Get the DataType_Type for a specified internal class-id

Usage

DataType_Type __datatype (Int_Type id)

Description

This function is the inverse of __class_type in the sense that it returns the DataType_Type for the specified class-id. If no such class exists, the function will return NULL.

Notes

One should not expect distinct interpreter instances to always return the same value for a dynamically assigned class-id such as one defined by a module or one stemming from a typedef statement.

See Also

__class_id, __class_type, typeof

26.6 _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

Notes

For testing sameness, use __is_same.

See Also

typeof, __is_same, __get_reference, __is_callable

26.7 get_environ

Synopsis

Get all environment variables

Usage

String_Type[] = get_environ()

Description

The get_environ function returns an array of strings representing the environmen variables defined for the current process. Each element of the array will be of the form NAME=VALUE.

This function will return NULL if the system does not support this feature.

See Also

getenv, putenv, is_defined

26.8 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

get_environ, putenv, strlen, is_defined

26.9 __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

26.10 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 accessible. 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

26.11 __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 by dereferencing the object. It returns 1 if the argument is callable, or zero otherwise.

Example

   __is_callable (7)      ==> 0
   __is_callable (&sin)   ==> 1
   a = [&sin];
   __is_callable (a[0])   ==> 1
   __is_callable (&a[0])  ==> 0

See Also

__is_numeric, is_defined

26.12 __is_datatype_numeric

Synopsis

Determine whether or not a type is a numeric type

Usage

Int_Type __is_datatype_numeric (DataType_Type type)

Description

This function may be used to determine if the specified datatype represents a numeric type. It returns 0 if the datatype does not represents a numeric type; otherwise it returns 1 for an integer type, 2 for a floating point type, and 3 for a complex type.

See Also

typeof, __is_numeric, __is_callable

26.13 __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 0 if the argument is non-numeric, 1 if it is an integer, 2 if a floating point number, and 3 if it is complex. 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);     ==> 2
   __is_numeric (2j);     ==> 3
   __is_numeric ([1,2]);  ==> 1
   __is_numeric ({1,2});  ==> 0

See Also

typeof, __is_datatype_numeric

26.14 __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

Notes

For testing equality, use _eqs.

See Also

typeof, _eqs, __get_reference, __is_callable

26.15 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

26.16 __set_argc_argv

Synopsis

Set the argument list

Usage

__set_argc_argv (Array_Type a)

Description

This function sets the __argc and __argv intrinsic variables.

26.17 _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

26.18 _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

26.19 __tmp

Synopsis

Returns the value of a variable and uninitialize the variable

Usage

__tmp (x)

Description

The __tmp function takes a single argument, a variable, returns the value of the variable, and then undefines the variable. The purpose of this pseudo-function is to free any memory associated with a variable if that variable is going to be re-assigned.

Example

     x = 3;
     y = __tmp(x);
will result in `y' having a value of `3' and `x' will be undefined.

Notes

This function is a pseudo-function because a syntax error results if used like

      __tmp(sin(x));

See Also

__uninitialize, __is_initialized

26.20 __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

26.21 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