1239 lines
18 KiB
ReStructuredText
1239 lines
18 KiB
ReStructuredText
=======
|
|
Hy Core
|
|
=======
|
|
|
|
|
|
Core Functions
|
|
==============
|
|
|
|
.. _butlast-fn:
|
|
|
|
butlast
|
|
-------
|
|
|
|
Usage: ``(butlast coll)``
|
|
|
|
Returns an iterator of all but the last item in *coll*.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (butlast (range 10)))
|
|
[0, 1, 2, 3, 4, 5, 6, 7, 8]
|
|
|
|
=> (list (butlast [1]))
|
|
[]
|
|
|
|
=> (list (butlast []))
|
|
[]
|
|
|
|
=> (import itertools)
|
|
=> (list (take 5 (butlast (itertools.count 10))))
|
|
[10, 11, 12, 13, 14]
|
|
|
|
|
|
.. _is-coll-fn:
|
|
|
|
coll?
|
|
-----
|
|
|
|
.. versionadded:: 0.10.0
|
|
|
|
Usage: ``(coll? x)``
|
|
|
|
Returns ``True`` if *x* is iterable and not a string.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (coll? [1 2 3 4])
|
|
True
|
|
|
|
=> (coll? {"a" 1 "b" 2})
|
|
True
|
|
|
|
=> (coll? "abc")
|
|
False
|
|
|
|
|
|
cons
|
|
----
|
|
|
|
.. versionadded:: 0.10.0
|
|
|
|
Usage: ``(cons a b)``
|
|
|
|
Returns a fresh :ref:`cons cell <hycons>` with car *a* and cdr *b*.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (setv a (cons 'hd 'tl))
|
|
|
|
=> (= 'hd (car a))
|
|
True
|
|
|
|
=> (= 'tl (cdr a))
|
|
True
|
|
|
|
|
|
cons?
|
|
-----
|
|
|
|
.. versionadded:: 0.10.0
|
|
|
|
Usage: ``(cons? foo)``
|
|
|
|
Checks whether *foo* is a :ref:`cons cell <hycons>`.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (setv a (cons 'hd 'tl))
|
|
|
|
=> (cons? a)
|
|
True
|
|
|
|
=> (cons? nil)
|
|
False
|
|
|
|
=> (cons? [1 2 3])
|
|
False
|
|
|
|
.. _dec-fn:
|
|
|
|
dec
|
|
---
|
|
|
|
Usage: ``(dec x)``
|
|
|
|
Returns one less than *x*. Equivalent to ``(- x 1)``. Raises ``TypeError``
|
|
if ``(not (numeric? x))``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (dec 3)
|
|
2
|
|
|
|
=> (dec 0)
|
|
-1
|
|
|
|
=> (dec 12.3)
|
|
11.3
|
|
|
|
|
|
.. _disassemble-fn:
|
|
|
|
disassemble
|
|
-----------
|
|
|
|
.. versionadded:: 0.10.0
|
|
|
|
Usage: ``(disassemble tree &optional [codegen false])``
|
|
|
|
Dump the Python AST for given Hy *tree* to standard output. If *codegen*
|
|
is ``True``, the function prints Python code instead.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (disassemble '(print "Hello World!"))
|
|
Module(
|
|
body=[
|
|
Expr(value=Call(func=Name(id='print'), args=[Str(s='Hello World!')], keywords=[], starargs=None, kwargs=None))])
|
|
|
|
=> (disassemble '(print "Hello World!") true)
|
|
print('Hello World!')
|
|
|
|
|
|
.. _emtpy?-fn:
|
|
|
|
empty?
|
|
------
|
|
|
|
Usage: ``(empty? coll)``
|
|
|
|
Returns ``True`` if *coll* is empty. Equivalent to ``(= 0 (len coll))``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (empty? [])
|
|
True
|
|
|
|
=> (empty? "")
|
|
True
|
|
|
|
=> (empty? (, 1 2))
|
|
False
|
|
|
|
|
|
.. _every?-fn:
|
|
|
|
every?
|
|
------
|
|
|
|
.. versionadded:: 0.10.0
|
|
|
|
Usage: ``(every? pred coll)``
|
|
|
|
Returns ``True`` if ``(pred x)`` is logical true for every *x* in *coll*,
|
|
otherwise ``False``. Return ``True`` if *coll* is empty.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (every? even? [2 4 6])
|
|
True
|
|
|
|
=> (every? even? [1 3 5])
|
|
False
|
|
|
|
=> (every? even? [2 4 5])
|
|
False
|
|
|
|
=> (every? even? [])
|
|
True
|
|
|
|
|
|
.. _float?-fn:
|
|
|
|
float?
|
|
-------
|
|
|
|
Usage: ``(float? x)``
|
|
|
|
Returns ``True`` if *x* is a float.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (float? 3.2)
|
|
True
|
|
|
|
=> (float? -2)
|
|
False
|
|
|
|
|
|
.. _fraction-fn:
|
|
|
|
fraction
|
|
--------
|
|
|
|
Returns a Python object of type ``fractions.Fraction``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (fraction 1 2)
|
|
Fraction(1, 2)
|
|
|
|
Note that Hy has a built-in fraction literal that does the same thing:
|
|
|
|
.. code-block:: hy
|
|
|
|
=> 1/2
|
|
Fraction(1, 2)
|
|
|
|
|
|
.. _even?-fn:
|
|
|
|
even?
|
|
-----
|
|
|
|
Usage: ``(even? x)``
|
|
|
|
Returns ``True`` if *x* is even. Raises ``TypeError`` if
|
|
``(not (numeric? x))``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (even? 2)
|
|
True
|
|
|
|
=> (even? 13)
|
|
False
|
|
|
|
=> (even? 0)
|
|
True
|
|
|
|
|
|
.. _identity-fn:
|
|
|
|
identity
|
|
--------
|
|
|
|
Usage: ``(identity x)``
|
|
|
|
Returns the argument supplied to the function.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (identity 4)
|
|
4
|
|
|
|
=> (list (map identity [1 2 3 4]))
|
|
[1 2 3 4]
|
|
|
|
|
|
.. _inc-fn:
|
|
|
|
inc
|
|
---
|
|
|
|
Usage: ``(inc x)``
|
|
|
|
Returns one more than *x*. Equivalent to ``(+ x 1)``. Raises ``TypeError``
|
|
if ``(not (numeric? x))``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (inc 3)
|
|
4
|
|
|
|
=> (inc 0)
|
|
1
|
|
|
|
=> (inc 12.3)
|
|
13.3
|
|
|
|
|
|
.. _instance?-fn:
|
|
|
|
instance?
|
|
---------
|
|
|
|
Usage: ``(instance? class x)``
|
|
|
|
Returns ``True`` if *x* is an instance of *class*.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (instance? float 1.0)
|
|
True
|
|
|
|
=> (instance? int 7)
|
|
True
|
|
|
|
=> (instance? str (str "foo"))
|
|
True
|
|
|
|
=> (defclass TestClass [object])
|
|
=> (setv inst (TestClass))
|
|
=> (instance? TestClass inst)
|
|
True
|
|
|
|
.. _integer?-fn:
|
|
|
|
integer?
|
|
--------
|
|
|
|
Usage: ``(integer? x)``
|
|
|
|
Returns `True` if *x* is an integer. For Python 2, this is
|
|
either ``int`` or ``long``. For Python 3, this is ``int``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (integer? 3)
|
|
True
|
|
|
|
=> (integer? -2.4)
|
|
False
|
|
|
|
|
|
.. _interleave-fn:
|
|
|
|
interleave
|
|
----------
|
|
|
|
.. versionadded:: 0.10.1
|
|
|
|
Usage: ``(interleave seq1 seq2 ...)``
|
|
|
|
Returns an iterable of the first item in each of the sequences,
|
|
then the second, etc.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (interleave (range 5) (range 100 105)))
|
|
[0, 100, 1, 101, 2, 102, 3, 103, 4, 104]
|
|
|
|
=> (list (interleave (range 1000000) "abc"))
|
|
[0, 'a', 1, 'b', 2, 'c']
|
|
|
|
|
|
.. _interpose-fn:
|
|
|
|
interpose
|
|
---------
|
|
|
|
.. versionadded:: 0.10.1
|
|
|
|
Usage: ``(interpose item seq)``
|
|
|
|
Returns an iterable of the elements of the sequence separated by the item.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (interpose "!" "abcd"))
|
|
['a', '!', 'b', '!', 'c', '!', 'd']
|
|
|
|
=> (list (interpose -1 (range 5)))
|
|
[0, -1, 1, -1, 2, -1, 3, -1, 4]
|
|
|
|
|
|
.. _iterable?-fn:
|
|
|
|
iterable?
|
|
---------
|
|
|
|
Usage: ``(iterable? x)``
|
|
|
|
Returns ``True`` if *x* is iterable. Iterable objects return a new iterator
|
|
when ``(iter x)`` is called. Contrast with :ref:`iterator?-fn`.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> ;; works for strings
|
|
=> (iterable? (str "abcde"))
|
|
True
|
|
|
|
=> ;; works for lists
|
|
=> (iterable? [1 2 3 4 5])
|
|
True
|
|
|
|
=> ;; works for tuples
|
|
=> (iterable? (, 1 2 3))
|
|
True
|
|
|
|
=> ;; works for dicts
|
|
=> (iterable? {:a 1 :b 2 :c 3})
|
|
True
|
|
|
|
=> ;; works for iterators/generators
|
|
=> (iterable? (repeat 3))
|
|
True
|
|
|
|
|
|
.. _iterator?-fn:
|
|
|
|
iterator?
|
|
---------
|
|
|
|
Usage: ``(iterator? x)``
|
|
|
|
Returns ``True`` if *x* is an iterator. Iterators are objects that return
|
|
themselves as an iterator when ``(iter x)`` is called. Contrast with
|
|
:ref:`iterable?-fn`.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> ;; doesn't work for a list
|
|
=> (iterator? [1 2 3 4 5])
|
|
False
|
|
|
|
=> ;; but we can get an iter from the list
|
|
=> (iterator? (iter [1 2 3 4 5]))
|
|
True
|
|
|
|
=> ;; doesn't work for dict
|
|
=> (iterator? {:a 1 :b 2 :c 3})
|
|
False
|
|
|
|
=> ;; create an iterator from the dict
|
|
=> (iterator? (iter {:a 1 :b 2 :c 3}))
|
|
True
|
|
|
|
|
|
.. _list*-fn:
|
|
|
|
list*
|
|
-----
|
|
|
|
Usage: ``(list* head &rest tail)``
|
|
|
|
Generates a chain of nested cons cells (a dotted list) containing the
|
|
arguments. If the argument list only has one element, return it.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list* 1 2 3 4)
|
|
(1 2 3 . 4)
|
|
|
|
=> (list* 1 2 3 [4])
|
|
[1, 2, 3, 4]
|
|
|
|
=> (list* 1)
|
|
1
|
|
|
|
=> (cons? (list* 1 2 3 4))
|
|
True
|
|
|
|
.. _macroexpand-fn:
|
|
|
|
macroexpand
|
|
-----------
|
|
|
|
.. versionadded:: 0.10.0
|
|
|
|
Usage: ``(macroexpand form)``
|
|
|
|
Returns the full macro expansion of *form*.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (macroexpand '(-> (a b) (x y)))
|
|
(u'x' (u'a' u'b') u'y')
|
|
|
|
=> (macroexpand '(-> (a b) (-> (c d) (e f))))
|
|
(u'e' (u'c' (u'a' u'b') u'd') u'f')
|
|
|
|
.. _macroexpand-1-fn:
|
|
|
|
macroexpand-1
|
|
-------------
|
|
|
|
.. versionadded:: 0.10.0
|
|
|
|
Usage: ``(macroexpand-1 form)``
|
|
|
|
Returns the single step macro expansion of *form*.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (macroexpand-1 '(-> (a b) (-> (c d) (e f))))
|
|
(u'_>' (u'a' u'b') (u'c' u'd') (u'e' u'f'))
|
|
|
|
|
|
.. _merge-with-fn:
|
|
|
|
merge-with
|
|
----------
|
|
|
|
.. versionadded:: 0.10.1
|
|
|
|
Usage: ``(merge-with f &rest maps)``
|
|
|
|
Returns a map that consist of the rest of the maps joined onto first.
|
|
If a key occurs in more than one map, the mapping(s) from the latter
|
|
(left-to-right) will be combined with the mapping in the result by
|
|
calling ``(f val-in-result val-in-latter)``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (merge-with (fn [x y] (+ x y)) {"a" 10 "b" 20} {"a" 1 "c" 30})
|
|
{u'a': 11L, u'c': 30L, u'b': 20L}
|
|
|
|
|
|
.. _neg?-fn:
|
|
|
|
neg?
|
|
----
|
|
|
|
Usage: ``(neg? x)``
|
|
|
|
Returns ``True`` if *x* is less than zero. Raises ``TypeError`` if
|
|
``(not (numeric? x))``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (neg? -2)
|
|
True
|
|
|
|
=> (neg? 3)
|
|
False
|
|
|
|
=> (neg? 0)
|
|
False
|
|
|
|
|
|
.. _nil?-fn:
|
|
|
|
nil?
|
|
----
|
|
|
|
Usage: ``(nil? x)``
|
|
|
|
Returns ``True`` if *x* is ``nil`` / ``None``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (nil? nil)
|
|
True
|
|
|
|
=> (nil? None)
|
|
True
|
|
|
|
=> (nil? 0)
|
|
False
|
|
|
|
=> (setf x nil)
|
|
=> (nil? x)
|
|
True
|
|
|
|
=> ;; list.append always returns None
|
|
=> (nil? (.append [1 2 3] 4))
|
|
True
|
|
|
|
|
|
.. _none?-fn:
|
|
|
|
none?
|
|
-----
|
|
|
|
Usage: ``(none? x)``
|
|
|
|
Returns ``True`` if *x* is ``None``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (none? None)
|
|
True
|
|
|
|
=> (none? 0)
|
|
False
|
|
|
|
=> (setf x None)
|
|
=> (none? x)
|
|
True
|
|
|
|
=> ;; list.append always returns None
|
|
=> (none? (.append [1 2 3] 4))
|
|
True
|
|
|
|
|
|
.. _nth-fn:
|
|
|
|
nth
|
|
---
|
|
|
|
Usage: ``(nth coll n &optional [default nil])``
|
|
|
|
Returns the *n*-th item in a collection, counting from 0. Return the
|
|
default value, ``nil``, if out of bounds (unless specified otherwise).
|
|
Raises ``ValueError`` if *n* is negative.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (nth [1 2 4 7] 1)
|
|
2
|
|
|
|
=> (nth [1 2 4 7] 3)
|
|
7
|
|
|
|
=> (nil? (nth [1 2 4 7] 5))
|
|
True
|
|
|
|
=> (nth [1 2 4 7] 5 "default")
|
|
'default'
|
|
|
|
=> (nth (take 3 (drop 2 [1 2 3 4 5 6])) 2))
|
|
5
|
|
|
|
=> (nth [1 2 4 7] -1)
|
|
Traceback (most recent call last):
|
|
...
|
|
ValueError: Indices for islice() must be None or an integer: 0 <= x <= sys.maxsize.
|
|
|
|
|
|
.. _numeric?-fn:
|
|
|
|
numeric?
|
|
--------
|
|
|
|
Usage: ``(numeric? x)``
|
|
|
|
Returns ``True`` if *x* is a numeric, as defined in Python's
|
|
``numbers.Number`` class.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (numeric? -2)
|
|
True
|
|
|
|
=> (numeric? 3.2)
|
|
True
|
|
|
|
=> (numeric? "foo")
|
|
False
|
|
|
|
|
|
.. _odd?-fn:
|
|
|
|
odd?
|
|
----
|
|
|
|
Usage: ``(odd? x)``
|
|
|
|
Returns ``True`` if *x* is odd. Raises ``TypeError`` if
|
|
``(not (numeric? x))``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (odd? 13)
|
|
True
|
|
|
|
=> (odd? 2)
|
|
False
|
|
|
|
=> (odd? 0)
|
|
False
|
|
|
|
|
|
.. _partition-fn:
|
|
|
|
partition
|
|
---------
|
|
|
|
Usage: ``(partition n coll)``
|
|
|
|
Chunks coll into tuples of length *n*. The remainder, if any, is not included.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (partition 3 (range 10)))
|
|
[(0, 1, 2), (3, 4, 5), (6, 7, 8)]
|
|
|
|
|
|
.. _pos?-fn:
|
|
|
|
pos?
|
|
----
|
|
|
|
Usage: ``(pos? x)``
|
|
|
|
Returns ``True`` if *x* is greater than zero. Raises ``TypeError``
|
|
if ``(not (numeric? x))``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (pos? 3)
|
|
True
|
|
|
|
=> (pos? -2)
|
|
False
|
|
|
|
=> (pos? 0)
|
|
False
|
|
|
|
|
|
.. _second-fn:
|
|
|
|
second
|
|
------
|
|
|
|
Usage: ``(second coll)``
|
|
|
|
Returns the second member of *coll*. Equivalent to ``(get coll 1)``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (second [0 1 2])
|
|
1
|
|
|
|
|
|
.. _some-fn:
|
|
|
|
some
|
|
----
|
|
|
|
.. versionadded:: 0.10.0
|
|
|
|
Usage: ``(some pred coll)``
|
|
|
|
Returns the first logically-true value of ``(pred x)`` for any ``x`` in
|
|
*coll*, otherwise ``nil``. Return ``nil`` if *coll* is empty.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (some even? [2 4 6])
|
|
True
|
|
|
|
=> (nil? (some even? [1 3 5]))
|
|
True
|
|
|
|
=> (nil? (some identity [0 "" []]))
|
|
True
|
|
|
|
=> (some identity [0 "non-empty-string" []])
|
|
'non-empty-string'
|
|
|
|
=> (nil? (some even? []))
|
|
True
|
|
|
|
|
|
.. _string?-fn:
|
|
|
|
string?
|
|
-------
|
|
|
|
Usage: ``(string? x)``
|
|
|
|
Returns ``True`` if *x* is a string.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (string? "foo")
|
|
True
|
|
|
|
=> (string? -2)
|
|
False
|
|
|
|
.. _symbol?-fn:
|
|
|
|
symbol?
|
|
-------
|
|
|
|
Usage: ``(symbol? x)``
|
|
|
|
Returns ``True`` if *x* is a symbol.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (symbol? 'foo)
|
|
True
|
|
|
|
=> (symbol? '[a b c])
|
|
False
|
|
|
|
.. _zero?-fn:
|
|
|
|
zero?
|
|
-----
|
|
|
|
Usage: ``(zero? x)``
|
|
|
|
Returns ``True`` if *x* is zero.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (zero? 3)
|
|
False
|
|
|
|
=> (zero? -2)
|
|
False
|
|
|
|
=> (zero? 0)
|
|
True
|
|
|
|
|
|
Sequence Functions
|
|
==================
|
|
|
|
Sequence functions can either create or operate on a potentially
|
|
infinite sequence without requiring the sequence be fully realized in
|
|
a list or similar container. They do this by returning a Python
|
|
iterator.
|
|
|
|
We can use the canonical infinite Fibonacci number generator
|
|
as an example of how to use some of these functions.
|
|
|
|
.. code-block:: hy
|
|
|
|
(defn fib []
|
|
(setv a 0)
|
|
(setv b 1)
|
|
(while true
|
|
(yield a)
|
|
(setv (, a b) (, b (+ a b)))))
|
|
|
|
|
|
Note the ``(while true ...)`` loop. If we run this in the REPL,
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (fib)
|
|
<generator object fib at 0x101e642d0>
|
|
|
|
|
|
Calling the function only returns an iterator, but does no
|
|
work until we consume it. Trying something like this is not recommend as
|
|
the infinite loop will run until it consumes all available RAM, or
|
|
in this case until I killed it.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (fib))
|
|
[1] 91474 killed hy
|
|
|
|
|
|
To get the first 10 Fibonacci numbers, use :ref:`take-fn`. Note that
|
|
:ref:`take-fn` also returns a generator, so I create a list from it.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (take 10 (fib)))
|
|
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
|
|
|
|
|
|
To get the Fibonacci number at index 9, (starting from 0):
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (nth (fib) 9)
|
|
34
|
|
|
|
|
|
.. _cycle-fn:
|
|
|
|
cycle
|
|
-----
|
|
|
|
Usage: ``(cycle coll)``
|
|
|
|
Returns an infinite iterator of the members of coll.
|
|
|
|
.. code-block:: clj
|
|
|
|
=> (list (take 7 (cycle [1 2 3])))
|
|
[1, 2, 3, 1, 2, 3, 1]
|
|
|
|
=> (list (take 2 (cycle [1 2 3])))
|
|
[1, 2]
|
|
|
|
|
|
.. _distinct-fn:
|
|
|
|
distinct
|
|
--------
|
|
|
|
Usage: ``(distinct coll)``
|
|
|
|
Returns an iterator containing only the unique members in *coll*.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (distinct [ 1 2 3 4 3 5 2 ]))
|
|
[1, 2, 3, 4, 5]
|
|
|
|
=> (list (distinct []))
|
|
[]
|
|
|
|
=> (list (distinct (iter [ 1 2 3 4 3 5 2 ])))
|
|
[1, 2, 3, 4, 5]
|
|
|
|
|
|
.. _drop-fn:
|
|
|
|
drop
|
|
----
|
|
|
|
Usage: ``(drop n coll)``
|
|
|
|
Returns an iterator, skipping the first *n* members of *coll*.
|
|
Raises ``ValueError`` if *n* is negative.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (drop 2 [1 2 3 4 5]))
|
|
[3, 4, 5]
|
|
|
|
=> (list (drop 4 [1 2 3 4 5]))
|
|
[5]
|
|
|
|
=> (list (drop 0 [1 2 3 4 5]))
|
|
[1, 2, 3, 4, 5]
|
|
|
|
=> (list (drop 6 [1 2 3 4 5]))
|
|
[]
|
|
|
|
|
|
.. _drop-last-fn:
|
|
|
|
drop-last
|
|
---------
|
|
|
|
Usage: ``(drop-last n coll)``
|
|
|
|
Returns an iterator of all but the last *n* items in *coll*. Raises
|
|
``ValueError`` if *n* is negative.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (drop-last 5 (range 10 20)))
|
|
[10, 11, 12, 13, 14]
|
|
|
|
=> (list (drop-last 0 (range 5)))
|
|
[0, 1, 2, 3, 4]
|
|
|
|
=> (list (drop-last 100 (range 100)))
|
|
[]
|
|
|
|
=> (import itertools)
|
|
=> (list (take 5 (drop-last 100 (itertools.count 10))))
|
|
[10, 11, 12, 13, 14]
|
|
|
|
|
|
.. _drop-while-fn:
|
|
|
|
drop-while
|
|
-----------
|
|
|
|
Usage: ``(drop-while pred coll)``
|
|
|
|
Returns an iterator, skipping members of *coll* until *pred* is ``False``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (drop-while even? [2 4 7 8 9]))
|
|
[7, 8, 9]
|
|
|
|
=> (list (drop-while numeric? [1 2 3 None "a"])))
|
|
[None, u'a']
|
|
|
|
=> (list (drop-while pos? [2 4 7 8 9]))
|
|
[]
|
|
|
|
|
|
.. _filter-fn:
|
|
|
|
filter
|
|
------
|
|
|
|
Usage: ``(filter pred coll)``
|
|
|
|
Returns an iterator for all items in *coll* that pass the predicate *pred*.
|
|
|
|
See also :ref:`remove-fn`.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (filter pos? [1 2 3 -4 5 -7]))
|
|
[1, 2, 3, 5]
|
|
|
|
=> (list (filter even? [1 2 3 -4 5 -7]))
|
|
[2, -4]
|
|
|
|
.. _flatten-fn:
|
|
|
|
flatten
|
|
-------
|
|
|
|
.. versionadded:: 0.9.12
|
|
|
|
Usage: ``(flatten coll)``
|
|
|
|
Returns a single list of all the items in *coll*, by flattening all
|
|
contained lists and/or tuples.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (flatten [1 2 [3 4] 5])
|
|
[1, 2, 3, 4, 5]
|
|
|
|
=> (flatten ["foo" (, 1 2) [1 [2 3] 4] "bar"])
|
|
['foo', 1, 2, 1, 2, 3, 4, 'bar']
|
|
|
|
|
|
.. _iterate-fn:
|
|
|
|
iterate
|
|
-------
|
|
|
|
Usage: ``(iterate fn x)``
|
|
|
|
Returns an iterator of *x*, *fn(x)*, *fn(fn(x))*, etc.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (take 5 (iterate inc 5)))
|
|
[5, 6, 7, 8, 9]
|
|
|
|
=> (list (take 5 (iterate (fn [x] (* x x)) 5)))
|
|
[5, 25, 625, 390625, 152587890625]
|
|
|
|
|
|
.. _read-fn:
|
|
|
|
read
|
|
----
|
|
|
|
Usage: ``(read &optional [from-file eof])``
|
|
|
|
Reads the next Hy expression from *from-file* (defaulting to ``sys.stdin``), and
|
|
can take a single byte as EOF (defaults to an empty string). Raises ``EOFError``
|
|
if *from-file* ends before a complete expression can be parsed.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (read)
|
|
(+ 2 2)
|
|
('+' 2 2)
|
|
=> (eval (read))
|
|
(+ 2 2)
|
|
4
|
|
|
|
=> (import io)
|
|
=> (def buffer (io.StringIO "(+ 2 2)\n(- 2 1)"))
|
|
=> (eval (apply read [] {"from_file" buffer}))
|
|
4
|
|
=> (eval (apply read [] {"from_file" buffer}))
|
|
1
|
|
|
|
=> ; assuming "example.hy" contains:
|
|
=> ; (print "hello")
|
|
=> ; (print "hyfriends!")
|
|
=> (with [[f (open "example.hy")]]
|
|
... (try
|
|
... (while true
|
|
... (let [[exp (read f)]]
|
|
... (do
|
|
... (print "OHY" exp)
|
|
... (eval exp))))
|
|
... (except [e EOFError]
|
|
... (print "EOF!"))))
|
|
OHY ('print' 'hello')
|
|
hello
|
|
OHY ('print' 'hyfriends!')
|
|
hyfriends!
|
|
EOF!
|
|
|
|
read-str
|
|
--------
|
|
|
|
Usage: ``(read-str "string")``
|
|
|
|
This is essentially a wrapper around `read` which reads expressions from a
|
|
string:
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (read-str "(print 1)")
|
|
(u'print' 1L)
|
|
=> (eval (read-str "(print 1)"))
|
|
1
|
|
=>
|
|
|
|
.. _remove-fn:
|
|
|
|
remove
|
|
------
|
|
|
|
Usage: ``(remove pred coll)``
|
|
|
|
Returns an iterator from *coll* with elements that pass the
|
|
predicate, *pred*, removed.
|
|
|
|
See also :ref:`filter-fn`.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (remove odd? [1 2 3 4 5 6 7]))
|
|
[2, 4, 6]
|
|
|
|
=> (list (remove pos? [1 2 3 4 5 6 7]))
|
|
[]
|
|
|
|
=> (list (remove neg? [1 2 3 4 5 6 7]))
|
|
[1, 2, 3, 4, 5, 6, 7]
|
|
|
|
|
|
|
|
.. _repeat-fn:
|
|
|
|
repeat
|
|
------
|
|
|
|
Usage: ``(repeat x)``
|
|
|
|
Returns an iterator (infinite) of ``x``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (take 6 (repeat "s")))
|
|
[u's', u's', u's', u's', u's', u's']
|
|
|
|
|
|
.. _repeatedly-fn:
|
|
|
|
repeatedly
|
|
----------
|
|
|
|
Usage: ``(repeatedly fn)``
|
|
|
|
Returns an iterator by calling *fn* repeatedly.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (import [random [randint]])
|
|
|
|
=> (list (take 5 (repeatedly (fn [] (randint 0 10)))))
|
|
[6, 2, 0, 6, 7]
|
|
|
|
|
|
.. _take-fn:
|
|
|
|
take
|
|
----
|
|
|
|
Usage: ``(take n coll)``
|
|
|
|
Returns an iterator containing the first *n* members of *coll*.
|
|
Raises ``ValueError`` if *n* is negative.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (take 3 [1 2 3 4 5]))
|
|
[1, 2, 3]
|
|
|
|
=> (list (take 4 (repeat "s")))
|
|
[u's', u's', u's', u's']
|
|
|
|
=> (list (take 0 (repeat "s")))
|
|
[]
|
|
|
|
.. _take-nth-fn:
|
|
|
|
take-nth
|
|
--------
|
|
|
|
Usage: ``(take-nth n coll)``
|
|
|
|
Returns an iterator containing every *n*-th member of *coll*.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (take-nth 2 [1 2 3 4 5 6 7]))
|
|
[1, 3, 5, 7]
|
|
|
|
=> (list (take-nth 3 [1 2 3 4 5 6 7]))
|
|
[1, 4, 7]
|
|
|
|
=> (list (take-nth 4 [1 2 3 4 5 6 7]))
|
|
[1, 5]
|
|
|
|
=> (list (take-nth 10 [1 2 3 4 5 6 7]))
|
|
[1]
|
|
|
|
|
|
.. _take-while-fn:
|
|
|
|
take-while
|
|
----------
|
|
|
|
Usage: ``(take-while pred coll)``
|
|
|
|
Returns an iterator from *coll* as long as *pred* returns ``True``.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (list (take-while pos? [ 1 2 3 -4 5]))
|
|
[1, 2, 3]
|
|
|
|
=> (list (take-while neg? [ -4 -3 1 2 5]))
|
|
[-4, -3]
|
|
|
|
=> (list (take-while neg? [ 1 2 3 -4 5]))
|
|
[]
|
|
|
|
.. _zipwith-fn:
|
|
|
|
zipwith
|
|
-------
|
|
|
|
.. versionadded:: 0.9.13
|
|
|
|
Usage: ``(zipwith fn coll ...)``
|
|
|
|
Equivalent to ``zip``, but uses a multi-argument function instead of creating
|
|
a tuple. If ``zipwith`` is called with N collections, then *fn* must accept
|
|
N arguments.
|
|
|
|
.. code-block:: hy
|
|
|
|
=> (import operator)
|
|
=> (list (zipwith operator.add [1 2 3] [4 5 6]))
|
|
[5, 7, 9]
|