source: project/wiki/eggref/5/ck-macros @ 37322

== ck-macros

Composable Scheme macros based on the CK abstract machine.

This egg is based on the CK-macro system described in
"[[http://okmij.org/ftp/Scheme/macros.html#ck-macros|Applicative syntax-rules: macros that compose better]]"
by Oleg Kiselyov.
This egg provides the core {{ck}} macro,
many useful (and some not-so-useful) predefined CK-macros,
the {{ck-wrapper}} procedure, and many wrappers of R5RS procedures.

If you create a useful or interesting general-purpose CK-macro,
or an improvement to an existing CK-macro,
please contact the maintainer (John) so your contribution can be added to the egg.
All source code (including contributions) is public domain.

; Project / Source Code Repository: [[https://gitlab.com/jcroisant/ck-macros]]
; Maintainer: [[/users/john-croisant|John Croisant]]
; Based on work by: Oleg Kiselyov
; License: Public Domain


'''Table of Contents'''
[[toc:]]


=== Version History

; 0.2.0 (2019-02-28) : Ported to CHICKEN 5. Added {{ck-wrapper}} and many R5RS wrappers. Added some new portable CK-macros. Breaking changes to {{c-apply}}. Renamed some CK-macros.
; 0.1.1 (2016-02-07) : Fixed {{c-append}} and {{c-vector-append}} failing when given one argument.
; 0.1.0 (2016-02-06) : Initial release. Includes version 1.1 (April 2011) of the core {{ck}} macro. Includes many CK-macros.

For more information about what changed in each version,
see the [[https://gitlab.com/jcroisant/ck-macros/blob/master/CHANGELOG.md|CHANGELOG]].


=== What are CK-macros?

CK-macros are Scheme macros written to be compatible with with the core {{ck}} macro.

The core {{ck}} macro is a {{syntax-rules}} macro which implements the CK abstract machine.
The CK abstract machine is a theoretical model of computation,
described in the paper "Control Operators, the SECD-Machine, and the Lambda-Calculus"
by Matthias Felleisen and Daniel P. Friedman.
But, you don't need to read or understand the paper in order to create or use CK-macros!

Basically, a CK-macro leverages the core {{ck}} macro
to recursively expand the CK-macros's arguments first,
before the CK-macro itself is expanded.
This gives you more control over the macro expansion process,
allowing you to easily combine simple reusable macros to form more complex macros.

This is very similar to the way Scheme allows you to easily combine simple resuable functions
({{map}}, {{fold}}, {{cons}}, etc.) to create more complex functions.
In fact, many useful Scheme functions can be translated to CK-macros,
allowing you to portably achieve the same effect at macro-expansion time.
You can even implement "higher-ordered macros" which take a macro as an argument.
See {{c-map1}} and {{c-compose}} for examples of higher-ordered macros.

CK-macros are not as flexibile, powerful, or efficient as
CHICKEN's [[/man/5/Module (chicken syntax)|explicit and implicit renaming macros]],
but CK-macros are much more portable.

* The [[#ck|core {{ck}} macro]] and everything in the
  [[#portable-ck-macros|Portable CK-Macros]] section
  are implemented using only standard R5RS features, such as {{syntax-rules}}.
  This means they will work on any implementation of R5RS or later.

* The [[#ck-wrapper|{{ck-wrapper}} procedure]] and everything in the
  [[#non-portable-r5rs-wrappers|Non-portable R5RS Wrappers]] section
  are implemented using
  [[/man/5/Module (chicken syntax)#explicit-renaming-macros|{{er-macro-transformer}}]],
  which is not standard R5RS but is available in many Scheme implementations.


=== How to write CK-macros

(Note: If you don't care about strict R5RS portability,
the easiest way to create a CK-macro is with [[#ck-wrapper|{{ck-wrapper}}]].)

Here is a basic template for portable CK-macros:

<enscript highlight="scheme">
(define-syntax c-foo
  (syntax-rules (quote)
    ((c-foo s 'input1 'input2 ...)
     (ck s output))))
</enscript>

A CK-macro is just a normal macro that expands to a call to the core {{ck}} macro.
To be portable, CK-macros are usually written using {{syntax-rules}}.
But, you can write CK-macros using other macro systems,
such as CHICKEN's [[/manual/Macros|explicit and implicit renaming macros]],
as long your macro eventually expands into a call to the core {{ck}} macro.

By convention, the names of CK-macros usually start with "c-",
to distinguish them from non-CK macros or procedures with similar names.
But, this naming convention is not required.

CK-macros treat quoting specially, so you should have {{quote}} in the list of literal identifiers (the first argument to {{syntax-rules}}).
You can also have other literal identifiers if needed.

Every CK-macro's first argument must be the stack, usually called {{s}}.
The stack is used internally by the core {{ck}} macro while recursively expanding macro arguments.
Your CK-macro should not touch the stack, only pass it through to the core {{ck}} macro.

Each {{'input}} is an argument passed to your macro.
Your macro can have any number of input arguments, and they can be named whatever you want.
They can also be lists or patterns, allowing you to destructure the arguments,
as is often done with {{syntax-rules}} macros.

The core {{ck}} macro expands the input arguments ahead of time,
so the arguments will always be quoted values by the time your macro is expanded.
Usually CK-macros are defined with their input arguments quoted (as above),
so that you can easily destructure the input to use in your macro.
You may recall that {{'a}} is translated by the reader to {{(quote a)}}.
So, the above example is exactly the same as:

<enscript highlight="scheme">
(define-syntax c-foo
  (syntax-rules (quote)
    ((c-foo s (quote input1) (quote input2) ...)
     (ck s output))))
</enscript>

When written in this way, it is easier to see that {{input1}} and {{input2}}
are merely placeholders in the {{syntax-rules}} pattern.
(This is also why you must tell {{syntax-rules}} that {{quote}} is a literal identifier.
Otherwise, {{syntax-rules}} would treat {{quote}} as a placeholder, too.)

Your macro should transform the {{input}}s in some way to produce the {{output}},
which is passed to the core {{ck}} macro.
The {{output}} must be either:

* A quoted value, such as {{'a}}, {{'(+ 1 2)}}, {{'"foo"}}, {{'42}}, or {{'#t}}.
* Or, an unquoted call to a CK-macro '''without the s argument''', such as {{(c-cons '+ '(1 2))}}.
  Nested calls are allowed, such as {{(c-cons '+ (c-list '1 '2))}}.

Quoting is how the core {{ck}} macro knows the difference between a value and a CK-macro call.
Therefore, '''all values must be quoted''',
even values which normally do not need to be quoted in Scheme code,
such as strings, numbers, and booleans.

Eventually, your CK-macro must expand into a call to the core {{ck}} macro
with a quoted value.
We say that the macro "yields" this quoted value.
The quoted value is either used as an argument to another CK-macro,
or if your CK-macro is the outer-most CK-macro call,
then the core {{ck}} macro expands into the '''unquoted value'''.

So, if your CK-macro yields the quoted value {{'(+ 1 2)}},
and it is the outer-most CK-macro (not an argument to another CK-macro),
the core {{ck}} macro will expand to the unquoted expression {{(+ 1 2)}},
which would later be evaluated to the number 3.
(If you want to yield a quoted form as the final result,
use {{c-quote}} as the outer-most CK-macro.)

See [[http://okmij.org/ftp/Scheme/macros.html#ck-macros|the original article]]
or [[https://gitlab.com/jcroisant/ck-macros/blob/master/lib/portable.scm|the source code]]
for many examples of CK-macros.


=== Combining CK and non-CK macros

The arguments to a CK-macro must either be a quoted value or a call to a CK-macro
(i.e. a macro that expands to a call to the core {{ck}} macro).
Therefore, most non-CK macros and special forms cannot be used as arguments to a CK-macro.

Some non-CK macros can be used in a way that expands into a user-provided expression.
It is therefore possible for these non-CK macros to be used as arguments to CK-macros,
as long as they eventually expand into a call to the core {{ck}} macro.

It is possible to write a non-CK macro which invokes a CK-macro via the core {{ck}} macro.
For example, if you are writing a macro for other people to use,
you can create a convenience macro, like so:

<enscript highlight="scheme">
(define-syntax foo
  (syntax-rules ()
    ((foo arg1 arg2 arg3)
     (ck () (c-foo 'arg1 'arg2 'arg3)))))
</enscript>

Also, it is possible for a CK-macro to expand into a call to a non-CK macro
as its final result, or as part of the body of its final result.
For example:

<enscript highlight="scheme">
(ck () (c-list 'when (c-list '< '1 '2) (c-list 'print '"Yay!")))
;;; Expands to the expression (when (< 1 2) (print "Yay!")).
</enscript>


=== Troubleshooting

CK-macros push the Scheme macro system in unusual ways,
so unfortunately they are not very user-friendly.

One common error you may see is, "no rule matches form".
This often indicates that you forgot to quote a value somewhere.
As explained in the section [[#how-to-write-ck-macros|How to write CK-macros]],
all values must be quoted,
even values which normally do not need to be quoted in Scheme code,
such as strings, numbers, and booleans.

For example, the code {{(ck () (c-not #t))}} will result in an error like this:

 Syntax error: no rule matches form
 
         (ck38782 (((c-not))) #t)

The solution is to quote the {{#t}}, like this: {{(ck () (c-not '#t))}}


=== Known issues and limitations

==== Slow compilation

CK-macros are pretty slow to compile,
because the computation is done at compile time,
using ''very'' deeply recursive macro expansions.

Non-portable wrappers created with [[#ck-wrapper|{{ck-wrapper}}]]
are probably somewhat faster than the portable CK-macros created with {{syntax-rules}}.
But this library prioritizes portability over efficiency,
so CK-macros are only implemented as wrappers if it is ''impossible''
to implement them using {{syntax-rules}}.

You could likely improve compilation speed in your own code by
redefining various CK-macros using {{ck-wrapper}}.


==== Pitfalls of c-sym-eq?

{{c-sym-eq?}} has some strange and unexpected behaviors
because of the way it uses {{let-syntax}}.

* The behavior of {{c-sym-eq?}} is undefined and non-portable
  when comparing anything except symbols.

* You should not use {{c-sym-eq?}} in any code that expands
  into a definition (of a variable, procedure, etc.),
  because that definition will not be visible from outside.
  This is because definitions that occur within the body of {{let-syntax}}
  are internal definitions, not global definitions.

For example, this code will not work as expected:

 (ck () (c-list 'define 'x (c-sym-eq? 'a 'a)))

You might expect it to expand to {{(define x #t)}},
defining a global variable {{x}} with the value {{#t}}.
But even though {{c-sym-eq?}} seems to be used "inside" the definition,
the core {{ck}} macro turns things "inside out"
to eagerly expand macro arguments first.
So, the definition will actually appear inside of a {{let-syntax}},
and {{x}} will not be visible from outside.

These pitfalls also affect other macros that use {{c-sym-eq?}} directly or indirectly:

* {{c-sym-equal?}}
* {{c-member}} with the default comparison operator
* {{c-assoc}} with the default comparison operator
* {{c-alist-delete}} with the default comparison operator

It is believed to be impossible to fix {{c-sym-eq?}} in a portable way,
so it is recommended that you avoid using it or {{c-sym-equal?}} if possible.
If you don't care about strict R5RS portability,
you should use the non-portable wrappers {{c-eq?}} and {{c-equal?}} instead.


=== ck

<syntax>(ck s 'v)</syntax>
<syntax>(ck s (op ...))</syntax>

This is the core {{ck}} macro, which implements the CK abstract machine.
This macro's public interface has two shapes:
one with a quoted value, and one with a CK-macro call.

; s : The stack, used internally by this macro. When initially invoking this macro, {{s}} should be the empty list, e.g. {{(ck () (c-cons '+ '(1 2)))}}.
; 'v : A quoted value. Can be a quoted list, symbol, or other literal value. The quote is necessary, even for literal values like strings, numbers, and booleans.
; (op ...) : A CK-macro call '''without the s argument''', such as {{(c-cons '+ '(1 2))}}.
Nested calls are allowed, such as {{(c-cons '+ (c-list '1 '2))}}.


=== ck-wrapper

<procedure>(ck-wrapper proc)  →  macro transformer</procedure>

Wrap a procedure in a CK-macro, returning a macro transformer
that can be used with {{define-syntax}} or {{let-syntax}}.

{{ck-wrapper}} requires '''version 0.2.0 or later''' of the ck-macros egg.
It is considered '''non-portable''' because it depends on
[[/man/5/Module (chicken syntax)#explicit-renaming-macros|{{er-macro-transformer}}]],
which is not defined in standard R5RS.
However, it should work on any Scheme which defines
{{er-macro-transformer}} in the usual way.

You can wrap any other expression that evaluates to a procedure,
such as a procedure name, a lambda form, a "let over lambda" expression, etc.
The expression will be evaluated once,
when the call to {{ck-wrapper}} is evaluated.
Therefore, the procedure you are wrapping must be available
in the syntax environment at macro expansion time.
(In other words, you should use
[[/man/5/Module (chicken syntax)#define-for-syntax|{{define-for-syntax}}]],
[[/man/5/Modules#import-for-syntax|{{import-for-syntax}}]], etc.)

Examples:

<enscript highlight="scheme">
;;; Import iota from SRFI 1.
(cond-expand
  (chicken-4
   (use-for-syntax (only srfi-1 iota)))
  (chicken-5
   (import-for-syntax (only (srfi 1) iota))))

(define-syntax c-iota (ck-wrapper iota))

(ck () (c-quote (c-iota '5)))
;; ==> '(0 1 2 3 4)

;;; A helper procedure that returns a closure.
(define-for-syntax (make-adder n)
  (lambda (x) (+ x n)))

;;; Temporarily define a ck-wrapper around a closure.
(let-syntax ((c-add2 (ck-wrapper (make-adder 2))))
  ;; Map c-add2 over the result of c-iota.
  (ck () (c-quote (c-map1 '(c-add2) (c-iota '5)))))
;; ==> '(2 3 4 5 6)
</enscript>


=== Portable CK-Macros

The CK-macros in this section are defined using only standard R5RS features,
such as {{syntax-rules}} and {{let-syntax}}.
So, these CK-macros will work on any implementation of R5RS or later.


==== General

<syntax>(c-quote X)  →  'X</syntax>

Adds an extra level of quotation to the argument.
This is useful for macros that should expand to a quoted value.

<enscript highlight="scheme">
;; Without c-quote
(ck () (c-cons '+ '(1 2)))
;; Expands to (+ 1 2), which evaluates to the number 3.

;; With c-quote
(ck () (c-quote (c-cons '+ '(1 2))))
;; Expands to '(+ 1 2), a quoted list.
</enscript>


<syntax>(c-eval '(OP ...))  →  result</syntax>

Takes a quoted operation and unquotes it,
allowing the CK machine to expand it.
Analogous to {{eval}}.

<enscript highlight="scheme">
(ck () (c-quote (c-eval '(c-cons 'a 'b))))
;; ==> '(a . b)
</enscript>


<syntax>(c-call '(OP ...) X ...)  →  result</syntax>

Like {{c-eval}}, but adds the given arguments on to the end of the operation.
Analogous to a lambda call in normal Scheme code.

<enscript highlight="scheme">
(ck () (c-quote (c-call '(c-cons 'a) 'b)))
;; ==> '(a . b)
</enscript>


<syntax>(c-apply '(OP ...) X ... '(Y ...))  →  result</syntax>

Like {{c-call}}, but the last argument is a list of more arguments.
Analogous to {{apply}}.

<enscript highlight="scheme">
(ck () (c-quote (c-apply '(c-list) 'a '(b) '(c d))))
;; ==> '(a (b) c d)
</enscript>

'''Prior to version 0.2.0''', the arguments in the final list required an extra level of quoting.


<syntax>(c-compose '((OP-N ...) ... (OP-1 ...)) X ...)  →  result</syntax>

Compose one or more CK-macros and apply them to the arguments.
Calls the right-most {{OP}} with the arguments {{X ...}},
then calls the next-right-most {{OP}} with that result, and so on:

 (OP-N ... (OP-2 ... (OP-1 ... X ...)))

{{OP-1}} must accept all the {{X}}s as arguments,
and the other {{OP}}s must each accept one argument (the result of the previous operation).
See also {{c-rcompose}}, which is more efficient.
Added in '''version 0.2.0'''


<enscript highlight="scheme">
(ck () (c-compose '((c-car) (c-cdr)) '(1 2 3)))
;; ==> 2

;;; Map over a list of lists to see which are not empty.
(ck () (c-quote (c-map1 '(c-compose '((c-not) (c-null?)))
                        '((1) () (2 3)))))
;; ==> '(#t #f #t)
</enscript>


<syntax>(c-rcompose '((OP-1 ...) ... (OP-N ...)) X ...)  →  result</syntax>

Like {{c-compose}}, but the operations are called in the reverse order (left to right).
This is more efficient than {{c-compose}}.
Added in '''version 0.2.0'''


<syntax>(c-identity X)  →  X</syntax>

Simply yields the value as given.
Sometimes useful for higher-order macros like {{c-filter}}.

<enscript highlight="scheme">
(ck () (c-quote (c-identity 'a)))
;; ==> 'a
</enscript>


==== Boolean Logic

<syntax>(c-not X)  →  '#t or '#f</syntax>

Yields {{'#t}} if the argument is {{'#f}}, otherwise yields {{'#f}}.
Analogous to {{not}}.


<syntax>(c-true X ...)  →  '#t</syntax>

Always yields {{'#t}}, regardless of its arguments.
May be useful for some higher-order macros.
Added in '''version 0.2.0'''.

<enscript highlight="scheme">
;;; Recursively check if two structure have the same length,
;;; nesting, etc, while ignoring the value of the atoms.
(ck () (c-compare? '(c-true) '(1 #(2) 3) '(a #(b) c)))
;; ==> '#t
</enscript>


<syntax>(c-false X ...)  →  '#f</syntax>

Always yields {{'#f}}, regardless of its arguments.
May be useful for some higher-order macros.
Added in '''version 0.2.0'''.


<syntax>(c-if TEST PASS FAIL)  →  PASS or FAIL</syntax>

Conditional branching.
If {{TEST}} is {{'#f}}, this yields {{FAIL}}.
Otherwise it yields {{PASS}}.

Due to the way the CK machine works, both branches will be expanded,
then the unneeded branch will be discarded.
If you only want the needed branch to be expanded
(e.g. because the branches are complex and slow to expand,
or because it would be an error to expand the unneeded branch),
use {{c-if*}} instead.

Analogous to
{{(lambda (test pass fail) (if test pass fail))}}.

<enscript highlight="scheme">
(ck () (c-quote (c-if (c-pair? '(x))
                      'pair
                      'not-pair)))
;; ==> 'pair

(ck () (c-quote (c-if (c-pair? 'x)
                      'pair
                      'not-pair)))
;; ==> 'not-pair
</enscript>


<syntax>(c-if* TEST 'PASS 'FAIL)  →  PASS or FAIL</syntax>

Similar to {{c-if}}, except that the branches must have an extra level of quoting,
and only one branch will be expanded.
This is more similar to how {{if}} behaves, but it is a bit awkward to use.

Analogous to
{{(lambda (test pass fail) (if test (eval pass) (eval fail)))}}

<enscript highlight="scheme">
(ck () (c-quote (c-if* (c-pair? '(x))
                       '(c-car '(x))
                       ''not-pair))
;; ==> 'x

(ck () (c-quote (c-if* (c-pair? 'x)
                       '(c-car 'x)
                       ''not-pair))
;; ==> 'not-pair
</enscript>


<syntax>(c-or X ...)  →  item or '#f</syntax>

Yields the first argument that is not {{'#f}}.
Yields {{'#f}} if all of the arguments are {{'#f}},
or if there are no arguments.

Roughly analogous to {{or}}, except all arguments are expanded.
If you only want to expand the arguments that are needed, use {{c-or*}} instead.


<syntax>(c-or* 'X ...)  →  item or '#f</syntax>

Similar to {{c-or}}, except that all the arguments must have an extra level of quoting,
and the arguments will be expanded one at a time until a non-{{'#f}} value is found.
This is more similar to how {{or}} behaves, but it is a bit awkward to use.


<syntax>(c-and X ...)  →  item or '#f</syntax>

If all arguments are not {{'#f}}, yields the last argument.
If any of the arguments is {{'#f}}, yields {{'#f}}.
If there are no arguments, yields {{'#t}}.

Roughly analogous to {{and}}, except all arguments are expanded.
If you only want to expand the arguments that are needed, use {{c-and*}} instead.


<syntax>(c-and* X ...)  →  item or '#f</syntax>

Similar to {{c-and}}, except that all the arguments must have an extra level of quoting,
and the arguments will be expanded one at a time until a {{'#f}} value is found.
This is more similar to how {{and}} behaves, but it is a bit awkward to use.


<syntax>(c-null? X)  →  '#t or '#f</syntax>

Yields {{'#t}} if {{X}} is the empty list, {{'()}}.
Otherwise yields {{'#f}}.
Analogous to {{null?}}.


<syntax>(c-pair? X)  →  '#t or '#f</syntax>

Yields {{'#t}} if {{X}} is a dotted pair or a non-empty list.
Otherwise yields {{'#f}}.
Analogous to {{pair?}}.


<syntax>(c-not-pair? X)  →  '#t or '#f</syntax>

Opposite of {{c-pair?}}.
Analogous to {{not-pair?}} from SRFI 1.


<syntax>(c-vector? X)  →  '#t or '#f</syntax>

Yields {{'#t}} if {{X}} is a vector.
Otherwise yields {{'#f}}.
Analogous to {{vector?}}.

<enscript highlight="scheme">
(ck () (c-quote (c-vector? '#(a))))
;; ==> '#t
</enscript>


<syntax>(c-boolean? X)  →  '#t or '#f</syntax>

Yields {{'#t}} if {{X}} is either {{'#t}} or {{'#f}}.
Otherwise yields {{'#f}}.
Analogous to {{boolean?}}.


<syntax>(c-sym-eq? X Y)  →  '#t or '#f</syntax>

'''ATTENTION:''' This CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]]
that you should be aware of.
If you don't require strict R5RS portability, it is recommended to use {{c-eq?}} instead.

Yields {{'#t}} if {{X}} and {{Y}} are the same symbol, otherwise yields {{'#f}}.
{{X}} should be a symbol.
{{Y}} can be any value.
Some Scheme implementations allow {{X}} to be other types,
but this macro is only portable if {{X}} is a symbol.

Roughly analogous to {{eq?}},
except it only works (portably) with symbols.
Based on {{symbol-eq?}} from the original implementation.


<syntax>(c-sym-equal? X Y)  →  '#t or '#f</syntax>

'''ATTENTION:''' This CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]]
that you should be aware of.
If you don't require strict R5RS portability,
it is recommended to use {{c-equal?}} instead.

Similar to {{c-sym-eq?}}, except it recursively compares
pairs, lists, and vectors.

Roughly analogous to {{equal?}},
except it only works (portably) with symbols, pairs, lists, vectors,
and nested combinations of those things.


<syntax>(c-compare? '(OP ...) X Y)  →  '#t or '#f</syntax>

Recursively compares atoms, pairs, lists, or vectors,
using {{OP}} as the predicate to compare atoms.
Similar to {{equal?}} but with a custom predicate.
Added in '''version 0.2.0'''.

{{OP}} will be called with two arguments:
an atom of {{X}}, and the corresponding atom of {{Y}}.
In other words, the Nth atom of {{X}} will be compared with the Nth atom of {{Y}},
descending recursively into nested structures.
If {{X}} and {{Y}} are themselves atoms, they are compared directly with {{OP}}.

Yields {{'#f}} if {{X}} and {{Y}} have dissimilar structures (length, nesting, type),
or if {{OP}} yields {{'#f}} for any corresponding atoms of {{X}} and {{Y}}.
Otherwise yields '#t.

<enscript highlight="scheme">
(ck () (c-compare? '(c-string-ci=?) '#("a" ("b")) '#("A" ("B"))))
;; ==> #t

;;; X is a vector with a list, but Y is a list with a vector.
;;; The structures are dissimilar.
(ck () (c-compare? '(c-string-ci=?) '#("a" ("b")) '("a" #("b"))))
;; ==> #f

;;; Can use any predicate. Here, X and Y have same structure,
;;; and each atom of X is less than the correponding atom of Y.
(ck () (c-compare? '(c-<) '(1 #(5)) '(2 #(6))))
;; ==> #t

;;; Can compare atoms directly.
(ck () (c-compare? '(c-<) '1 '2))
;; ==> #t
</enscript>


==== List Processing

<syntax>(c-cons X Y)  →  '(X . Y)</syntax>

Yields a pair with the two given arguments.
Analogous to {{cons}}.

<enscript highlight="scheme">
(ck () (c-quote (c-cons 'a 'b)))
;; ==> '(a . b).

(ck () (c-quote (c-cons '+ '(1 2))))
;; ==> '(+ 1 2).

(ck () (c-quote (c-cons '+ (c-cons '1 (c-cons '2 '())))))
;; ==> '(+ 1 2).
</enscript>


<syntax>(c-xcons X Y)  →  '(Y . X)</syntax>

Like {{c-cons}}, but exchanges the order of arguments.
Analogous to {{xcons}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-xcons 'a 'b)))
;; ==> '(b . a).
</enscript>


<syntax>(c-list X ...)  →  list</syntax>

Yields a list containing the given items.
Analogous to {{list}}.

<enscript highlight="scheme">
(ck () (c-quote (c-list)))
;; ==> '()
(ck () (c-quote (c-list 'a 'b 'c)))
;; ==> '(a b c)
</enscript>


<syntax>(c-car P)  →  item</syntax>

Yields the head of the given pair.
Analogous to {{car}}.

<enscript highlight="scheme">
(ck () (c-quote (c-car '(a . b))))
;; ==> 'a

(ck () (c-quote (c-car '(a b))))
;; ==> 'a
</enscript>


<syntax>(c-cdr P)  →  tail</syntax>

Yields the tail of the given pair.
Analogous to {{cdr}}.

<enscript highlight="scheme">
(ck () (c-quote (c-cdr '(a . b))))
;; ==> 'b

(ck () (c-quote (c-cdr '(a b))))
;; ==> '(b)
</enscript>


<syntax>(c-first   L)  →  item</syntax>
<syntax>(c-second  L)  →  item</syntax>
<syntax>(c-third   L)  →  item</syntax>
<syntax>(c-fourth  L)  →  item</syntax>
<syntax>(c-fifth   L)  →  item</syntax>
<syntax>(c-sixth   L)  →  item</syntax>
<syntax>(c-seventh L)  →  item</syntax>
<syntax>(c-eighth  L)  →  item</syntax>
<syntax>(c-ninth   L)  →  item</syntax>
<syntax>(c-tenth   L)  →  item</syntax>

Yields the Nth item of the given list.
Fails if the list is too short.

Analogous to {{first}} ... {{tenth}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-first  '(a b c d e f g h i j k))))  ; ==> 'a
(ck () (c-quote (c-second '(a b c d e f g h i j k))))  ; ==> 'b
(ck () (c-quote (c-third  '(a b c d e f g h i j k))))  ; ==> 'c
;;; ...
(ck () (c-quote (c-tenth  '(a b c d e f g h i j k))))  ; ==> 'j
</enscript>


<syntax>(c-last L)  →  item</syntax>

Yields the last value of the given list.
Fails if the list is empty or is not a proper list.

Analogous to {{last}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-last '(a b c))))    ; ==> 'c
(ck () (c-quote (c-last '(a b . c))))  ; ==> ERROR!
</enscript>


<syntax>(c-last-pair L)  →  pair</syntax>

Yields the last pair of the given list.
Fails if the list is empty.

Analogous to {{last-pair}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-last-pair '(a b c))))    ; ==> '(c)
(ck () (c-quote (c-last-pair '(a b . c))))  ; ==> '(b . c)
</enscript>


<syntax>(c-drop1 L)  →  list</syntax>
<syntax>(c-drop2 L)  →  list</syntax>
<syntax>(c-drop3 L)  →  list</syntax>
<syntax>(c-drop4 L)  →  list</syntax>
<syntax>(c-drop5 L)  →  list</syntax>

Drops a predefined number of items from the front of the given list.
Fails if the list is too short.
See also {{c-udrop}}.

Analogous to {{(drop L N)}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-drop1 '(a b c d e f g))))  ; ==> '(b c d e f g)
(ck () (c-quote (c-drop2 '(a b c d e f g))))  ; ==> '(c d e f g)
(ck () (c-quote (c-drop3 '(a b c d e f g))))  ; ==> '(d e f g)
(ck () (c-quote (c-drop4 '(a b c d e f g))))  ; ==> '(e f g)
(ck () (c-quote (c-drop5 '(a b c d e f g))))  ; ==> '(f g)
</enscript>


<syntax>(c-take1 L)  →  list</syntax>
<syntax>(c-take2 L)  →  list</syntax>
<syntax>(c-take3 L)  →  list</syntax>
<syntax>(c-take4 L)  →  list</syntax>
<syntax>(c-take5 L)  →  list</syntax>

Yields a list containing a predefined number of items from the front of the given list.
Fails if the list is too short.
See also {{c-utake}}.

Analogous to {{(take L N)}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-take1 '(a b c d e f g))))  ; ==> '(a)
(ck () (c-quote (c-take2 '(a b c d e f g))))  ; ==> '(a b)
(ck () (c-quote (c-take3 '(a b c d e f g))))  ; ==> '(a b c)
(ck () (c-quote (c-take4 '(a b c d e f g))))  ; ==> '(a b c d)
(ck () (c-quote (c-take5 '(a b c d e f g))))  ; ==> '(a b c d e)
</enscript>


<syntax>(c-reverse L)  →  list</syntax>

Yields the given list in reverse order.
Fails if the list is not a proper list.
Analogous to {{reverse}}.

<enscript highlight="scheme">
(ck () (c-quote (c-reverse '(a b c))))
;; ==> '(c b a)
</enscript>


<syntax>(c-suffix L X ...)  →  list</syntax>

Yields the given list with the extra arguments added to the end.

<enscript highlight="scheme">
(ck () (c-quote (c-suffix '(a) 'b 'c)))
;; ==> '(a b c)
</enscript>


<syntax>(c-append L ...)  →  list</syntax>

Appends the given lists.
Analogous to {{append}}.

<enscript highlight="scheme">
(ck () (c-quote (c-append)))
;; ==> '()

(ck () (c-quote (c-append '(+) (c-append '(1) '(2)))))
;; ==> '(+ 1 2)

(ck () (c-quote (c-append '(define foo) '((+ 1 2)))))
;; ==> '(define foo (+ 1 2 3))
</enscript>


<syntax>(c-append-map1 '(OP ...) L)  →  list</syntax>

Yields a list by calling the quoted operation on each item in the list,
then appending the results.
The operation must be a CK-macro that yields a list.
The operation may have leading arguments.

Analogous to {{append-map}} from SFRI-1, but only accepts one list.
'''Prior to version 0.2.0''', this was named {{c-append-map}}.
This was named {{c-concatMap}} in the original implementation.

<enscript highlight="scheme">
(ck () (c-quote (c-append-map1 '(c-list 'a 'b) '(1 2))))
;; ==> '(a b 1 a b 2)
</enscript>


<syntax>(c-map1 '(OP ...) L)  →  list</syntax>

Yields a list by calling the quoted operation on each item in the given list.
The operation may have leading arguments.
Analogous to {{map}}, but only accepts one list.
(See also {{c-map2}} ... {{c-map5}} for versions that accept more lists.)
'''Prior to version 0.2.0''', this was named {{c-map}}.

<enscript highlight="scheme">
(ck () (c-quote (c-map1 '(c-cons 'a) '(1 2))))
;; ==> '((a . 1) (a . 2))
</enscript>


<syntax>(c-map2 '(OP ...) L1 L2)  →  list</syntax>
<syntax>(c-map3 '(OP ...) L1 L2 L3)  →  list</syntax>
<syntax>(c-map4 '(OP ...) L1 L2 L3 L4)  →  list</syntax>
<syntax>(c-map5 '(OP ...) L1 L2 L3 L4 L5)  →  list</syntax>

Like {{c-map1}}, but they accept exactly two, three, four, or five lists respectively.
{{OP}} must accept the two, three, four, or five extra arguments.
If the lists are different lengths, terminates when the shortest list runs out.
Analogous to {{map}} from SRFI 1, but they accept a specific number of lists.
Added in '''version 0.2.0'''.

<enscript highlight="scheme">
;; The argument '(1 2) is shortest so the result only has two items.
(ck () (c-quote (c-map3 '(c-list) '(a b c) '(1 2) '(x y z))))
;; ==> '((a 1 x) (b 2 y))
</enscript>


<syntax>(c-fold1 '(OP ...) INIT L)  →  result</syntax>

Yield a value by repeatedly calling the quoted operation
with each item from the list plus the previous result.

If the list is empty, yields {{INIT}}.
Otherwise, the operation is first called with two arguments:
the first item of the list, and INIT.
Then, the operation is repeatedly called with the next item of the list and the previous result,
until it reaches the end of the list.
Yields the final result.

Analogous to {{fold}} from SRFI 1, but only accepts one list.
'''Prior to version 0.2.0''', this was named {{c-fold}}.

<enscript highlight="scheme">
(ck () (c-quote (c-fold1 '(c-cons) '(x) '())))
;; ==> '(x)
(ck () (c-quote (c-fold1 '(c-cons) '(x) '(a b c d e f))))
;; ==> '(f e d c b a x)
</enscript>


<syntax>(c-filter '(OP ...) L)  →  list</syntax>

Yields a list by calling the quoted operation on each item in the given list,
and discarding any item for which the test yields {{'#f}}.
Analogous to {{filter}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-filter '(c-pair?)
                          '(a (b . c) 1 (d e) #t))))
;; ==> '((b . c) (d e))
</enscript>


<syntax>(c-remove '(OP ...) L)  →  list</syntax>

Opposite of {{c-filter}}.
Discards items that pass the test, keeps items that fail the test.
Analogous to {{remove}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-remove '(c-pair?)
                          '(a (b . c) 1 (d e) #t))))
;; ==> '(a 1 #t)
</enscript>


<syntax>(c-find '(OP ...) L)  →  item or '#f</syntax>

Searches the list for the first item that passes the predicate operation
(i.e. the predicate yields a non-{{'#f}} value),
then yields that item.
Yields {{'#f}} if no item passes the predicate.

Analogous to {{find}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-find '(c-pair?)
                        '(a (b . c) 1 (d e) #t))))
;; ==> '(b . c)
</enscript>


<syntax>(c-find-tail '(OP ...) L)  →  pair or '#f</syntax>

Searches the list for the first item that passes the predicate operation
(i.e. the predicate yields a non-{{'#f}} value),
then yields the tail of the list starting with that item.
Yields {{'#f}} if no item passes the predicate.

Analogous to {{find-tail}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-find-tail '(c-pair?)
                             '(a (b . c) 1 (d e) #t))))
;; ==> '((b . c) 1 (d e) #t)
</enscript>


<syntax>(c-member X L)  →  '#t or '#f</syntax>
<syntax>(c-member X L '(OP ...))  →  '#t or '#f</syntax>

'''ATTENTION:''' When using the default comparison operator,
this CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]] that you should be aware of.
If you don't require strict R5RS portability,
it is recommended to use the comparison operator {{'(c-equal?)}} instead.

Searches the list for the first occurance of {{X}},
then yields the tail of the list starting with that item.
Yields {{'#f}} if the list does not contain {{X}}.

Uses {{'(OP ...)}} for comparison,
or {{'(c-sym-equal?)}} if the operation is omitted.
So by default, {{X}} must be a symbol, list, pair, vector,
or nested combination of those things.

Same as {{(c-find-tail '(OP ... X) L)}}.
Roughly analogous to {{member}} except for the default allowed types.

<enscript highlight="scheme">
(ck () (c-quote (c-member 'b '(a b c))))
;; ==> '(b c)

(ck () (c-quote (c-member 'x '(a b c))))
;; ==> '#f

(ck () (c-quote (c-member '(a b c)
                          '((a) (x y z) (a b))
                          '(c-u=))))
;; ==> '((x y z) (a b))
;; Because (c-u= '(a b c) '(x y z)) yields '#t
</enscript>


<syntax>(c-any1 '(OP ...) L)  →  result or '#f</syntax>

Calls the operation on each value in the given list
until it finds a result that is not {{'#f}}, then yields that result.
Yields {{'#f}} if the predicate yields {{'#f}} for all items in the list,
or if the list is empty.

Analogous to {{any}} from SRFI 1, but only accepts one list.
'''Prior to version 0.2.0''', this was named {{c-any}}.

<enscript highlight="scheme">
(ck () (c-quote (c-any1 '(c-pair?) '())))
;; ==> '#f
(ck () (c-quote (c-any1 '(c-pair?) '(a b c))))
;; ==> '#f
(ck () (c-quote (c-any1 '(c-pair?) '(a (b . c)))))
;; ==> '#t

(ck () (c-quote (c-any1 '(c-cons 'z) '(a b c))))
;; ==> '(1 . a)
;; Because (c-cons 'z 'a) yields a value that is not '#f.
</enscript>


<syntax>(c-every1 '(OP ...) L)  →  result or '#f</syntax>

Calls the operation on each value in the given list
until it finds a result that is {{'#f}}, then yields {{'#f}}.
If the predicate yields a non-{{'#f}} value for every item in the list,
this yields the result of calling the predicate on the last item.
Yields {{'#t}} if the list is empty.

Analogous to {{every}} from SRFI 1, but only accepts one list.
'''Prior to version 0.2.0''', this was named {{c-every}}.

<enscript highlight="scheme">
(ck () (c-quote (c-every1 '(c-pair?) '())))
;; ==> '#t
(ck () (c-quote (c-every1 '(c-pair?) '(a (b . c)))))
;; ==> '#f
(ck () (c-quote (c-every1 '(c-pair?) '((a . b) (b . c)))))
;; ==> '#t

(ck () (c-quote (c-every1 '(c-cons 'z) '(a b c))))
;; ==> '(z . c)
;; Because all results were non-'#f and (c-cons 'z 'c) was the final operation.
</enscript>


<syntax>(c-assoc KEY ALIST)  →  pair or '#f</syntax>
<syntax>(c-assoc KEY ALIST '(OP ...))  →  pair or '#f</syntax>

'''ATTENTION:''' When using the default comparison operator,
this CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]] that you should be aware of.
If you don't require strict R5RS portability,
it is recommended to use the comparison operator {{'(c-equal?)}} instead.

Searches {{ALIST}} for the first pair whose car matches {{KEY}},
then yields that pair.
Yields {{'#f}} if no match is found.
{{ALIST}} must be an association list, i.e. a list of pairs.

Uses {{'(OP ...)}} for comparison,
or {{'(c-sym-equal?)}} if {{'(OP ...)}} is omitted.

Analogous to {{assoc}} from SRFI 1.

<enscript highlight="scheme">
(ck () (c-quote (c-assoc 'x '((a . 1) (b . 2) (a . 3)))))
;; ==> '#f
(ck () (c-quote (c-assoc 'a '((a . 1) (b . 2) (a . 3)))))
;; ==> '(a . 1)
(ck () (c-quote (c-assoc '(a) '((a . 1) (b . 2) ((a) . 3)))))
;; ==> '((a) . 3)
</enscript>


<syntax>(c-alist-delete KEY ALIST)  →  list</syntax>
<syntax>(c-alist-delete KEY ALIST '(OP ...))  →  list</syntax>

'''ATTENTION:''' When using the default comparison operator,
this CK-macro has [[#pitfalls-of-c-sym-eq|major pitfalls]] that you should be aware of.
If you don't require strict R5RS portability,
it is recommended to use the comparison operator {{'(c-equal?)}} instead.

Removes all pairs in {{ALIST}} whose car matches {{KEY}}.
{{ALIST}} must be an association list, i.e. a list of pairs.

Uses {{'(OP ...)}} for comparison,
or {{'(c-sym-equal?)}} if {{'(OP ...)}} is omitted.

Analogous to {{alist-delete}} from SRFI 1.
Based on {{c-delete-assoc}} from the original implementation.

<enscript highlight="scheme">
(ck () (c-quote (c-alist-delete 'a '((a . 1) (b . 2) (a . 3) (c . 4)))))
;; ==> '((b . 2) (c . 4)
(ck () (c-quote (c-alist-delete '(a) '((a . 1) (b . 2) ((a) . 3)))))
;; ==> '((a . 1) (b . 2))
</enscript>


==== Vector Processing

<syntax>(c-vector X ...)  →  vector</syntax>

Yields a vector containing the given items.
Analogous to {{vector}}.


<syntax>(c-list->vector L)  →  vector</syntax>

Yields a vector containing the same items as the given list.
Analogous to {{list->vector}} from SRFI 43.


<syntax>(c-vector->list V)  →  list</syntax>

Yields a list containing the same items as the given vector.
Analogous to {{vector->list}} from SRFI 43.


<syntax>(c-vector-reverse V)  →  vector</syntax>

Yields the given vector in reverse order.
Similar to {{vector-reverse-copy}} from SRFI 43,
but does not take a start or end argument.


<syntax>(c-vector-suffix V X ...)  →  vector</syntax>

Yields the given vector with the extra arguments added to the end.

<enscript highlight="scheme">
(ck () (c-quote (c-vector-suffix '#(a b) 'c 'd)))
;; ==> '#(a b c d)
</enscript>


<syntax>(c-vector-append V ...)  →  vector</syntax>

Appends the given vectors.
Analogous to {{vector-append}} from SRFI 43,
but only accepts two vectors.

<enscript highlight="scheme">
(ck () (c-quote (c-vector-append)))
;; ==> '#()

(ck () (c-quote (c-vector-append '#(a b) '#(c d) '#(e f))))
;; ==> '#(a b c d e f)
</enscript>


<syntax>(c-vector-map1 '(OP ...) V)  →  vector</syntax>

Yields a vector by calling the quoted operation on each item in the given vector.
The operation may have leading arguments.

Analogous to {{vector-map}} from SRFI 43, but only accepts one vector.
'''Prior to version 0.2.0''', this was named {{c-vector-map}}.


==== Unary Math

The CK-macros in this section perform mathematical operations by treating lists as unary numbers.
Unary math is pretty slow for large values or complex operations,
but it is interesting, portable, and maybe even useful in some cases.

Unary numbers are a way of representing non-negative integers as a list of a certain length.
For example, the list {{'(a b c d e)}} means the number 5,
and the list {{'()}} means the number 0.
The contents of the list do not matter, only the length.
Negative numbers and non-integral numbers cannot be represented in unary.


<syntax>(c-u= U1 U2)  →  '#t or '#f</syntax>

Unary equality.
Yields {{'#t}} if the two lists have the same lengths,
otherwise yields {{'#f}}.

<enscript highlight="scheme">
(ck () (c-quote (c-u= '(a b c) '(a b c))))
;; ==> '#t
(ck () (c-quote (c-u= '(1 2 3) '(a b c))))
;; ==> '#t
(ck () (c-quote (c-u= '(1 2) '(a b c))))
;; ==> '#f
</enscript>


<syntax>(c-u< U1 U2)  →  '#t or '#f</syntax>

Unary less-than.
Yields {{'#t}} if the first list is shorter than the second list,
otherwise yields {{'#f}}.

<enscript highlight="scheme">
(ck () (c-quote (c-u< '(1 2) '(a b c))))
;; ==> '#t
(ck () (c-quote (c-u< '(1 2 3) '(a b c))))
;; ==> '#f
</enscript>


<syntax>(c-u<= U1 U2)  →  '#t or '#f</syntax>

Unary less-than-or-equals.
Yields {{'#t}} if first list is the same length or shorter than the second list,
otherwise yields {{'#f}}.

<enscript highlight="scheme">
(ck () (c-quote (c-u<= '(1 2) '(a b c))))
;; ==> '#t
(ck () (c-quote (c-u<= '(1 2 3) '(a b c))))
;; ==> '#t
(ck () (c-quote (c-u<= '(1 2 3 4) '(a b c))))
;; ==> '#f
</enscript>


<syntax>(c-u> U1 U2)  →  '#t or '#f</syntax>

Unary greater-than.
Yields {{'#t}} if the first list is longer than the second list,
otherwise yields {{'#f}}.

<enscript highlight="scheme">
(ck () (c-quote (c-u> '(1 2 3 4) '(a b c))))
;; ==> '#t
(ck () (c-quote (c-u> '(1 2 3) '(a b c))))
;; ==> '#f
</enscript>


<syntax>(c-u>= U1 U2)  →  '#t or '#f</syntax>

Unary greater-than-or-equals.
Yields {{'#t}} if first list is same length or longer than the second list,
otherwise yields {{'#f}}.

<enscript highlight="scheme">
(ck () (c-quote (c-u>= '(1 2 3 4) '(a b c))))
;; ==> '#t
(ck () (c-quote (c-u>= '(1 2 3) '(a b c))))
;; ==> '#t
(ck () (c-quote (c-u>= '(1 2) '(a b c))))
;; ==> '#f
</enscript>


<syntax>(c-uzero? U)  →  '#t or '#f</syntax>

Unary {{zero?}}.
Yields {{'#t}} if the list is empty, otherwise yields {{'#f}}.
Same as {{c-null?}}.

<enscript highlight="scheme">
(ck () (c-quote (c-uzero? '())))
;; ==> '#t
(ck () (c-quote (c-uzero? '(a))))
;; ==> '#f
</enscript>


<syntax>(c-ueven? U)  →  '#t or '#f</syntax>

Unary {{even?}}.
Yields {{'#t}} if the given list's length is even
(i.e. a multiple of 2), otherwise yields {{'#f}}.

<enscript highlight="scheme">
(ck () (c-quote (c-ueven? '())))
;; ==> '#t
(ck () (c-quote (c-ueven? '(a))))
;; ==> '#f
(ck () (c-quote (c-ueven? '(a b))))
;; ==> '#t
</enscript>


<syntax>(c-uodd? U)  →  '#t or '#f</syntax>

Unary {{odd?}}.
Yields {{'#t}} if the given list's length is odd
(i.e. not a multiple of 2), otherwise yields {{'#f}}.

<enscript highlight="scheme">
(ck () (c-quote (c-uodd? '())))
;; ==> '#f
(ck () (c-quote (c-uodd? '(a))))
;; ==> '#t
(ck () (c-quote (c-uodd? '(a b))))
;; ==> '#f
</enscript>


<syntax>(c-u+ U1 U2)  →  list</syntax>

Unary addition.
Same as {{c-append}}.
This was named {{c-add}} in the original implementation.

<enscript highlight="scheme">
(ck () (c-quote (c-u+ '(a b) '(c))))
;; ==> '(a b c)
</enscript>


<syntax>(c-u- U1 U2)  →  list</syntax>

Unary subtraction.
Drops an element from the front of the first list for each element in second list,
then yields the remaining list.
Negative numbers cannot be represented in unary,
so this yields '() if the second list is equal or longer than the first.

<enscript highlight="scheme">
(ck () (c-quote (c-u- (c-list 'a 'b 'c 'd) '(x y))))
;; ==> '(c d)

(ck () (c-quote (c-u- (c-list 'a 'b) (c-list 'x 'y 'z))))
;; ==> '()
;; Because negative numbers cannot be represented in unary.
</enscript>


<syntax>(c-u* U1 U2)  →  list</syntax>

Unary multiplication.
Yields a list containing the contents of the first list,
repeated once for every item in the second list.

Based on {{c-mul}} from the original implementation,
except the symbol 'u has no special significance,
and result is made from duplicating the first list.

<enscript highlight="scheme">
(ck () (c-quote (c-u* '(a b) '(c d e))))
;; ==> '(a b a b a b)
</enscript>


<syntax>(c-u/ U1 U2)  →  list</syntax>

Unary division.
Yields a list of two unary numbers,
representing the quotient and the remainder of the division.

Given the second list has length {{N}},
the quotient will contain every {{N}}th item from the first list,
and the remainder will contain the tail of the first list.
Division by zero (empty list) is a syntax error.

<enscript highlight="scheme">
(ck () (c-quote (c-u/ '(a b c d e f g h i j k)
                      '(x y z))))
;; ==> '((g d a) (j k))
;; Because 11 / 3 = 3 with a remainder of 2.
</enscript>


<syntax>(c-ufactorial U)  →  list</syntax>

Unary factorial.
If the given list has length zero, yields the list {{'(u)}}.
If the given list has length one, yields the given list.
Otherwise, yields a list containing items of the given list repeated {{(N-1)!}} times,
where {{N}} is the length of the given list.
This was named {{c-fact}} in the original implementation.

<enscript highlight="scheme">
(ck () (c-quote (c-ufactorial '(a b c))))
;; ==> '(a b c a b c)
;; Because 3! = 6.
</enscript>


<syntax>(c-udrop L U)  →  list</syntax>

Drops up to U items from the front of the given list,
where U is a unary number.

Same as {{c-u-}}.
Analogous to {{drop}} from SRFI 1,
but uses unary numbers,
and yields empty list if the list is too short.

<enscript highlight="scheme">
(ck () (c-quote (c-udrop (c-list 'a 'b 'c 'd) '(x y))))
;; ==> '(c d)
(ck () (c-quote (c-udrop (c-list 'a 'b) (c-list 'x 'y 'z))))
;; ==> '()
</enscript>


<syntax>(c-utake L U)  →  list</syntax>

Yields a list containing up to U items from the front of the given list,
where U is a unary number.

Analogous to {{take}} from SRFI 1,
but uses unary numbers,
and yields the entire list if it is too short.

<enscript highlight="scheme">
(ck () (c-quote (c-utake '(a b c d) '(x y z))))
;; ==> '(a b c)
(ck () (c-quote (c-utake '(a b) '(x y z))))
;; ==> '(a b)
</enscript>



=== Non-portable R5RS Wrappers

These are CK-macros that wrap some R5RS procedures that are useful for building macros.
Not every R5RS procedure is provided here.
If you need other procedures, use [[#ck-wrapper|{{ck-wrapper}}]]
to create your own wrappers.

These wrappers are considered non-portable because they use ck-wrapper,
which is not portable to all R5RS Scheme implementations.
See the ck-wrapper docs for portability information.

Some R5RS procedures have portable, non-wrapper CK-macro equivalents,
which are described in the [[#portable-ck-macros|Portable CK-macros]] section, above.
For example, there is no wrapper for {{pair?}} listed below,
because {{c-pair?}} is a portable CK-macro listed above.


==== General (R5RS Wrappers)

<syntax>(c-eqv? X Y)  →  '#t or '#f</syntax>

CK-macro wrapper for {{eqv?}}.
Added in '''version 0.2.0'''.

<syntax>(c-eq? X Y)  →  '#t or '#f</syntax>

CK-macro wrapper for {{eq?}}.
Added in '''version 0.2.0'''.

<syntax>(c-equal? X Y)  →  '#t or '#f</syntax>

CK-macro wrapper for {{equal?}}.
Added in '''version 0.2.0'''.


==== Numbers and Math (R5RS Wrappers)

<syntax>(c-number? X)  →  '#t or '#f</syntax>

CK-macro wrapper for {{number?}}.
Added in '''version 0.2.0'''.

<syntax>(c-integer? X)  →  '#t or '#f</syntax>

CK-macro wrapper for {{integer?}}.
Added in '''version 0.2.0'''.

<syntax>(c-= N ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{=}} (equal).
Added in '''version 0.2.0'''.

<syntax>(c-< N ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{<}} (less than).
Added in '''version 0.2.0'''.

<syntax>(c-> N ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{>}} (greater than).
Added in '''version 0.2.0'''.

<syntax>(c-<= N ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{<=}} (less than or equal).
Added in '''version 0.2.0'''.

<syntax>(c->= N ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{>=}} (greater than or equal).
Added in '''version 0.2.0'''.

<syntax>(c-max N ...)  →  number</syntax>

CK-macro wrapper for {{max}}.
Added in '''version 0.2.0'''.

<syntax>(c-min N ...)  →  number</syntax>

CK-macro wrapper for {{min}}.
Added in '''version 0.2.0'''.

<syntax>(c-+ N ...)  →  number</syntax>

CK-macro wrapper for {{+}} (addition).
Added in '''version 0.2.0'''.

<syntax>(c-* N ...)  →  number</syntax>

CK-macro wrapper for {{*}} (multiplication).
Added in '''version 0.2.0'''.

<syntax>(c-- N ...)  →  number</syntax>

CK-macro wrapper for {{-}} (subtraction).
Added in '''version 0.2.0'''.

<syntax>(c-/ N ...)  →  number</syntax>

CK-macro wrapper for {{/}} (division).
Added in '''version 0.2.0'''.

<syntax>(c-remainder N1 N2)  →  number</syntax>

CK-macro wrapper for {{remainder}}.
Added in '''version 0.2.0'''.

<syntax>(c-floor N)  →  number</syntax>

CK-macro wrapper for {{floor}}.
Added in '''version 0.2.0'''.

<syntax>(c-round N)  →  number</syntax>

CK-macro wrapper for {{round}}.
Added in '''version 0.2.0'''.

<syntax>(c-exact->inexact N)  →  inexact number</syntax>

CK-macro wrapper for {{exact->inexact}}.
Added in '''version 0.2.0'''.

<syntax>(c-inexact->exact N)  →  exact number</syntax>

CK-macro wrapper for {{inexact->exact}}.
Added in '''version 0.2.0'''.

<syntax>(c-number->string N)  →  string</syntax>
<syntax>(c-number->string N RADIX)  →  string</syntax>

CK-macro wrapper for {{number->string}}.
Added in '''version 0.2.0'''.

<syntax>(c-string->number STR)  →  number or '#f</syntax>
<syntax>(c-string->number STR RADIX)  →  number or '#f</syntax>

CK-macro wrapper for {{string->number}}.
Added in '''version 0.2.0'''.


==== Pairs and Lists (R5RS Wrappers)

<syntax>(c-length L)  →  integer</syntax>

CK-macro wrapper for {{length}}.
Added in '''version 0.2.0'''.

<syntax>(c-list-ref L I)  →  item</syntax>

CK-macro wrapper for {{list-ref}}.
Added in '''version 0.2.0'''.


==== Symbols (R5RS Wrappers)

<syntax>(c-symbol? X)  →  '#t or '#f</syntax>

CK-macro wrapper for {{symbol?}}.
Added in '''version 0.2.0'''.

<syntax>(c-symbol->string SYM)  →  string</syntax>

CK-macro wrapper for {{symbol->string}}.
Added in '''version 0.2.0'''.

<syntax>(c-string->symbol STR)  →  symbol</syntax>

CK-macro wrapper for {{string->symbol}}.
Added in '''version 0.2.0'''.


==== Chars and Strings (R5RS Wrappers)

<syntax>(c-char? CHAR ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{char?}}.
Added in '''version 0.2.0'''.

<syntax>(c-char=? CHAR ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{char=?}}.
Added in '''version 0.2.0'''.

<syntax>(c-string? X)  →  '#t or '#f</syntax>

CK-macro wrapper for {{string?}}.
Added in '''version 0.2.0'''.

<syntax>(c-string CHAR ...)  →  string</syntax>

CK-macro wrapper for {{string}}.
Added in '''version 0.2.0'''.

<syntax>(c-string-length STR)  →  integer</syntax>

CK-macro wrapper for {{string-length}}.
Added in '''version 0.2.0'''.

<syntax>(c-string-ref STR I)  →  char</syntax>

CK-macro wrapper for {{string-ref}}.
Added in '''version 0.2.0'''.

<syntax>(c-string=? STR ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{string=?}}.
Added in '''version 0.2.0'''.

<syntax>(c-string-ci=? STR ...)  →  '#t or '#f</syntax>

CK-macro wrapper for {{string-ci=?}}.
Added in '''version 0.2.0'''.

<syntax>(c-substring STR START)  →  string</syntax>
<syntax>(c-substring STR START END)  →  string</syntax>

CK-macro wrapper for {{substring}}.
Added in '''version 0.2.0'''.

<syntax>(c-string-append STR ...)  →  string</syntax>

CK-macro wrapper for {{string-append}}.
Added in '''version 0.2.0'''.


==== Vectors (R5RS Wrappers)

<syntax>(c-vector-length V)  →  integer</syntax>

CK-macro wrapper for {{vector-length}}.
Added in '''version 0.2.0'''.

<syntax>(c-vector-ref V I)  →  item</syntax>

CK-macro wrapper for {{vector-ref}}.
Added in '''version 0.2.0'''.