The common-extensions Module

The common-extensions module contains a variety of useful basic extensions to the Dylan language and is exported from the common-dylan library. As a convenience, the common-dylan module re-exports everything from the common-extensions and dylan modules.

The extensions are:

assert Statement Macro

Signals an error if the expression passed to it evaluates to false.

Macro Call:

assert expression format-string [format-arg] => false
assert expression => false

Parameters:

  • expression – A Dylan expression bnf.

  • format-string – A Dylan expression bnf.

  • format-arg – A Dylan expression bnf.

Values:

  • false – #f.

Discussion:

Signals an error if expression evaluates to #f.

An assertion or “assert” is a simple tool for testing that conditions hold in program code.

The format-string is a format string as defined on page 112 of the DRM. If format-string is supplied, the error is formatted accordingly, along with any instances of format-arg.

If expression is not #f, assert does not evaluate format-string or any instances of format-arg.

See also:

<byte-character> Sealed Class

The class of 8-bit characters that instances of <byte-string> can contain.

Superclasses:

<character>

Discussion:

The class of 8-bit characters that instances of <byte-string> can contain.

concatenate! Open Generic function

A destructive version of the Dylan language’s concatenate; that is, one that might modify its first argument.

Signature:

concatenate! sequence #rest more-sequences => result-sequence

Parameters:
Values:
Discussion:

A destructive version of the Dylan language’s concatenate; that is, one that might modify its first argument.

It returns the concatenation of one or more sequences, in a sequence that may or may not be freshly allocated. If result-sequence is freshly allocated, then, as for concatenate, it is of the type returned by type-for-copy of sequence.

Example:
> define variable *x* = "great-";
"great-"
> define variable *y* = "abs";
"abs"
> concatenate! (*x*, *y*);
"great-abs"
> *x*;
"great-abs"
>
condition-to-string Open Generic function

Returns a <string> representation of a condition object.

Signature:

condition-to-string condition => string

Parameters:
Values:
Discussion:

Returns a string representation of a general instance of <condition>.

Note that it is often not necessary to write a method on this generic function for your condition classes because you can use the method provided by <simple-condition>, usually via one of its subclasses, <simple-error>, <simple-warning>, or <simple-restart>. Simply make your condition a subclass of one of these classes and provide the format-string: and format-arguments: init keywords.

debug-assert Statement Macro

Signals an error if the expression passed to it evaluates to false — but only when the code is compiled in interactive development mode.

Macro Call:

debug-assert expression format-string [format-arg] => false
debug-assert expression => false

Parameters:

  • expression – A Dylan expression bnf.

  • format-string – A Dylan expression bnf.

  • format-arg – A Dylan expression bnf.

Values:

  • false – #f.

Discussion:

Signals an error if expression evaluates to false — but only when the code is compiled in debugging mode.

An assertion or “assert” is a simple and popular development tool for testing conditions in program code.

This macro is identical to assert, except that the assert is defined to take place only while debugging.

The Open Dylan compiler removes debug-assertions when it compiles code in “production” mode as opposed to “debugging” mode.

The format-string is a format string as defined on page 112 of the DRM.

See also:

debug-message Function

Formats a string and outputs it to the debugger.

Signature:

debug-message format-string #rest format-args => ()

