The trivial-coerce Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The trivial-coerce Reference Manual

This is the trivial-coerce Reference Manual, version 0.0.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 07:25:23 2022 GMT+0.

Table of Contents


1 Introduction

trivial-coerce

Status

I suspect that unless there are requests, I will not work on optimizing for run-time performance.

In case someone has a better idea for trivial-coerce - feel free to raise an issue, and in the worst case, if more than a handful think (or I get convinced) the other library better deserves the name, I'd be glad to rename this library to something else. (Therefore, use with package-local-nicknames.)

Crucial dependencies:

Why

Common Lisp has a variety of non-uniform type-conversions. Some use cl:coerce, others use cl:float or cl:string, and lots more. In some sense, the cl:coerce function is information-preserving in that it prevents non-integers from being coerced into integers, or characters from being converted to and from integers. If you find these semantics useful, you might not find trivial-coerce:coerce as useful.

OTOH, a case could be made that the prevalence of information non-preserving type conversions makes things easier for prototyping, enables better polymorphism, as well as makes things easier for new people.

Examples

See coercions.lisp and tests.lisp and docstrings.

generic-cl:coerce

I do not find generic-functions suitable for the purpose of coercion. For instance:

(in-package :generic-cl)
(deftype int () 'integer)
(defmethod coerce ((num real) (type (eql 'integer)))
  (floor num))

(coerce 2.5 'integer) ;=> works
(coerce 2.5 'int) ;=> does not work
(trivial-coerce:coerce 2.5 'int) ;=> works

;; Yet another example would concern the order of applicants in a OR or AND or MEMBER
;; compound-type-specifiers - and it surely feels useful to say: (and vector (not string))

I do not know of alternatives.

Documentation

The main function is (trivial-coerce:coerce object output-type-spec): This converts OBJECT to type specified by OUTPUT-TYPE-SPEC.

The applicable coercion is guaranteed to take an object of (super)type of OBJECT and return an object of type= specified by OUTPUT-TYPE-SPEC. (See Role of Extended Types.)

Important functions and macros

Example usages of define-coercion can be found in coercions.lisp.

Compile Time Optimizations

CL-USER> (defun to-type (a type)
           (coerce a type))
TO-TYPE
CL-USER> (defun to-type (a type)
           (declare (optimize speed))
           (coerce a type))

; (Compiler) Macro of
;    #<POLYMORPHIC-FUNCTIONS:POLYMORPHIC-FUNCTION COERCE (38)> 
; is unable to optimize
;   (COERCE A TYPE)
; because:
;   
;   Type of
;     TYPE
;   could not be determined
WARNING: redefining COMMON-LISP-USER::TO-TYPE in DEFUN
TO-TYPE
CL-USER> (defun to-string (a)
           (declare (optimize speed))
           (coerce a 'string))
           
; (Compiler) Macro of
;    #<POLYMORPHIC-FUNCTIONS:POLYMORPHIC-FUNCTION COERCE (38)> 
; is unable to optimize
;   (COERCE A 'STRING)
; because:
;   
;   Type of
;     A
;   could not be determined
TO-STRING
CL-USER> (defun to-string (a)
           (declare (optimize speed)
                    (type number a))
           (coerce a 'string))
WARNING: redefining COMMON-LISP-USER::TO-STRING in DEFUN
TO-STRING
CL-USER> (disassemble 'to-string)
; disassembly for TO-STRING
; Size: 17 bytes. Origin: #x5374A224                          ; TO-STRING
; 24:       B902000000       MOV ECX, 2
; 29:       FF7508           PUSH QWORD PTR [RBP+8]
; 2C:       B8C2333650       MOV EAX, #x503633C2              ; #<FDEFN SB-INT:STRINGIFY-OBJECT>
; 31:       FFE0             JMP RAX
; 33:       CC10             INT3 16                          ; Invalid argument count trap
NIL

Role of Extended Types

The form (define-coercion (sequence :to list :from sequence) (cl:coerce sequence 'list)) macroexpands to:

(defpolymorph (coerce :inline t)
    ((sequence sequence) (#:output-type-spec1824 (type= list)))
    list
  (declare (ignorable sequence #:output-type-spec1824))
  (common-lisp:coerce sequence 'list))

Thus, we use the extended type (type= list) to denote all the type specifiers that are type= to list. Thus (typep '(and list) '(type= list)) holds (using polymorphic-functions.extended-types:typep).

*If you are using extensible-compound-types, then the appropriate type= would be extensible-compound-types:type= instead of polymorphic-functions.extended-types:type=.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 trivial-coerce

‘trivial-coerce‘ primarily provides a ‘trivial-coerce:coerce‘ function intended as an extensible alternative to ‘cl:coerce‘.

Author

<Shubhamkar Ayare (shubhamayare@yahoo.co.in)>

License

MIT

Version

0.0.2

Dependencies
  • trivial-types (system).
  • polymorphic-functions (system).
  • ctype (system).
Source

trivial-coerce.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 trivial-coerce/trivial-coerce.asd

Source

trivial-coerce.asd.

Parent Component

trivial-coerce (system).

ASDF Systems

trivial-coerce.


3.1.2 trivial-coerce/package.lisp

Source

trivial-coerce.asd.

Parent Component

trivial-coerce (system).

Packages

trivial-coerce.


3.1.3 trivial-coerce/trivial-coerce.lisp

Dependency

package.lisp (file).

Source

trivial-coerce.asd.

Parent Component

trivial-coerce (system).

Public Interface
Internals

3.1.4 trivial-coerce/coercions.lisp

Dependency

trivial-coerce.lisp (file).

Source

trivial-coerce.asd.

Parent Component

trivial-coerce (system).


4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 trivial-coerce

Source

package.lisp.

Use List
  • common-lisp.
  • ctype.
  • polymorphic-functions.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Macros

Macro: define-coercion ((var &key to from) &body body)

Defines a coercion for VAR of type FROM to type TO.
Assumes the coercion to be valid in null lexical environment.
If a TYPE= coercion is available, and
- if IF-EXISTS is :OVERWRITE, then the same coercion will be overwritten.
- if IF-EXISTS is :SUPERSEDE, then the existing coercion will be first deleted. In practice, this means that :SUPERSEDE also replaces the stored type-specs, while :OVERWRITE leaves the stored type-specs unchanged.
- if IF-EXISTS is :ERROR, an ERROR is signalled

Package

trivial-coerce.

Source

trivial-coerce.lisp.


5.1.2 Compiler macros

Compiler Macro: coerce (form &optional env)
Package

trivial-coerce.

Alias for

pf-compiler-macro.


5.1.3 Ordinary functions

Function: list-all-coercions (&optional to)
Package

trivial-coerce.

Source

trivial-coerce.lisp.

Function: undefine-coercion (from to)

Removes a coercion TYPE= to FROM and TO.

Package

trivial-coerce.

Source

trivial-coerce.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *trivial-coerce-toplevel-p*

Used inside the default COERCE POLYMORPH to better the case of undefined coercions.

Package

trivial-coerce.

Source

trivial-coerce.lisp.


Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary functions

Function: coerce-error (name env args &optional arg-types)
Package

trivial-coerce.

Source

trivial-coerce.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*trivial-coerce-toplevel-p*: Private special variables

S
Special Variable, *trivial-coerce-toplevel-p*: Private special variables

Jump to:   *  
S