README.md

DC-ECLECTIC Reference

Table of Contents

• 1 Overview
• 2 Installation
• 3 Functions and Macros
• 4 Special Variables

[in package DC-ECLECTIC]

A collection of eclectic, battle-tested Common Lisp utilities for everyday programming tasks.

1 Overview

dc-eclectic provides a grab-bag of high-quality utility functions for file operations, string manipulation, hashing, random generation, list processing, path handling, and more. These functions are designed to be practical, performant, and easy to use.

2 Installation

With Rowswell

ros install macnod/dc-eclectic/{release}

where {release} looks like vX.XX. You can find the latest release in the repo.

With QuickLisp

Clone the repo to a directory that is visible to ASDF, such as ~/common-lisp, then, in a REPL, do (ql:quickload :dc-eclectic).

3 Functions and Macros

Alphabetical list of functions and macros that DC-UTILITIES defines.

• [function] ALL-PERMUTATIONS LIST

  Returns a list of every permutation of elements in LIST. For example: '(1 2 3) -> '((1 2 3) (1 3 2) (2 1 3) (2 3 1) (3 1 2) (3 2 1))

• [function] ALL-PERMUTATIONS-OF-STRING S

  Returns a list of strings representing every permutation of the orginal string S. For example: "abc" -> '("abc" "acb" "bac" "bca" "cab" "cba")

• [function] ASCII-ALPHA

  Return a string with all the alphabetic ASCII characters.

• [function] ASCII-ALPHA-LOWER

  Returns a string with all the lower-case alphabetic ASCII characters (a-z).

• [function] ASCII-ALPHA-NUM

  Returns a string with all the alpha-numeric ASCII characters.

• [function] ASCII-ALPHA-NUM-LOWER

  Returns a string with all the lower-case alpha-numeric ASCII characters.

• [function] ASCII-ALPHA-NUM-UPPER

  Returns a string with all the upper-case alpha-numeric ASCII characters.

• [function] ASCII-ALPHA-UPPER

  Returns a string with all the upper-case alphabetic ASCII characters (A-Z).

• [function] ASCII-CHAR-RANGE BEGIN END

  Returns a string that includes ASCII characters in the ASCII code range given by BEGIN and END.

• [function] ASCII-NUMERIC

  Returns a string with all the ASCII characters that represent digits.

• [function] BASE64-DECODE BASE64-ENCODED-STRING

  Decodes BASE64-ENCODED-STRING and returns the result. This function is compatible with base64-encode and with popular implementation of base64 encoding and decoding functions. However, this function doesn't properly handle multi-byte characters. Unless you require compatibility with external functions, use the other decoding functions in DC-ECLECTIC. See SAFE-ENCODE, SAFE-DECODE, and DEFINE-BASE-ENCODER.

• [function] BASE64-ENCODE STRING

  Returns a base64-encoded version of STRING that that works list like the standard base64-encode implementations in the Linux command line and Emacs Lisp. These do not properly handle multibyte characters, so use this function only if you need compatibility with popular implementations. DC-ECLECTIC contains better encoding and decoding functions. See SAFE-ENCODE, SAFE-DECODE, and DEFINE-BASE-ENCODER.

• [function] CHOOSE-ONE SEQ &OPTIONAL RSTATE

  Returns a random element from SEQ.

• [function] CHOOSE-SOME SEQ N &OPTIONAL RSTATE

  Choose N elements from SEQ and return a new sequence with those elements, with the new sequence having the same type as SEQ.

  N must be an integer that is greater than or equal to 1.

  If N is greater than the length of SEQ, this function returns a copy of SEQ.

  If N is less than 1, then this function returns nil, even if the sequence is not a list.

  This function uses the RANDOM function, which accepts an optional RSTATE parameter that you can optionally pass in here.

