multiple fixes:

- don’t do function copying in benchmarking
- fix the array_update benchmark
- add Filepath.file-from-path
- add tests for the `Filepath` module
- reformat a lot of documentation

bench/array_update.carp

@@ -10,7 +10,7 @@
 
 (defn some-updating []
  (let-do [a (replicate n &12345)
- b (aupdate a 0 inc-ref)]
+ b (aupdate a 0 &inc-ref)]
  (assert (= (nth &b 0) &12346))
  (assert (= (nth &b 1) &12345))))
 

core/Bench.carp

@@ -8,7 +8,9 @@
  (private min-runs)
  (hidden min-runs)
 
- (doc set-min-runs! "Set the minimum number of runs. If your functions takes a large amount of time, experimenting with this might make sense.")
+ (doc set-min-runs! "sets the minimum number of runs to `n`.
+
+If your functions takes a large amount of time, experimenting with this might make sense. The default value is `50`, which means that your function runs at least `50` times before even hitting a timeout.")
  (defn set-min-runs! [n]
  ; / 2 because we run it twice per benchmarking run,
  ; but this is an implementation detail
@@ -36,7 +38,7 @@
  (defn ns-iter-inner [f n]
  (let [start (get-time-elapsed)]
  (do
- (for [i 0 n] (ignore (f)))
+ (for [i 0 n] (ignore (~f)))
  (Double.- (get-time-elapsed) start))))
 
  (private print-bench-results)
@@ -55,7 +57,7 @@
  samples (Array.replicate min-runs &zero)]
  (do
  (for [i 0 min-runs]
- (Array.aset! &samples i (Double./ (ns-iter-inner @&f (Double.to-int n)) n))) ;; TODO: Get rid of '@&' here.
+ (Array.aset! &samples i (Double./ (ns-iter-inner f (Double.to-int n)) n)))
  (Statistics.summary &(Statistics.winsorize &samples 5.0)))))
 
  (private min-one)
@@ -65,9 +67,9 @@
 
  ; it is actually possible to make this run forever by supplying a _really_
  ; long-running function, where long-running is everything over 30ms.
