|
13 | 13 | # limitations under the License. |
14 | 14 |
|
15 | 15 | import ./private/p_display, |
16 | | - ./data_structure, |
17 | | - typetraits |
| 16 | + ./data_structure |
| 17 | +import std / typetraits |
18 | 18 |
|
19 | | -proc pretty*[T](t: Tensor[T], precision = -1): string = |
20 | | - ## Pretty-print a Tensor with the option to set a custom `precision` |
21 | | - ## for float values. |
22 | | - var desc = t.type.name & " of shape \"" & $t.shape & "\" on backend \"" & "Cpu" & "\"" |
23 | | - if t.storage.isNil: # return useful message for uninit'd tensors instead of crashing |
24 | | - return "Uninitialized " & $desc |
25 | | - if t.size() == 0: |
26 | | - return desc & "\n [] (empty)" |
27 | | - elif t.rank == 1: # for rank 1 we want an indentation, because we have no `|` |
28 | | - return desc & "\n " & t.prettyImpl(precision = precision) |
29 | | - else: |
30 | | - return desc & "\n" & t.prettyImpl(precision = precision) |
| 19 | +proc pretty*[T](t: Tensor[T], precision: int = -1, showHeader: static bool = true): string = |
| 20 | + ## Pretty-print a Tensor as a "table" with a given precision and optional header |
| 21 | + ## |
| 22 | + ## Pretty-print a Tensor with options to set a custom `precision` for float |
| 23 | + ## values and to show or hide a header describing the tensor type and shape. |
| 24 | + ## |
| 25 | + ## Inputs: |
| 26 | + ## - Input Tensor. |
| 27 | + ## - precision: The number of decimals printed (for float tensors), |
| 28 | + ## _including_ the decimal point. |
| 29 | + ## - showHeader: If true (the default) show a description header |
| 30 | + ## indicating the tensor type and shape. |
| 31 | + ## Result: |
| 32 | + ## - A string containing a "pretty-print" representation of the Tensor. |
| 33 | + ## |
| 34 | + ## Examples: |
| 35 | + ## ```nim |
| 36 | + ## let t = arange(-2.0, 4.0).reshape(2, 3) |
| 37 | + ## |
| 38 | + ## echo t.pretty() |
| 39 | + ## # Tensor[system.float] of shape "[2, 3]" on backend "Cpu" |
| 40 | + ## # |-2 -1 0| |
| 41 | + ## # |1 2 3| |
| 42 | + ## |
| 43 | + ## # Note that the precision counts |
| 44 | + ## echo t.pretty(2) |
| 45 | + ## # Tensor[system.float] of shape "[2, 3]" on backend "Cpu" |
| 46 | + ## # |-2.0 -1.0 0.0| |
| 47 | + ## # |1.0 2.0 3.0| |
| 48 | + ## ``` |
| 49 | + const specifier = if showHeader: "" else: "||" |
| 50 | + t.prettyImpl(precision = precision, specifier = specifier) |
| 51 | + |
| 52 | +proc pretty*[T](t: Tensor[T], specifier: static string = ""): string = |
| 53 | + ## Pretty-print a Tensor with the option to set a custom format `specifier` |
| 54 | + ## |
| 55 | + ## The "format specifier" is similar to those used in format strings, with |
| 56 | + ## the addition of a few, tensor specific modifiers (shown below). |
| 57 | + ## |
| 58 | + ## Inputs: |
| 59 | + ## - Input Tensor |
| 60 | + ## - specifier: A format specifier similar to those used in format strings, |
| 61 | + ## which are used to control how the tensor and its elements |
| 62 | + ## are displayed. |
| 63 | + ## All of the standard format specifiers, such as "f", "g", |
| 64 | + ## "+", etc. (and including, in nim 2.2 and above, the 'j' |
| 65 | + ## specifier for complex tensors) can be used (check the |
| 66 | + ## documentation of nim's `strformat` module for more info). |
| 67 | + ## In addition to those standard format specifiers which |
| 68 | + ## control how the elements of the tensor are displayed, you |
| 69 | + ## can use a few, tensor specific modifiers which can be |
| 70 | + ## combined to achieve different results: |
| 71 | + ## - "[:]": Display the tensor as if it were a nim "array". |
| 72 | + ## This makes it easy to use the representation of a |
| 73 | + ## tensor in your own code. No header is shown. |
| 74 | + ## - "<>[:]": Same as "[:]" but displays a header describing |
| 75 | + ## the tensor type and shape. |
| 76 | + ## - "[]": Same as "[:]" but displays the tensor in a single |
| 77 | + ## line. No header is shown. |
| 78 | + ## - "<>[:]": Same as "[]" but displays a header describing |
| 79 | + ## the tensor type and shape. |
| 80 | + ## - "||": "Pretty-print" the tensor _without_ a header. |
| 81 | + ## - "<>||": Same as "||" but displays a header describing the |
| 82 | + ## tensor type and shape. This is the default display |
| 83 | + ## mode. |
| 84 | + ## - "<>": When used on its own (i.e. not combined with "[:]", |
| 85 | + ## "[]" and "||" as shown above) it is equivalent to |
| 86 | + ## "<>[]" (i.e. single-line, nim-like representation |
| 87 | + ## with a header). Cannot wrap the element specifier. |
| 88 | + ## |
| 89 | + ## Notes: |
| 90 | + ## - The default format (i.e. when none of these tensor-specific tokens is |
| 91 | + ## used) is pretty printing with a header (i.e. "<>||"). |
| 92 | + ## - These tensor specific modifiers can placed at the start or at the end |
| 93 | + ## of the format specifier (e.g. "<>[:]06.2f", or "06.2f<>[:]"), or they |
| 94 | + ## can "wrap" the element specifier (e.g. "<>[:06.2f]"). |
| 95 | + ## - When wrapping you cannot use the "compact forms" of these specifiers |
| 96 | + ## (i.e. "<:>" and "<|>"). |
| 97 | + ## - When using the wrapping form of "[:]", start with "[:" and end with |
| 98 | + ## either "]" or ":]" (i.e. both "[:06.2f]" and "[:06.2f:]" are valid). |
| 99 | + ## - This version of this function does not have a `showHeader` argument |
| 100 | + ## because to disable the header you can simply select the right format |
| 101 | + ## specifier. |
| 102 | + ## |
| 103 | + ## Examples: |
| 104 | + ## ```nim |
| 105 | + ## let t_int = arange(-2, 22, 4).reshape(2, 3) |
| 106 | + ## |
| 107 | + ## # You can specify a format for the elements in the tensor |
| 108 | + ## # Note that the default is "pretty-printing" the tensor |
| 109 | + ## # _and_ showing a header describing its type and shape |
| 110 | + ## echo t_int.pretty("+05X") |
| 111 | + ## # Tensor[system.int] of shape "[2, 3]" on backend "Cpu" |
| 112 | + ## # |-0002 +0002 +0006| |
| 113 | + ## # |+000A +000E +0012| |
| 114 | + ## |
| 115 | + ## # The header can be disabled by using "||" |
| 116 | + ## echo t_int.pretty("+05X||") |
| 117 | + ## # |-0002 +0002 +0006| |
| 118 | + ## # |+000A +000E +0012| |
| 119 | + ## |
| 120 | + ## # Use the "[:]" format specifier to print the tensor as a |
| 121 | + ## # "multi-line array" _without_ a header |
| 122 | + ## echo t_int.pretty("[:]") |
| 123 | + ## # [[-2, 2, 6], |
| 124 | + ## # [10, 14, 18]] |
| 125 | + ## |
| 126 | + ## # Enable the header adding "<>" (i.e. "<>[:]") or the shorter "<:>" |
| 127 | + ## echo t_int.pretty("<:>") |
| 128 | + ## # Tensor[int]<2,3>: |
| 129 | + ## # [[-2, 2, 6], |
| 130 | + ## # [10, 14, 18]] |
| 131 | + ## |
| 132 | + ## # The "[]" specifier is similar to "[:]" but prints on a single line |
| 133 | + ## echo t_int.pretty("[]") |
| 134 | + ## # [[-2, 2, 6], [10, 14, 18]] |
| 135 | + ## |
| 136 | + ## # You can also enable the header using "<>" or "<>[]" |
| 137 | + ## echo t_int.pretty("<>") |
| 138 | + ## # Tensor[int]<2,3>:[[-2, 2, 6], [10, 14, 18]] |
| 139 | + ## |
| 140 | + ## # You can combine "[]", "[:]", "<>" and "<:>" with a regular format spec: |
| 141 | + ## let t_float = arange(-2.0, 22.0, 4.0).reshape(2, 3) |
| 142 | + ## |
| 143 | + ## echo t_float.pretty("6.2f<:>") |
| 144 | + ## # Tensor[int]<2,3>: |
| 145 | + ## # [[ -2.00, 2.00, 6.00], |
| 146 | + ## # [ 10.00, 14.00, 18.00]] |
| 147 | + ## |
| 148 | + ## # The equivalent to the wrapping form is: |
| 149 | + ## echo t_float.pretty("<>[:6.2f]") |
| 150 | + ## # Tensor[int]<2,3>: |
| 151 | + ## # [[ -2.00, 2.00, 6.00], |
| 152 | + ## # [ 10.00, 14.00, 18.00]] |
| 153 | + ## ``` |
| 154 | + t.prettyImpl(precision = -1, specifier = specifier) |
31 | 155 |
|
32 | 156 | proc `$`*[T](t: Tensor[T]): string = |
33 | 157 | ## Pretty-print a tensor (when using ``echo`` for example) |
34 | 158 | t.pretty() |
| 159 | + |
| 160 | +proc `$$`*[T](t: Tensor[T]): string = |
| 161 | + ## Print the "elements" of a tensor as a multi-line array |
| 162 | + t.pretty(specifier = "<:>") |
| 163 | + |
| 164 | +proc `$<>`*[T](t: Tensor[T]): string = |
| 165 | + ## Print the "elements" of a tensor as a single-line array |
| 166 | + t.pretty(specifier = "<>") |
| 167 | + |
| 168 | +proc formatValue*[T](result: var string, t: Tensor[T], specifier: static string) = |
| 169 | + ## Standard format implementation for `Tensor` |
| 170 | + ## |
| 171 | + ## Note that it makes little sense to call this directly, but it is required |
| 172 | + ## to exist by the `&` macro. |
| 173 | + ## |
| 174 | + ## See the documentation of the `pretty` procedure for more information on the |
| 175 | + ## supported format specifiers (which include a number of tensor specific |
| 176 | + ## tokens). |
| 177 | + if specifier.len == 0: |
| 178 | + result.add $t |
| 179 | + else: |
| 180 | + result.add t.pretty(specifier = specifier) |
0 commit comments