• [function] COMPARABLE-HASH-DUMP HASH &KEY (F-SORT #'STRING<) (F-MAKE-SORTABLE (LAMBDA (K) (FORMAT NIL "~a" K))) FLAT

  Turns the given hash table into a list of pairs or, if FLAT is T, into a plist that represents the hash. In the resulting list, the keys are sorted, so that the list can be more easily compared with other lists. HASH is the hash you want to dump. F-SORT is the sort predicate, which defaults to sorting strings in ascending order. F-MAKE-SORTABLE is a function that accepts a key and returns a sortable version of the key. This defaults to turning the key into a string. If the keys to the hash are integers, for example, you can provide an F-SORT of #'<, which sorts integers numerically in ascending order, and you can provide an F-MAKE-SORTABLE of #'identity, which will leave the keys as integers for sorting purposes.

• [function] COPY-FILE SOURCE DESTINATION &KEY (IF-EXISTS :SUPERSEDE) (BUFFER-SIZE (* 64 1024))

  Copies SOURCE file to DESTINATION file. If DESTINATION's directories do not exist, they are created. IF-EXISTS controls the behavior if DESTINATION already exists, and may be :error, :new-version, :rename, :rename-and-delete, :overwrite, :append, or :supersede. IF-EXISTS defaults to :supersede. BUFFER-SIZE controls the size of the buffer used during the copy operation, and defaults to 64 KB. Returns the DESTINATION path.

• [function] DEEP-COPY THING

  Deep copy THING, recursively copying lists, vectors, and strings.

• [macro] DEFINE-BASE-ENCODER NAME ALPHABET

  Creates 2 functions using NAME (a symbol), and ALPHABET (a string): {NAME}-ENCODE and {NAME-DECODE}. {NAME}-ENCODE takes 1 parameter, DATA (a string), and returns the string encoded with ALPHABET. {NAME}-DECODE accepts a single parameter (an encoded string) and returns the original strinng. For example, if you need to encode strings using hexadecimal characters, you can call this function as follows:

    (define-base-encoder hex "0123456789abcdef")
  

  That will produce the functions HEX-ENCODE and HEX-DECODE. Those function will work as follows:

    (hex-encode "Hello World!")             ;; => "48656c6c6f20576f726c6421"
    (hex-decode "48656c6c6f20576f726c6421") ;; => "Hello World!"
  

• [function] DENORMALIZE-LIST LIST MIN MAX &KEY INTEGER

  Returns a new list with the numbers in LIST, which are floating-point numbers between 0 and 1, expanded to the range MAX - MIN, such that the number 1.0 is converted to MAX, the number 0.0 is converted to MIN, and all the other numbers fall in the range MIN to MAX. INTEGER is T, the new list contains integers. Otherwise, the new list contains floating-point numbers.

• [function] DIRECTORY-EXISTS-P PATH

  Returns a boolean value indicating if the directory specified by PATH exists.

• [function] DISTINCT-ELEMENTS SEQUENCE &KEY (KEY #'IDENTITY)

  Accepts a sequence of elements (list or vector) and returns a new sequence of the same type with distinct elements from the original. If the elements in the sequence are hash tables, plists, or objects with methods, then you can provide a value or function for the :key parameter. If you provide a value, the function will use the value as the key of the element, and the value of the key will represent the unique signature of the element. If you provide a function, then the function will be applied to the element to compute the elements unique signature.

• [function] DISTINCT-STRINGS LIST

  Alternative for returning a list of distinct strings.

• [function] DISTINCT-VALUES LIST

  Synonym for DISTINCT-ELEMENTS.

• [function] ENDS-WITH S SUFFIX

  Returns T if string S ends with SUFFIX.

• [generic-function] EXCLUDE REFERENCE-LIST EXCLUDE

  Returns a list containing the elements of REFERENCE-LIST that are not in EXCLUDE. If EXCLUDE is a list, this function excludes all elements in EXCLUDE from REFERENCE-LIST. If EXCLUDE is a string, this function excludes the string from REFERENCE-LIST

• [function] EXCLUDE-REGEX REFERENCE-LIST EXCLUDE &OPTIONAL EXCEPTIONS

  Returns a list of the elements of REFERENCE-LIST that that don't match the EXCLUDE regular expression. However, elements that are not in EXCEPTIONS are not excluded, even if they match EXCLUDE.

• [function] EXISTING-N-GRAM-STRINGS CHARS COUNT HASH

  Returns all the COUNT n-grams for string CHARS, but only of n-grams that exist as keys in HASH.

• [function] EXISTING-PERMUTATIONS-OF-STRING S HASH

  Works just like all-permutations-of-string, but excludes any permutations of S that are not among the keys in HASH.

• [function] FILE-EXISTS-P PATH

  Returns a boolean value indicating if the file specified by PATH exists.

• [function] FILE-EXTENSION PATH

  Returns a string consisting of the file extension for the file name given in PATH.

• [function] FILENAME-ONLY FILENAME

  Retrieves the filename (filename only, without the path) of FILENAME.

• [function] FLATTEN L

  Given a nested list L, return a flat list. If an array or other sequence is among the elements of L, the sequence is not flattened, but treated as a single element.

• [function] FREEZE OBJECT

  Stringifies OBJECT.

• [function] GETENV NAME &KEY DEFAULT REQUIRED (TYPE :STRING)

  Get the value of the environment variable NAME, returning a string or an integer, depending on TYPE. If the environment variable is not set, then return DEFAULT, which must be of type TYPE. If the environment variable is not set and DEFAULT is NIL, then this function returns NIL.

  TYPE can be :integer, :string, or :boolean.

• [generic-function] HAS REFERENCE-LIST THING

  Returns T if REFERENCE-LIST contains THING. If THING is a string, number, or symbol (including keywords), this function checks for that item in REFERENCE-LIST. If THING is a list, this function checks that all elements of THING are in REFERENCE-LIST.

• [function] HAS-SOME REFERENCE-LIST QUERY-LIST

  Returns T if REFERENCE-LIST contains any of the elements in QUERY-LIST.

• [function] HASH-HMAC-256 SECRET TEXT

  Hash TEXT using SECRET and hmac-sha-256 and return a hex representation of the hash

• [function] HASH-KEYS HASH

  Returns a list of the keys in hash table HASH.

• [function] HASH-STRING STRING &KEY (SALT "") (SIZE 128)

  Hash STRING and return a hex representation of the hash

• [function] HASH-VALUES HASH

  Returns a list of the values in hash table HASH.

• [function] HASHIFY-LIST LIST &KEY (METHOD :COUNT) F-KEY HASH-KEY PLIST-KEY ALIST-KEY (F-VALUE (LAMBDA (KEY-RAW KEY-CLEAN VALUE) (DECLARE (IGNORE KEY-RAW KEY-CLEAN)) VALUE)) (INITIAL-VALUE 0)

  Creates a hash table from LIST and returns the hash table, according to METHOD. Supported methods are :COUNT, :PLIST, :ALIST, :INDEX, AND(0 1) :CUSTOM.

  :COUNT

    With the :COUNT method, which the function uses by default, the function
    creates a hash table in which each key is an item of the list and the
    associated value for each key is the incidence of the item in the list. For
    example:
    
    (hashify-list '(7 8 7 7 8 9))
    
    gives you a hash table that looks like this:
    
    {7: 3, 8: 2, 9: 1}
  

  :ALIST and :PLIST

    The :ALIST and :PLIST methods convert the list into a hash that conceptually
    represent the same map as the list. Alists and plists both consist of
    collections of key/value pairs. Alists look like this:
    
    '((key1 . value1) (key2 . value2) (key3 . value3)...)
    
    Plists look like this:
    
    '(:key1 value1 :key2 value2 :key3 value3 ...)
    
    If a key repeats in one of these lists, its value simply overwrites the
    value of the repeated key. However, you can change that behavior. See the
    description of the :CUSTOM method for information on how to do that.
  

  :INDEX

    The :index method causes the values in the list to become the keys in the
    hash table. The value associated with each key should be an increasing
    integer, starting with 0. Thus, the list '(a b c) becomes the hash {a: 1, b:
    2, c: 3}.
    
    If the objects in the list that you're indexing are hash tables, then you
    can specify the object key for the value that the function should use as a
    key in the resulting hash. That object key should be present in every object
    in the list. This allows you to index a list of hash tables by some specific
    value in the hash table. Consider the following example:
    
    [
      {id: "a-001", first: "john", last: "doe"},
      {id: "a-002", first: "jane", last: "doe"}
    ]
    
    If you specify :method :index :hash-key "id", this function will
    create a hash table that looks like this:
    
    {
      "a-001": {id: "a-001", first: "john", last: "doe"},
      "a-002": {id: "a-002", first: "jane", last: "doe"}
    }
    
    And, voilá, you no longer need to iterate through a list to find your
    object.
    
    If the objects are plists, and you specify the index with plist-key, you'll
    see the same behavior with the plist as we demonstrated above for hash
    tables.
    
    HASH-KEY and PLIST-KEY are just shortcuts to save you from having to write
    some code for F-KEY. You can specify only one of HASH-KEY, PLIST-KEY, and
    F-KEY.
  

  :CUSTOM

    The :CUSTOM method requires that you provide functions for computing the
    keys and values that the function inserts into the resulting hash.
    
    Use F-KEY to provide a function that accepts an element from LIST and
    returns a computed hash key. Here are some examples F-KEY of acceptable
    definitions:
    
        - #'identity
        - #'string-upcase
        - (lambda (x) (zerop (mod x 10)))
    
    Use F-VALUE to provide a function that accepts an element from LIST, the
    computed key (which might be different from the element), and the value
    that's currently associated with the computed key in the resulting hash
    table. Here are some examples:
    
        - (lambda (element computed-key value)
            (declare (ignore element computed-key))
            value)
        - (lambda (element computed-key value)
            (declare (ignore element value))
            (incf value))
    
    If there's no hash value associated with the computed key, then the value
    specified by :INITIAL-VALUE is used.
  

• [generic-function] INDEX-OF-MAX LIST-OR-VECTOR

  Returns the index of the largest number in LIST-OR-VECTOR.

• [function] JOIN-PATHS &REST PATH-PARTS

  Joins parameters (collected in PATH-PARTS) into a unix-like file path, inserting slashes where necessary. PATH-PARTS can be strings or pathnames. If the first element in PATH-PARTS starts with a slash, the resulting path will be absolute; otherwise, it will be relative. If the last element of PATH-PARTS ends in a slash, the resulting path will also end in a slash. PATH-PARTS elements should be strings or pathnames, but this function will try to convert other types to strings, if possible. NIL or empty strings are ignored.

• [function] MAKE-KEYWORD S

  Returns a keyword form of the string S. Examples:

  hello world      => :HELLO-WORLD
  -hello--world--- => :HELLO-WORLD
  hello__world     => :HELLO-WORLD
  

• [function] N-GRAM-STRINGS CHARS COUNT

  Accepts CHARS, a string, and COUNT, an integer, and returns all the possible combinations of length COUNT of the characters in CHARS. For example, (n-gram-strings "abc" 2) => '("aa" "ab" "ac" "ba" "bb" "bc" "ca" "cb" "cc")

• [function] N-GRAMS LIST COUNT

  Returns n-gram lists of length COUNT using elements of LIST.

• [function] NORMALIZE-LIST LIST &KEY MAX MIN

  Returns a new list with new values between 0.0 and 1.0. MAX is the largest value that LIST can hold, and MIN is the smallest. Each new value N is computed from the corresponding old value O in LIST, as follows:

  N = (O - MIN) / (MAX - MIN)

  If you don't provide MAX and MIN, this function does an initial pass through list where it sets MAX and MIN to the largest number and the smallest number in LIST, respectively. Therefore, you can improve the performance of this function if you already know those values. Furthermore, in some cases the list may not even contain the values for MAX and MIN that you need.

• [function] PATH-LEAF-ONLY PATH

  Returns the last part of the directory PATH. For example, /home/one/two => two. If PATH is /, this function returns /.

• [function] PATH-ONLY FILENAME

  Retrieves the path (path only, without the filename) of FILENAME. FILENAME should be a string, a pathname, or NIL. If FILENAME is NIL or the empty string, this function returns the empty string. If FILENAME has no path component, this function returns "/".

• [function] PATH-PARENT PATH

  Returns the absolute path to the directory that is the parent of PATH. PATH must be an absolute path. If PATH points to a file, then this returns the path to the file, minus the file name. If PATH points to a directory, this returns the parent of the directory in PATH. If PATH points to a directory, it must end in /. If PATH is / or not an absolute path, this function returns NIL.

• [function] PATH-TYPE PATH

  Returns :FILE, :DIRECTORY, or :NOT-FOUND, depending on what PATH points to.

• [function] PLIST-KEYS PLIST

  Returns a list of the keys in PLIST.

• [function] PLIST-VALUES PLIST

  Returns a list of the values in PLIST.

• [function] PLISTP THING

  Returns T if THING is a plist.

• [function] PLURAL WORD

  Convert singular to plural form (works most of the time). Return value is always in lower case.

• [function] RAND VALUE &OPTIONAL RSTATE

  Returns a random number below VALUE. With RSTATE, draws from that random state. Without it, draws from default-rstate, which is lazily seeded from the OS on first use (per-process randomness; not the global random-state).

• [function] RANDOM-HEX-NUMBER &OPTIONAL (DIGITS 7) (NON-ZERO-START) RSTATE

  Returns a random hexadecimal number with DIGITS digits. If NON-ZERO-START is specified, then the resulting hexadecimal number starts with a character other than 0.

• [function] RANDOM-NUMBER &OPTIONAL (DIGITS 4) RSTATE

  Returns a random integer of DIGITS digits.

• [function] RANDOM-STRING STRING-LENGTH ALPHABET &OPTIONAL RSTATE

  Returns a random string of length STRING-LENGTH. The string is constructed from characters in ALPHABET. ALPHABET is a string. There are several functions available for building ALPHABET, all starting with the prefix 'ASCII-'. For example:

  (random-string 10 (ascii-alpha-num-lower))
  

• [function] RANGE START END &KEY (STEP 1) (FILTER #'IDENTITY) SHUFFLE

  Returns a list of values between START and END (inclusive), skipping values by STEP, filtering remaining values with the function in FILTER, and shuffling the remaining values if SHUFFLE is true. STEP defaults to 1, FILTER defaults to allowing all values through, and SHUFFLE default to nil.

• [function] REPLACE-EXTENSION FILENAME NEW-EXTENSION

  Replaces the file extension in FILENAME with the file extension provided in NEW-EXTENSION.

• [function] ROOT-PATH FILES

  Given FILES, a list of paths in the form of strings, returns the starting path that all the paths have in common.

• [function] SAFE-DECODE DATA

  Decodes DATA using the SAFE alphabet.

• [function] SAFE-ENCODE DATA

  Encodes data using the SAFE alphabet.

• [function] SAFE-SORT LIST &KEY PREDICATE

  Returns a sorted copy of LIST, without modifying LIST. If PREDICATE is not provided, the function determines the type of the first element of the list to pick a suitable sort predicate. The function assumes that all the elements in LIST are of the same type and that they are either strings, keywords, or numbers. The function sorts in ascending order by default. If PREDICATE is provided, then the function uses that predicate.

• [function] SETENV NAME VALUE

  Set environment variable NAME to VALUE. VALUE is always converted into a string. Returns a string with VALUE.

• [function] SHELL-COMMAND-BACKGROUND COMMAND &KEY (WAIT-INTERVAL 0.1)

  Run COMMAND in the background. Returns a process-info plist with keys: :pid, :exit-code (nil if running), :output, :error-output, :running-p, :wait-interval (for polling), :status.

  Returns an INFO object that you can use later to check on the backgrounded process. Use (SHELL-COMMAND-RUNNING-P INFO), (SHELL-COMMAND-WAIT INFO), (SHELL-COMMAND-EXIT-CODE INFO) to check status.

• [function] SHELL-COMMAND-RUNNING-P INFO

  Returns T if the background process is still running. INFO is the object that SHELL-COMMAND-BACKGROUND returns when it starts the process.

• [function] SHELL-COMMAND-TO-STRING COMMAND

  Executes COMMAND in the shell and returns the output as a string.

• [function] SHELL-COMMAND-WAIT INFO &OPTIONAL TIMEOUT

  Wait for process to finish (with optional TIMEOUT seconds). INFO is the object that SHELL-COMMAND-BACKGROUND returns when Updates INFO with output and exit code. Returns updated INFO. If TIMEOUT is ommitted or NIL, waits until the process finishes, which might be forever if the process is a server process, for example. If TIMEOUT is provided and the process does not finish within TIMEOUT seconds, the process is terminated. When the process terminates normally, INFO is updated with :status :completed, the exit code, and the output and error-output strings. When the process is terminated due a timeout, INFO is updated with :status :terminated, and the exit code, but output and error-output are left NIL.

• [function] SHUFFLE SEQ &OPTIONAL RSTATE

  Return a sequence with the same elements as the given sequence S, but in random order (shuffled).

• [function] SINGULAR WORD

  Convert plural to singular form (works most of the time). Return value is always in lower case.

• [function] SLURP FILENAME

  Returns a string with the content of the file at FILENAME.

• [function] SPEW STRING FILENAME

  Write STRING to filename, creating the file if necessary, and replacing the contents of the file if the file already exists.

• [function] SPLIT-N-TRIM STRING &KEY (ON-REGEX "\\s+") (FAT "^\\s+|\\s+$")

  Splits STRING into substrings on ON-REGEX, then trims FAT from each substring. The ON-REGEX parameter value, which is optional, defaults to "\s+", which is to say that the string is split into a list of words at the whitespace boundaries. The default value for FAT, which is also optional, "\s+|\s+$", causes this function to trim whitespace from the beggining and end of each substring. Here's an example:

    (split-n-trim "Hello  beautiful      world!")
    
    => '("Hello" "beautiful" "world!")
  

• [function] STARTS-WITH S PREFIX

  Returns T if string S starts with PREFIX.

• [function] THAW STRING

  Returns an object resulting from the evalation of STRING. This is the opposite of FREEZE.

• [function] TO-ASCII STRING &KEY (REPLACEMENT-CHAR #\?) (PRINTABLE-ONLY T)

  In STRING, replaces non-ASCII characters with REPLACEMENT_CHAR, which defaults to the question mark. If PRINTABLE-ONLY is true, only printable ASCII characters are kept, with the rest being replaced by REPLACEMENT-CHAR.

• [function] TREE-COL TREE &REST PATH

  Treat all the elements in PATH minus the last element as the node path and treats the last element of PATH as the column key. The node path should lead to a node that consists of a list of plists. This list can be NIL. This function locates the node given by the node path and retrieves the values associated with the column key from the plists in the node, returning those values ina list. For example, if PATH is '(:a :b :c), and the node at path '(:a :b) is a list of plists, this function returns a list consiting of the value associated with :c in every plist at '(:a :b). If the node at the node path does not exist, this function returns nil. If a node at the node path exists and is not a plist (nil counts as a plist), then this function signals an error.

• [function] TREE-GET TREE &REST PATH

  Get value from the TREE structure, at PATH. TREE is a nested data structure where each value can be a plist, list, object, t, or nil.

• [macro] TREE-PUT VALUE TREE &REST PATH

  Set VALUE at the location specified by PATH in the TREE structure. Expands into a series of getf and nth calls for efficient access.

• [function] TRIM S &OPTIONAL (FAT "^\\s+|\\s+$")

  Trim FAT from the string in S. The FAT parameter is optional and defaults to "^\s+|\s+$", which means "Whitespace at the beginning or end of the string".

• [function] TRIM-WHITESPACE S

  Trim Whitespace from the beginning and end of S.

• [function] UUID &OPTIONAL RSTATE

  Returns a random UUID string.

• [function] VERIFY-STRING STRING REGEX &KEY IGNORE-CASE

  Return t if STRING matches the REGEX exactly. Use the IGNORE-CASE parameter if you want case-insensitve matches.

• [function] ZIP &REST LISTS

  Returns a new list with elements from the multiple lists in LISTS merged. Each list in LISTS can be of any size. This function picks the first element from each list and adds it to the result, then picks the second element of each list, and adds it to the result, and so on. If any list runs out of elements, the function continues performing the same operation with the lists that still have elements left. This function does not alter the original lists. Examples:

  (zip '(1 4 7) '(2 5 8) '(3 6 9 10)) ;; => '(1 2 3 4 5 6 7 8 9 10)

4 Special Variables

Exported special variables.

• [variable] *ALPHABET-ALPHANUM* "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"

  Alphabet with all ASCII letters and numbers.

• [variable] *ALPHABET-BITCOIN* "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"

  Bitcoin alphabet. No zero, no capital 'o' or 'i', and now lowercase 'l'.

• [variable] *ALPHABET-ALPHANUM-UPPER* "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"

  Alphabet with uppercase letters and numbers.

• [variable] *DEFAULT-RSTATE* NIL

  Shared random state for the random generators and uuid when no RSTATE is passed. Lazily seeded from the OS on first use; nil until then. Bind to (reference-random-state) for deterministic output.