- (doc bench "Benchmark function f and print the results.")
+ (doc bench "benchmarks the function `f` and prints the results to `stdout`.")
  (defn bench [f]
- (let [ns (ns-iter-inner @&f 1) ;; @& HACK, TODO: Should be able to pass the ref instead
+ (let [ns (ns-iter-inner &f 1)
  ns-target-total 1000000.0
  _n (Double./ ns-target-total (min-one ns))
  n (min-one _n)
@@ -77,8 +79,8 @@
  (do
  (while (and (Double.< total 3000000000.0) (not done))
  (let [loop-start (get-time-elapsed)
- summ (get-samples @&f n) ;; @& HACK, TODO: Should be able to pass the ref instead
- summ5 (get-samples @&f n) ;; @& HACK, TODO: Should be able to pass the ref instead
+ summ (get-samples &f n)
+ summ5 (get-samples &f n)
  loop-run (- (get-time-elapsed) loop-start)]
  (if (and
  (Double.> loop-run 100000.0)

core/Char.carp

@@ -8,7 +8,7 @@
  (register from-int (Fn [Int] Char))
  (register copy (Fn [&Char] Char))
 
- (doc meaning "Convert a numerical char into the appropriate number.")
+ (doc meaning "converts a numerical char into the appropriate number (e.g. from `\1` to `1`).")
  (defn meaning [char-ref]
  (cond
  (= @char-ref \0) 0
@@ -26,11 +26,11 @@
  (defn /= [a b]
  (not (= (the Char a) b)))
 
- (doc lower-case? "Tests whether a character is lower case.")
+ (doc lower-case? "tests whether a character is lower case.")
  (defn lower-case? [c]
  (and (<= \a c) (<= c \z)))
 
- (doc upper-case? "Tests whether a character is upper case.")
+ (doc upper-case? "tests whether a character is upper case.")
  (defn upper-case? [c]
  (and (<= \A c) (<= c \Z)))
 )

core/Color.carp

@@ -25,22 +25,24 @@
  @"bg-cyan" @"46"
  @"bg-white" @"47"})
 
- (doc color "Generates ANSI coloration.")
+ (doc color "generates ANSI coloration based on a color name `cname`.")
  (defn color [cname]
  (let [n (Map.get &table cname)]
  (String.append "\x1b[" &(String.append &n "m"))))
 
- (doc colorize "Wraps a string in ANSI coloration and prints it.")
+ (doc colorize "wraps a string `s` in ANSI coloration based on a color name `cname` and prints it.
+
+It will reset the color afterwards.")
  (defn colorize [cname s]
  (String.append &(color cname) &(String.append s &(color "reset"))))
 )
 
 (defmodule IO
- (doc color "Sets the output color using ANSI.")
+ (doc color "sets the output color using ANSI coloration based on a color name `cname`.")
  (defn color [cname]
  (print &(Color.color cname)))
 
- (doc colorize "Wraps a string in ANSI coloration and prints it.")
+ (doc colorize "wraps a string in ANSI coloration based on a color name `cname` and prints it.")
  (defn colorize [cname s]
  (print &(Color.colorize cname s)))
 )

core/Debug.carp

@@ -2,22 +2,24 @@
 
 (defmodule Debug
 
- (doc sanitize-addresses "Instruct the compiler to sanitize addresses.")
+ (doc sanitize-addresses "instructs the compiler to sanitize addresses.
+
+This might not work on all compilers, but reasonably new versions of GCC and Clang are supported.")
  (defdynamic sanitize-addresses []
  (add-cflag "-fsanitize=address"))
 
  (register memory-balance (Fn [] Long))
  (register reset-memory-balance! (Fn [] ()))
  (register log-memory-balance! (Fn [Bool] ()))
 
- (doc memory-logged "Log all calls to memory allocation within te form. Requires compiling with --log-memory.")
+ (doc memory-logged "logs all calls to memory allocation within the form. Requires the flag `--log-memory` to be passed during compilation.")
  (defmacro memory-logged [form]
  (list 'do
  '(Debug.log-memory-balance! true)
  form
  '(Debug.log-memory-balance! false)))
 
- (doc assert-balanced "Raises an error if the memory balance (numberr of alloc:s - number of free:s) isn't 0. Requires compiling with --log-memory.")
+ (doc assert-balanced "raises an error if the memory balance (number of `alloc`s - number of `free`s) isn't `0`. Requires the flag `--log-memory` to be passed durng compilation.")
  (defmacro assert-balanced [form]
  (list 'let '[balance (Debug.memory-balance)]
  (list 'do
@@ -29,14 +31,14 @@
  (System.exit 1)))
  ())))
 
- (doc trace "Print the value of an expression to stdout, then return its value.")
+ (doc trace "prints the value of an expression to `stdout`, then returns its value.")
  (defmacro trace [x]
  (list 'let-do (array 'tmp x)
  (list 'IO.println (list 'ref (list 'fmt "%s:%d:%d: %s" (file x) (line x) (column x) '&(str tmp))))
  'tmp)
  )
 
- (doc leak-array "Leak some memory. Useful for testing tools that detect leaks.")
+ (doc leak-array "leaks some memory. This function is useful for testing tools that detect leaks.")
  (register leak-array (Fn [a] ()) "Debug_leak_MINUS_array")
 
 )

core/Double.carp

@@ -49,7 +49,9 @@
  min
  val)))
 
- (doc approx "checks whether x and y are approximately (i.e. margin of error of 0.00001) equal")
+ (doc approx "checks whether `x` and `y` are approximately equal.
+
+The margin of error is `0.00001`.")
  (defn approx [x y]
  (if (> x y)
  (< (- x y) 0.00001)
@@ -58,6 +60,7 @@
  (defn /= [x y]
  (not (Double.= x y)))
 
+ (doc zero "returns the value `0.0`.")
  (defn zero []
  0.0)
 

core/Filepath.carp

@@ -2,11 +2,17 @@
 
  (use Array)
 
- (doc dir-from-path "Removes the file-name part of a path to a file.")
+ (doc dir-from-path "removes the file name part of a path to a file, similar to the `basename` utility in Shell scripting.")
  (defn dir-from-path [path]
  (let [segments (split-by path &[\/])
  n (dec (length &segments))
  without-last (prefix-array &segments n)]
  (concat &(copy-map &(fn [s] (str* s "/")) &without-last))))
 
+ (doc file-from-path "removes the base name part of a path to a file, similar to the `filename` utility in Shell scripting.")
+ (defn file-from-path [path]
+ (let [segments (split-by path &[\/])]
+ ; this is actually safe here, because split by will return an array of
+ ; length > 0
+ (unsafe-last &segments)))
  )

core/Float.carp

@@ -25,7 +25,9 @@
  min
  val)))
 
- (doc approx "checks whether x and y are approximately (i.e. margin of error of 0.00001) equal")
+ (doc approx "checks whether `x` and `y` are approximately equal.
+
+The margin of error is 0.00001.")
  (defn approx [x y]
  (if (> x y)
  (< (- x y) 0.00001f)
@@ -55,6 +57,7 @@
  (register copy (Fn [(Ref Float)] Float))
  (register abs (Fn [Float] Float))
 
+ (doc zero "returns `0.0f`.")
  (defn zero []
  0.0f)
 

core/Format.carp

@@ -23,6 +23,6 @@
  (fmt-internal (String.substring s (+ (inc idx) next) len)
  (cdr args)))))))))))
 
