From 3bc18b90211bcc0fe03b19a6f82987184e146745 Mon Sep 17 00:00:00 2001 From: Cory McWilliams Date: Sun, 25 Feb 2024 18:52:34 -0500 Subject: [PATCH] Docs for util.js.h. --- src/util.js.h | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/src/util.js.h b/src/util.js.h index d7e12508..9c71b505 100644 --- a/src/util.js.h +++ b/src/util.js.h @@ -10,24 +10,134 @@ #include +/** +** Register utility script functions. +** @param context The JS context. +*/ void tf_util_register(JSContext* context); + +/** +** Convert UTF-8 bytes in a buffer or Uint8Array or similar to a String. +** @param context The JS context. +** @param value The UTF-8 bytes. +** @return A string representation of the data interpreted as UTF-8 bytes. +*/ JSValue tf_util_utf8_decode(JSContext* context, JSValue value); + +/** +** Get the data from what might be an ArrayBuffer. +** @param context The JS context. +** @param[out] psize The size of the data in bytes. +** @param obj The object which might be an ArrayBuffer. +** @return The ArrayBuffer's data. +*/ uint8_t* tf_util_try_get_array_buffer(JSContext* context, size_t* psize, JSValueConst obj); + +/** +** Get the ArrayBuffer from what might be a typed ArrayBuffer. +** @param context The JS context. +** @param obj The object which might be a typed ArrayBuffer. +** @param[out] pbyte_offset The offset into the buffer at which the typed ArrayBuffer starts. +** @param[out] pbyte_length The length of the buffer. +** @param[out] pbytes_per_element Element size in bytes. +** @return An ArrayBuffer if obj was a typed ArrayBuffer. +*/ JSValue tf_util_try_get_typed_array_buffer(JSContext* context, JSValueConst obj, size_t* pbyte_offset, size_t* pbyte_length, size_t* pbytes_per_element); + +/** +** Print an error and message the owning task if possible. +** @param context The JS context. +** @param value The value which might be an exception. +** @return true If the value was an exception and an error was reported. +*/ bool tf_util_report_error(JSContext* context, JSValue value); + +/** +** Get the length of an array. +** @param context The JS context. +** @param value An array with a "length" field. +** @return The array's length. +*/ int tf_util_get_length(JSContext* context, JSValue value); + +/** +** Get the index at which to insert into an array in order to preserve sorted order. +** @param key The key being inserted. +** @param base The beginning of the array. +** @param count The number of elements in the array. +** @param size The size of a single element of the array. +** @param compare A comparison function comparing key and an element of the array. +** @return The index at which to insert key in the array, between 0 and count inclusive. +*/ int tf_util_insert_index(const void* key, const void* base, size_t count, size_t size, int (*compare)(const void*, const void*)); + +/** +** Create a Uint8Array from bytes. +** @param context The JS context. +** @param data The bytes. +** @param size The number of bytes in data. +** @return The created array. +*/ JSValue tf_util_new_uint8_array(JSContext* context, const uint8_t* data, size_t size); +/** +** Base64-encode data. +** @param source The source data. +** @param source_length The length of the source data. +** @param[out] out A buffer to receive the encoded data. +** @param out_length The size of the buffer to receive encoded data. +** @return The size of the encoded data. +*/ size_t tf_base64_encode(const uint8_t* source, size_t source_length, char* out, size_t out_length); + +/** +** Base64-decode data. +** @param source The source data. +** @param source_length The length of the source data. +** @param[out] out A buffer to receipve the decoded data. +** @param out_length The size of the buffer to receive decoded data. +** @return The size of the decoded data. +*/ size_t tf_base64_decode(const char* source, size_t source_length, uint8_t* out, size_t out_length); +/** +** Capture a stack backtrace of the calling thread. +** @param[out] buffer A buffer with at least count element to receive the backtrace. +** @param count The size of buffer. +** @return The numbef of captured frames. +*/ int tf_util_backtrace(void** buffer, int count); + +/** +** Convert a stack backtrace to string. +** @param buffer A stack backtrace. +** @param count The number of elements in the backtrace. +** @return A string representation of the stack backtrace with function names, +** files, and line numbers, as possible. Must be freed with tf_free() by the +** caller. +*/ const char* tf_util_backtrace_to_string(void* const* buffer, int count); + +/** +** Capture a stack backtrace of the calling thread and convert it immediately to string. +** @return A string representation of the stack backtrace with function names, +** files, and line numbers, as possible. Must be freed with tf_free() by the +** caller. +*/ const char* tf_util_backtrace_string(); +/** +** Convert a function pointer to its name, if possible. +** @return The function name or null. +*/ const char* tf_util_function_to_string(void* function); +/** +** Get the minimum of two values. +** @param a The first value. +** @param b The second value. +** @return The minimum of a and b. +*/ #define tf_min(a, b) \ ({ \ __typeof__(a) _a = (a); \