uncomplicate.commons.utils — uncomplicate/commons 0.16.1

Assorted utility functions used across Uncomplicate projects.

For converting keyword options to integers, use mask, unmask, and unmask1.

For converting C-style error as returned numbers to exceptions, use with-check and dragan-says-ex.

A few assorted functions: enc-keyword, cond-into.

When working with ByteBuffers, enlist the following functions for help: direct-buffer, slice-buffer, capacity, put-float! get-float put-double! get-double put-long! get-long put-int! get-int put-short! get-short put-byte! get-byte

When mapping files to direct buffers, these functions can help. mapped-buffer, reverse-short-bytes!, reverse-long-bytes!

The following functions are useful when working with Java file channels. [[dev-open-option]], channel random-access

Sometimes we need a pseudo-random number for kick-starting a random number generator. generate-secure-seed, generate-seed

And we may need to count groups of items in a larger group. count-groups

capacity clj

(capacity b)

Returns the capacity of a byte buffer.

channel clj

(channel file)

(channel p options)

Creates a file channel

cond-into clj

(cond-into x & s)

Puts all even arguments into collection x, given that the previous argument was not nil or false.

count-groups clj

(count-groups per-group items)

Calculates the number of groups of certain size in the total number of items.

create-temp-dir clj

(create-temp-dir prefix)

Creates a temp directory appropriate for the operating system, prefixed with 'uncomplicate_.

dec-open-option clj

(dec-open-option option)

Decode keywords to StandardOpenOption's

delete clj

(delete path)

Deletes the path, if it exists.

direct-buffer clj

(direct-buffer size)

Allocates a direct buffer with native byte order.

dragan-says-ex clj

(dragan-says-ex message)

(dragan-says-ex message data)

Throws and ex-info with an explanation and a tip towards a solution.

enc-keyword clj

(enc-keyword kw-map kw)

Given a hash-map and a key, returns the appropriate value, or throws an exception with the listing of available keys.

generate-secure-seed clj

(generate-secure-seed)

Generates a secure seed. This pseudo-random number is random more than enough for almost all purposes Uncomplicate projects deal with, but it is often slow to generate as we have to wait for the operating systems to do the rain dance to acquire it. For most simulation work, it is much better to use generate-seed, which returns fairly good pseudo-random numbers that are further used as seeds of pseudo-random number generators.

generate-seed clj

(generate-seed)

Generates a pseudo-random seed for jump-starting pseudo-random generators. Random enough for most simulation algorithms that we use in Uncomplicate, and very cheap to acquire.

get-byte clj

(get-byte b i)

Gets a byte value at position i in a byte buffer.

get-double clj

(get-double b i)

Gets a double value at position i in a byte buffer.

get-float clj

(get-float b i)

Gets a float value at position i in a byte buffer.

get-int clj

(get-int b i)

Gets an int value at position i in a byte buffer.

get-long clj

(get-long b i)

Gets a long value at position i in a byte buffer.

get-short clj

(get-short b i)

Gets a short value at position i in a byte buffer.

mapped-buffer clj

(mapped-buffer channel)

(mapped-buffer channel size-or-flag)

(mapped-buffer channel size flag)

(mapped-buffer channel offset size flag)

Returns a ByteBuffer mapped to a FileChannel of given size, from offset.

mask clj

(mask table flags)

(mask table flag flags)

(mask table flag1 flag2 flags)

Converts keywords to a bitfield mask.

Given one or more keyword flags, creates a long bitmask that can be consumed by native functions. Needs a hashmap table that contains possible long mappings, 0-2 keywords, and a (possibly empty) list of additional keywords. If called with nil table or an unknown keyword, throws Illegalargumentexception. The inverse function is unmask.

Examples:

(mask {:a 1 :b 2 :c 4} [:a :c]) => 5
(mask {:a 1 :b 2 :c 4} :a [:c]) => 5
(mask {:a 1 :b 2 :c 4} :a :c []) => 5

path clj

(path path-name file-name & file-names)

Builds Java Path from the appropriate path name and file names.

put-byte! clj

(put-byte! b i x)

Puts a byte into a byte buffer, at position i.

put-double! clj

(put-double! b i x)

Puts a double into a byte buffer, at position i.

put-float! clj

(put-float! b i x)

Puts a float into a byte buffer, at position i.

put-int! clj

(put-int! b i x)

Puts an int into a byte buffer, at position i.

put-long! clj

(put-long! b i x)

Puts a long into a byte buffer, at position i.

put-short! clj

(put-short! b i x)

Puts a short into a byte buffer, at position i.

random-access clj

(random-access path)

(random-access path flag)

Creates a random access file.

reverse-int-bytes! clj

(reverse-int-bytes! buffer!)

Reverses bytes in integer numbers in a given ByteBuffer

reverse-long-bytes! clj

(reverse-long-bytes! buffer!)

Reverses bytes in long numbers in a given ByteBuffer

reverse-short-bytes! clj

(reverse-short-bytes! buffer!)

Reverses bytes in short numbers in a given ByteBuffer

slice-buffer clj

(slice-buffer buf ofst len)

Slices a buffer from offset with the given length.

unmask clj

(unmask table mask)

Converts a bitfield mask to keywords.

Given a mapping table and a bitfield mask, returns a lazy sequence with decoded keyword flags contained in the bitmask. The reverse function is mask.

Examples:

(unmask {:a 1 :b 2 :c 4} 5) =>  '(:a :c)

unmask1 clj

(unmask1 table mask)

Converts a bitfield mask to one keyword.

Given a mapping table and a bitfield mask, returns the first decoded keyword that is contained in the bitmask. This is useful when we know that just one of the values in the table fits the bitmask, so the result of unmask would contain one element anyway. The reverse function is mask.

Examples:

(unmask1 {:a 1 :b 2 :c 4} 2) => :b

with-check clj macro

(with-check error-fn status form)

Evaluates form if status is zero (e.g. CL_SUCCESS), otherwise throws an appropriate ExceptionInfo with decoded informative details. It helps with native interop methods that return error codes directly, while returning computation results through side-effects in arguments.

Example:

(with-check (some-call-that-returns-error-code) result)