Chapter 12

The Built-In Functions

Coercing and Copying Objects

The following functions are used to coerce, copy, or simply return objects.

identity [Function]

Returns its argument.

Signature:

identity object ⇒ object

Arguments:
object

An instance of <object>.

Values:
object

An instance of <object>; the same object that was passed in as an argument.

Description:

Returns object unaltered.

values [Function]

Returns its arguments as multiple values.

Signature:

values #rest the-values ⇒ #rest the-values

Arguments:
the-values

Zero or more instances of <object>.

Values:
the-values

Zero or more instances of <object>; the objects that were passed as arguments.

Description:

Returns the-values as multiple values.

values(1, 2, 3)
 ⇒ 1    // first value returned
    2    // second value returned
    3    // third value returned

General Coercion Function

as [Open Generic Function]

Coerces an object to a type.

Signature:

as type object ⇒ instance

Arguments:
type

An instance of <type>.

object

An instance of <object>.

Values:
instance

An instance of <object>. It must be an instance of type.

Description:

Coerces object to type. That is, it returns an instance of type that has the same contents as object. If object is already an instance of type, it is returned unchanged. In general, the value returned may or may not be freshly allocated.

Predefined methods allow coercion between integers and characters, between strings and symbols, and between collection types. No methods are predefined for other classes. Programs may define additional methods.

as collection-type collection ⇒ instance-of-collection-type [G.F. Method]

When converting between collection types, the return value will have the same number of elements as collection. If the collection is an instance of <sequence> and the collection-type is a subtype of <sequence>, the elements will be in the same order. The individual elements may also undergo some conversion. The specific collection types for which as is defined is implementation defined.

as (singleton (<integer>)) character ⇒ integer [Sealed G.F. Method]

This method on as returns a numeric equivalent for character. The integer returned is implementation dependent.

as (singleton (<character>)) integer ⇒ character [Sealed G.F. Method]

This method on as returns the character equivalent to integer. The meaning of integer is implementation dependent.

as (singleton (<symbol>)) string ⇒ symbol [Sealed G.F. Method]

This method on as returns the symbol that has the name string. If the symbol does not yet exist, it is created. This method on as will always return the same symbol for strings of the same characters, without regard to alphabetic case.

as(<symbol>, "foo")
 ⇒  #"foo"
#"FOO" == as(<symbol>, "foo")
 ⇒  #t
#"Foo"
 ⇒  #"foo"
as (singleton (<string>)) symbol ⇒ string [Sealed G.F. Method]

This method on as returns the name of the symbol, which will be a string.

as(<string>, #"Foo")
 ⇒  "Foo"

Coercing Case

as-uppercase [Open Generic Function]

Coerces an object to uppercase.

Signature:

as-uppercase object1 ⇒ object2

Arguments:
object1

An instance of <object>.

Values:
object2

An instance of <object>.

Description:

Coerces an object to uppercase and returns the resulting new object.

object1 is not modified by this operation.

as-uppercase character ⇒ uppercase-character [Sealed G.F. Method]

This method returns the uppercase equivalent for character. If character already is uppercase or does not exist in two cases, it is returned unchanged.

as-uppercase string ⇒ new-string [G.F. Method]

This method is equivalent to map(as-uppercase, string).

as-uppercase! [Open Generic Function]

Coerces an object to uppercase in place.

Signature:

as-uppercase! object ⇒ object

Arguments:
object

An instance of <object>.

Values:
object

An instance of <object>; the same object that was passed in as an argument.

Description:

Coerces an object to uppercase in place and returns the modified object.

object may be modified by this operation, and the result will be == to the object.

as-uppercase! string ⇒ string [G.F. Method]

This method is equivalent to map-into(string, as-uppercase, string).

as-lowercase [Open Generic Function]

Coerces an object to lowercase.

Signature:

as-lowercase object1 ⇒ object2

Arguments:
object1

An instance of <object>.

Values:
object2

An instance of <object>.

Description:

Coerces an object to lowercase and returns the resulting new object.

object1 will not be modified by this operation.

as-lowercase character ⇒ lowercase-character [Sealed G.F. Method]

The <character> method on as-lowercase returns the lowercase equivalent for character. If character already is lowercase or does not exist in two cases, it is returned unchanged.

as-lowercase string ⇒ new-string [G.F. Method]

This method is equivalent to map(as-lowercase, string).

as-lowercase! [Open Generic Function]

Coerces an object to lowercase in place.

Signature:

as-lowercase! object ⇒ object

Arguments:
object

An instance of <object>.

Values:
object

An instance of <object>; the same object that was passed in as an argument.

Description:

Coerces an object to lowercase in place and returns the modified object.

object may be modified by this operation, and the result will be == to the object.

as-lowercase! string ⇒ string [G.F. Method]

This method is equivalent to map-into(string, as-lowercase, string).

Copying Objects

shallow-copy [Open Generic Function]

Returns a copy of its argument.

Signature:

shallow-copy object1 ⇒ #rest objects

Arguments:
object1

An instance of <object>.

Values:
objects

Instances of <object>.

Description:

Returns a new object that has the same contents as object1. The contents are not copied but are the same objects contained in object1.

There is a predefined method for instances of <collection>. For other classes, the programmer must provide a method.

shallow-copy collection ⇒ new-collection [G.F. Method]

The method for <collection> creates a new object by calling make on the type-for-copy of collection and filling it with the same elements as collection.

type-for-copy [Open Generic Function]

Returns an appropriate type for creating mutable copies of its argument.

Signature:

type-for-copy object ⇒ type

Arguments:
object

An instance of <object>.

Values:
type

An instance of <type>.

Description:

Returns an appropriate type for creating mutable copies of object.

The type-for-copy value of a collection must be an instantiable subtype of <mutable-collection>. For collections that are themselves mutable, the collection's actual class is generally the most appropriate (assuming it is instantiable). The type-for-copy value for a sequence should be a subtype of <sequence>, and the type-for-copy value of an explicit-key-collection should be a subtype of <explicit-key-collection>.

type-for-copy object ⇒ type [G.F. Method]

The method on <object> returns the result of calling object-class on the object.

type-for-copy mutable-collection ⇒ type [G.F. Method]

The method on <mutable-collection> returns the result of calling object-class on the mutable-collection.

type-for-copy limited-collection ⇒ type [Sealed G.F. Method]

For a type L1 created by limited(C, of: T, size: S) where C is not <range>, type-for-copy of an object made by instantiating L1 returns a type L2 that satisfies each of the following:

  • L2 is either a class or a limited collection type.
  • L2 is a subtype of C.
  • L2's element type is equivalent to T.
  • If L2 is a limited collection type, its size attribute is #f.
type-for-copy range ⇒ <list> [Sealed G.F. Method]

The method on <range> returns <list>.

type-for-copy limited-range ⇒ <list> [Sealed G.F. Method]

The method on instances of limited(singleton(<range>)…) returns <list>, the same as for any instance of <range>.