-(doc fmt "fmt formats a string. It supports all of the string interpolations defined in format of the type that should be interpolated (e.g. %d and %x on integers).")
+(doc fmt "formats a string. It supports all of the string interpolations defined in format of the type that should be interpolated (e.g. %d and %x on integers).")
 (defmacro fmt [s :rest args]
  (fmt-internal s args))

core/Geometry.carp

@@ -1,9 +1,9 @@
 (defmodule Geometry
- (doc degree-to-radians "Converts degrees expressed as a double into radians.")
+ (doc degree-to-radians "converts degrees expressed as a double `n` into radians.")
  (defn degree-to-radians [n]
  (Double.* n (Double./ Double.pi 180.0)))
 
- (doc radians-to-degree "Converts radians expressed as a double into degree.")
+ (doc radians-to-degree "converts radians expressed as a double `n` into degrees.")
  (defn radians-to-degree [n]
  (Double.* n (Double./ 180.0 Double.pi)))
 )

test/filepath.carp

@@ -0,0 +1,37 @@
+(load "Filepath.carp")
+(load "Test.carp")
+
+(use-all Test Filepath)
+
+(deftest test
+ (assert-equal test
+ "test.h"
+ &(file-from-path "/an/absolute/path/for/test.h")
+ "file-from-path works with non-empty paths"
+ )
+ (assert-equal test
+ "."
+ &(file-from-path ".")
+ "file-from-path works with relative paths"
+ )
+ (assert-equal test
+ ""
+ &(file-from-path "")
+ "file-from-path works with empty paths"
+ )
+ (assert-equal test
+ "/an/absolute/path/for/"
+ &(dir-from-path "/an/absolute/path/for/test.h")
+ "dir-from-path works with non-empty paths"
+ )
+ (assert-equal test
+ ""
+ &(dir-from-path ".")
+ "dir-from-path works with relative paths"
+ )
+ (assert-equal test
+ ""
+ &(dir-from-path "")
+ "dir-from-path works with empty paths"
+ )
+)