Parameters:

  • format-string – An instance of <string>.

  • format-args (#rest) – Instances of <object>.

Discussion:

Formats a string and outputs it to the debugger.

The format-string is a format string as defined on page 112 of the DRM.

default-handler(<warning>) Method

Prints the message of a warning instance to the Open Dylan debugger window’s messages pane.

Signature:

default-handler warning => false

Parameters:
Values:

  • false – #f.

Discussion:

Prints the message of a warning instance to the Open Dylan debugger window’s messages pane. It uses debug-message, to do so.

This method is a required, predefined method in the Dylan language, described on page 361 of the DRM as printing the warning’s message in an implementation-defined way. We document this method here because our implementation of it uses the function debug-message, which is defined in the common-dylan library. Thus to use this default-handler method on <warning>, your library needs to use the common-dylan library or a library that uses it, rather than simply using the Dylan library.

Example:

In the following code, the signalled messages appear in the Open Dylan debugger window.

define class <my-warning> (<warning>)
end class;

define method say-hello()
  format-out("hello there!\\n");
  signal("help!");
  signal(make(<my-warning>));
  format-out("goodbye\\n");
end method say-hello;

say-hello();

The following messages appear in the debugger messages pane:

Application Dylan message: Warning: help!
Application Dylan message: Warning: {<my-warning>}

Where {<my-warning>} means an instance of <my-warning>.

See also:

default-last-handler Function

Formats and outputs a Dylan condition using condition-to-string and passes control on to the next handler.

Signature:

default-last-handler serious-condition next-handler => ()

Parameters:
Discussion:

A handler utility function defined on objects of class <serious-condition> that can be by bound dynamically around a computation via let handler or installed globally via define last-handler.

This function formats and outputs the Dylan condition serious-condition using condition-to-string from this library, and passes control on to the next handler.

This function is automatically installed as the last handler if your library uses the common-dylan library.

Example:

The following form defines a dynamic handler around some body:

let handler <serious-condition> = default-last-handler;

while the following form installs a globally visible last-handler:

define last-handler <serious-condition>
  = default-last-handler;
See also:

  • define last-handler

  • win32-last-handler in the C FFI and Win32 library reference, under library win32-user and module win32-default-handler.

define last-handler Defining Macro

Defines a “last-handler” to be used after any dynamic handlers and before calling default-handler.

Macro Call:

define last-handler (condition, #key test, init-args) = handler ;

define last-handler condition = handler;

define last-handler;

Parameters:

  • condition – A Dylan expression bnf. The class of condition for which the handler should be invoked.

  • test – A Dylan expression bnf. A function of one argument called on the condition to test applicability of the handler.

  • init-args – A Dylan expression bnf. A sequence of initialization arguments used to make an instance of the handler’s condition class.

  • handler – A Dylan expression bnf. A function of two arguments,

  • condition – and next-handler, that is called on a condition which matches the handler’s condition class and test function.

Discussion:

A last-handler is a global form of the dynamic handler introduced via let handler, and is defined using an identical syntax. The last handler is treated as a globally visible dynamic handler. During signalling if a last-handler has been installed then it is the last handler tested for applicability before default-handler is invoked. If a last-handler has been installed then it is also the last handler iterated over in a call to do-handlers.

The first two defining forms are equivalent to the two alternate forms of let handler. If more than one of these first defining forms is executed then the last one executed determines the installed handler. The current last-handler can be uninstalled by using the degenerate third case of the defining form, that has no condition description or handler function.

The intention is that libraries will install last handlers to provide basic runtime error handling, taking recovery actions such as quitting the application, trying to abort the current application operation, or entering a connected debugger.

Example:

The following form defines a last-handler function called default-last-handler that is invoked on conditions of class <serious-condition>:

define last-handler <serious-condition>
  = default-last-handler;
See also:

  • win32-last-handler in the C FFI and Win32 library reference, under library win32-user and module win32-default-handler.

define table Defining Macro

Defines a constant binding in the current module and initializes it to a new table object.

Macro Call:

define table name [ :: type ] = { [ key => element ]* }

Parameters:

  • name – A Dylan name bnf.

  • type – A Dylan operand bnf. Default value: <table>.

  • key – A Dylan expression bnf.

  • element – A Dylan expression bnf.

Discussion:

Defines a constant binding name in the current module, and initializes it to a new table object, filled in with the keys and elements specified.

If the argument type is supplied, the new table created is an instance of that type. Therefore type must be <table> or a subclass thereof. If type is not supplied, the new table created is an instance of a concrete subclass of <table>.

Example:
define table $colors :: <object-table>
  = { #"red" => $red,
      #"green" => $green,
      #"blue" => $blue };
difference Open Generic function

Returns a sequence containing the elements of one sequence that are not members of a second.

Signature:

difference sequence-1 sequence-2 #key test => result-sequence

Parameters:
Values:
Discussion:

Returns a sequence containing the elements of sequence-1 that are not members of sequence-2. You can supply a membership test function as test.

Example:
> difference(#(1,2,3), #(2,3,4));
#(1)
>
false-or Function

Returns a union type comprised of singleton(#f) and one or more types.

Signature:

false-or type #rest more-types => result-type

Parameters:

  • type – An instance of <type>.

  • more-types (#rest) – Instances of <type>.

Values:

  • result-type – An instance of <type>.

Discussion:

Returns a union type comprised of singleton(#f), type, any other types passed as more-types.

This function is useful for specifying slot types and function return values.

The expression

false-or(*t-1*, *t-2*, ..)

is type-equivalent to

type-union(singleton(#f), *t-1*, *t-2*, ..)

fill-table! Function

Fills a table with the keys and elements supplied.

Signature:

fill-table! table keys-and-elements => table

Parameters:
Values:

  • table – An instance of <table>.

Discussion:

Modifies table so that it contains the keys and elements supplied in the sequence keys-and-elements.

This function interprets keys-and-elements as key-element pairs, that is, it treats the first element as a table key, the second as the table element corresponding to that key, and so on. The keys and elements should be suitable for table.

Because keys-and-elements is treated as a sequence of paired key-element values, it should contain an even number of elements; if it contains an odd number of elements, fill-table! ignores the last element (which would have been treated as a key).

find-element Open Generic function

Returns an element from a collection such that the element satisfies a predicate.

Signature:

find-element collection function #key skip failure => element

Parameters:

  • collection – An instance of <collection>.

  • predicate – An instance of <function>.

  • skip (#key) – An instance of <integer>. Default value: 0.

  • failure (#key) – An instance of <object>. Default value: #f.

Values:
Discussion:

Returns a collection element that satisfies predicate.

This function is identical to Dylan’s find-key, but it returns the element that satisfies predicate rather than the key that corresponds to the element.

float-to-string Function

Formats a floating-point number to a string.

Signature:

float-to-string float => string

Parameters:

  • float – An instance of <float>.

Values:
Discussion:

Formats a floating-point number to a string. It uses scientific notation where necessary.

ignore Function

A compiler directive that tells the compiler it must not issue a warning if its argument is bound but not referenced.

Signature:

ignore variable => ()

Parameters:

  • variable – A Dylan variable-name bnf.

Discussion:

When the compiler encounters a variable that is bound but not referenced, it normally issues a warning. The ignore function is a compiler directive that tells the compiler it must not issue this warning if variable is bound but not referenced. The ignore function has no run-time cost.

The ignore function is useful for ignoring arguments passed to, or values returned by, a function, method, or macro. The function has the same extent as a let; that is, it applies to the smallest enclosing implicit body.

Use ignore if you never intend to reference variable within the extent of the ignore. The compiler will issue a warning to tell you if your program violates the ignore. If you are not concerned about the ignore being violated, and do not wish to be warned if violation occurs, use ignorable instead.

Example:

This function ignores some of its arguments:

define method foo (x ::<integer>, #rest args)
  ignore(args);
  ...
end

Here, we use ignore to ignore one of the values returned by fn:

let (x,y,z) = fn();
ignore(y);
See also:

ignorable Function

A compiler directive that tells the compiler it need not issue a warning if its argument is bound but not referenced.

Signature:

ignorable variable => ()

Parameters:

  • variable – A Dylan variable-name bnf.

Discussion:

When the compiler encounters a variable that is bound but not referenced, it normally issues a warning. The ignorable function is a compiler directive that tells the compiler it need not issue this warning if variable is bound but not referenced. The ignorable function has no run-time cost.

The ignorable function is useful for ignoring arguments passed to, or values returned by, a function, method, or macro. The function has the same extent as a let; that is, it applies to the smallest enclosing implicit body.

The ignorable function is similar to ignore. However, unlike ignore, it does not issue a warning if you subsequently reference variable within the extent of the ignorable declaration. You might prefer ignorable to ignore if you are not concerned about such violations and do not wish to be warned about them.

Example:

This function ignores some of its arguments:

define method foo (x ::<integer>, #rest args)
  ignorable(args);
  ...
end

Here, we use ignorable to ignore one of the values returned by fn:

let (x,y,z) = fn();
ignorable(y);
See also:

integer-to-string Function

Returns a string representation of an integer.

Signature:

integer-to-string integer #key base size fill => string

Parameters:
Values:
Discussion:

Returns a string representation of integer in the given base, which must be between 2 and 36. The size of the string is right-aligned to size, and it is filled with the fill character. If the string is already larger than size then it is not truncated. If lowercase? is true then lowercase characters are used when base is higher than 10.

iterate Statement Macro

Iterates over a body.

Macro Call:

iterate name ({argument = init-value}*)
  [ body ]
end [ iterate ]

Parameters:

  • name – A Dylan variable-name bnf.

  • argument – A Dylan variable-name bnf.

  • init-value – A Dylan expression bnf.

  • body – A Dylan body bnf.

Values:

  • value – Zero or more instances of <object>.

Discussion:

Defines a function that can be used to iterate over a body. It is similar to for, but allows you to control when iteration will occur.

It creates a function called name which will perform a single step of the iteration at a time; body can call name whenever it wants to iterate another step. The form evaluates by calling the new function with the initial values specified.

Example:
iterate recurse (x = 5)
  if (x < 2) x else x * recurse(x - 1) end
end
one-of Function

Returns a union type comprised of singletons formed from its arguments.

Signature:

one-of object #rest more-objects => type

Parameters:

  • object – An instance of <object>.

  • more-objects (#rest) – Instances of <object>.

Values:

  • type – An instance of <type>.

Discussion:

Returns a union type comprised of singleton(object) and the singletons of any other objects passed with more-object.

one-of(x, y, z)

Is a type expression that is equivalent to

type-union(singleton(x), singleton(y), singleton(z))

position Open Generic function

Returns the key at which a particular value occurs in a sequence.

Signature:

position sequence target #key test start end skip count => position

Parameters:

  • sequence – An instance of <sequence>.

  • target – An instance of <object>.

  • test (#key) – An instance of <function>. Default value: ==.

  • start (#key) – An instance of <integer>. Default value: 0.

  • end (#key) – An instance of <object>. Default value: #f.

  • skip (#key) – An instance of <integer>. Default value: 0.

  • count (#key) – An instance of <object>. Default value: #f.

Values:

  • position – An instance of false-or(<integer>).

Discussion:

Returns the position at which target occurs in sequence.

If test is supplied, position uses it as an equivalence predicate for comparing sequence ‘s elements to target. It should take two objects and return a boolean. The default predicate used is ==.

The skip argument is interpreted as it is by Dylan’s find-key function: position ignores the first skip elements that match target, and if skip or fewer elements satisfy test, it returns #f.

The start and end arguments indicate, if supplied, which subrange of the sequence is used for the search.

remove-all-keys! Open Generic function

Removes all keys in a mutable collection, leaving it empty.

Signature:

remove-all-keys! mutable-collection => ()

Parameters:
Discussion:

Modifies mutable-collection by removing all its keys and leaving it empty. There is a predefined method on <table>.

<simple-condition> Instantiable Sealed Class

The class of conditions that accept a format string and format arguments with which to build a message describing the condition.

Superclasses:

<condition>

Discussion:

As the superclass of <simple-error>, <simple-warning>, and <simple-restart>, the <simple-condition> class provides the format-string: and format-arguments: init keywords described in the DRM.

Operations:

See also:

<stretchy-sequence> Open Abstract Class

The class of stretchy sequences.

Superclasses:

<sequence>, <stretchy-collection>

Discussion:

The class of stretchy sequences.

<string-table> Instantiable Sealed Class

The class of tables that use strings for keys.

Superclasses:

<table>

Discussion:

The class of tables that use instances of <string> for their keys. It is an error to use a key that is not an instance of <string>.

Keys are compared with the equivalence predicate \=.

The elements of the table are instances of <object>.

It is an error to modify a key once it has been used to add an element to a <string-table>. The effects of modification are not defined.

Note

This class is also exported from the table-extensions module of the table-extensions library.

string-to-integer Function

Returns the integer represented by its string argument, or by a substring of that argument, in a number base between 2 and 36.

Signature:

string-to-integer string #key base start end default => integer next-key

Parameters:

  • string – An instance of <byte-string>.

  • base (#key) – An instance of <integer>. Default value: 10.

  • start (#key) – An instance of <integer>. Default value: 0.

  • end (#key) – An instance of <integer>. Default value: sizeof(*string*).

  • default (#key) – An instance of <integer>. Default value: $unsupplied.

Values:
Discussion:

Returns the integer represented by the characters of string in the number base base, where base is between 2 and 36. You can constrain the search to a substring of string by giving values for start and end.

This function returns the next key beyond the last character it examines.

If there is no integer contained in the specified region of the string, this function returns default, if specified. If you do not give a value for default, this function signals an error.

This function is similar to C’s strtod function.

subclass Function

Returns a type representing a class and its subclasses.

Signature:

subclass class => subclass-type

Parameters:

  • class – An instance of <class>.

Values:

  • subclass-type – An instance of <type>.

Discussion:

Returns a type that describes all the objects representing subclasses of the given class. We term such a type a subclass type.

The subclass function is allowed to return an existing type if that type is type equivalent to the subclass type requested.

Without subclass, methods on generic functions (such as Dylan’s standard make and as) that take types as arguments are impossible to reuse without resorting to ad hoc techniques. In the language defined by the DRM, the only mechanism available for specializing such methods is to use singleton types. A singleton type specializer used in this way, by definition, gives a method applicable to exactly one type. In particular, such methods are not applicable to subtypes of the type in question. In order to define reusable methods on generic functions like this, we need a type which allows us to express applicability to a type and all its subtypes.

For an object O and class Y, the following instance? relationship applies:

INSTANCE-1: instance?(*O*, subclass(*Y*))

True if and only if O is a class and O is a subclass of Y.

For classes X and Y the following subtype? relationships hold (note that a rule applies only when no preceding rule matches):

SUBTYPE-1: subtype?(subclass(*X*), subclass(*Y*))

True if and only if X is a subclass of Y.

SUBTYPE-2: subtype?(singleton(*X*), subclass(*Y*))

True if and only if X is a class and X is a subclass of Y.

SUBTYPE-3: subtype?(subclass(*X*), singleton(*Y*))

Always false.

SUBTYPE-4: subtype?(subclass(*X*), *Y*)

where Y is not a subclass type. True if Y is <class> or any proper superclass of <class> (including <object>, any implementation-defined supertypes, and unions involving any of these). There may be other implementation-defined combinations of types X and Y for which this is also true.

SUBTYPE-5: subtype?(*X*, subclass(*Y*))

where X is not a subclass type. True if Y is <object> or any proper supertype of <object> and X is a subclass of <class>.

Note that by subclass relationships SUBTYPE-4 and SUBTYPE-5, we get this correspondence: <class> and subclass(<object>) are type equivalent.

Where the subtype? test has not been sufficient to determine an ordering for a method’s argument position, the following further method-ordering rules apply to cases involving subclass types (note that a rule applies only when no preceding rule matches):

  • SPECIFICITY+1. subclass(*X*) precedes subclass(*Y*) when the argument is a class C and X precedes Y in the class precedence list of C.

  • SPECIFICITY+2. subclass(*X*) always precedes Y, Y not a subclass type. That is, applicable subclass types precede any other applicable class-describing specializer.

The constraints implied by sealing come by direct application of sealing rules 1–3 (see page 136 of the DRM) and the following disjointness criteria for subclass types (note that a rule applies only when no preceding rule matches):

  • DISJOINTNESS+1. A subclass type subclass(*X*) and a type Y are disjoint if Y is disjoint from <class>, or if Y is a subclass of <class> without instance classes that are also subclasses of X.

  • DISJOINTNESS+2. Two subclass types subclass(*X*) and subclass(*Y*) are disjoint if the classes X and Y are disjoint.

  • DISJOINTNESS+3. A subclass type subclass(*X*) and a singleton type singleton(*O*) are disjoint unless O is a class and O is a subclass of X.

The guiding principle behind the semantics is that, as far as possible, methods on classes called with an instance should behave isomorphically to corresponding methods on corresponding subclass types called with the class of that instance. So, for example, given the heterarchy:

<object>
  \|
  <A>
  / \\
<B> <C>
 \\ /
  <D>

and methods:

method foo (<A>)
method foo (<B>)
method foo (<C>)
method foo (<D>)

method foo-using-type (subclass(<A>))
method foo-using-type (subclass(<B>))
method foo-using-type (subclass(<C>))
method foo-using-type (subclass(<D>))

that for a direct instance D1 of <D>:

foo-using-type(<D>)

should behave analogously to:

foo(D1)

with respect to method selection.

Example:
define class <A> (<object>) end;
define class <B> (<A>) end;
define class <C> (<A>) end;
define class <D> (<B>, <C>) end;

define method make (class :: subclass(<A>), #key)
  print("Making an <A>");
  next-method();
end method;

define method make (class :: subclass(<B>), #key)
  print("Making a <B>");
  next-method();
end method;

define method make (class :: subclass(<C>), #key)
  print("Making a <C>");
  next-method();
end method;

define method make (class :: subclass(<D>), #key)
  print("Making a <D>");
  next-method();
end method;

? make(<D>);
Making a <D>
Making a <B>
Making a <C>
Making an <A>
{instance of <D>}
$unfound Constant

A unique value that can be used to indicate that a search operation failed.

Type:

<list>

Value:

A unique value.

Discussion:

A unique value that can be used to indicate that a search operation failed.

Example:
if (unfound?(element(section-index-table, section-name,
                     default: $unfound)))
  section-index-table[section-name] := section-index-table.size + 1;
  write-record(stream, #"SECTIONNAME", section-name);
end if;
See also:

unfound Function

Returns the unique “unfound” value, $unfound.

Signature:

unfound () => unfound-marker

Values:

  • unfound-marker – The value $unfound.

Discussion:

Returns the unique “unfound” value, $unfound.

Example:

See $unfound.

See also:

found? Function

Returns true if object is not equal to $unfound, and false otherwise.

Signature:

found? object => boolean

Parameters:
Values:
Discussion:

Returns true if object is not equal to $unfound, and false otherwise.

It uses \= as the equivalence predicate.

Example:

See $unfound.

See also:

unfound? Function

Returns true if its argument is equal to the unique “unfound” value, $unfound, and false if it is not.

Signature:

unfound? object => unfound?

Parameters:
Values:
Discussion:

Returns true if object is equal to the unique “unfound” value, $unfound, and false if it is not. It uses \= as the equivalence predicate.

Example:

See $unfound.

See also:

$unsupplied Constant

A unique value that can be used to indicate that a keyword was not supplied.

Type:

<list>

Value:

A unique value.

Discussion:

A unique value that can be used to indicate that a keyword was not supplied.

Example:
define method find-next-or-previous-string
    (frame :: <editor-state-mixin>,
     #key reverse? = $unsupplied)
 => ()
  let editor :: <basic-editor> = frame-editor(frame);
  let reverse?
    = if (supplied?(reverse?))
        reverse?
      else
        editor-reverse-search?(editor)
      end;
  ...
end;
See also:

unsupplied Function

Returns the unique “unsupplied” value, $unsupplied.

Signature:

unsupplied () => unsupplied-marker

Values:
Discussion:

Returns the unique “unsupplied” value, $unsupplied.

Example:

See $unsupplied.

See also:

supplied? Function

Returns true if its argument is not equal to the unique “unsupplied” value, $unsupplied, and false if it is.

Signature:

supplied? object => supplied?

Parameters:
Values:
Discussion:

Returns true if object is not equal to the unique “unsupplied” value, $unsupplied, and false if it is. It uses \= as the equivalence predicate.

Example:

See $unsupplied.

See also:

unsupplied? Function

Returns true if its argument is equal to the unique “unsupplied” value, $unsupplied, and false if it is not.

Signature:

unsupplied? value => boolean

Parameters:
Values:
Discussion:

Returns true if its argument is equal to the unique “unsupplied” value, $unsupplied, and false if it is not. It uses \= as the equivalence predicate.

Example:

See $unsupplied.

See also:

when Statement Macro

Executes an implicit body if a test expression is true, and does nothing if the test is false.

Macro Call:

when (test) [ consequent ] end [ when ]

Parameters:

  • test – A Dylan expression bnf.

  • consequent – A Dylan body bnf.

Values:

  • value – Zero or more instances of <object>.

Discussion:

Executes consequent if test is true, and does nothing if test is false.

This macro behaves identically to Dylan’s standard if statement macro, except that there is no alternative flow of execution when the test is false.

Example:
when (x < 0)
  ~ x;
end;
split Open Generic function

Split a sequence (e.g., a string) into subsequences delineated by a given separator.

Signature:

split sequence separator #key start end count remove-if-empty? => parts

Parameters:

  • sequence – An instance of <sequence>.

  • separator – An instance of <object>.

  • start (#key) – An instance of <integer>. Default value: 0.

  • end (#key) – An instance of <integer>. Default value: sequence.size.

  • count (#key) – An instance of <integer>. Default value: no limit.

  • remove-if-empty? (#key) – An instance of <boolean>. Default value: #f.

Values:
Discussion:

Splits sequence into subsequences, splitting at each occurrence of separator. The sequence is searched from left to right, starting at start and ending at end - 1.

The resulting parts sequence is limited in size to count elements.

If remove-if-empty? is true, the result will not contain any subsequences that are empty.

See also:

split(<sequence>, <function>) Method

Split a sequence (e.g., a string) into subsequences delineated by a given separator.

Signature:

split sequence separator #key start end count remove-if-empty? => parts

Parameters:

  • sequence – An instance of <sequence>.

  • separator – An instance of <function>.

  • start (#key) – An instance of <integer>. Default value: 0.

  • end (#key) – An instance of <integer>. Default value: sequence.size.

  • count (#key) – An instance of <integer>. Default value: no limit.

  • remove-if-empty? (#key) – An instance of <boolean>. Default value: #f.

Values:

This is in some sense the most basic method, since others can be implemented in terms of it. The separator function must accept three arguments:

  1. The sequence in which to search for a separator,

  2. the start index in that sequence at which to begin searching, and

  3. the index at which to stop searching (exclusive).

The separator function must return #f to indicate that no separator was found, or two values:

  1. The start index of the separator in the sequence and

  2. the index of the first element after the end of the separator.

It is an error for the returned start and end indices to be equal since this is equivalent to splitting on an empty separator, which is undefined. It is undefined what happens if the return values are outside the [start, end) range passed to the separator function.

The initial start and end indices passed to the separator function are the same as the start and end arguments passed to this method. The separator function should stay within the given bounds whenever possible. (In particular it may not always be possible when the separator is a regular expression.)

See the source code for split(<sequence>, <object>) for an example of using this method.

split(<sequence>, <object>) Method

Split a sequence (e.g., a string) into subsequences separated by a specific object.

Signature:

split sequence separator #key start end count remove-if-empty? => parts

Parameters:

  • sequence – An instance of <sequence>.

  • separator – An instance of <object>.

  • start (#key) – An instance of <integer>. Default value: 0.

  • end (#key) – An instance of <integer>. Default value: sequence.size.

  • count (#key) – An instance of <integer>. Default value: no limit.

  • remove-if-empty? (#key) – An instance of <boolean>. Default value: #f.

  • test (#key) – An instance of <function>. Default value: ==.

Values:

Splits sequence around each occurrence of separator, which is compared to each element with the test function.

This method handles the relatively common case where sequence is a string and separator is a <character>.

Example:
split("a.b.c", '.')     => #("a", "b", "c")
split(#[1, 2, 3, 4], 2) => #(#[1], #[3, 4])
split(<sequence>, <sequence>) Method

Split a sequence (e.g., a string) into subsequences separated by another sequence.

Signature:

split sequence separator #key start end count remove-if-empty? => parts

Parameters:

  • sequence – An instance of <sequence>.

  • separator – An instance of <sequence>.

  • start (#key) – An instance of <integer>. Default value: 0.

  • end (#key) – An instance of <integer>. Default value: sequence.size.

  • count (#key) – An instance of <integer>. Default value: no limit.

  • remove-if-empty? (#key) – An instance of <boolean>. Default value: #f.

  • test (#key) – An instance of <function>. Default value: ==.

Values:

  • parts –

    An instance of <sequence>.

    Splits sequence around occurrences of the separator subsequence. This handles the relatively common case where sequence and separator are both instances of <string>.

    example:
    split("aabbccdd", "bb")) => #("aa", "ccdd")

    Note

    If you want to use split to find a <sequence> which is a single element of another sequence it may not do what you expect because this method is more specific than split(<sequence>, <object>). This is expected to be a rare case that can be handled by using split(<sequence>, <function>) if necessary.

join Open Generic function

Join several sequences (e.g. strings) together, including a separator between each pair of adjacent sequences.

Signature:

join sequences separator #key key conjunction => joined

Parameters:

  • sequences – An instance of <sequence>.

  • separator – An instance of <sequence>.

  • key (#key) – Transformation to apply to each item. Default value: identity.

  • conjunction (#key) – Last separator. Default value: #f

Values:
Discussion:

Join sequences together, including separator between each sequence.

If the first argument is empty, an empty sequence of type type-for-copy(separator) is returned. If sequences is of size one, the first element is returned. Otherwise, the resulting joined sequence will be of the same type as sequences.

Every element in sequences is transformed by key, which is a function that must accept one argument.

If conjunction is not false, it is used instead of separator to join the last pair of elements in sequences.

Example:

join(range(from: 1, to: 3), ", ",
     key: integer-to-string, conjunction: " and ")
=> "1, 2 and 3"
See also:

join(<sequence>, <sequence>) Method

Join several sequences together, including a separator between each pair of adjacent sequences.

Signature:

join sequences separator #key key conjunction => joined

Parameters:

  • items – An instance of <sequence>.

  • separator – An instance of <sequence>.

  • key (#key) – Transformation to apply to each item. An instance of <function>.

  • conjunction (#key) – Last separator. An instance of false-or(<sequence>).

Values:
See also:

application-arguments Function

Returns the arguments passed to the running application.

Signature:

application-arguments => arguments

Values:
Discussion:

Returns the arguments passed to the running application as a vector of instances of <byte-string>.

See also:

application-filename Function

Returns the full filename of the running application.

Signature:

application-filename => false-or-filename

Values:

  • false-or-filename – An instance of false-or(<byte-string>).

Discussion:

Returns the full filename (that is, the absolute pathname) of the running application, or #f if the filename cannot be determined.

Example:

The following is an example of an absolute pathname naming an application:

"C:\\Program Files\\foo\\bar.exe"
See also:

application-name Function

Returns the name of the running application.

Signature:

application-name => name

Values:
Discussion:

Returns the name of the running application. This is normally the command name as typed on the command line and may be a non-absolute pathname.

Example:

The following is an example of a non-absolute pathname used to refer to the application name:

"foo\\bar.exe"
See also:

exit-application Function

Terminates execution of the running application.

Signature:

exit-application status => ()

Parameters:
Discussion:

Terminates execution of the running application, returning the value of status to whatever launched the application, for example an MS-DOS window or Windows 95/NT shell.

Note

This function is also available from the operating-system module.

See also:

register-application-exit-function Function

Register a function to be executed when the application is about to exit.

Signature:

register-application-exit-function function => ()

Parameters:
Discussion:

Register a function to be executed when the application is about to exit. The Dylan runtime will make sure that these functions are executed.

The function should not expect any arguments, nor expect that any return values be used.

Note

Currently, the registered functions will be invoked in the reverse order in which they were added. This is not currently a contractual guarantee and may be subject to change.

Note

This function is also available from the operating-system module.

Example:

See also:

tokenize-command-line Function

Parses a command line into a command name and arguments.

Signature:

tokenize-command-line line => command #rest arguments

Parameters:
Values:
Discussion:

Parses the command specified in line into a command name and arguments. The rules used to tokenize the string are given in Microsoft’s C/C++ reference in the section “Parsing C Command-Line Arguments”.

See also: