Debian Codegraph @

texmf-dist/doc/latex/tkz-elements/TKZdoc-elements-utils.tex

raw
1 \newpage
2 \section{Module utils}
3 The \tkzname{utils} module provides low-level numerical and parsing
4 utilities used internally by \tkzname{tkz-elements}.
5 These functions ensure safe numeric conversions and consistent
6 string formatting for TikZ output.
7
8
9 \subsection{Table of module functions \tkzname{utils}}
10
11 \begin{table}[htbp]
12 \centering
13 \caption{Functions of the module \tkzMod{utils}.}
14
15 \begin{tabular}{@{}ll@{}}
16 \toprule
17 \texttt{Function} & \texttt{Reference} \\
18 \midrule
19
20 \tkzFct{utils}{utils.parse\_point(str)} & [\ref{sub:function_utils_parse_point}] \\
21
22 \tkzFct{utils}{utils.format\_number(r, n)} & [\ref{sub:function_utils_format_number}]\\
23
24 \tkzFct{utils}{utils.format\_coord(x, decimals)} & [\ref{sub:function_utils_format_coord}]\\
25
26 \tkzFct{utils}{utils.format\_point(z, decimals)} & [\ref{sub:function_utils_format_point}]\\
27
28 \tkzFct{utils}{utils.checknumber(x, decimals)} & [\ref{sub:function_utils_checknumber}]\\
29
30 \tkzFct{utils}{utils.almost\_equal(a, b, eps)} & [\ref{sub:function_utils_almost_equal}]\\
31
32 \tkzFct{utils}{utils.wlog(...)} & [\ref{sub:function_utils_wlog}]\\
33 \bottomrule
34 \end{tabular}
35 \end{table}
36
37
38
39 \subsection{Function \tkzFct{utils}{utils.parse\_point(str)}}
40 \label{sub:function_utils_parse_point}
41
42 Parses a string of the form \code{"(x,y)"} and returns the corresponding numeric coordinates. This function supports optional spaces and scientific notation.
43
44 \medskip
45 \texttt{Arguments: } \code{str} – A string representing a point, e.g., \code{"(3.5, -2.0)"}.
46
47 The function accepts:
48 \begin{itemize}
49 \item Decimal notation: \texttt{(3.5,-2)}
50 \item Scientific notation: \texttt{(1e-5,2E3)}
51 \item Optional spaces
52 \item Optional parentheses
53 \end{itemize}
54
55 \medskip
56 \texttt{Syntax: }
57
58 \begin{center}
59 \code{local x, y = utils.parse\_point("(1.5, -2.3)")}
60 \end{center}
61
62 \medskip
63 \texttt{Purpose: }
64
65 The function takes a string argument and parses it to extract the \code{x} and \code{y} components as numbers. The input string must follow the format \code{"(x, y)"} where \code{x} and \code{y} can be floating-point values written in decimal or scientific notation.
66
67
68 \medskip
69 \texttt{Returns: }
70
71 Two numbers: \texttt{x}, \texttt{y} – numeric coordinates as Lua numbers.
72 Two numerical values: the real and imaginary parts of the point.
73
74
75 \medskip
76 \texttt{Example usage: }
77
78 \begin{verbatim}
79 utils.parse_point("(3.5, -2)")
80 -- 3.5 -2.0
81
82 utils.parse_point("(1e-5,2E3)")
83 -- 1e-05 2000
84
85 utils.parse_point(" -3.2e+1 , 4.5e-2 ")
86 -- -32 0.045
87 \end{verbatim}
88
89 Scientific and decimal forms are numerically equivalent:
90
91 \begin{verbatim}
92 local x1 = utils.parse_point("(1e-5,0)")
93 local x2 = utils.parse_point("(0.00001,0)")
94 -- x1 == x2 --> true
95 \end{verbatim}
96
97 \medskip
98 \texttt{Error handling}
99
100 Invalid input raises a \texttt{tex.error}:
101
102 \begin{verbatim}
103 utils.parse_point("(a,b)")
104 -- Invalid point string
105 \end{verbatim}
106
107
108
109 \subsection{Function \tkzFct{utils}{utils.format\_number(x, decimals)}}
110 \label{sub:function_utils_format_number}
111
112 This function formats a numeric value (or a numeric string) into a string representation with a fixed number of decimal places.
113
114 \texttt{Syntax: }
115
116 \begin{center}
117 \code{local str = utils.format\_number(math.pi, 3)}
118 \end{center}
119
120 \texttt{Purpose: }
121
122 The function converts a number (or a string that can be converted to a number) into a string with the specified number of decimal digits. It is especially useful when generating clean numerical output for display or export to \TIKZ{} coordinates.
123
124 \texttt{Arguments: }
125
126 \begin{itemize}
127 \item \code{x} – numeric value
128 \item \code{decimals} – Optional. number of decimal places (default: 5)
129 \end{itemize}
130
131 \texttt{Returns: } A string representing the value of \code{x} with the specified number of decimals.
132
133 \texttt{Features: }
134
135 \begin{itemize}
136 \item Automatically converts strings to numbers if possible.
137 \item Ensures consistent formatting for \TIKZ{} coordinates or LaTeX output.
138 \item Raises an error if the input is not valid.
139 \end{itemize}
140
141 \texttt{Example usage: }
142
143 \begin{verbatim}
144 utils.format_number(1e-5,5)
145 -- "0.00001"
146
147 utils.format_number(math.pi, 3)
148 -- "3.142"
149
150 utils.format_number("2.718281828", 2)
151 -- "2.72"
152
153 utils.format_number(2e3,2)
154 -- "2000.00"
155
156 utils.format_number(-4.2e-2,4)
157 -- "-0.0420"
158 \end{verbatim}
159
160
161 \subsection{Typical Use in tkz-elements}
162
163 Example of a complete parsing and formatting pipeline:
164
165 \begin{tkzexample}[latex=.4\textwidth]
166 \directlua{
167 init_elements()
168 local x,y = utils.parse_point("(1e-5,2e3)")
169
170 local sx = utils.format_number(x,5)
171 local sy = utils.format_number(y,2)
172 tex.print(sx)
173 tex.print('\\\\')
174 tex.print(sy)
175 }
176 \end{tkzexample}
177
178
179
180 \subsection{Function \tkzFct{utils}{utils.format\_coord(x, decimals)}}
181 \label{sub:function_utils_format_coord}
182
183 This function formats a numerical value into a string with a fixed number of decimal places. It is a lighter version of \tkzFct{utils}{format\_number}, intended for internal use when inputs are guaranteed to be numeric.
184
185 \texttt{Syntax: }
186
187 \begin{center}
188 \code{local s = utils.format\_coord(3.14159, 2)} \hfill $\rightarrow$ \code{"3.14"}
189 \end{center}
190
191 \texttt{Arguments: }
192
193 \begin{itemize}
194 \item \code{x} – A number (not validated).
195 \item \code{decimals} – Optional number of decimal places (default: 5).
196 \end{itemize}
197
198 \medskip
199 \texttt{Returns: }
200
201 A string with fixed decimal formatting.
202
203 \medskip
204 \texttt{Notes: }
205
206 This function is used internally by \tkzFct{path}{add\_pair\_to\_path} and other path-building methods.
207
208 Unlike \tkzFct{utils}{format\_number}, it does not perform input validation and should only be used with known numeric inputs.
209
210 \medskip
211 \texttt{Related functions: }
212
213 \begin{itemize}
214 \item \tkzFct{utils}{format\_number(x, decimals)} – safer alternative with validation
215 \end{itemize}
216
217 \medskip
218 \texttt{Precision considerations: }
219
220 Very small values may be rounded to zero depending on the number of decimals:
221
222 \begin{verbatim}
223 utils.format_number(1e-8,5)
224 -- "0.00000"
225
226 utils.format_number(1e-8,10)
227 -- "0.0000000100"
228 \end{verbatim}
229
230 \texttt{Important note: }
231
232 Lua may internally represent numbers using scientific notation:
233
234 \begin{verbatim}
235 print(1e-5)
236 -- 1e-05
237 \end{verbatim}
238
239 However, \verb|utils.format_number| always produces a fixed decimal
240 representation suitable for TikZ output.
241
242 \subsection{Interaction with \tkzname{path}}
243
244 The formatting utilities are especially important when building
245 TikZ paths from computed points.
246
247 \texttt{Example: Scientific notation inside a path}
248
249 Consider a very small coordinate obtained after a computation:
250
251 \begin{verbatim}
252 local x = 1e-5
253 local y = 2
254 \end{verbatim}
255
256 If inserted directly into a path without formatting:
257
258 \begin{verbatim}
259 PA.curve:add_point(point(x,y))
260 \end{verbatim}
261
262 Lua may internally represent the coordinate as:
263
264 \begin{verbatim}
265 (1e-05,2)
266 \end{verbatim}
267
268 While numerically correct, scientific notation is not ideal
269 for TikZ output.
270
271
272 \texttt{Complete example}
273
274 \begin{verbatim}
275 local p = path()
276 p:add_point(point(1e-5,0),5)
277 p:add_point(point(2e-5,1),5)
278
279 -- produces:
280 -- (0.00001,0.00000) -- (0.00002,1.00000)
281 \end{verbatim}
282
283
284
285
286
287 \subsection{Function \tkzFct{utils}{utils.checknumber(x, decimals)}}
288 \label{sub:function_utils_checknumber}
289
290 Validates and converts a number or numeric string into a fixed-format decimal string.
291
292 Alias of \verb|utils.format_number| (kept for backward compatibility)
293
294 \begin{verbatim}
295 utils.checknumber(1e-5,5)
296 -- "0.00001"
297 \end{verbatim}
298
299
300
301
302 \subsection{Function \tkzFct{utils}{utils.format\_point(z, decimals)}}
303 \label{sub:function_utils_format_point}
304
305 Converts a complex point into a string representation suitable for coordinate output.
306
307 \texttt{Syntax: }
308
309 \begin{center}
310 \code{local s = utils.format\_point(z, 4)} \hfill $\rightarrow$ \code{"(1.0000,2.0000)"}
311 \end{center}
312
313 \medskip
314 \texttt{Arguments: }
315
316 \begin{itemize}
317 \item \code{z} – A table with fields \code{re} and \code{im}.
318 \item \code{decimals} – Optional precision (default: 5).
319 \end{itemize}
320
321 \medskip
322 \texttt{Returns: }
323
324 A string representing the point as \code{"(x,y)"}.
325
326 \medskip
327 \texttt{Error handling.}
328
329 Raises an error if \code{z} does not have numeric \code{re} and \code{im} components.
330
331 \medskip
332 \texttt{Related functions: }
333
334 \begin{itemize}
335 \item \tkzFct{utils}{format\_coord}
336 \end{itemize}
337
338 \subsection{Function \tkzFct{utils}{utils.almost\_equal(a, b, epsilon)}}
339 \label{sub:function_utils_almost_equal}
340
341 Returns \code{true} if two numbers are approximately equal within a given tolerance.
342
343 \medskip
344 \texttt{Syntax: }
345
346 \begin{center}
347 \code{if utils.almost\_equal(x, y) then ... end}
348 \end{center}
349
350 \medskip
351 \texttt{Arguments: }
352
353 \begin{itemize}
354 \item \code{a}, \code{b} – Two numbers to compare.
355 \item \code{epsilon} – Optional tolerance (default: \code{tkz\_epsilon}).
356 \end{itemize}
357
358 \medskip
359 \texttt{Returns: }
360
361 A boolean: \code{true} if the values differ by less than the tolerance.
362
363
364
365 \subsection{Function \tkzFct{utils}{utils.wlog(...)}}
366 \label{sub:function_utils_wlog}
367
368 Logs a formatted message to the .log file only, with a \code{[tkz-elements]} prefix.
369
370 \medskip
371 \texttt{Syntax: }
372
373 \begin{center}
374 \code{utils.wlog("Internal value: \%s", tostring(value))}
375 \end{center}
376
377 \medskip
378 \texttt{Returns: }
379
380 No return value. Logging only.
381 \endinput