@node General Utilities
@section General Utilities

Provided by the module @code{(hnh util)}.

@defmac define-syntax [stx]
Extends the default syntax from the default
@lisp
(define-syntax @r{<name>} (λ (stx) body ...))
@end lisp
To also allow
@lisp
(define-syntax (@r{<name>} stx) body ...)
@end lisp
@end defmac


@defmac when pred body ...
@defmacx unless pred body ...
Extends @var{when} and @var{unless} to return @code{'()} on the
false-case (instead of being undefined).
@end defmac


@defmac aif condition consequent alternate
@defmacx awhen condition consequent ...
Equivalent to the standard @var{if} and @var{when}@footnote{Actually
our extra specialized @var{when}}, but binds the return of
@var{condition} in the variable @var{it}.
@end defmac


@defmac for key in collection body ...
@defmacx for (key ...) in collection body ...
Syntactic sugar over @code{map}.
@example
for x in collection
    body ...
@end example
expands into
@example
(map (lambda (x) body ...) collection)
@end example

If keys are a list, an match-lambda is used instead.
@xref{Pattern Matching,,,guile}
@end defmac

@defmac let* forms body ...
Replace let* with a version that can bind from lists.
Also supports SRFI-71 (extended let-syntax for multiple values)
@lisp
(let* ([a b (values 1 2)]               ; @r{SRFI-71}
       [(c d) '(3 4)]                   ; @r{Let-list (mine)}
       [(a b . c) (cons* 1 2 3)]        ; @r{Improper list matching (mine)}
       [e 5])                           ; @r{Regular}
  (list e d c b a))
;; => (5 4 3 2 1)
@end lisp
@end defmac

@defmac print-and-return expr
Prints @var{expr}, and then returns it.
Only evaluates @var{expr} once.
@end defmac


@defun swap f
@math{swap (λ (x y) body ...) ⇔ λ (y x) body ...}
@end defun

@defmac case* clauses
Like Scheme's regular @var{case}, but evaluates each symbol before
checking against them.
@end defmac

@defmac set! key value ...
@defmacx set! key = proc ...
@defmacx set! key = (op args ...) ...
Extends @var{set!} to allow multiple forms in one, also introduces the
cases:
@lisp
(set! x = f) ⇔ (set! x (f x))
(set! x = (+ 1) ⇔ (set! x (+ x 1))
@end lisp
@end defmac

@defmac set/r! key value ...
See @var{set!}, but also returns the final value.
@end defmac

@defmac label name proc
Equivalent to
@lisp
(letrec ((name proc))
       proc)
@end lisp
@end defmac


@defun sort* items comperator [get=identity]
@defunx sort*! items comperator [get=identity]
A sort more similar to Python's. Applies @var{get} to each item before
calling @var{comperator} on them.

@var{sort*!} may modify the input list.
@end defun


@defun find-extreme items [<=<] [access=identity]
Returns 2 values, the most extreme value, as compared by @var{<} after
calling @var{access} on each element, along with the remaining values
in an undefined order.

Should be faster than @var{car+cdr} ∘ @var{sort*}.
@end defun

@defun find-min list [access=identity]
@defunx find-max list [access=identity]
See @var{find-extreme}
@end defun

@defun filter-sorted proc list
@c TODO document me
@end defun

@defun != args ...
@lisp
(define != (negate =))
@end lisp
@end defun

@defun take-to lst n
Equivalent to @var{take}, but return everything (instead of crash) if
n > (length lst).
@end defun

@defun string-take-to str n
Same as @var{take-to}, but for strings
@end defun


@defun string-first
@defunx string-last
Returns the first and last character of a string respectivly
@end defun


@defun as-symb s
Returns @code{(string->symbol s)} if @var{s} is a string, @var{s} otherwise.
@end defun

@defun enumerate lst
Returns a list of lists, where the @var{car} is the index in the list,
and the @var{cadr} is the corresponding element of the original list
@end defun


@defun unval proc [n=0]
Takes a procedure returning multiple values, and returns a function
which takes the same arguments as the original procedure, but only
returns one of the procedures. Which procedure can be sent as an
additional parameter.
@end defun


@defun flatten lst
Takes an arbitrarily nested list, and flattens it to a depth 1 list
@end defun


@defmac let-lazy forms body ...
Syntactically equivalent to a regular @var{let}, but wraps each variable
in @var{forms} in @var{delay}, while it finds each instance of that
variable in body and wraps in in @var{force}.
@end defmac


@defun map/dotted proc dotted-list
Like @var{map}, but also works for improper lists.
@end defun


@defun assq-merge a b
@c TODO
@end defun

@defun kvlist->assq
Given a flat list where each odd element (counting from 1) is a
keyword, and each even element is any value, return these as a list of
pairs of symbols and values.

@lisp
(kvlist->assq '(#:a 1 #:b "Hello"))
⇒ ((a 1)
   (b "Hello"))
@end lisp
@end defun

@defun assq-limit alist [number=1]
@c TODO document
@end defun

@defun group-by proc lst
Calls @var{proc} on each element in @var{lst}, and return a
association list which @code{(proc e)} as its keys, and all elements
which mapped to that value.
@end defun

@defun split-by lst element
Split a list into sub-lists on @var{element}
@lisp
(split-by '(0 1 2 3 4 2 5 6) 2)
⇒ ((0 1) (3 4) (5 6))
@end lisp
@end defun


@defun span-upto count predicate list
Simar to span from srfi-1, but never takes more than
@var{count} items. Can however still take less.
@example
(span-upto 2 char-numeric? (string->list "123456"))
⇒ (#\1 #\2)
⇒ (#\3 #\4 #\5 #\6)
(span-upto 2 char-numeric? (string->list "H123456"))
⇒ ()
⇒ (#\H #\1 #\2 #\3 #\4 #\5 #\6)
@end example
@end defun


@defun cross-product args ...
Returns the cross product between all given lists. Each pair will be a
list, whose indices matches the order of the inputs
@end defun

@defun string-flatten tree
@c TODO document me
@end defun

@defun intersperse item list
Inserts @var{item} between each element in @var{list}.
@end defun


@defun insert-ordered item collection [<=<]
Inserts @var{item} into @var{collection}, such that collection
remainins sorted if it was sorted beforehand.
@end defun


@defmac -> item forms ...
@defmacx ->> item forms ...
Applies each form onto item, from left to right.
A form can either by a symbol, which is the applied directly, or a
list, in which case @var{->} inserts item as the second argument
(after the operand), and @var{->>} inserts it last.
@end defmac


@defmac set (accessor object) value
@defmacx set (accessor object) = (operation args ...)
See @xref{SRFI-9 Records,,,guile}
@end defmac

@defmac set-> object (accessor value) rest ...
@defmacx set-> object (accessor = (operator args)) rest ...
Wrapper around @var{set}, but applies transformations from left to
right, similar to @var{->}.
@end defmac


@defmac and=>> value procedures ...
Chained application of @code{and=>}, so applies each procedure from
left to right, stopping when one return @code{#f}.
@end defmac

@defun downcase-symbol
Converts a symbol to lower case.
@end defun


@defun group list chunk-size
Splits @var{list} into sub-lists of size @var{chunk-size}.
Requires that @math{chunk-size|(length list)}
@end defun


@defun iterate proc until base
Repeatedly applies @var{proc} to @var{base}, until @var{until} is
satisfied.
@end defun

@defun valued-map proc lists ...
Applies a procedure which returns multiple values to each element of a
list, and returns all values returned from all procedure calls.
@example
(define (± x) (values x (- x)))
(valued-map ± '(1 2))
⇒  1
⇒ -1
⇒  2
⇒ -2
@end example
@end defun


@defun assoc-ref-all alist key
@defunx assq-ref-all alist key
@defunx assv-ref-all alist key
Equivalent to assoc-ref (and family), but works on association lists with
non-unique keys, returning all mathing records (instead of just the first).
@lisp
(assoc-ref-all '((a . 1) (b . 2) (a . 3)) 'a)
⇒ (1 3)
@end lisp
@end defun


@defun vector-last v
Returns the last element of @var{v}.
@end defun

@defun ->str any
@defunx ->string any
Converts @var{any} to a string, as per @var{display}.
@end defun

@defun ->quoted-string any
Converts @var{any} to a string, as per @var{write}.
@end defun



@defmac let-env bindings body ...
Similar to @var{let}, but sets environment variables for the code in
body. Restores the old values once we leave.
@end defmac

@defmac catch* thunk (symbol proc) ...
Macro allowing multiple exception types to be caught. Each (symbol
proc) pair expands to a regular @code{catch}, with the leftmost being
innermost.
@end defmac

@subsection UUID generation

Provided by module @code{(hnh util uuid)}.

@defun uuid-v4
Generates a UUID-v4 string.
@end defun

@defun uuid
Generates an implementation defined (but guaranteed valid) UUID.
@end defun