From 3a41f7b96397d5172c100f0657123bb46bbc7b86 Mon Sep 17 00:00:00 2001 From: Boris Batkin Date: Tue, 17 Feb 2026 12:16:24 -0800 Subject: [PATCH 1/6] only 3 warnings left in sphinx --- daslib/apply_in_context.das | 11 +- daslib/decs_boost.das | 22 +- daslib/json_boost.das | 13 +- daslib/linq_boost.das | 4 +- daslib/math_boost.das | 2 +- daslib/quote.das | 18 +- daslib/rst.das | 17 +- daslib/stringify.das | 13 +- daslib/templates_boost.das | 5 +- daslib/typemacro_boost.das | 19 +- doc/source/conf.py | 9 +- doc/source/daslang.py | 96 +++ doc/source/reference/language/annotations.rst | 8 +- .../reference/language/builtin_functions.rst | 4 +- doc/source/reference/language/expressions.rst | 8 +- doc/source/reference/language/functions.rst | 4 +- .../reference/language/lexical_structure.rst | 4 +- doc/source/reference/language/statements.rst | 4 +- .../reference/language/string_builder.rst | 4 +- .../reference/language/type_mangling.rst | 2 +- doc/source/reference/tutorials/07_strings.rst | 2 +- doc/source/reference/tutorials/16_modules.rst | 4 +- .../reference/tutorials/23_string_format.rst | 2 +- .../tutorials/24_pattern_matching.rst | 8 +- .../tutorials/integration_cpp_13_aot.rst | 16 +- .../integration_cpp_17_coroutines.rst | 2 +- doc/source/stdlib/algorithm.rst | 27 + doc/source/stdlib/apply.rst | 5 + doc/source/stdlib/apply_in_context.rst | 16 +- doc/source/stdlib/archive.rst | 83 +- doc/source/stdlib/array_boost.rst | 11 +- doc/source/stdlib/assert_once.rst | 7 + doc/source/stdlib/ast.rst | 805 +++++++++++++++--- doc/source/stdlib/ast_block_to_loop.rst | 5 + doc/source/stdlib/ast_boost.rst | 136 ++- doc/source/stdlib/ast_used.rst | 7 + doc/source/stdlib/async_boost.rst | 13 + doc/source/stdlib/base64.rst | 9 + doc/source/stdlib/bitfield_boost.rst | 39 +- doc/source/stdlib/bitfield_trait.rst | 9 + doc/source/stdlib/bool_array.rst | 35 +- doc/source/stdlib/builtin.rst | 606 +++++++++---- doc/source/stdlib/class_boost.rst | 6 + doc/source/stdlib/constexpr.rst | 8 + doc/source/stdlib/consume.rst | 5 + doc/source/stdlib/contracts.rst | 22 + doc/source/stdlib/coroutines.rst | 15 + doc/source/stdlib/cpp_bind.rst | 5 + doc/source/stdlib/cuckoo_hash_table.rst | 7 + doc/source/stdlib/dap.rst | 63 ++ doc/source/stdlib/das_source_formatter.rst | 12 +- .../stdlib/das_source_formatter_fio.rst | 6 + doc/source/stdlib/debug_eval.rst | 7 + doc/source/stdlib/decs.rst | 69 +- doc/source/stdlib/decs_boost.rst | 35 +- doc/source/stdlib/decs_state.rst | 3 + doc/source/stdlib/defer.rst | 11 + doc/source/stdlib/dynamic_cast_rtti.rst | 9 + doc/source/stdlib/enum_trait.rst | 14 + doc/source/stdlib/export_constructor.rst | 5 + doc/source/stdlib/faker.rst | 53 ++ doc/source/stdlib/fio.rst | 67 +- doc/source/stdlib/flat_hash_table.rst | 4 + doc/source/stdlib/functional.rst | 38 + doc/source/stdlib/fuzzer.rst | 31 + doc/source/stdlib/generic_return.rst | 5 + .../handmade/structure-regex-ReNode.rst | 2 +- ...structure_annotation-ast-ExprSetInsert.rst | 2 +- .../typedef-ast-MoreFunctionFlags.rst | 2 +- doc/source/stdlib/if_not_null.rst | 5 + doc/source/stdlib/instance_function.rst | 5 + doc/source/stdlib/interfaces.rst | 6 + doc/source/stdlib/is_local.rst | 9 + doc/source/stdlib/jobque.rst | 93 +- doc/source/stdlib/jobque_boost.rst | 88 +- doc/source/stdlib/json.rst | 33 +- doc/source/stdlib/json_boost.rst | 109 ++- doc/source/stdlib/linq.rst | 133 +++ doc/source/stdlib/linq_boost.rst | 37 +- doc/source/stdlib/lint.rst | 5 + doc/source/stdlib/lpipe.rst | 5 + doc/source/stdlib/macro_boost.rst | 15 + doc/source/stdlib/match.rst | 11 + doc/source/stdlib/math.rst | 218 ++++- doc/source/stdlib/math_bits.rst | 22 + doc/source/stdlib/math_boost.rst | 32 +- doc/source/stdlib/network.rst | 33 +- doc/source/stdlib/profiler.rst | 5 + doc/source/stdlib/profiler_boost.rst | 6 + doc/source/stdlib/quote.rst | 44 + doc/source/stdlib/random.rst | 81 +- doc/source/stdlib/refactor.rst | 19 +- doc/source/stdlib/regex.rst | 45 +- doc/source/stdlib/regex_boost.rst | 5 + doc/source/stdlib/remove_call_args.rst | 5 + doc/source/stdlib/rst.rst | 27 +- doc/source/stdlib/rtti.rst | 191 ++++- doc/source/stdlib/safe_addr.rst | 36 +- doc/source/stdlib/soa.rst | 11 + doc/source/stdlib/sort_boost.rst | 5 + doc/source/stdlib/static_let.rst | 8 + doc/source/stdlib/stringify.rst | 18 +- doc/source/stdlib/strings.rst | 165 +++- doc/source/stdlib/strings_boost.rst | 32 +- doc/source/stdlib/temp_strings.rst | 13 +- doc/source/stdlib/templates.rst | 8 + doc/source/stdlib/templates_boost.rst | 94 +- doc/source/stdlib/type_traits.rst | 8 + doc/source/stdlib/typemacro_boost.rst | 49 +- doc/source/stdlib/unroll.rst | 7 + doc/source/stdlib/uriparser.rst | 49 +- doc/source/stdlib/uriparser_boost.rst | 16 + doc/source/stdlib/utf8_utils.rst | 17 + doc/source/stdlib/validate_code.rst | 5 + 114 files changed, 3729 insertions(+), 719 deletions(-) diff --git a/daslib/apply_in_context.das b/daslib/apply_in_context.das index 528ebc65a6..72cf42e545 100644 --- a/daslib/apply_in_context.das +++ b/daslib/apply_in_context.das @@ -29,11 +29,12 @@ class AppendCondAnnotation : AstFunctionAnnotation { //! If specified context is not installed, panic is called. //! //! For example:: - //! [apply_in_context(opengl_cache)] - //! def public cache_font(name:string implicit) : Font? - //! ... - //! ... - //! let font = cache_font("Arial") // call invoked in the "opengl_cache" debug agent context + //! + //! [apply_in_context(opengl_cache)] + //! def public cache_font(name:string implicit) : Font? + //! ... + //! ... + //! let font = cache_font("Arial") // call invoked in the "opengl_cache" debug agent context def override patch(var func : FunctionPtr; var group : ModuleGroup; args, progArgs : AnnotationArgumentList; var errors : das_string; var astChanged : bool&) : bool { for (ann in func.annotations) { diff --git a/daslib/decs_boost.das b/daslib/decs_boost.das index 96431b9af0..4a138e7b6d 100644 --- a/daslib/decs_boost.das +++ b/daslib/decs_boost.das @@ -267,9 +267,11 @@ enum private DecsQueryType { [call_macro(name="query")] class DecsQueryMacro : AstCallMacro { - //! This macro implements 'query` functionality. There are 2 types of queries: - //! * query(...) - returns a list of entities matching the query - //! * query(eid) - returns a single entity matching the eid + //! This macro implements `query` functionality. There are 2 types of queries: + //! + //! * query(...) - returns a list of entities matching the query + //! * query(eid) - returns a single entity matching the eid + //! //! For example:: //! //! query() <| $ ( eid:EntityId; pos, vel : float3 ) @@ -280,6 +282,7 @@ class DecsQueryMacro : AstCallMacro { //! //! query(kaboom) <| $ ( var pos:float3&; vel:float3; col:uint=13u ) //! pos += vel + //! //! The query above will add the velocity to the position of an entity with eid kaboom. //! //! Query can have `REQUIRE` and `REQUIRE_NOT` clauses:: @@ -477,10 +480,12 @@ class DecsQueryMacro : AstCallMacro { [call_macro(name="find_query")] class DecsFindQueryMacro : DecsQueryMacro { - //! This macro implements 'find_query` functionality. + //! This macro implements `find_query` functionality. //! It is similar to `query` in most ways, with the main differences being: - //! * there is no eid-based find query - //! * the find_query stops once the first match is found + //! + //! * there is no eid-based find query + //! * the find_query stops once the first match is found + //! //! For example:: //! //! let found = find_query <| $ ( pos,dim:float3; obstacle:Obstacle ) @@ -500,7 +505,7 @@ class DecsFindQueryMacro : DecsQueryMacro { [function_macro(name="decs")] class DecsEcsMacro : AstFunctionAnnotation { - //! This macro converts a function into a DECS pass stage query. Possible arguments are `stage`, 'REQUIRE', and `REQUIRE_NOT`. + //! This macro converts a function into a DECS pass stage query. Possible arguments are `stage`, `REQUIRE`, and `REQUIRE_NOT`. //! It has all other properties of a `query` (like ability to operate on templates). For example:: //! //! [decs(stage=update_ai, REQUIRE=ai_turret)] @@ -587,12 +592,15 @@ class DecsEcsMacro : AstFunctionAnnotation { [call_macro(name="from_decs")] class FromDecsMacro : AstCallMacro { //! This macro converts a DECS query into an iterator>. For example:: + //! //! let it = from_decs($(index:int; text:string){}) //! for (item in it) { //! // process item //! print("Entity {item.index}: {item.text}\n") //! } + //! //! Internally it generates the following code:: + //! //! let it = invoke($() { //! var res : array> //! query($(index:int; text:string) { diff --git a/daslib/json_boost.das b/daslib/json_boost.das index 20ff1accb9..e64e05127b 100644 --- a/daslib/json_boost.das +++ b/daslib/json_boost.das @@ -214,12 +214,13 @@ class private BetterJsonMacro : AstVariantMacro { [reader_macro(name="json")] class private JsonReader : AstReaderMacro { //! This macro implements embedding of the JSON object into the program:: - //! var jsv = %json~ - //! { - //! "name": "main_window", - //! "value": 500, - //! "size": [1,2,3] - //! } %% + //! + //! var jsv = %json~ + //! { + //! "name": "main_window", + //! "value": 500, + //! "size": [1,2,3] + //! } %% def override accept(prog : ProgramPtr; mod : Module?; var expr : ExprReader?; ch : int; info : LineInfo) : bool { //! Implement the accept method to read until '%%' is found. append(expr.sequence, ch) diff --git a/daslib/linq_boost.das b/daslib/linq_boost.das index 30f9e33f43..fb6f07f4e3 100644 --- a/daslib/linq_boost.das +++ b/daslib/linq_boost.das @@ -790,7 +790,9 @@ def private fold_linq_default(var expr : ExpressionPtr) : ExpressionPtr { class private LinqFold : AstCallMacro { //! implements _fold(expression) that folds LINQ expressions into optimized sequnences //! for example:: - //! _fold(each(foo)._where(_ > 5)._select(_ * 2)) + //! + //! _fold(each(foo)._where(_ > 5)._select(_ * 2)) + //! //! expands into a single comprehension that does all operations in one pass def override visit(prog : ProgramPtr; mod : Module?; var call : smart_ptr) : ExpressionPtr { //! Visits the _fold macro call and folds LINQ expressions into optimized sequences. diff --git a/daslib/math_boost.das b/daslib/math_boost.das index 909c81826b..cfe219ccc8 100644 --- a/daslib/math_boost.das +++ b/daslib/math_boost.das @@ -209,7 +209,7 @@ def plane_dot(Plane, Vec : float4) { } def plane_normalize(Plane : float4) { - //! normalize `Plane', length xyz will be 1.0 (or 0.0 for no plane) + //! normalize ``Plane``, length xyz will be 1.0 (or 0.0 for no plane) let len = length(Plane.xyz) return len != 0.0 ? Plane / len : float4(0) } diff --git a/daslib/quote.das b/daslib/quote.das index 7facbbc652..e0daaada3c 100644 --- a/daslib/quote.das +++ b/daslib/quote.das @@ -40,13 +40,13 @@ def public clone(var a : dasvector`CaptureEntry; b : array } } -struct LineInfoInitData { +struct public LineInfoInitData { //! Initialization data for source line info reconstruction. - fileInfo : FileInfo? - column : uint - line : uint - last_column : uint - last_line : uint + fileInfo : FileInfo? //! Pointer to the source file info. + column : uint //! Column number (1-based). + line : uint //! Line number (1-based). + last_column : uint //! Last column number of the range. + last_line : uint //! Last line number of the range. } @@ -140,10 +140,10 @@ def public cvt_to_mks(var args) : smart_ptr { return <- res; } -struct FileInfoInitData { +struct public FileInfoInitData { //! Initialization data for reconstructing file info. - name : string - tabSize : int + name : string //! File name string. + tabSize : int //! Tab size for the file. } def public clone_file_info(b : FileInfoInitData) : FileInfo? { diff --git a/daslib/rst.das b/daslib/rst.das index 2fa51f8977..25ca09cc0a 100644 --- a/daslib/rst.das +++ b/daslib/rst.das @@ -99,11 +99,11 @@ def public safe_function_name(name : string) : string { ("*", "_st_"), (".", "_dot_"), ("?", "_q_"), - ("&", ""), + ("&", "_ref_"), ("(", ""), (")", ""), - ("[", ""), - ("]", ""), + ("[", "_lb_"), + ("]", "_rb_"), ("|", "")]) } @@ -501,7 +501,7 @@ def describe_type(td : TypeDeclPtr) { } write(writer, ">") } elif (baseType == Type.tTuple || baseType == Type.tVariant || baseType == Type.option) { - let delim = baseType == Type.option ? "|" : ";" + let delim = baseType == Type.option ? "\\ | " : ";" write(writer, das_to_string(baseType)) write(writer, "<") if (td.argTypes |> length != 0) { @@ -561,10 +561,10 @@ def describe_type(td : TypeDeclPtr) { write(writer, "]") } if (td.flags.ref) { - write(writer, "&") + write(writer, "\\ &") } if (td.flags.temporary) { - write(writer, "#") + write(writer, "\\ #") } if (td.flags._implicit) { write(writer, " implicit") @@ -595,7 +595,7 @@ def make_ref(name, text : string) { def public make_group(name : string; plus : string = "+") { //! Creates an RST group header with the given name surrounded by separator lines. let len = length(name) - return "{strings::repeat(plus,len)}\n{name}\n{strings::repeat(plus,len)}\n\n" + return "\n{strings::repeat(plus,len)}\n{name}\n{strings::repeat(plus,len)}\n\n" } def make_header(name, lab : string) { @@ -896,7 +896,7 @@ def document_topic(doc_file : file; topic, content : string implicit; cb : block if (topic_file != null) { let instxt = cb |> invoke(fread(topic_file)) fwrite(doc_file, instxt) - fwrite(doc_file, "\n") + fwrite(doc_file, "\n\n") } else { PANIC("can't open {topic_file_name}") } @@ -2268,6 +2268,7 @@ def public documents(name : string; mods : array; fname : string; var g mod_name = "_builtin" } fwrite(doc_file, make_header(name, mod_name)) + fwrite(doc_file, ".. das:module:: {mod_name}\n\n") // if length(header)!=0 // fwrite(doc_file,".. include:: {header}\n\n") for (mod in mods) { diff --git a/daslib/stringify.das b/daslib/stringify.das index 9a01d02ea2..88b501d39b 100644 --- a/daslib/stringify.das +++ b/daslib/stringify.das @@ -17,12 +17,13 @@ require daslib/ast_boost [reader_macro(name="stringify")] class private LongStringReader : AstReaderMacro { - //! This macro implements embedding of the long string into the source code. - //! var st = %stringify~ - //! This is a long string - //! with multiple lines - //! and special charactes like { this } and "that" - //! %% + //! This macro implements embedding of the long string into the source code. :: + //! + //! var st = %stringify~ + //! This is a long string + //! with multiple lines + //! and special charactes like { this } and "that" + //! %% def override accept(prog : ProgramPtr; mod : Module?; var expr : ExprReader?; ch : int; info : LineInfo) : bool { //! Accepts characters into the reader sequence until the closing %% delimiter is found. if (ch != '\r') { diff --git a/daslib/templates_boost.das b/daslib/templates_boost.das index d029829eba..c1969d2a01 100644 --- a/daslib/templates_boost.das +++ b/daslib/templates_boost.das @@ -537,8 +537,9 @@ def make_unique_private_name(prefix : string; vat : LineInfo) { //! Generates unique private name for the variable, given prefix and line info. //! //! .. warning:: - //! The assumption is that line info is unique for the context of the unique name generation. - //! If it is not, additional measures must be taken to ensure uniqueness of prefix. + //! + //! The assumption is that line info is unique for the context of the unique name generation. + //! If it is not, additional measures must be taken to ensure uniqueness of prefix. return "{prefix}_{vat.line}_{vat.column}" } diff --git a/daslib/typemacro_boost.das b/daslib/typemacro_boost.das index 45d97cd1d4..5a4cefeb33 100644 --- a/daslib/typemacro_boost.das +++ b/daslib/typemacro_boost.das @@ -492,15 +492,16 @@ class TemplateTypeMacroMacro : AstFunctionAnnotation { class TemplateStructure : AstStructureAnnotation { //! This macro creates typemacro function and associates it with the structure. //! It also creates the typemacro_template_function to associate with it. - //! For example: - //! [template_structure(KeyType,ValueType)] struct template TFlatHashTable { ... } - //! creates: - //! 1) [typemacro_function] def TFlatHashTable (macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr) : TypeDeclPtr { - //! return <- make`template`TFlatHashTable(macroArgument, passArgument, KeyType, ValueType) - //! } - //! 2) [typemacro_template_function(TFlatHashTable)] def make`template`TFlatHashTable (macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr) : TypeDeclPtr { - //! return <- default - //! } + //! For example:: + //! + //! [template_structure(KeyType,ValueType)] struct template TFlatHashTable { ... } + //! creates: + //! 1) [typemacro_function] def TFlatHashTable (macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr) : TypeDeclPtr { + //! return <- make`template`TFlatHashTable(macroArgument, passArgument, KeyType, ValueType) + //! } + //! 2) [typemacro_template_function(TFlatHashTable)] def make`template`TFlatHashTable (macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr) : TypeDeclPtr { + //! return <- default + //! } def override apply(var st : StructurePtr; var group : ModuleGroup; args : AnnotationArgumentList; var errors : das_string) : bool { if (length(args) == 0) { errors := "expecting at least one template argument name" diff --git a/doc/source/conf.py b/doc/source/conf.py index 894de29b79..aece4aacce 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -36,7 +36,6 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -exclude_patterns = ['index/detail/*', 'index/handmade/*'] suppress_warnings = ['toctree.not_included'] @@ -70,7 +69,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -80,7 +79,9 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +# Exclude detail/ and handmade/ under stdlib/ — these are intermediate files +# used by das2rst generation, not standalone documentation pages. +exclude_patterns = ['stdlib/detail', 'stdlib/handmade'] # The reST default role (used for this markup: `text`) to use for all # documents. @@ -146,7 +147,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/doc/source/daslang.py b/doc/source/daslang.py index 7ec6452592..c8f9ff958f 100644 --- a/doc/source/daslang.py +++ b/doc/source/daslang.py @@ -14,6 +14,11 @@ from docutils import nodes from docutils.parsers.rst import directives +from pygments.lexer import RegexLexer, bygroups, words, include +from pygments.token import ( + Comment, Keyword, Name, Number, Operator, Punctuation, String, Text, Token +) + from sphinx import version_info from sphinx import addnodes @@ -415,9 +420,100 @@ def get_full_qualified_name(self, node): return '.'.join(filter(None, [modname, prefix, target])) +class DaslangLexer(RegexLexer): + """Simple Pygments lexer for the daslang (daScript) language.""" + + name = 'daslang' + aliases = ['das', 'daslang', 'dascript'] + filenames = ['*.das'] + + tokens = { + 'root': [ + # Line comments + (r'//.*$', Comment.Single), + # Block comments + (r'/\*', Comment.Multiline, 'block_comment'), + # Strings + (r'"', String.Double, 'string'), + # Character literals + (r"'[^']*'", String.Char), + # Numbers (hex, float, int) + (r'0[xX][0-9a-fA-F_]+[uU]?[lL]?', Number.Hex), + (r'[0-9][0-9_]*\.[0-9_]*([eE][+-]?[0-9_]+)?[fFlL]?', Number.Float), + (r'[0-9][0-9_]*[uU]?[lL]?', Number.Integer), + # Keywords + (words(( + 'struct', 'class', 'let', 'var', 'def', 'while', 'if', 'static_if', + 'else', 'elif', 'for', 'finally', 'in', 'is', 'as', + 'where', 'return', 'yield', 'break', 'continue', + 'pass', 'try', 'recover', 'delete', 'deref', + 'new', 'typeinfo', 'type', 'array', 'table', + 'block', 'function', 'lambda', 'generator', + 'expect', 'override', 'abstract', 'sealed', + 'require', 'module', 'public', 'private', + 'options', 'operator', 'enum', 'typedef', 'variant', 'tuple', + 'with', 'cast', 'upcast', 'reinterpret', 'aka', + 'assume', 'unsafe', 'addr', 'label', 'goto', + 'implicit', 'explicit', 'shared', 'smart_ptr', 'inscope', + 'static', 'fixed_array', 'iterator', 'bitfield', + 'move_new', 'move', + ), prefix=r'\b', suffix=r'\b'), Keyword), + # Boolean / null + (words(('true', 'false', 'null', 'nothing'), prefix=r'\b', suffix=r'\b'), Keyword.Constant), + # Built-in types + (words(( + 'void', 'bool', 'string', 'auto', + 'int', 'int2', 'int3', 'int4', 'int8', 'int16', 'int64', + 'uint', 'uint2', 'uint3', 'uint4', 'uint8', 'uint16', 'uint64', + 'float', 'float2', 'float3', 'float4', + 'double', 'range', 'urange', 'range64', 'urange64', + ), prefix=r'\b', suffix=r'\b'), Keyword.Type), + # Annotations + (r'\[[\w]+\]', Name.Decorator), + # Lambda/block/function pointer sigils + (r'@@?', Operator), + (r'\$', Operator), + # Identifiers + (r'[a-zA-Z_]\w*', Name), + # Operators + (r'[+\-*/%&|^~<>=!?:#]+', Operator), + # Punctuation + (r'[{}()\[\];,.]', Punctuation), + # Pipe operator + (r'\|>', Operator), + # Arrow / move + (r'<-', Operator), + (r'->', Operator), + (r'<\|', Operator), + (r'=>', Operator), + # Whitespace + (r'\s+', Text), + # Catch-all for any other character (Unicode, etc.) + (r'.', Text), + ], + 'block_comment': [ + (r'/\*', Comment.Multiline, '#push'), + (r'\*/', Comment.Multiline, '#pop'), + (r'[^/*]+', Comment.Multiline), + (r'[/*]', Comment.Multiline), + ], + 'string': [ + (r'\\[\\nrt"\'{]', String.Escape), + (r'\{', String.Interpol, 'interpolation'), + (r'[^"\\{]+', String.Double), + (r'"', String.Double, '#pop'), + ], + 'interpolation': [ + (r'\}', String.Interpol, '#pop'), + include('root'), + ], + } + + def setup(app): # type: (Sphinx) -> Dict[unicode, Any] app.add_domain(DaslangDomain) + app.add_lexer('das', DaslangLexer) return { 'version': 'builtin', diff --git a/doc/source/reference/language/annotations.rst b/doc/source/reference/language/annotations.rst index 4ef4dc918b..c42d5e0627 100644 --- a/doc/source/reference/language/annotations.rst +++ b/doc/source/reference/language/annotations.rst @@ -181,9 +181,9 @@ Lint Control Declares that the function has side effects, even if the compiler cannot detect any. Prevents the optimizer from removing calls to this function. -^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^ Generics and Contracts -^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^ ``[generic]`` Marks a function as generic (a template that is instantiated for each unique set of @@ -293,9 +293,9 @@ Markers and Hints ``[marker]`` A generic function marker annotation. Does not change behavior. ---------------------- +------------------------------- Structure and Class Annotations ---------------------- +------------------------------- ``[cpp_layout]`` Uses C++ memory layout (matching C++ struct alignment rules):: diff --git a/doc/source/reference/language/builtin_functions.rst b/doc/source/reference/language/builtin_functions.rst index 2f5009a76d..2bb52aa778 100644 --- a/doc/source/reference/language/builtin_functions.rst +++ b/doc/source/reference/language/builtin_functions.rst @@ -120,9 +120,9 @@ Panic print("recovered from panic\n") } ---------------------- +----------------------- Memory & Type Utilities ---------------------- +----------------------- .. das:function:: addr(x) diff --git a/doc/source/reference/language/expressions.rst b/doc/source/reference/language/expressions.rst index 5bad995e75..a7c9a24c2c 100644 --- a/doc/source/reference/language/expressions.rst +++ b/doc/source/reference/language/expressions.rst @@ -182,9 +182,9 @@ By default, ``interval(a, b : int)`` returns ``range(a, b)`` and ``interval(a, b : uint)`` returns ``urange(a, b)``. Custom ``interval`` functions or generics can be defined for other types. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Null-Coalescing Operator (??) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. index:: pair: ?? Operator; Operators @@ -307,9 +307,9 @@ This is useful in generic functions to branch on the actual type of a parameter: } } -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Cast, Upcast, and Reinterpret -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. index:: pair: Cast Operators; Operators diff --git a/doc/source/reference/language/functions.rst b/doc/source/reference/language/functions.rst index 65c23e4624..97b69ade97 100644 --- a/doc/source/reference/language/functions.rst +++ b/doc/source/reference/language/functions.rst @@ -387,8 +387,8 @@ To overload an operator, you need to define a special function with the name of def operator () : # Implementation here -In this syntax, is the name of the operator you want to overload (e.g. +, -, *, /, ==, etc.), - are the parameters that the operator function takes, and is the return type of the operator function. +In this syntax, ```` is the name of the operator you want to overload (e.g. ``+``, ``-``, ``*``, ``/``, ``==``, etc.), +```` are the parameters that the operator function takes, and ```` is the return type of the operator function. For example, here's how you could overload the == operator for a custom struct called iVec2:: diff --git a/doc/source/reference/language/lexical_structure.rst b/doc/source/reference/language/lexical_structure.rst index 0d088d7f1a..bb181aa0f6 100644 --- a/doc/source/reference/language/lexical_structure.rst +++ b/doc/source/reference/language/lexical_structure.rst @@ -145,9 +145,9 @@ Literals Daslang accepts integer numbers, unsigned integers, floating-point and double-precision numbers, and string literals. -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^ Numeric Literals -^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^ +-------------------------------+------------------------------------------+ | ``34`` | Integer (base 10) | diff --git a/doc/source/reference/language/statements.rst b/doc/source/reference/language/statements.rst index 0e22224ced..566581e9eb 100644 --- a/doc/source/reference/language/statements.rst +++ b/doc/source/reference/language/statements.rst @@ -538,9 +538,9 @@ Trigger a runtime panic with an optional message:: The panic message is available in the runtime log. A panic can be caught by a ``try``/``recover`` block. ------- +-------------- label and goto ------- +-------------- .. index:: pair: label; statement diff --git a/doc/source/reference/language/string_builder.rst b/doc/source/reference/language/string_builder.rst index 6619d89d01..0344feb876 100644 --- a/doc/source/reference/language/string_builder.rst +++ b/doc/source/reference/language/string_builder.rst @@ -93,9 +93,9 @@ Examples:: print("{-7:+d}\n") // "-7" — with sign print("{255:#x}\n") // "0xff" — with 0x prefix ---------------------- +----------------------- Escaping Curly Brackets ---------------------- +----------------------- To include a literal ``{`` or ``}`` in a string, escape them with a backslash:: diff --git a/doc/source/reference/language/type_mangling.rst b/doc/source/reference/language/type_mangling.rst index 00a96e6347..5c48688378 100644 --- a/doc/source/reference/language/type_mangling.rst +++ b/doc/source/reference/language/type_mangling.rst @@ -306,4 +306,4 @@ mangled strings match the daslang-side expectations. :ref:`tutorial_integration_c_unaligned_advanced` — unaligned ABI interop functions - :ref:`_contexts` — runtime context lookups by mangled name hash + :ref:`contexts` — runtime context lookups by mangled name hash diff --git a/doc/source/reference/tutorials/07_strings.rst b/doc/source/reference/tutorials/07_strings.rst index f043a05303..17b1b80586 100644 --- a/doc/source/reference/tutorials/07_strings.rst +++ b/doc/source/reference/tutorials/07_strings.rst @@ -237,4 +237,4 @@ Running the tutorial Next tutorial: :ref:`tutorial_structs` - :ref:`_strings` in the language reference + :ref:`string_builder` in the language reference diff --git a/doc/source/reference/tutorials/16_modules.rst b/doc/source/reference/tutorials/16_modules.rst index 20ed170d00..e7a5b6d998 100644 --- a/doc/source/reference/tutorials/16_modules.rst +++ b/doc/source/reference/tutorials/16_modules.rst @@ -1,8 +1,8 @@ .. _tutorial_modules: -======================== +============================= Modules and Program Structure -======================== +============================= .. index:: single: Tutorial; Modules diff --git a/doc/source/reference/tutorials/23_string_format.rst b/doc/source/reference/tutorials/23_string_format.rst index 3a2000bba1..b79f2ad200 100644 --- a/doc/source/reference/tutorials/23_string_format.rst +++ b/doc/source/reference/tutorials/23_string_format.rst @@ -63,7 +63,7 @@ Writer functions: .. seealso:: - :ref:`String builder `, :ref:`Strings ` in + :ref:`String builder ` in the language reference. Full source: :download:`tutorials/language/23_string_format.das <../../../../tutorials/language/23_string_format.das>` diff --git a/doc/source/reference/tutorials/24_pattern_matching.rst b/doc/source/reference/tutorials/24_pattern_matching.rst index 1c385b43ae..e441634ef6 100644 --- a/doc/source/reference/tutorials/24_pattern_matching.rst +++ b/doc/source/reference/tutorials/24_pattern_matching.rst @@ -39,10 +39,10 @@ Wildcards and binding - ``_`` — wildcard, matches anything - ``$v(name)`` — bind matched value to a variable:: - match (point) { - if (Point(x = 0, y = 0)) { return "origin" } - if (Point(x = $v(x), y = $v(y))) { return "({x}, {y})" } - } + match (point) { + if (Point(x = 0, y = 0)) { return "origin" } + if (Point(x = $v(x), y = $v(y))) { return "({x}, {y})" } + } Guards ====== diff --git a/doc/source/reference/tutorials/integration_cpp_13_aot.rst b/doc/source/reference/tutorials/integration_cpp_13_aot.rst index 5c5a39df75..5e62914bcd 100644 --- a/doc/source/reference/tutorials/integration_cpp_13_aot.rst +++ b/doc/source/reference/tutorials/integration_cpp_13_aot.rst @@ -158,14 +158,14 @@ the function runs through the interpreter. With it linked in, Key policies ============ -+---------------------------+------------------------------------------+ -| ``policies.aot`` | Enable AOT linking during simulate | -+---------------------------+------------------------------------------+ -| ``policies.fail_on_no_aot``| Error if a function lacks AOT (default | -| | ``true``) | -+---------------------------+------------------------------------------+ -| ``policies.aot_module`` | This is a module AOT (not entry point) | -+---------------------------+------------------------------------------+ ++-----------------------------+------------------------------------------+ +| ``policies.aot`` | Enable AOT linking during simulate | ++-----------------------------+------------------------------------------+ +| ``policies.fail_on_no_aot`` | Error if a function lacks AOT (default | +| | ``true``) | ++-----------------------------+------------------------------------------+ +| ``policies.aot_module`` | This is a module AOT (not entry point) | ++-----------------------------+------------------------------------------+ Building and running diff --git a/doc/source/reference/tutorials/integration_cpp_17_coroutines.rst b/doc/source/reference/tutorials/integration_cpp_17_coroutines.rst index ff7dd8e4cc..111e0eb19b 100644 --- a/doc/source/reference/tutorials/integration_cpp_17_coroutines.rst +++ b/doc/source/reference/tutorials/integration_cpp_17_coroutines.rst @@ -140,4 +140,4 @@ The output is interleaved: each ``yield`` in daslang produces a Next tutorial: :ref:`tutorial_integration_cpp_dynamic_scripts` - Related: :ref:`_generators` + Related: :ref:`generators` diff --git a/doc/source/stdlib/algorithm.rst b/doc/source/stdlib/algorithm.rst index cceadbfa50..873ab4df4e 100644 --- a/doc/source/stdlib/algorithm.rst +++ b/doc/source/stdlib/algorithm.rst @@ -5,6 +5,8 @@ Miscellaneous algorithms ======================== +.. das:module:: algorithm + The ALGORITHM module provides array and collection manipulation algorithms including sorting, searching, set operations, element removal, and more. @@ -41,6 +43,8 @@ Example: :: print("is_sorted: {is_sorted(arr)}\n") } + + ++++++ Search ++++++ @@ -82,6 +86,7 @@ binary_search Returns true if val appears within the range [f, last). + :Arguments: * **a** : auto * **f** : int @@ -131,6 +136,7 @@ equal_range Returns a pair of indices [lower, upper) bounding the range of elements equal to val within [f, l). The array must be sorted. + :Arguments: * **a** : array * **f** : int @@ -155,6 +161,7 @@ lower_bound Returns the index of the first element in the array for which less returns false, or length(a) if no such element is found. + :Arguments: * **a** : array * **value** : auto(QQ) @@ -201,6 +208,7 @@ upper_bound Returns the index of the first element in the range [f, l) for which less(val, element) returns true, or l if no such element is found. + :Arguments: * **a** : array * **f** : int @@ -241,6 +249,7 @@ Returns the index of the first element in the range [f, l) for which less(val, e ---- + ++++++++++++++++++ Array manipulation ++++++++++++++++++ @@ -277,6 +286,7 @@ combine Returns a new array containing elements from a followed by b. + :Arguments: * **a** : array * **b** : array @@ -295,6 +305,7 @@ Erases all elements equal to value from arr in O(n) time. Uses swap to support non-copyable types. Removed elements are swapped to the tail and properly finalized by resize. + :Arguments: * **arr** : auto * **value** : auto @@ -309,6 +320,7 @@ fill Sets all elements of the array to the given value using clone. + :Arguments: * **a** : array * **value** : TT @@ -329,6 +341,7 @@ is_sorted Returns true if the array is sorted in non-descending order. + :Arguments: * **a** : auto .. _function-algorithm_is_sorted_array_ls_autoTT_gr_: @@ -351,6 +364,7 @@ max_element Returns the index of the maximum element in the array, or -1 if the array is empty. + :Arguments: * **a** : auto .. _function-algorithm_max_element_array_ls_autoTT_gr__block_ls_a_c_TT;b_c_TT_c_bool_gr_: @@ -373,6 +387,7 @@ min_element Returns the index of the minimum element according to the provided less function, or -1 if the array is empty. + :Arguments: * **a** : array * **less** : block<(a:TT;b:TT):bool> @@ -397,6 +412,7 @@ reverse Reverses the elements of array a in place. + :Arguments: * **a** : auto .. _function-algorithm_reverse_array_ls_auto_gr_: @@ -416,6 +432,7 @@ rotate Rotates the array so that the element at index mid becomes the first element. Elements before mid are moved to the end. + :Arguments: * **a** : array * **mid** : int @@ -434,6 +451,7 @@ Returns an array of elements from a, sorted and with duplicates removed. The elements are sorted in ascending order. The resulting array has only unique elements. + :Arguments: * **a** : array .. _function-algorithm_topological_sort_array_ls_autoNode_gr_: @@ -445,6 +463,7 @@ Each node has an id, and set (table with no values) of dependencies. Dependency `before` represents a link from a node, which should appear in the sorted list before the node. Returns a sorted list of nodes. + :Arguments: * **nodes** : array .. _function-algorithm_unique_array_ls_autoTT_gr_: @@ -454,8 +473,10 @@ Returns a sorted list of nodes. Returns an array with adjacent duplicate elements removed. The array should be sorted first if all duplicates need to be removed. + :Arguments: * **a** : array + ++++++++++++++++++ Table manipulation ++++++++++++++++++ @@ -473,6 +494,7 @@ Table manipulation Returns the difference of two sets. + :Arguments: * **a** : table * **b** : table @@ -483,6 +505,7 @@ Returns the difference of two sets. Returns true if the two sets are identical. + :Arguments: * **a** : table * **b** : table @@ -493,6 +516,7 @@ Returns true if the two sets are identical. Returns the intersection of two sets. + :Arguments: * **a** : table * **b** : table @@ -503,6 +527,7 @@ Returns the intersection of two sets. Returns true if all elements of a are contained in b. + :Arguments: * **a** : table * **b** : table @@ -513,6 +538,7 @@ Returns true if all elements of a are contained in b. Returns the symmetric difference of two sets (elements in either set but not both). + :Arguments: * **a** : table * **b** : table @@ -523,6 +549,7 @@ Returns the symmetric difference of two sets (elements in either set but not bot Returns the union of two sets. + :Arguments: * **a** : table * **b** : table diff --git a/doc/source/stdlib/apply.rst b/doc/source/stdlib/apply.rst index 965edd2ce0..51c726bfa3 100644 --- a/doc/source/stdlib/apply.rst +++ b/doc/source/stdlib/apply.rst @@ -5,6 +5,8 @@ Apply reflection pattern ======================== +.. das:module:: apply + The APPLY module provides the ``apply`` macro for iterating over struct, tuple, and variant fields at compile time. Each field is visited with its name and a reference to its value, enabling generic per-field operations like @@ -36,6 +38,8 @@ Example: :: // b = 3.14 // c = hello + + +++++++++++ Call macros +++++++++++ @@ -56,3 +60,4 @@ For example Would print x = 1.0 y = 2.0 + diff --git a/doc/source/stdlib/apply_in_context.rst b/doc/source/stdlib/apply_in_context.rst index 8fe9ddf836..19aec73dfe 100644 --- a/doc/source/stdlib/apply_in_context.rst +++ b/doc/source/stdlib/apply_in_context.rst @@ -5,6 +5,8 @@ Cross-context evaluation helpers ================================ +.. das:module:: apply_in_context + The APPLY_IN_CONTEXT module extends apply operations to work across different execution contexts, enabling cross-context function invocation with packed arguments. @@ -13,6 +15,8 @@ All functions and symbols are in "apply_in_context" module, use require to get a require daslib/apply_in_context + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -26,10 +30,12 @@ Function is modified, so that it is called in the debug agent context, specified If specified context is not installed, panic is called. For example:: - [apply_in_context(opengl_cache)] - def public cache_font(name:string implicit) : Font? - ... - ... - let font = cache_font("Arial") // call invoked in the "opengl_cache" debug agent context + + [apply_in_context(opengl_cache)] + def public cache_font(name:string implicit) : Font? + ... + ... + let font = cache_font("Arial") // call invoked in the "opengl_cache" debug agent context + diff --git a/doc/source/stdlib/archive.rst b/doc/source/stdlib/archive.rst index afb674ed2c..f5c8d50080 100644 --- a/doc/source/stdlib/archive.rst +++ b/doc/source/stdlib/archive.rst @@ -5,6 +5,8 @@ General purpose serialization ============================= +.. das:module:: archive + The ARCHIVE module implements general-purpose serialization infrastructure. It provides the ``Archive`` type and ``serialize`` functions for reading and writing binary data. Custom types are supported by implementing ``serialize`` @@ -46,6 +48,8 @@ Example: :: // output: // a = 3.14, b = hello + + ++++++++++ Structures ++++++++++ @@ -63,6 +67,8 @@ Archive is a combination of serialization stream, and state (version, and readin * **stream** : :ref:`Serializer `? - Serialization stream. + + +++++++ Classes +++++++ @@ -74,6 +80,7 @@ Classes Base class for serializers. + .. _struct-archive-MemSerializer: .. das:attribute:: MemSerializer : Serializer @@ -84,12 +91,14 @@ current reading offset last error code + .. _function-archive_MemSerializer_rq_write_MemSerializer_void_q__implicit_int_0x3a: .. das:function:: MemSerializer.write(bytes: void? implicit; size: int) : bool Appends bytes at the end of the data. + :Arguments: * **bytes** : void? implicit * **size** : int @@ -100,6 +109,7 @@ Appends bytes at the end of the data. Reads bytes from data, advances the reading position. + :Arguments: * **bytes** : void? implicit * **size** : int @@ -110,6 +120,7 @@ Reads bytes from data, advances the reading position. Sets the last error code. + :Arguments: * **code** : string .. _function-archive_MemSerializer_rq_OK_MemSerializer_0x36: @@ -118,68 +129,76 @@ Sets the last error code. Implements 'OK' method, which returns true if the serializer is in a valid state. + .. _function-archive_MemSerializer_rq_extractData_MemSerializer_0x29: .. das:function:: MemSerializer.extractData() : array Extract the data from the serializer. + .. _function-archive_MemSerializer_rq_getCopyOfData_MemSerializer_0x2d: .. das:function:: MemSerializer.getCopyOfData() : array Returns copy of the data from the serializer. + .. _function-archive_MemSerializer_rq_getLastError_MemSerializer_0x32: .. das:function:: MemSerializer.getLastError() : string Returns last serialization error. + .. _function-archive_MemSerializer_0x21: .. das:function:: MemSerializer() : MemSerializer Initialize the serializer for reading or writing. + .. _function-archive_MemSerializer_array_ls_uint8_gr__0x25: .. das:function:: MemSerializer(from: array) : MemSerializer Initialize the serializer for reading from the given data. + :Arguments: * **from** : array + +++++++++++++ Serialization +++++++++++++ - * :ref:`read_raw (var arch: Archive; var value: auto(TT)&) : auto ` + * :ref:`read_raw (var arch: Archive; var value: auto(TT)&) : auto ` * :ref:`serialize (var arch: Archive; var value: float3x4) ` - * :ref:`serialize (var arch: Archive; var value: string&) ` + * :ref:`serialize (var arch: Archive; var value: string&) ` * :ref:`serialize (var arch: Archive; var value: float3x3) ` - * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` + * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` * :ref:`serialize (var arch: Archive; var value: float4x4) ` - * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` + * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` * :ref:`serialize (var arch: Archive; var value: table\) : auto ` - * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` - * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` - * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` - * :ref:`serialize (var arch: Archive; var value: auto(TT)[]) : auto ` + * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` + * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` + * :ref:`serialize (var arch: Archive; var value: auto(TT)&) : auto ` + * :ref:`serialize (var arch: Archive; var value: auto(TT)[]) : auto ` * :ref:`serialize (var arch: Archive; var value: array\) : auto ` * :ref:`serialize (var arch: Archive; var value: auto(TT)?) : auto ` - * :ref:`serialize_raw (var arch: Archive; var value: auto(TT)&) : auto ` - * :ref:`write_raw (var arch: Archive; var value: auto(TT)&) : auto ` + * :ref:`serialize_raw (var arch: Archive; var value: auto(TT)&) : auto ` + * :ref:`write_raw (var arch: Archive; var value: auto(TT)&) : auto ` -.. _function-archive_read_raw_Archive_autoTT_0x6b: +.. _function-archive_read_raw_Archive_autoTT_ref__0x6b: .. das:function:: read_raw(arch: Archive; value: auto(TT)&) : auto Read raw data (straight up bytes for raw pod) + :Arguments: * **arch** : :ref:`Archive ` - * **value** : auto(TT)& + * **value** : auto(TT)\ & serialize @@ -191,11 +210,12 @@ serialize Serializes float3x4 matrix + :Arguments: * **arch** : :ref:`Archive ` * **value** : :ref:`float3x4 ` -.. _function-archive_serialize_Archive_string: +.. _function-archive_serialize_Archive_string_ref_: .. das:function:: serialize(arch: Archive; value: string&) @@ -203,7 +223,7 @@ Serializes float3x4 matrix .. das:function:: serialize(arch: Archive; value: float3x3) -.. _function-archive_serialize_Archive_autoTT_0x78: +.. _function-archive_serialize_Archive_autoTT_ref__0x78: .. das:function:: serialize(arch: Archive; value: auto(TT)&) : auto @@ -211,7 +231,7 @@ Serializes float3x4 matrix .. das:function:: serialize(arch: Archive; value: float4x4) -.. _function-archive_serialize_Archive_autoTT_0x7e: +.. _function-archive_serialize_Archive_autoTT_ref__0x7e: .. das:function:: serialize(arch: Archive; value: auto(TT)&) : auto @@ -219,19 +239,19 @@ Serializes float3x4 matrix .. das:function:: serialize(arch: Archive; value: table) : auto -.. _function-archive_serialize_Archive_autoTT_0xa9: +.. _function-archive_serialize_Archive_autoTT_ref__0xa9: .. das:function:: serialize(arch: Archive; value: auto(TT)&) : auto -.. _function-archive_serialize_Archive_autoTT_0x9e: +.. _function-archive_serialize_Archive_autoTT_ref__0x9e: .. das:function:: serialize(arch: Archive; value: auto(TT)&) : auto -.. _function-archive_serialize_Archive_autoTT_0xb4: +.. _function-archive_serialize_Archive_autoTT_ref__0xb4: .. das:function:: serialize(arch: Archive; value: auto(TT)&) : auto -.. _function-archive_serialize_Archive_autoTT_0xc6: +.. _function-archive_serialize_Archive_autoTT_lb__rb__0xc6: .. das:function:: serialize(arch: Archive; value: auto(TT)[]) : auto @@ -245,51 +265,56 @@ Serializes float3x4 matrix ---- -.. _function-archive_serialize_raw_Archive_autoTT_0x62: +.. _function-archive_serialize_raw_Archive_autoTT_ref__0x62: .. das:function:: serialize_raw(arch: Archive; value: auto(TT)&) : auto Serialize raw data (straight up bytes for raw pod) + :Arguments: * **arch** : :ref:`Archive ` - * **value** : auto(TT)& + * **value** : auto(TT)\ & -.. _function-archive_write_raw_Archive_autoTT_0x71: +.. _function-archive_write_raw_Archive_autoTT_ref__0x71: .. das:function:: write_raw(arch: Archive; value: auto(TT)&) : auto Write raw data (straight up bytes for raw pod) + :Arguments: * **arch** : :ref:`Archive ` - * **value** : auto(TT)& + * **value** : auto(TT)\ & + ++++++++++++++ Memory archive ++++++++++++++ - * :ref:`mem_archive_load (var data: array\; var t: auto&; canfail: bool = false) : bool ` - * :ref:`mem_archive_save (var t: auto&) : auto ` + * :ref:`mem_archive_load (var data: array\; var t: auto&; canfail: bool = false) : bool ` + * :ref:`mem_archive_save (var t: auto&) : auto ` -.. _function-archive_mem_archive_load_array_ls_uint8_gr__auto_bool_0x121: +.. _function-archive_mem_archive_load_array_ls_uint8_gr__auto_ref__bool_0x121: .. das:function:: mem_archive_load(data: array; t: auto&; canfail: bool = false) : bool Loads the object from a memory archive. `data` is the array with the serialized data, returned from `mem_archive_save`. + :Arguments: * **data** : array - * **t** : auto& + * **t** : auto\ & * **canfail** : bool -.. _function-archive_mem_archive_save_auto_0x119: +.. _function-archive_mem_archive_save_auto_ref__0x119: .. das:function:: mem_archive_save(t: auto&) : auto Saves the object to a memory archive. Result is array with the serialized data. -:Arguments: * **t** : auto& + +:Arguments: * **t** : auto\ & diff --git a/doc/source/stdlib/array_boost.rst b/doc/source/stdlib/array_boost.rst index 252a1d75fa..a0e9270955 100644 --- a/doc/source/stdlib/array_boost.rst +++ b/doc/source/stdlib/array_boost.rst @@ -5,6 +5,8 @@ Boost package for array manipulation ==================================== +.. das:module:: array_boost + The ARRAY_BOOST module extends array operations with temporary array views over fixed-size arrays and C++ handled vectors, emptiness checks, sub-array views, and arithmetic operators on fixed-size arrays. @@ -13,6 +15,8 @@ All functions and symbols are in "array_boost" module, use require to get access require daslib/array_boost + + ++++++++++++++++ Temporary arrays ++++++++++++++++ @@ -39,6 +43,7 @@ Important requirements are: * each element follows the next one directly, with the stride equal to size of the element * object memory does not change within the lifetime of the returned array + :Arguments: * **arr** : auto implicit! .. _function-array_boost_temp_array__auto_implicit__eq__eq_const_0x2e: @@ -55,6 +60,7 @@ Important requirements are: ---- + +++++++++++ Empty check +++++++++++ @@ -67,8 +73,10 @@ Empty check returns true if 'v' has 0 elements. this also implies that `length(v)` is defined. + :Arguments: * **v** : auto(VecT) + ++++++++++++++ Sub-array view ++++++++++++++ @@ -86,13 +94,14 @@ array_view creates a view of the array, which is a temporary array that is valid only within the block + :Arguments: * **bytes** : array! * **offset** : int * **length** : int - * **blk** : block<(view:array#):void> + * **blk** : block<(view:array\ #):void> .. _function-array_boost_array_view_array_ls_autoTT_gr__int_int_block_ls_view_c_array_ls_TT_gr__hh__c_void_gr_: diff --git a/doc/source/stdlib/assert_once.rst b/doc/source/stdlib/assert_once.rst index 43f0034c43..14c94d526f 100644 --- a/doc/source/stdlib/assert_once.rst +++ b/doc/source/stdlib/assert_once.rst @@ -5,6 +5,8 @@ Assert once =========== +.. das:module:: assert_once + The ASSERT_ONCE module provides the ``assert_once`` macro — an assertion that triggers only on its first failure. Subsequent failures at the same location are silently ignored, preventing assertion storms in loops or frequently @@ -14,6 +16,8 @@ All functions and symbols are in "assert_once" module, use require to get access require daslib/assert_once + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -29,6 +33,8 @@ This macro convert assert_once(expr,message) to the following code:: __assert_once_I = false assert(false,message) + + +++++++++ Assertion +++++++++ @@ -41,6 +47,7 @@ Assertion Same as assert, only the check will be not be repeated after the assertion failed the first time. + :Arguments: * **expr** : bool * **message** : string diff --git a/doc/source/stdlib/ast.rst b/doc/source/stdlib/ast.rst index f3ac6e7645..c645befe12 100644 --- a/doc/source/stdlib/ast.rst +++ b/doc/source/stdlib/ast.rst @@ -5,6 +5,8 @@ AST manipulation library ======================== +.. das:module:: ast + The AST module provides access to the abstract syntax tree representation of daslang programs. It defines node types for all language constructs (expressions, statements, types, functions, structures, enumerations, etc.), visitors for tree traversal, and utilities for AST @@ -15,6 +17,8 @@ All functions and symbols are in "ast" module, use require to get access to it. require ast + + ++++++++++++ Type aliases ++++++++++++ @@ -62,6 +66,7 @@ properties of the `TypeDecl` object. * **autoToAlias** (0x20000) - The type is an auto-to-alias. + .. _alias-FieldDeclarationFlags: .. das:attribute:: bitfield FieldDeclarationFlags @@ -89,6 +94,7 @@ properties of the `FieldDeclaration` object. * **classMethod** (0x200) - This field is a class method. + .. _alias-StructureFlags: .. das:attribute:: bitfield StructureFlags @@ -136,6 +142,7 @@ properties of the `Structure` object. * **noGenCtor** (0x80000) - This structure does not generate a default constructor. + .. _alias-ExprGenFlags: .. das:attribute:: bitfield ExprGenFlags @@ -149,6 +156,7 @@ generation (genFlags) properties of the `Expression` object. * **userSaidItsSafe** (0x4) - Expression is marked as safe explicitly. + .. _alias-ExprLetFlags: .. das:attribute:: bitfield ExprLetFlags @@ -162,6 +170,7 @@ properties of the `ExprLet` object. * **itTupleExpansion** (0x4) - It's 'let itTupleExpansion' expression. + .. _alias-ExprFlags: .. das:attribute:: bitfield ExprFlags @@ -179,6 +188,7 @@ properties of the `Expression` object. * **isCallArgument** (0x10) - Expression is a call argument. + .. _alias-ExprPrintFlags: .. das:attribute:: bitfield ExprPrintFlags @@ -192,6 +202,7 @@ printing properties of the `Expression` object. * **bottomLevel** (0x4) - Its a bottom level expression - no sub-expressions or nesting. + .. _alias-FunctionFlags: .. das:attribute:: bitfield FunctionFlags @@ -263,6 +274,7 @@ properties of the `Function` object. * **macroInit** (0x80000000) - Function is macro init. + .. _alias-MoreFunctionFlags: .. das:attribute:: bitfield MoreFunctionFlags @@ -271,7 +283,7 @@ additional properties of the `Function` object. :Fields: * **macroFunction** (0x1) - Function is a macro function. - * **needStringCast** (0x2) - Converts das string arguments to C++ char *. Empty string, which is null in das, is converted to "". + * **needStringCast** (0x2) - Converts das string arguments to C++ ``char *``. Empty string, which is null in das, is converted to "". * **aotHashDeppendsOnArguments** (0x4) - Function hash depends on arguments. @@ -330,6 +342,7 @@ additional properties of the `Function` object. * **isConstClassMethod** (0x20000000) - Function is a const class method. + .. _alias-FunctionSideEffectFlags: .. das:attribute:: bitfield FunctionSideEffectFlags @@ -349,6 +362,7 @@ side-effect properties of the `Function` object. * **invoke** (0x20) - Function is using 'invoke', so we don't know any additional side effects. + .. _alias-VariableFlags: .. das:attribute:: bitfield VariableFlags @@ -400,6 +414,7 @@ properties of the `Variable` object. * **single_return_via_move** (0x200000) - This variable is returned via move in a function with only one return path + .. _alias-VariableAccessFlags: .. das:attribute:: bitfield VariableAccessFlags @@ -419,6 +434,7 @@ access properties of the `Variable` object. * **access_fold** (0x20) - Variable was folded aways (optimized out). + .. _alias-ExprBlockFlags: .. das:attribute:: bitfield ExprBlockFlags @@ -460,6 +476,7 @@ properties of the `ExprBlock` object. * **isGeneratorBlock** (0x10000) - Block is a generator block. + .. _alias-ExprAtFlags: .. das:attribute:: bitfield ExprAtFlags @@ -477,6 +494,7 @@ properties of the `ExprAt` object. * **under_clone** (0x10) - The expression is under a clone operation. + .. _alias-ExprMakeLocalFlags: .. das:attribute:: bitfield ExprMakeLocalFlags @@ -496,6 +514,7 @@ properties of the `ExprMakeLocal` object (`ExprMakeArray`, `ExprMakeStruct`, 'Ex * **alwaysAlias** (0x20) - Always alias the result, so temp value is always allocated on the stack. + .. _alias-ExprAscendFlags: .. das:attribute:: bitfield ExprAscendFlags @@ -509,6 +528,7 @@ properties of the `ExprAscend` object. * **isMakeLambda** (0x4) - Is a lambda expression. + .. _alias-ExprCastFlags: .. das:attribute:: bitfield ExprCastFlags @@ -520,6 +540,7 @@ properties of the `ExprCast` object. * **reinterpretCast** (0x2) - Reinterpret cast, i.e. casting between unrelated types (like pointer to integer) + .. _alias-ExprVarFlags: .. das:attribute:: bitfield ExprVarFlags @@ -543,6 +564,7 @@ properties of the `ExprVar` object. * **under_clone** (0x80) - This is a foo := bar expression, and the variable is being cloned to. + .. _alias-ExprMakeStructFlags: .. das:attribute:: bitfield ExprMakeStructFlags @@ -574,6 +596,7 @@ properties of the `ExprMakeStruct` object. * **canShadowBlock** (0x800) - 'where' section argument can shadow other variables. This is for nested comprehensions and such. + .. _alias-MakeFieldDeclFlags: .. das:attribute:: bitfield MakeFieldDeclFlags @@ -585,6 +608,7 @@ Properties of the `MakeFieldDecl` object. * **cloneSemantics** (0x2) - Initialized with clone semantics, := + .. _alias-ExprFieldDerefFlags: .. das:attribute:: bitfield ExprFieldDerefFlags @@ -596,6 +620,7 @@ dereferencing properties of the `ExprField` object. * **ignoreCaptureConst** (0x2) - Ignore capture const, i.e. was captured as constant - but used as mutable. + .. _alias-ExprFieldFieldFlags: .. das:attribute:: bitfield ExprFieldFieldFlags @@ -613,6 +638,7 @@ field properties of the `ExprField` object. * **under_clone** (0x10) - Under clone, i.e. 'Foo.bar := ...' + .. _alias-ExprSwizzleFieldFlags: .. das:attribute:: bitfield ExprSwizzleFieldFlags @@ -626,6 +652,7 @@ properties of the `ExprSwizzle` object. * **write** (0x4) - This is part of a write operation, and a field or part of it is being assigned to. + .. _alias-ExprYieldFlags: .. das:attribute:: bitfield ExprYieldFlags @@ -637,6 +664,7 @@ properties of the `ExprYield` object. * **skipLockCheck** (0x2) - Skip lock checks. + .. _alias-ExprReturnFlags: .. das:attribute:: bitfield ExprReturnFlags @@ -662,6 +690,7 @@ properties of the `ExprReturn` object. * **skipLockCheck** (0x100) - Skip lock checks. + .. _alias-ExprMakeBlockFlags: .. das:attribute:: bitfield ExprMakeBlockFlags @@ -673,6 +702,7 @@ properties of the `ExprMakeBlock` object. * **isLocalFunction** (0x2) - Is a local function, i.e. @@(...) { ... } + .. _alias-CopyFlags: .. das:attribute:: bitfield CopyFlags @@ -686,6 +716,7 @@ properties of the `ExprCopy` object. * **allowConstantLValue** (0x4) - Promote to clone, i.e. this is 'foo := bar' and not 'foo = bar' + .. _alias-MoveFlags: .. das:attribute:: bitfield MoveFlags @@ -701,6 +732,7 @@ Properties of the `ExprMove` object. * **podDelete** (0x8) - Move is a POD delete. + .. _alias-IfFlags: .. das:attribute:: bitfield IfFlags @@ -712,121 +744,146 @@ properties of the `ExprIf` object. * **doNotFold** (0x2) - Do not fold this 'if' expression during compilation. + .. _alias-ExpressionPtr: .. das:attribute:: ExpressionPtr = smart_ptr Smart pointer to an `Expression` object. The fundamental handle type for all AST expression nodes. + .. _alias-ProgramPtr: .. das:attribute:: ProgramPtr = smart_ptr Smart pointer to a `Program` object. Represents the root of a compiled daslang program, containing all modules, functions, and structures. + .. _alias-TypeDeclPtr: .. das:attribute:: TypeDeclPtr = smart_ptr Smart pointer to a `TypeDecl` object. The fundamental handle type for all type declarations in the AST type system. + .. _alias-VectorTypeDeclPtr: .. das:attribute:: VectorTypeDeclPtr = dasvector`smart_ptr`TypeDecl Smart pointer to a ``das::vector``. Represents an ordered collection of type declarations, typically used for function argument lists and tuple fields. + .. _alias-EnumerationPtr: .. das:attribute:: EnumerationPtr = smart_ptr Smart pointer to an `Enumeration` object. Used for creating and manipulating enumeration declarations in the AST. + .. _alias-StructurePtr: .. das:attribute:: StructurePtr = smart_ptr Smart pointer to a `Structure` object. Used for creating and manipulating structure declarations in the AST. + .. _alias-FunctionPtr: .. das:attribute:: FunctionPtr = smart_ptr Smart pointer to a `Function` object. Used for creating and manipulating function declarations in the AST. + .. _alias-VariablePtr: .. das:attribute:: VariablePtr = smart_ptr Smart pointer to a `Variable` object. Used for creating and manipulating variable declarations in the AST. + .. _alias-MakeFieldDeclPtr: .. das:attribute:: MakeFieldDeclPtr = smart_ptr Smart pointer to a `MakeFieldDecl` object. Represents a single field initializer in structure or variant construction expressions. + .. _alias-ExprMakeBlockPtr: .. das:attribute:: ExprMakeBlockPtr = smart_ptr Smart pointer to an `ExprMakeBlock` expression. Wraps block or lambda creation expressions in the AST. + .. _alias-FunctionAnnotationPtr: .. das:attribute:: FunctionAnnotationPtr = smart_ptr Smart pointer to a `FunctionAnnotation` object. Used for registering and managing function annotation macros. + .. _alias-StructureAnnotationPtr: .. das:attribute:: StructureAnnotationPtr = smart_ptr Smart pointer to a `StructureAnnotation` object. Used for registering and managing structure annotation macros. + .. _alias-EnumerationAnnotationPtr: .. das:attribute:: EnumerationAnnotationPtr = smart_ptr Smart pointer to an `EnumerationAnnotation` object. Used for registering and managing enumeration annotation macros. + .. _alias-PassMacroPtr: .. das:attribute:: PassMacroPtr = smart_ptr Smart pointer to a `PassMacro` object. Used for registering and managing custom inference pass macros. + .. _alias-VariantMacroPtr: .. das:attribute:: VariantMacroPtr = smart_ptr Smart pointer to a `VariantMacro` object. Used for registering and managing custom variant dispatch macros. + .. _alias-ReaderMacroPtr: .. das:attribute:: ReaderMacroPtr = smart_ptr Smart pointer to a `ReaderMacro` object. Used for registering and managing custom reader (parsing) macros. + .. _alias-CommentReaderPtr: .. das:attribute:: CommentReaderPtr = smart_ptr Smart pointer to a `CommentReader` object. Used for registering and managing custom comment parsing macros. + .. _alias-CallMacroPtr: .. das:attribute:: CallMacroPtr = smart_ptr Smart pointer to a `CallMacro` object. Used for registering and managing custom call-like expression macros. + .. _alias-TypeInfoMacroPtr: .. das:attribute:: TypeInfoMacroPtr = smart_ptr Smart pointer to a `TypeInfoMacro` object. Used for registering and managing custom ``typeinfo`` trait macros. + .. _alias-ForLoopMacroPtr: .. das:attribute:: ForLoopMacroPtr = smart_ptr Smart pointer to a `ForLoopMacro` object. Used for registering and managing custom for-loop macros. + .. _alias-CaptureMacroPtr: .. das:attribute:: CaptureMacroPtr = smart_ptr Smart pointer to a `CaptureMacro` object. Used for registering and managing custom lambda capture macros. + .. _alias-TypeMacroPtr: .. das:attribute:: TypeMacroPtr = smart_ptr Smart pointer to a `TypeMacro` object. Used for registering and managing custom type declaration macros. + .. _alias-SimulateMacroPtr: .. das:attribute:: SimulateMacroPtr = smart_ptr Smart pointer to a `SimulateMacro` object. Used for registering and managing macros that hook into the simulation phase. + + ++++++++++++ Enumerations ++++++++++++ @@ -848,6 +905,7 @@ Enumeration with lambda variables capture modes. * **capture_by_move** = 4 - Value is moved. + .. _enum-ast-SideEffects: .. das:attribute:: SideEffects @@ -877,6 +935,8 @@ Enumeration with all possible side effects of expression or function. * **inferredSideEffects** = 56 - Mask for all sideefects, which can be inferred from the code. + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -888,6 +948,7 @@ Handled structures Object which holds list of `Module` and provides access to them. + .. _handle-ast-Expression: .. das:attribute:: Expression @@ -907,6 +968,7 @@ Any expression (base class). * **printFlags** : :ref:`ExprPrintFlags ` - Expression print flags + .. _handle-ast-TypeDecl: .. das:attribute:: TypeDecl @@ -917,528 +979,616 @@ Any expression (base class). Returns whether the given type can be ahead-of-time compiled. + .. _function-ast__dot__rq_isExprType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isExprType() : bool Returns whether the type hierarchy contains an expression type. + .. _function-ast__dot__rq_isSimpleType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isSimpleType() : bool Returns whether the given type is a simple non-void type that does not require resolution at inference time. + .. _function-ast__dot__rq_isArray_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isArray() : bool Returns whether the given type is an array type. + .. _function-ast__dot__rq_isGoodIteratorType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isGoodIteratorType() : bool Returns whether the given type is an iterator type. + .. _function-ast__dot__rq_isGoodArrayType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isGoodArrayType() : bool Returns whether the given type is a dynamic array type. + .. _function-ast__dot__rq_isGoodTableType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isGoodTableType() : bool Returns whether the given type is a table type. + .. _function-ast__dot__rq_isGoodBlockType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isGoodBlockType() : bool Returns whether the given type is a block type. + .. _function-ast__dot__rq_isGoodFunctionType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isGoodFunctionType() : bool Returns whether the given type is a function type. + .. _function-ast__dot__rq_isGoodLambdaType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isGoodLambdaType() : bool Returns whether the given type is a lambda type. + .. _function-ast__dot__rq_isGoodTupleType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isGoodTupleType() : bool Returns whether the given type is a tuple type. + .. _function-ast__dot__rq_isGoodVariantType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isGoodVariantType() : bool Returns whether the given type is a variant type. + .. _function-ast__dot__rq_isVoid_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isVoid() : bool Returns whether the given type is the void type. + .. _function-ast__dot__rq_isAnyType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isAnyType() : bool Returns whether the given type is the any type, passed as vec4f via standard C++ interop. + .. _function-ast__dot__rq_isRef_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isRef() : bool Returns whether the given type is a reference value. + .. _function-ast__dot__rq_isRefType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isRefType() : bool Returns whether the given type is a reference type. + .. _function-ast__dot__rq_canWrite_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canWrite() : bool Returns whether the given type can be written to. + .. _function-ast__dot__rq_isAotAlias_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isAotAlias() : bool Returns whether the type definition contains an AOT alias type. + .. _function-ast__dot__rq_isShareable_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isShareable() : bool Returns whether the given type is shareable across contexts. + .. _function-ast__dot__rq_isIndex_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isIndex() : bool Returns whether the given type is an index type. + .. _function-ast__dot__rq_isBool_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isBool() : bool Returns whether the given type is a boolean type. + .. _function-ast__dot__rq_isInteger_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isInteger() : bool Returns whether the given type is an integer type. + .. _function-ast__dot__rq_isSignedInteger_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isSignedInteger() : bool Returns whether the given type is a signed integer type. + .. _function-ast__dot__rq_isUnsignedInteger_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isUnsignedInteger() : bool Returns whether the given type is an unsigned integer type. + .. _function-ast__dot__rq_isSignedIntegerOrIntVec_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isSignedIntegerOrIntVec() : bool Returns whether the given type is a signed integer or signed integer vector type. + .. _function-ast__dot__rq_isUnsignedIntegerOrIntVec_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isUnsignedIntegerOrIntVec() : bool Returns whether the given type is an unsigned integer or unsigned integer vector type. + .. _function-ast__dot__rq_isFloatOrDouble_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isFloatOrDouble() : bool Returns whether the given type is a float or double type. + .. _function-ast__dot__rq_isNumeric_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isNumeric() : bool Returns whether the given type is a numeric type. + .. _function-ast__dot__rq_isNumericComparable_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isNumericComparable() : bool Returns whether the given type supports numeric comparison. + .. _function-ast__dot__rq_isPointer_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isPointer() : bool Returns whether the given type is a pointer type. + .. _function-ast__dot__rq_isSmartPointer_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isSmartPointer() : bool Returns whether the given type is a smart pointer type. + .. _function-ast__dot__rq_isVoidPointer_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isVoidPointer() : bool Returns whether the given type is a void pointer type. + .. _function-ast__dot__rq_isIterator_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isIterator() : bool Returns whether the given type is an iterator type. + .. _function-ast__dot__rq_isEnum_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isEnum() : bool Returns whether the given type is an enumeration type. + .. _function-ast__dot__rq_isEnumT_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isEnumT() : bool Returns whether the base type of the given type is an enumeration type. + .. _function-ast__dot__rq_isHandle_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isHandle() : bool Returns whether the given type is a handle type, representing a C++ type exposed to daslang via TypeAnnotation. + .. _function-ast__dot__rq_isStructure_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isStructure() : bool Returns whether the given type is a structure type. + .. _function-ast__dot__rq_isClass_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isClass() : bool Returns whether the given type is a class type. + .. _function-ast__dot__rq_isFunction_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isFunction() : bool Returns whether the given type is a function type. + .. _function-ast__dot__rq_isTuple_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isTuple() : bool Returns whether the given type is a tuple type. + .. _function-ast__dot__rq_isVariant_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isVariant() : bool Returns whether the given type is a variant type. + .. _function-ast__dot__rq_sizeOf_TypeDecl_implicit: .. das:function:: TypeDecl implicit.sizeOf() : int Returns the size of the given type in bytes. + .. _function-ast__dot__rq_countOf_TypeDecl_implicit: .. das:function:: TypeDecl implicit.countOf() : int Returns the number of elements if the given type is a fixed array, otherwise returns 1. + .. _function-ast__dot__rq_alignOf_TypeDecl_implicit: .. das:function:: TypeDecl implicit.alignOf() : int Returns the memory alignment requirement of the type in bytes. + .. _function-ast__dot__rq_baseSizeOf_TypeDecl_implicit: .. das:function:: TypeDecl implicit.baseSizeOf() : int Returns the size of the given type in bytes, excluding fixed array dimensions. + .. _function-ast__dot__rq_stride_TypeDecl_implicit: .. das:function:: TypeDecl implicit.stride() : int Returns the stride size in bytes of an element in a fixed array type. + .. _function-ast__dot__rq_tupleSize_TypeDecl_implicit: .. das:function:: TypeDecl implicit.tupleSize() : int Returns the size of the given tuple type in bytes. + .. _function-ast__dot__rq_tupleAlign_TypeDecl_implicit: .. das:function:: TypeDecl implicit.tupleAlign() : int Returns the alignment of the given tuple type in bytes. + .. _function-ast__dot__rq_variantSize_TypeDecl_implicit: .. das:function:: TypeDecl implicit.variantSize() : int Returns the size of the given variant type in bytes. + .. _function-ast__dot__rq_variantAlign_TypeDecl_implicit: .. das:function:: TypeDecl implicit.variantAlign() : int Returns the alignment of the given variant type in bytes. + .. _function-ast__dot__rq_canCopy_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canCopy() : bool Returns whether the given type can be copied. + .. _function-ast__dot__rq_canMove_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canMove() : bool Returns whether the given type can be moved. + .. _function-ast__dot__rq_canClone_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canClone() : bool Returns whether the given type can be cloned. + .. _function-ast__dot__rq_canCloneFromConst_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canCloneFromConst() : bool Returns whether the given type can be cloned from a const instance. + .. _function-ast__dot__rq_canNew_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canNew() : bool Returns whether the given type can be heap-allocated via the new operator. + .. _function-ast__dot__rq_canDeletePtr_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canDeletePtr() : bool Returns whether the pointer to the given type can be deleted. + .. _function-ast__dot__rq_canDelete_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canDelete() : bool Returns whether the given type can be deleted. + .. _function-ast__dot__rq_needDelete_TypeDecl_implicit: .. das:function:: TypeDecl implicit.needDelete() : bool Returns whether the given type requires explicit deletion. + .. _function-ast__dot__rq_isPod_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isPod() : bool Returns whether the given type is a plain old data (POD) type. + .. _function-ast__dot__rq_isRawPod_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isRawPod() : bool Returns whether the given type is a raw POD type containing no pointers or strings. + .. _function-ast__dot__rq_isNoHeapType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isNoHeapType() : bool Returns whether the given type can be used without heap allocation. + .. _function-ast__dot__rq_isWorkhorseType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isWorkhorseType() : bool Returns whether the given type is a workhorse type, which is a built-in non-reference type. + .. _function-ast__dot__rq_isPolicyType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isPolicyType() : bool Returns whether the given type is a policy type with SimNode implementations available for it. + .. _function-ast__dot__rq_isVecPolicyType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isVecPolicyType() : bool Returns whether the given type is a vector policy type, which is any policy type other than string. + .. _function-ast__dot__rq_isReturnType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isReturnType() : bool Returns whether the given type can be used as a return type, which includes anything except block. + .. _function-ast__dot__rq_isCtorType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isCtorType() : bool Returns whether the given basic type is a constructor type that can be constructed via its type name, such as int(3.4). + .. _function-ast__dot__rq_isRange_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isRange() : bool Returns whether the given type is a range type. + .. _function-ast__dot__rq_isString_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isString() : bool Returns whether the given type is a string type. + .. _function-ast__dot__rq_isConst_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isConst() : bool Returns whether the given type is const-qualified. + .. _function-ast__dot__rq_isFoldable_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isFoldable() : bool Returns whether the given type is foldable, such as integer or float, as opposed to pointer or array. + .. _function-ast__dot__rq_isAlias_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isAlias() : bool Returns whether the type definition contains an alias type. + .. _function-ast__dot__rq_isAutoArrayResolved_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isAutoArrayResolved() : bool Returns whether all fixed array dimensions are fully resolved with no auto or expression dimensions remaining. + .. _function-ast__dot__rq_isAuto_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isAuto() : bool Returns whether the type definition contains an auto type. + .. _function-ast__dot__rq_isAutoOrAlias_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isAutoOrAlias() : bool Returns whether the type definition contains an auto or alias type. + .. _function-ast__dot__rq_isVectorType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isVectorType() : bool Returns whether the given type is a vector type such as int2, float3, or range64. + .. _function-ast__dot__rq_isBitfield_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isBitfield() : bool Returns whether the given type is a bitfield type. + .. _function-ast__dot__rq_isLocal_TypeDecl_implicit: .. das:function:: TypeDecl implicit.isLocal() : bool Returns whether the given type is a local type that can be allocated on the stack. + .. _function-ast__dot__rq_hasClasses_TypeDecl_implicit: .. das:function:: TypeDecl implicit.hasClasses() : bool Returns whether the type definition contains any class types. + .. _function-ast__dot__rq_hasNonTrivialCtor_TypeDecl_implicit: .. das:function:: TypeDecl implicit.hasNonTrivialCtor() : bool Returns whether the type definition contains any non-trivial constructors. + .. _function-ast__dot__rq_hasNonTrivialDtor_TypeDecl_implicit: .. das:function:: TypeDecl implicit.hasNonTrivialDtor() : bool Returns whether the type definition contains any non-trivial destructors. + .. _function-ast__dot__rq_hasNonTrivialCopy_TypeDecl_implicit: .. das:function:: TypeDecl implicit.hasNonTrivialCopy() : bool Returns whether the type definition contains any non-trivial copy operations. + .. _function-ast__dot__rq_canBePlacedInContainer_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canBePlacedInContainer() : bool Returns whether the given type can be placed in a container. + .. _function-ast__dot__rq_vectorBaseType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.vectorBaseType() : Type Returns the scalar base type of a vector type, for example float for float4. + .. _function-ast__dot__rq_vectorDim_TypeDecl_implicit: .. das:function:: TypeDecl implicit.vectorDim() : int Returns the number of components in a vector type, for example 4 for float4. + .. _function-ast__dot__rq_canInitWithZero_TypeDecl_implicit: .. das:function:: TypeDecl implicit.canInitWithZero() : bool Returns whether the given type can be initialized by zeroing its memory. + .. _function-ast__dot__rq_rangeBaseType_TypeDecl_implicit: .. das:function:: TypeDecl implicit.rangeBaseType() : Type Returns the base type of a range type, for example int64 for range64. + .. _function-ast__dot__rq_unsafeInit_TypeDecl_implicit: .. das:function:: TypeDecl implicit.unsafeInit() : bool Returns whether the given type requires initialization and skipping it would be unsafe. + .. _function-ast__dot__rq_get_mnh_TypeDecl_implicit: .. das:function:: TypeDecl implicit.get_mnh() : uint64 Returns the mangled name hash of the given type. + :Properties: * **canAot** : bool * **isExprType** : bool @@ -1646,6 +1796,7 @@ Any type declaration. * **_module** : :ref:`Module `? - Module this type belongs to + .. _handle-ast-Structure: .. das:attribute:: Structure @@ -1656,6 +1807,7 @@ Any type declaration. Returns the size of the given type in bytes. + :Properties: * **sizeOf** : int Structure declaration. @@ -1675,6 +1827,7 @@ Structure declaration. * **flags** : :ref:`StructureFlags ` - Structure flags + .. _handle-ast-FieldDeclaration: .. das:attribute:: FieldDeclaration @@ -1696,6 +1849,7 @@ Structure field declaration. * **flags** : :ref:`FieldDeclarationFlags ` - Field flags + .. _handle-ast-EnumEntry: .. das:attribute:: EnumEntry @@ -1711,6 +1865,7 @@ Entry in the enumeration. * **value** : smart_ptr< :ref:`Expression `> - Value of the enumeration entry (typicall 'ExprConst' derivative) + .. _handle-ast-Enumeration: .. das:attribute:: Enumeration @@ -1736,6 +1891,7 @@ Enumeration declaration. * **isPrivate** : bool - Is this enumeration private (not visible from outside the module) + .. _handle-ast-Function: .. das:attribute:: Function @@ -1746,18 +1902,21 @@ Enumeration declaration. Returns the origin function, indicating which generic function this was instantiated from, if any. + .. _function-ast__dot__rq_getMangledNameHash_Function_implicit: .. das:function:: Function implicit.getMangledNameHash() : uint64 Returns the mangled name hash of the given function. + .. _function-ast__dot__rq_isGeneric_Function_implicit: .. das:function:: Function implicit.isGeneric() : bool Returns whether the given function is a generic function. + :Properties: * **origin** : :ref:`Function `? * **getMangledNameHash** : uint64 @@ -1805,6 +1964,7 @@ Function declaration. * **aotHash** : uint64 - Hash of the function signature for AOT purposes + .. _handle-ast-BuiltInFunction: .. das:attribute:: BuiltInFunction @@ -1852,6 +2012,7 @@ Bindings for the 'BuiltInFunction', which is used for the builtin (bound) functi * **cppName** : :ref:`das_string ` - C++ function name. + .. _handle-ast-ExternalFnBase: .. das:attribute:: ExternalFnBase @@ -1900,6 +2061,7 @@ Bindings for the 'BuiltInFunction', which is used for the builtin (bound) functi * **cppName** : :ref:`das_string ` - C++ function name. + .. _handle-ast-InferHistory: .. das:attribute:: InferHistory @@ -1911,6 +2073,7 @@ Generic function infer history. * **func** : :ref:`Function `? - Function being inferred + .. _handle-ast-Variable: .. das:attribute:: Variable @@ -1921,12 +2084,14 @@ Generic function infer history. Returns whether the given variable is never accessed in the code. + .. _function-ast__dot__rq_getMangledNameHash_Variable_implicit: .. das:function:: Variable implicit.getMangledNameHash() : uint64 Returns the mangled name hash of the given function. + :Properties: * **isAccessUnused** : bool * **getMangledNameHash** : uint64 @@ -1960,6 +2125,7 @@ Variable declaration. * **annotation** : :ref:`AnnotationArgumentList ` - Annotations attached to this variable + .. _handle-ast-AstContext: .. das:attribute:: AstContext @@ -1977,6 +2143,7 @@ Lexical context for the particular expression. * **_with** : vector> - Stack of active 'with' expressions + .. _handle-ast-ExprBlock: .. das:attribute:: ExprBlock @@ -2024,6 +2191,7 @@ Any block expression, including regular blocks and all types of closures. * **inFunction** : :ref:`Function `? - Which function this block belongs to + .. _handle-ast-ExprLet: .. das:attribute:: ExprLet @@ -2049,6 +2217,7 @@ Local variable declaration (`let v = expr;`). * **letFlags** : :ref:`ExprLetFlags ` - Properties of the `ExprLet` object. + .. _handle-ast-ExprStringBuilder: .. das:attribute:: ExprStringBuilder @@ -2072,6 +2241,7 @@ String builder expression ("blah{blah1}blah2"). * **stringBuilderFlags** : :ref:`StringBuilderFlags ` - Flags specific to string builder expressions + .. _handle-ast-MakeFieldDecl: .. das:attribute:: MakeFieldDecl @@ -2089,6 +2259,7 @@ Part of `ExprMakeStruct`, declares single field (`a = expr` or `a <- expr` etc) * **flags** : :ref:`MakeFieldDeclFlags ` - Flags specific to this field declaration + .. _handle-ast-ExprNamedCall: .. das:attribute:: ExprNamedCall @@ -2116,6 +2287,7 @@ Named call (`call([argname1=expr1, argname2=expr2])`). * **argumentsFailedToInfer** : bool - Whether any arguments failed to infer their types + .. _handle-ast-ExprLooksLikeCall: .. das:attribute:: ExprLooksLikeCall @@ -2143,6 +2315,7 @@ Anything which looks like call (`call(expr1,expr2)`). * **atEnclosure** : :ref:`LineInfo ` - Location of the expression in source code + .. _handle-ast-ExprCallFunc: .. das:attribute:: ExprCallFunc @@ -2174,6 +2347,7 @@ Actual function call (`func(expr1,...)`). * **stackTop** : uint - Stack top at the point of call, if temporary variable allocation is needed + .. _handle-ast-ExprNew: .. das:attribute:: ExprNew @@ -2209,6 +2383,7 @@ New expression (`new Foo`, `new Bar(expr1..)`, but **NOT** `new [[Foo ...]]`) * **initializer** : bool - Whether there is an initializer for the new expression, or it's just default construction + .. _handle-ast-ExprCall: .. das:attribute:: ExprCall @@ -2246,6 +2421,7 @@ Anything which looks like call (`call(expr1,expr2)`). * **notDiscarded** : bool - If the call result is not discarded + .. _handle-ast-ExprPtr2Ref: .. das:attribute:: ExprPtr2Ref @@ -2271,6 +2447,7 @@ Pointer dereference (`*expr` or `deref(expr)`). * **assumeNoAlias** : bool - If true, assume no aliasing occurs + .. _handle-ast-ExprNullCoalescing: .. das:attribute:: ExprNullCoalescing @@ -2298,6 +2475,7 @@ Null coalescing (`expr1 ?? default_value`). * **defaultValue** : smart_ptr< :ref:`Expression `> - Default value expression + .. _handle-ast-ExprAt: .. das:attribute:: ExprAt @@ -2323,6 +2501,7 @@ Index lookup (`expr[expr1]`). * **atFlags** : :ref:`ExprAtFlags ` - Flags specific to `ExprAt` expressions + .. _handle-ast-ExprSafeAt: .. das:attribute:: ExprSafeAt @@ -2348,6 +2527,7 @@ Safe index lookup (`expr?[expr1]`). * **atFlags** : :ref:`ExprAtFlags ` - Flags specific to `ExprAt` expressions + .. _handle-ast-ExprIs: .. das:attribute:: ExprIs @@ -2371,6 +2551,7 @@ Is expression for variants and such (`expr is Foo`). * **typeexpr** : smart_ptr< :ref:`TypeDecl `> - Type being checked against + .. _handle-ast-ExprOp: .. das:attribute:: ExprOp @@ -2378,6 +2559,7 @@ Is expression for variants and such (`expr is Foo`). Compilation time only base class for any operator. + .. _handle-ast-ExprOp2: .. das:attribute:: ExprOp2 @@ -2415,6 +2597,7 @@ Two operand operator (`expr1 + expr2`) * **right** : smart_ptr< :ref:`Expression `> - Right operand expression + .. _handle-ast-ExprOp3: .. das:attribute:: ExprOp3 @@ -2454,6 +2637,7 @@ Three operand operator (`cond ? expr1 : expr2`) * **right** : smart_ptr< :ref:`Expression `> - Right operand expression + .. _handle-ast-ExprCopy: .. das:attribute:: ExprCopy @@ -2493,6 +2677,7 @@ Copy operator (`expr1 = expr2`) * **copy_flags** : :ref:`CopyFlags ` - Flags specific to copy operation + .. _handle-ast-ExprMove: .. das:attribute:: ExprMove @@ -2532,6 +2717,7 @@ Move operator (`expr1 <- expr2`) * **move_flags** : :ref:`MoveFlags ` - Flags specific to move operation + .. _handle-ast-ExprClone: .. das:attribute:: ExprClone @@ -2569,6 +2755,7 @@ Clone operator (`expr1 := expr2`) * **right** : smart_ptr< :ref:`Expression `> - Right operand expression + .. _handle-ast-ExprWith: .. das:attribute:: ExprWith @@ -2592,6 +2779,7 @@ With section (`with expr {your; block; here}`). * **body** : smart_ptr< :ref:`Expression `> - The body of the with block + .. _handle-ast-ExprAssume: .. das:attribute:: ExprAssume @@ -2617,6 +2805,7 @@ Assume expression (`assume name = expr`) or (`typedef name = type`). * **assumeType** : smart_ptr< :ref:`TypeDecl `> - The type being assumed, if specified + .. _handle-ast-ExprWhile: .. das:attribute:: ExprWhile @@ -2640,6 +2829,7 @@ While loop (`while expr {your; block; here;}`) * **body** : smart_ptr< :ref:`Expression `> - The body of the while loop + .. _handle-ast-ExprTryCatch: .. das:attribute:: ExprTryCatch @@ -2663,6 +2853,7 @@ Try-recover expression (`try {your; block; here;} recover {your; recover; here;} * **catch_block** : smart_ptr< :ref:`Expression `> - The recover block + .. _handle-ast-ExprIfThenElse: .. das:attribute:: ExprIfThenElse @@ -2690,6 +2881,7 @@ If-then-else expression (`if expr1 {your; block; here;} else {your; block; here; * **if_flags** : :ref:`IfFlags ` - Flags specific to if-then-else expressions + .. _handle-ast-ExprFor: .. das:attribute:: ExprFor @@ -2731,6 +2923,7 @@ For loop (`for expr1 in expr2 {your; block; here;}`) * **canShadow** : bool - Whether shadowing is allowed, i.e. if the iterator names can shadow outer scope variables + .. _handle-ast-ExprMakeLocal: .. das:attribute:: ExprMakeLocal @@ -2758,6 +2951,7 @@ Any make expression (`ExprMakeBlock`, `ExprMakeTuple`, `ExprMakeVariant`, `ExprM * **makeFlags** : :ref:`ExprMakeLocalFlags ` - Flags specific to make-local expressions + .. _handle-ast-ExprMakeStruct: .. das:attribute:: ExprMakeStruct @@ -2793,6 +2987,7 @@ Make structure expression (`[[YourStruct v1=expr1elem1, v2=expr2elem1, ...; v1=e * **makeStructFlags** : :ref:`ExprMakeStructFlags ` - Flags specific to make-struct expressions + .. _handle-ast-ExprMakeVariant: .. das:attribute:: ExprMakeVariant @@ -2822,6 +3017,7 @@ Make variant expression (`[YourVariant variantName=expr1]`) * **variants** : vector> - Array of variants being made + .. _handle-ast-ExprMakeArray: .. das:attribute:: ExprMakeArray @@ -2855,6 +3051,7 @@ Make array expression (`[[auto 1;2;3]]` or `[{auto "foo";"bar"}]` for static and * **gen2** : bool - If gen2 syntax is used (i.e. `[...]` instead of `[[...]]`) + .. _handle-ast-ExprMakeTuple: .. das:attribute:: ExprMakeTuple @@ -2890,6 +3087,7 @@ Make tuple expression (`[[auto f1,f2,f3]]`) * **isKeyValue** : bool - If key-value syntax is used (i.e. `[key=>val; key2=>val2]`) + .. _handle-ast-ExprArrayComprehension: .. das:attribute:: ExprArrayComprehension @@ -2919,6 +3117,7 @@ Array comprehension (`[for (x in 0..3); x]`, `[iterator for (y in range(100)); x * **tableSyntax** : bool - If table syntax is used (i.e. `{for ...}` instead of `[for]`) + .. _handle-ast-TypeInfoMacro: .. das:attribute:: TypeInfoMacro @@ -2930,6 +3129,7 @@ Compilation time only structure which holds live information about typeinfo expr * **_module** : :ref:`Module `? - The module where the macro is defined + .. _handle-ast-ExprTypeInfo: .. das:attribute:: ExprTypeInfo @@ -2961,6 +3161,7 @@ typeinfo() expression (`typeinfo dim(a)`, `typeinfois_ref_type()`) * **macro** : :ref:`TypeInfoMacro `? - The macro associated with the typeinfo expression + .. _handle-ast-ExprTypeDecl: .. das:attribute:: ExprTypeDecl @@ -2982,6 +3183,7 @@ typedecl() expression (`typedecl(1+2)`) * **typeexpr** : smart_ptr< :ref:`TypeDecl `> - The type expression being queried for type information + .. _handle-ast-ExprLabel: .. das:attribute:: ExprLabel @@ -3005,6 +3207,7 @@ Label (`label 13:`) * **comment** : :ref:`das_string ` - The label comment + .. _handle-ast-ExprGoto: .. das:attribute:: ExprGoto @@ -3028,6 +3231,7 @@ Goto expression (`goto label 13`, `goto x`) * **subexpr** : smart_ptr< :ref:`Expression `> - Expression evaluating to label to go to, if specified + .. _handle-ast-ExprRef2Value: .. das:attribute:: ExprRef2Value @@ -3049,6 +3253,7 @@ Compilation time only structure which holds reference to value conversion for th * **subexpr** : smart_ptr< :ref:`Expression `> - The sub-expression being converted from reference to value + .. _handle-ast-ExprRef2Ptr: .. das:attribute:: ExprRef2Ptr @@ -3070,6 +3275,7 @@ Addr expresion (`addr(expr)`) * **subexpr** : smart_ptr< :ref:`Expression `> - The sub-expression being converted from pointer to reference + .. _handle-ast-ExprAddr: .. das:attribute:: ExprAddr @@ -3095,6 +3301,7 @@ Function address (`@@foobarfunc` or `@@foobarfunc<(int;int):bool>`) * **func** : :ref:`Function `? - Function being referenced (if resolved) + .. _handle-ast-ExprAssert: .. das:attribute:: ExprAssert @@ -3124,6 +3331,7 @@ Assert expression (`assert(x<13)`, or `assert(x<13, "x is too big")`, or `verify * **isVerify** : bool - Whether the assert is a verify expression (verify expressions have to have sideeffects, assert expressions cant) + .. _handle-ast-ExprQuote: .. das:attribute:: ExprQuote @@ -3151,6 +3359,7 @@ Compilation time expression which holds its subexpressions but does not infer th * **atEnclosure** : :ref:`LineInfo ` - Location of the enclosure where the query is used + .. _handle-ast-ExprStaticAssert: .. das:attribute:: ExprStaticAssert @@ -3178,6 +3387,7 @@ Static assert expression (`static_assert(x<13)` or `static_assert(x<13, "x is to * **atEnclosure** : :ref:`LineInfo ` - Location of the enclosure where the static_assert is used + .. _handle-ast-ExprDebug: .. das:attribute:: ExprDebug @@ -3205,6 +3415,7 @@ Debug expression (`debug(x)` or `debug(x,"x=")`) * **atEnclosure** : :ref:`LineInfo ` - Location of the enclosure where the debug is used + .. _handle-ast-ExprInvoke: .. das:attribute:: ExprInvoke @@ -3215,6 +3426,7 @@ Debug expression (`debug(x)` or `debug(x,"x=")`) Returns whether the given invoke expression requires a copy or move of a reference type. + :Properties: * **isCopyOrMove** : bool Invoke expression (`invoke(fn)` or `invoke(lamb, arg1, arg2, ...)`) @@ -3248,6 +3460,7 @@ Invoke expression (`invoke(fn)` or `invoke(lamb, arg1, arg2, ...)`) * **cmresAlias** : bool - If true, then CMRES aliasing is allowed for this invoke (and stack will be allocated) + .. _handle-ast-ExprErase: .. das:attribute:: ExprErase @@ -3275,11 +3488,12 @@ Erase expression (`erase(tab,key)`) * **atEnclosure** : :ref:`LineInfo ` - Location of the enclosure where the erase is used + .. _handle-ast-ExprSetInsert: .. das:attribute:: ExprSetInsert -Set insert expression, i.e. tab |> insert(key). +Set insert expression, i.e. ``tab |> insert(key)``. :Fields: * **at** : :ref:`LineInfo ` - Location of the expression in source code @@ -3302,6 +3516,7 @@ Set insert expression, i.e. tab |> insert(key). * **atEnclosure** : :ref:`LineInfo ` - Location of the enclosure where the set-insert is used + .. _handle-ast-ExprFind: .. das:attribute:: ExprFind @@ -3329,6 +3544,7 @@ Find expression (`find(tab,key) <| { your; block; here; }`) * **atEnclosure** : :ref:`LineInfo ` - Location of the enclosure where the find is used + .. _handle-ast-ExprKeyExists: .. das:attribute:: ExprKeyExists @@ -3356,6 +3572,7 @@ Key exists expression (`key_exists(tab,key)`) * **atEnclosure** : :ref:`LineInfo ` - Location of the enclosure where the key-exists is used + .. _handle-ast-ExprAscend: .. das:attribute:: ExprAscend @@ -3383,6 +3600,7 @@ New expression for ExprMakeLocal (`new [[Foo fld=val,...]]` or `new [[Foo() fld= * **ascendFlags** : :ref:`ExprAscendFlags ` - Flags specific to `ExprAscend` expressions + .. _handle-ast-ExprCast: .. das:attribute:: ExprCast @@ -3408,6 +3626,7 @@ Any cast expression (`cast a`, `upcast b` or `reinterpret c`) * **castFlags** : :ref:`ExprCastFlags ` - Flags specific to `ExprCast` expressions + .. _handle-ast-ExprDelete: .. das:attribute:: ExprDelete @@ -3433,6 +3652,7 @@ Delete expression (`delete blah`) * **native** : bool - True if the delete is native, and not to be expanded at compilation time. + .. _handle-ast-ExprVar: .. das:attribute:: ExprVar @@ -3462,6 +3682,7 @@ Variable access (`foo`) * **varFlags** : :ref:`ExprVarFlags ` - The flags of the variable + .. _handle-ast-ExprTag: .. das:attribute:: ExprTag @@ -3487,6 +3708,7 @@ Compilation time only tag expression, used for reification. For example $c(....) * **name** : :ref:`das_string ` - Name of the tag + .. _handle-ast-ExprSwizzle: .. das:attribute:: ExprSwizzle @@ -3514,6 +3736,7 @@ Vector swizzle operation (`vec.xxy` or `vec.y`) * **fieldFlags** : :ref:`ExprSwizzleFieldFlags ` - Flags specific to `ExprSwizzle` expressions + .. _handle-ast-ExprField: .. das:attribute:: ExprField @@ -3524,6 +3747,7 @@ Vector swizzle operation (`vec.xxy` or `vec.y`) Returns a pointer to the named field of a structure, or null if the field does not exist or the type is not a structure. + :Properties: * **field** : :ref:`FieldDeclaration `? Field lookup (`foo.bar`) @@ -3555,6 +3779,7 @@ Field lookup (`foo.bar`) * **fieldFlags** : :ref:`ExprFieldFieldFlags ` - Flags specific to field access expressions + .. _handle-ast-ExprSafeField: .. das:attribute:: ExprSafeField @@ -3590,6 +3815,7 @@ Safe field lookup (`foo?.bar`) * **skipQQ** : bool - If true the subexpression is already a pointer and no additional dereference is needed + .. _handle-ast-ExprIsVariant: .. das:attribute:: ExprIsVariant @@ -3623,6 +3849,7 @@ Is expression (`foo is bar`) * **fieldFlags** : :ref:`ExprFieldFieldFlags ` - Flags specific to field access expressions + .. _handle-ast-ExprAsVariant: .. das:attribute:: ExprAsVariant @@ -3656,6 +3883,7 @@ As expression (`foo as bar`) * **fieldFlags** : :ref:`ExprFieldFieldFlags ` - Flags specific to field access expressions + .. _handle-ast-ExprSafeAsVariant: .. das:attribute:: ExprSafeAsVariant @@ -3691,6 +3919,7 @@ Safe as expression (`foo? as bar`) * **skipQQ** : bool - If true the subexpression is already a pointer and no additional dereference is needed + .. _handle-ast-ExprOp1: .. das:attribute:: ExprOp1 @@ -3726,6 +3955,7 @@ Single operator expression (`+a` or `-a` or `!a` or `~a`) * **subexpr** : smart_ptr< :ref:`Expression `> - That one argument of the operator + .. _handle-ast-ExprReturn: .. das:attribute:: ExprReturn @@ -3757,6 +3987,7 @@ Return expression (`return` or `return foo`, or `return <- foo`) * **_block** : :ref:`ExprBlock `? - Block associated with the return expression + .. _handle-ast-ExprYield: .. das:attribute:: ExprYield @@ -3780,6 +4011,7 @@ Yield expression (`yield foo` or `yield <- bar`) * **returnFlags** : :ref:`ExprYieldFlags ` - Yield flags + .. _handle-ast-ExprBreak: .. das:attribute:: ExprBreak @@ -3799,6 +4031,7 @@ Break expression (`break`) * **printFlags** : :ref:`ExprPrintFlags ` - Expression print flags + .. _handle-ast-ExprContinue: .. das:attribute:: ExprContinue @@ -3818,6 +4051,7 @@ Continue expression (`continue`) * **printFlags** : :ref:`ExprPrintFlags ` - Expression print flags + .. _handle-ast-ExprConst: .. das:attribute:: ExprConst @@ -3839,6 +4073,7 @@ Compilation time constant expression base class * **baseType** : :ref:`Type ` - Base type of the constant expression + .. _handle-ast-ExprFakeContext: .. das:attribute:: ExprFakeContext @@ -3860,6 +4095,7 @@ Compilation time only fake context expression. Will simulate as current evaluati * **baseType** : :ref:`Type ` - Base type of the constant expression (Type::fakeContext) + .. _handle-ast-ExprFakeLineInfo: .. das:attribute:: ExprFakeLineInfo @@ -3870,6 +4106,7 @@ Compilation time only fake context expression. Will simulate as current evaluati Returns the constant value stored in this expression node. + :Properties: * **getValue** : void? Compilation time only fake lineinfo expression. Will simulate as current file and line `LineInfo`. @@ -3891,6 +4128,7 @@ Compilation time only fake lineinfo expression. Will simulate as current file an * **value** : void? - Pointer to the LineInfo, as void? + .. _handle-ast-ExprConstPtr: .. das:attribute:: ExprConstPtr @@ -3901,6 +4139,7 @@ Compilation time only fake lineinfo expression. Will simulate as current file an Returns the constant value stored in this expression node. + :Properties: * **getValue** : void? Null (`null`). Technically can be any other pointer, but it is used for nullptr. @@ -3922,6 +4161,7 @@ Null (`null`). Technically can be any other pointer, but it is used for nullptr. * **value** : void? - Pointer value. Typically this is 'null' constant, so the value is zero. + .. _handle-ast-ExprConstInt8: .. das:attribute:: ExprConstInt8 @@ -3932,6 +4172,7 @@ Null (`null`). Technically can be any other pointer, but it is used for nullptr. Returns the constant value stored in this expression node. + :Properties: * **getValue** : int8 Holds int8 constant. @@ -3953,6 +4194,7 @@ Holds int8 constant. * **value** : int8 - Value of the constant expression + .. _handle-ast-ExprConstInt16: .. das:attribute:: ExprConstInt16 @@ -3963,6 +4205,7 @@ Holds int8 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : int16 Holds int16 constant. @@ -3984,6 +4227,7 @@ Holds int16 constant. * **value** : int16 - Value of the constant expression + .. _handle-ast-ExprConstInt64: .. das:attribute:: ExprConstInt64 @@ -3994,6 +4238,7 @@ Holds int16 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : int64 Holds int64 constant. @@ -4015,6 +4260,7 @@ Holds int64 constant. * **value** : int64 - Value of the constant expression + .. _handle-ast-ExprConstInt: .. das:attribute:: ExprConstInt @@ -4025,6 +4271,7 @@ Holds int64 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : int Holds int constant. @@ -4046,6 +4293,7 @@ Holds int constant. * **value** : int - Value of the constant expression + .. _handle-ast-ExprConstInt2: .. das:attribute:: ExprConstInt2 @@ -4056,6 +4304,7 @@ Holds int constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : int2 Holds int2 constant. @@ -4077,6 +4326,7 @@ Holds int2 constant. * **value** : int2 - Value of the constant expression + .. _handle-ast-ExprConstInt3: .. das:attribute:: ExprConstInt3 @@ -4087,6 +4337,7 @@ Holds int2 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : int3 Holds int3 constant. @@ -4108,6 +4359,7 @@ Holds int3 constant. * **value** : int3 - Value of the constant expression + .. _handle-ast-ExprConstInt4: .. das:attribute:: ExprConstInt4 @@ -4118,6 +4370,7 @@ Holds int3 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : int4 Holds int4 constant. @@ -4139,6 +4392,7 @@ Holds int4 constant. * **value** : int4 - Value of the constant expression + .. _handle-ast-ExprConstUInt8: .. das:attribute:: ExprConstUInt8 @@ -4149,6 +4403,7 @@ Holds int4 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : uint8 Holds uint8 constant. @@ -4170,6 +4425,7 @@ Holds uint8 constant. * **value** : uint8 - Value of the constant expression + .. _handle-ast-ExprConstUInt16: .. das:attribute:: ExprConstUInt16 @@ -4180,6 +4436,7 @@ Holds uint8 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : uint16 Holds uint16 constant. @@ -4201,6 +4458,7 @@ Holds uint16 constant. * **value** : uint16 - Value of the constant expression + .. _handle-ast-ExprConstUInt64: .. das:attribute:: ExprConstUInt64 @@ -4211,6 +4469,7 @@ Holds uint16 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : uint64 Holds uint64 constant. @@ -4232,6 +4491,7 @@ Holds uint64 constant. * **value** : uint64 - Value of the constant expression + .. _handle-ast-ExprConstUInt: .. das:attribute:: ExprConstUInt @@ -4242,6 +4502,7 @@ Holds uint64 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : uint Holds uint constant. @@ -4263,6 +4524,7 @@ Holds uint constant. * **value** : uint - Value of the constant expression + .. _handle-ast-ExprConstUInt2: .. das:attribute:: ExprConstUInt2 @@ -4273,6 +4535,7 @@ Holds uint constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : uint2 Holds uint2 constant. @@ -4294,6 +4557,7 @@ Holds uint2 constant. * **value** : uint2 - Value of the constant expression + .. _handle-ast-ExprConstUInt3: .. das:attribute:: ExprConstUInt3 @@ -4304,6 +4568,7 @@ Holds uint2 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : uint3 Holds uint3 constant. @@ -4325,6 +4590,7 @@ Holds uint3 constant. * **value** : uint3 - Value of the constant expression + .. _handle-ast-ExprConstUInt4: .. das:attribute:: ExprConstUInt4 @@ -4335,6 +4601,7 @@ Holds uint3 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : uint4 Holds uint4 constant. @@ -4356,6 +4623,7 @@ Holds uint4 constant. * **value** : uint4 - Value of the constant expression + .. _handle-ast-ExprConstRange: .. das:attribute:: ExprConstRange @@ -4366,6 +4634,7 @@ Holds uint4 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : range Holds range constant. @@ -4387,6 +4656,7 @@ Holds range constant. * **value** : range - Value of the constant expression + .. _handle-ast-ExprConstURange: .. das:attribute:: ExprConstURange @@ -4397,6 +4667,7 @@ Holds range constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : urange Holds urange constant. @@ -4418,6 +4689,7 @@ Holds urange constant. * **value** : urange - Value of the constant expression + .. _handle-ast-ExprConstRange64: .. das:attribute:: ExprConstRange64 @@ -4428,6 +4700,7 @@ Holds urange constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : range64 Holds range64 constant. @@ -4449,6 +4722,7 @@ Holds range64 constant. * **value** : range64 - Value of the constant expression + .. _handle-ast-ExprConstURange64: .. das:attribute:: ExprConstURange64 @@ -4459,6 +4733,7 @@ Holds range64 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : urange64 Holds urange64 constant. @@ -4480,6 +4755,7 @@ Holds urange64 constant. * **value** : urange64 - Value of the constant expression + .. _handle-ast-ExprConstFloat: .. das:attribute:: ExprConstFloat @@ -4490,6 +4766,7 @@ Holds urange64 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : float Holds float constant. @@ -4511,6 +4788,7 @@ Holds float constant. * **value** : float - Value of the constant expression + .. _handle-ast-ExprConstFloat2: .. das:attribute:: ExprConstFloat2 @@ -4521,6 +4799,7 @@ Holds float constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : float2 Holds float2 constant. @@ -4542,6 +4821,7 @@ Holds float2 constant. * **value** : float2 - Value of the constant expression + .. _handle-ast-ExprConstFloat3: .. das:attribute:: ExprConstFloat3 @@ -4552,6 +4832,7 @@ Holds float2 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : float3 Holds float3 constant. @@ -4573,6 +4854,7 @@ Holds float3 constant. * **value** : float3 - Value of the constant expression + .. _handle-ast-ExprConstFloat4: .. das:attribute:: ExprConstFloat4 @@ -4583,6 +4865,7 @@ Holds float3 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : float4 Holds float4 constant. @@ -4604,6 +4887,7 @@ Holds float4 constant. * **value** : float4 - Value of the constant expression + .. _handle-ast-ExprConstDouble: .. das:attribute:: ExprConstDouble @@ -4614,6 +4898,7 @@ Holds float4 constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : double Holds double constant. @@ -4635,6 +4920,7 @@ Holds double constant. * **value** : double - Value of the constant expression + .. _handle-ast-ExprConstBool: .. das:attribute:: ExprConstBool @@ -4645,6 +4931,7 @@ Holds double constant. Returns the constant value stored in this expression node. + :Properties: * **getValue** : bool Holds bool constant. @@ -4666,6 +4953,7 @@ Holds bool constant. * **value** : bool - Value of the constant expression + .. _handle-ast-CaptureEntry: .. das:attribute:: CaptureEntry @@ -4677,6 +4965,7 @@ Single entry in lambda capture. * **mode** : :ref:`CaptureMode ` - How the variable is captured (by value, by reference, etc.) + .. _handle-ast-ExprMakeBlock: .. das:attribute:: ExprMakeBlock @@ -4706,6 +4995,7 @@ Any closure. Holds block as well as capture information in `CaptureEntry`. * **aotFunctorName** : :ref:`das_string ` - Name of the AOT functor (if applicable) + .. _handle-ast-ExprMakeGenerator: .. das:attribute:: ExprMakeGenerator @@ -4737,6 +5027,7 @@ Generator closure (`generator` or `generator`) * **_capture** : vector - List of captured variables + .. _handle-ast-ExprMemZero: .. das:attribute:: ExprMemZero @@ -4764,6 +5055,7 @@ Memzero (`memzero(expr)`) * **atEnclosure** : :ref:`LineInfo ` - Location of the enclosure where the memzero is used + .. _handle-ast-ExprConstEnumeration: .. das:attribute:: ExprConstEnumeration @@ -4789,6 +5081,7 @@ Holds enumeration constant, both type and entry (`Foo bar`). * **value** : :ref:`das_string ` - Value of the constant expression + .. _handle-ast-ExprConstBitfield: .. das:attribute:: ExprConstBitfield @@ -4799,6 +5092,7 @@ Holds enumeration constant, both type and entry (`Foo bar`). Returns the constant value stored in this expression node. + :Properties: * **getValue** : uint64 Holds bitfield constant (`Foo bar`). @@ -4822,6 +5116,7 @@ Holds bitfield constant (`Foo bar`). * **bitfieldType** : smart_ptr< :ref:`TypeDecl `> - Type declaration of the bitfield + .. _handle-ast-ExprConstString: .. das:attribute:: ExprConstString @@ -4845,6 +5140,7 @@ Holds string constant. * **value** : :ref:`das_string ` - Value of the constant expression + .. _handle-ast-ExprUnsafe: .. das:attribute:: ExprUnsafe @@ -4866,6 +5162,7 @@ Unsafe expression (`unsafe(addr(x))`) * **body** : smart_ptr< :ref:`Expression `> - Body expression that is marked as unsafe + .. _handle-ast-VisitorAdapter: .. das:attribute:: VisitorAdapter @@ -4873,6 +5170,7 @@ Unsafe expression (`unsafe(addr(x))`) Adapter for the `AstVisitor` interface. + .. _handle-ast-FunctionAnnotation: .. das:attribute:: FunctionAnnotation @@ -4880,6 +5178,7 @@ Unsafe expression (`unsafe(addr(x))`) Adapter for the `AstFunctionAnnotation`. + .. _handle-ast-StructureAnnotation: .. das:attribute:: StructureAnnotation @@ -4887,6 +5186,7 @@ Unsafe expression (`unsafe(addr(x))`) Adapter for the `AstStructureAnnotation`. + .. _handle-ast-EnumerationAnnotation: .. das:attribute:: EnumerationAnnotation @@ -4894,6 +5194,7 @@ Unsafe expression (`unsafe(addr(x))`) Adapter for the `AstEnumerationAnnotation`. + .. _handle-ast-PassMacro: .. das:attribute:: PassMacro @@ -4903,6 +5204,7 @@ Adapter for the `AstPassMacro`. :Fields: * **name** : :ref:`das_string ` - Name of the macro + .. _handle-ast-ReaderMacro: .. das:attribute:: ReaderMacro @@ -4914,6 +5216,7 @@ Adapter for the `AstReaderMacro`. * **_module** : :ref:`Module `? - Module where the macro is defined + .. _handle-ast-CommentReader: .. das:attribute:: CommentReader @@ -4921,6 +5224,7 @@ Adapter for the `AstReaderMacro`. Adapter for the `AstCommentReader`. + .. _handle-ast-CallMacro: .. das:attribute:: CallMacro @@ -4932,6 +5236,7 @@ Adapter for the `AstCallMacro`. * **_module** : :ref:`Module `? - Module where the macro is defined + .. _handle-ast-VariantMacro: .. das:attribute:: VariantMacro @@ -4941,6 +5246,7 @@ Adapter for the `AstVariantMacro`. :Fields: * **name** : :ref:`das_string ` - Name of the macro + .. _handle-ast-ForLoopMacro: .. das:attribute:: ForLoopMacro @@ -4950,6 +5256,7 @@ Adapter for the 'AstForLoopMacro'. :Fields: * **name** : :ref:`das_string ` - Name of the macro + .. _handle-ast-CaptureMacro: .. das:attribute:: CaptureMacro @@ -4959,6 +5266,7 @@ Adapter for the `AstCaptureMacro`. :Fields: * **name** : :ref:`das_string ` - Name of the macro + .. _handle-ast-TypeMacro: .. das:attribute:: TypeMacro @@ -4968,6 +5276,7 @@ Compilation time only structure which holds live information about type macro. :Fields: * **name** : :ref:`das_string ` - Name of the macro + .. _handle-ast-SimulateMacro: .. das:attribute:: SimulateMacro @@ -4977,6 +5286,7 @@ Adapter for the `AstSimulateMacro`. :Fields: * **name** : :ref:`das_string ` - Name of the macro. + .. _handle-ast-ExprReader: .. das:attribute:: ExprReader @@ -5000,6 +5310,7 @@ Compilation time only expression which holds temporary information for the `AstR * **sequence** : :ref:`das_string ` - Sequence of characters being read. + .. _handle-ast-ExprCallMacro: .. das:attribute:: ExprCallMacro @@ -5029,6 +5340,8 @@ Compilation time only expression which holds temporary information for the `AstC * **macro** : :ref:`CallMacro `? - Call macro, if resolved + + +++++++++++ Call macros +++++++++++ @@ -5038,6 +5351,8 @@ Call macros .. das:attribute:: quote Returns the AST expression tree of the provided code without evaluating or type-inferring it. Used in macro programming to capture source code as a manipulable AST. + + +++++++++++++++ Typeinfo macros +++++++++++++++ @@ -5047,11 +5362,14 @@ Typeinfo macros .. das:attribute:: ast_typedecl Returns a `TypeDeclPtr` for the type specified via `type<>` or subexpression type, for example `typeinfo(ast_typedecl type)`. Useful in macros that need compile-time access to type declarations. + .. _call-macro-ast-ast_function: .. das:attribute:: ast_function Returns a `FunctionPtr` to the function specified by the subexpression, for example ``typeinfo(ast_function @@foo)``. Useful in macros that need compile-time access to function declarations. + + +++++++++++++ Handled types +++++++++++++ @@ -5061,6 +5379,8 @@ Handled types .. das:attribute:: MakeStruct Annotation representing a vector of `MakeFieldDecl` used to initialize fields in `ExprMakeStruct` expressions. + + +++++++ Classes +++++++ @@ -5072,6 +5392,7 @@ Classes Annotation macro that attaches to `Function` declarations. Provides compile-time hooks for transforming functions, adding finalization logic, and controlling function compilation behavior. + .. _struct-ast-AstBlockAnnotation: .. das:attribute:: AstBlockAnnotation @@ -5079,6 +5400,7 @@ Annotation macro that attaches to `Function` declarations. Provides compile-time Annotation macro that attaches to `ExprBlock` nodes. Provides compile-time hooks for inspecting and transforming code blocks, including loop bodies and scoped blocks. + .. _struct-ast-AstStructureAnnotation: .. das:attribute:: AstStructureAnnotation @@ -5086,6 +5408,7 @@ Annotation macro that attaches to `ExprBlock` nodes. Provides compile-time hooks Annotation macro that attaches to `Structure` declarations. Provides compile-time hooks for inspecting and modifying structure definitions, fields, and layout. + .. _struct-ast-AstPassMacro: .. das:attribute:: AstPassMacro @@ -5093,6 +5416,7 @@ Annotation macro that attaches to `Structure` declarations. Provides compile-tim Macro that executes as an additional inference pass during compilation. Allows injecting custom analysis and transformation logic into the type-inference pipeline. + .. _struct-ast-AstVariantMacro: .. das:attribute:: AstVariantMacro @@ -5100,6 +5424,7 @@ Macro that executes as an additional inference pass during compilation. Allows i Macro for implementing custom ``is``, ``as``, and ``?as`` expressions. Allows user-defined variant-like dispatch and type-checking patterns beyond the built-in variant type. + .. _struct-ast-AstForLoopMacro: .. das:attribute:: AstForLoopMacro @@ -5107,6 +5432,7 @@ Macro for implementing custom ``is``, ``as``, and ``?as`` expressions. Allows us Macro for implementing custom for-loop iteration patterns. Intercepts for-loop expressions during compilation, similar to the ``visitExprFor`` callback of `AstVisitor`. + .. _struct-ast-AstCaptureMacro: .. das:attribute:: AstCaptureMacro @@ -5114,6 +5440,7 @@ Macro for implementing custom for-loop iteration patterns. Intercepts for-loop e Macro for implementing custom lambda capture behavior. Controls how variables are captured from the enclosing scope when creating lambdas and generators. + .. _struct-ast-AstTypeMacro: .. das:attribute:: AstTypeMacro @@ -5121,6 +5448,7 @@ Macro for implementing custom lambda capture behavior. Controls how variables ar Macro that participates in type declarations, enabling syntax like ``$macro_name(args)`` for custom type construction and transformation. + .. _struct-ast-AstSimulateMacro: .. das:attribute:: AstSimulateMacro @@ -5128,6 +5456,7 @@ Macro that participates in type declarations, enabling syntax like ``$macro_name Macro that hooks into the context simulation phase — the final compilation step where the AST is translated into executable simulation nodes. + .. _struct-ast-AstReaderMacro: .. das:attribute:: AstReaderMacro @@ -5135,6 +5464,7 @@ Macro that hooks into the context simulation phase — the final compilation ste Macro for implementing custom parsing syntax using the ``%MacroName~`` notation. The reader macro controls the start and end of the custom parsing region and produces an AST expression from the parsed content. + .. _struct-ast-AstCommentReader: .. das:attribute:: AstCommentReader @@ -5142,6 +5472,7 @@ Macro for implementing custom parsing syntax using the ``%MacroName~`` notation. Macro for implementing custom comment parsing, such as extracting doxygen-style documentation or other structured metadata from source comments during compilation. + .. _struct-ast-AstCallMacro: .. das:attribute:: AstCallMacro @@ -5149,6 +5480,7 @@ Macro for implementing custom comment parsing, such as extracting doxygen-style Macro for implementing custom call-like expressions (e.g. ``foo(bar, bar2, ...)``). The macro intercepts specific function calls during compilation and can rewrite them into arbitrary AST. + .. _struct-ast-AstTypeInfoMacro: .. das:attribute:: AstTypeInfoMacro @@ -5156,6 +5488,7 @@ Macro for implementing custom call-like expressions (e.g. ``foo(bar, bar2, ...)` Macro for implementing custom ``typeinfo`` traits, enabling expressions like ``typeinfo(YourTraitHere ...)`` that extract compile-time type information. + .. _struct-ast-AstEnumerationAnnotation: .. das:attribute:: AstEnumerationAnnotation @@ -5163,6 +5496,7 @@ Macro for implementing custom ``typeinfo`` traits, enabling expressions like ``t Annotation macro that attaches to `Enumeration` declarations. Provides compile-time hooks for inspecting and modifying enumeration definitions. + .. _struct-ast-AstVisitor: .. das:attribute:: AstVisitor @@ -5170,6 +5504,8 @@ Annotation macro that attaches to `Enumeration` declarations. Provides compile-t Implements the `Visitor` interface for traversing and transforming the AST tree. Provides ``visit`` and ``preVisit`` callbacks for every expression and declaration node type. + + +++++++++++++++ Call generation +++++++++++++++ @@ -5182,10 +5518,12 @@ Call generation Creates the appropriate call expression for a given function name in the program. + :Arguments: * **at** : :ref:`LineInfo ` implicit * **name** : string implicit + +++++++++++++++ Visitor pattern +++++++++++++++ @@ -5210,6 +5548,7 @@ visit Invokes an AST visitor on the given object. + :Arguments: * **expression** : smart_ptr< :ref:`TypeDecl `> implicit * **adapter** : smart_ptr< :ref:`VisitorAdapter `> implicit @@ -5234,6 +5573,7 @@ Invokes an AST visitor on the given object. Invokes an AST visitor on the given enumeration. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **enumeration** : smart_ptr< :ref:`Enumeration `> implicit @@ -5246,6 +5586,7 @@ Invokes an AST visitor on the given enumeration. Invokes the visitor on the finally section of a block. + :Arguments: * **expression** : smart_ptr< :ref:`ExprBlock `> implicit * **adapter** : smart_ptr< :ref:`VisitorAdapter `> implicit @@ -5256,6 +5597,7 @@ Invokes the visitor on the finally section of a block. Invokes an AST visitor on the given module. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **adapter** : smart_ptr< :ref:`VisitorAdapter `> implicit @@ -5268,6 +5610,7 @@ Invokes an AST visitor on the given module. Invokes an AST visitor on all modules in the specified program. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **adapter** : smart_ptr< :ref:`VisitorAdapter `> implicit @@ -5278,18 +5621,20 @@ Invokes an AST visitor on all modules in the specified program. Invokes an AST visitor on the given structure. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **structure** : smart_ptr< :ref:`Structure `> implicit * **adapter** : smart_ptr< :ref:`VisitorAdapter `> implicit + +++++++++++++++++++++ Expression generation +++++++++++++++++++++ - * :ref:`force_generated (function: smart_ptr\ const& implicit; value: bool) ` - * :ref:`force_generated (expression: smart_ptr\ const& implicit; value: bool) ` + * :ref:`force_generated (function: smart_ptr\ const& implicit; value: bool) ` + * :ref:`force_generated (expression: smart_ptr\ const& implicit; value: bool) ` * :ref:`get_expression_annotation (expr: Expression? implicit) : Annotation? ` * :ref:`make_type_info_structure (ctx: Context implicit; type: smart_ptr\ implicit) : TypeInfo? ` @@ -5297,17 +5642,18 @@ Expression generation force_generated ^^^^^^^^^^^^^^^ -.. _function-ast_force_generated_smart_ptr_ls_Function_gr__const_implicit_bool: +.. _function-ast_force_generated_smart_ptr_ls_Function_gr__const_ref__implicit_bool: .. das:function:: force_generated(function: smart_ptr const& implicit; value: bool) Sets the generated flag on an expression and its subexpressions. -:Arguments: * **function** : smart_ptr< :ref:`Function `>& implicit + +:Arguments: * **function** : smart_ptr< :ref:`Function `>\ & implicit * **value** : bool -.. _function-ast_force_generated_smart_ptr_ls_Expression_gr__const_implicit_bool: +.. _function-ast_force_generated_smart_ptr_ls_Expression_gr__const_ref__implicit_bool: .. das:function:: force_generated(expression: smart_ptr const& implicit; value: bool) @@ -5319,6 +5665,7 @@ Sets the generated flag on an expression and its subexpressions. Returns the Annotation associated with an Expression or its inherited types. + :Arguments: * **expr** : :ref:`Expression `? implicit .. _function-ast_make_type_info_structure_Context_implicit_smart_ptr_ls_TypeDecl_gr__implicit: @@ -5327,10 +5674,12 @@ Returns the Annotation associated with an Expression or its inherited types. Returns a new TypeInfo corresponding to the specified type. + :Arguments: * **ctx** : :ref:`Context ` implicit * **type** : smart_ptr< :ref:`TypeDecl `> implicit + ++++++++++++++++++ Adapter generation ++++++++++++++++++ @@ -5364,7 +5713,7 @@ Adapter generation * :ref:`make_struct_variable_debug_info (helper: smart_ptr\ implicit; st: Structure const? implicit; var: FieldDeclaration const? implicit) : VarInfo? ` * :ref:`make_structure_annotation (name: string; var someClassPtr: auto) : StructureAnnotationPtr ` * :ref:`make_structure_annotation (name: string implicit; class: void? implicit; info: StructInfo const? implicit) : smart_ptr\ ` - * :ref:`make_type_info (helper: smart_ptr\ implicit; info: TypeInfo? implicit; type: smart_ptr\ const& implicit) : TypeInfo? ` + * :ref:`make_type_info (helper: smart_ptr\ implicit; info: TypeInfo? implicit; type: smart_ptr\ const& implicit) : TypeInfo? ` * :ref:`make_type_macro (name: string; var someClassPtr: auto) : TypeMacroPtr ` * :ref:`make_type_macro (name: string implicit; class: void? implicit; info: StructInfo const? implicit) : smart_ptr\ ` * :ref:`make_typeinfo_macro (name: string implicit; class: void? implicit; info: StructInfo const? implicit) : smart_ptr\ ` @@ -5385,6 +5734,7 @@ make_block_annotation Creates an adapter for the AstBlockAnnotation interface. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5401,6 +5751,7 @@ Creates an adapter for the AstBlockAnnotation interface. Generates a TypeDeclPtr for a specified block or lambda type. + :Arguments: * **blk** : :ref:`ExprBlock `? implicit @@ -5413,6 +5764,7 @@ make_call_macro Creates an adapter for the AstCallMacro interface. + :Arguments: * **name** : string implicit * **class** : void? implicit @@ -5435,6 +5787,7 @@ make_capture_macro Creates an adapter for the AstCaptureMacro interface. + :Arguments: * **name** : string implicit * **class** : void? implicit @@ -5453,6 +5806,7 @@ Creates an adapter for the AstCaptureMacro interface. Generates a clone function for the given structure. + :Arguments: * **structure** : :ref:`Structure `? implicit @@ -5465,6 +5819,7 @@ make_comment_reader Creates an adapter for the AstCommentReader interface. + :Arguments: * **class** : void? implicit * **info** : :ref:`StructInfo `? implicit @@ -5481,6 +5836,7 @@ Creates an adapter for the AstCommentReader interface. Generates an EnumInfo for the specified enumeration using the given DebugInfoHelper. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **en** : :ref:`Enumeration `? implicit @@ -5495,6 +5851,7 @@ make_enumeration_annotation Creates an adapter for the AstEnumerationAnnotation interface. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5515,6 +5872,7 @@ make_for_loop_macro Creates an adapter for the AstForLoopMacro interface. + :Arguments: * **name** : string implicit * **class** : void? implicit @@ -5537,6 +5895,7 @@ make_function_annotation Creates an adapter for the AstFunctionAnnotation interface. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5553,6 +5912,7 @@ Creates an adapter for the AstFunctionAnnotation interface. Generates a FuncInfo for the specified function using the given DebugInfoHelper. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **fn** : :ref:`Function `? implicit @@ -5563,6 +5923,7 @@ Generates a FuncInfo for the specified function using the given DebugInfoHelper. Generates a FuncInfo for an invokable type such as a lambda or block using the given DebugInfoHelper. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **blk** : smart_ptr< :ref:`TypeDecl `> implicit @@ -5579,6 +5940,7 @@ make_pass_macro Creates an adapter for the AstPassMacro interface. + :Arguments: * **name** : string implicit * **class** : void? implicit @@ -5601,6 +5963,7 @@ make_reader_macro Creates an adapter for the AstReaderMacro interface. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5621,6 +5984,7 @@ make_simulate_macro Creates an adapter for the AstSimulateMacro interface. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5637,6 +6001,7 @@ Creates an adapter for the AstSimulateMacro interface. Generates a StructInfo for the specified structure using the given DebugInfoHelper. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **st** : :ref:`Structure `? implicit @@ -5647,6 +6012,7 @@ Generates a StructInfo for the specified structure using the given DebugInfoHelp Generates a VariableInfo for a structure field using the given DebugInfoHelper. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **st** : :ref:`Structure `? implicit @@ -5663,6 +6029,7 @@ make_structure_annotation Creates an adapter for the AstStructureAnnotation interface. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5673,17 +6040,18 @@ Creates an adapter for the AstStructureAnnotation interface. ---- -.. _function-ast_make_type_info_smart_ptr_ls_DebugInfoHelper_gr__implicit_TypeInfo_q__implicit_smart_ptr_ls_TypeDecl_gr__const_implicit: +.. _function-ast_make_type_info_smart_ptr_ls_DebugInfoHelper_gr__implicit_TypeInfo_q__implicit_smart_ptr_ls_TypeDecl_gr__const_ref__implicit: .. das:function:: make_type_info(helper: smart_ptr implicit; info: TypeInfo? implicit; type: smart_ptr const& implicit) : TypeInfo? Generates a TypeInfo for the specified type using the given DebugInfoHelper. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **info** : :ref:`TypeInfo `? implicit - * **type** : smart_ptr< :ref:`TypeDecl `>& implicit + * **type** : smart_ptr< :ref:`TypeDecl `>\ & implicit make_type_macro @@ -5695,6 +6063,7 @@ make_type_macro Creates an adapter for the AstTypeMacro interface. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5715,6 +6084,7 @@ make_typeinfo_macro Creates an adapter for the AstTypeInfoMacro interface. + :Arguments: * **name** : string implicit * **class** : void? implicit @@ -5733,6 +6103,7 @@ Creates an adapter for the AstTypeInfoMacro interface. Generates a VariableInfo for the specified variable using the given DebugInfoHelper. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **var** : :ref:`Variable `? implicit @@ -5747,6 +6118,7 @@ make_variant_macro Creates an adapter for the AstVariantMacro interface. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5767,6 +6139,7 @@ make_visitor Creates an adapter for the AstVisitor interface. + :Arguments: * **someClass** : auto .. _function-ast_make_visitor_void_q__implicit_StructInfo_const_q__implicit: @@ -5775,24 +6148,25 @@ Creates an adapter for the AstVisitor interface. ---- + +++++++++++++++++++ Adapter application +++++++++++++++++++ - * :ref:`add_block_annotation (block: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_block_annotation (block: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_call_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_capture_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_comment_reader (module: Module? implicit; reader: smart_ptr\& implicit) ` - * :ref:`add_dirty_infer_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_enumeration_annotation (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_for_loop_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_function_annotation (function: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_function_annotation (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_function_annotation (function: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_global_lint_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_infer_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_lint_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_block_annotation (block: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_block_annotation (block: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_call_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_capture_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_comment_reader (module: Module? implicit; reader: smart_ptr\& implicit) ` + * :ref:`add_dirty_infer_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_enumeration_annotation (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_for_loop_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_function_annotation (function: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_function_annotation (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_function_annotation (function: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_global_lint_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_infer_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_lint_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` * :ref:`add_module_option (module: Module? implicit; option: string implicit; type: Type) ` * :ref:`add_new_block_annotation (name: string; var someClassPtr: auto) : auto ` * :ref:`add_new_call_macro (name: string; var someClassPtr: auto) : auto ` @@ -5813,149 +6187,160 @@ Adapter application * :ref:`add_new_type_macro (name: string; var someClassPtr: auto) : auto ` * :ref:`add_new_typeinfo_macro (name: string; var someClassPtr: auto) : auto ` * :ref:`add_new_variant_macro (name: string; var someClassPtr: auto) : auto ` - * :ref:`add_optimization_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_reader_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_simulate_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_structure_annotation (structure: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_structure_annotation (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_structure_annotation (structure: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_type_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_typeinfo_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` - * :ref:`add_variant_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_optimization_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_reader_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_simulate_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_structure_annotation (structure: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_structure_annotation (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_structure_annotation (structure: smart_ptr\ implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_type_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_typeinfo_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` + * :ref:`add_variant_macro (module: Module? implicit; annotation: smart_ptr\& implicit) ` add_block_annotation ^^^^^^^^^^^^^^^^^^^^ -.. _function-ast_add_block_annotation_smart_ptr_ls_ExprBlock_gr__implicit_smart_ptr_ls_FunctionAnnotation_gr__implicit: +.. _function-ast_add_block_annotation_smart_ptr_ls_ExprBlock_gr__implicit_smart_ptr_ls_FunctionAnnotation_gr__ref__implicit: .. das:function:: add_block_annotation(block: smart_ptr implicit; annotation: smart_ptr& implicit) Adds an annotation declaration to a block. + :Arguments: * **block** : smart_ptr< :ref:`ExprBlock `> implicit - * **annotation** : smart_ptr< :ref:`FunctionAnnotation `>& implicit + * **annotation** : smart_ptr< :ref:`FunctionAnnotation `>\ & implicit -.. _function-ast_add_block_annotation_smart_ptr_ls_ExprBlock_gr__implicit_smart_ptr_ls_AnnotationDeclaration_gr__implicit: +.. _function-ast_add_block_annotation_smart_ptr_ls_ExprBlock_gr__implicit_smart_ptr_ls_AnnotationDeclaration_gr__ref__implicit: .. das:function:: add_block_annotation(block: smart_ptr implicit; annotation: smart_ptr& implicit) ---- -.. _function-ast_add_call_macro_Module_q__implicit_smart_ptr_ls_CallMacro_gr__implicit: +.. _function-ast_add_call_macro_Module_q__implicit_smart_ptr_ls_CallMacro_gr__ref__implicit: .. das:function:: add_call_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstCallMacro adapter to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`CallMacro `>& implicit + * **annotation** : smart_ptr< :ref:`CallMacro `>\ & implicit -.. _function-ast_add_capture_macro_Module_q__implicit_smart_ptr_ls_CaptureMacro_gr__implicit: +.. _function-ast_add_capture_macro_Module_q__implicit_smart_ptr_ls_CaptureMacro_gr__ref__implicit: .. das:function:: add_capture_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstCaptureMacro to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`CaptureMacro `>& implicit + * **annotation** : smart_ptr< :ref:`CaptureMacro `>\ & implicit -.. _function-ast_add_comment_reader_Module_q__implicit_smart_ptr_ls_CommentReader_gr__implicit: +.. _function-ast_add_comment_reader_Module_q__implicit_smart_ptr_ls_CommentReader_gr__ref__implicit: .. das:function:: add_comment_reader(module: Module? implicit; reader: smart_ptr& implicit) Adds an AstCommentReader adapter to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **reader** : smart_ptr< :ref:`CommentReader `>& implicit + * **reader** : smart_ptr< :ref:`CommentReader `>\ & implicit -.. _function-ast_add_dirty_infer_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__implicit: +.. _function-ast_add_dirty_infer_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__ref__implicit: .. das:function:: add_dirty_infer_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstPassMacro adapter to the dirty inference pass. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`PassMacro `>& implicit + * **annotation** : smart_ptr< :ref:`PassMacro `>\ & implicit -.. _function-ast_add_enumeration_annotation_Module_q__implicit_smart_ptr_ls_EnumerationAnnotation_gr__implicit: +.. _function-ast_add_enumeration_annotation_Module_q__implicit_smart_ptr_ls_EnumerationAnnotation_gr__ref__implicit: .. das:function:: add_enumeration_annotation(module: Module? implicit; annotation: smart_ptr& implicit) Adds an annotation to an enumeration and calls apply if applicable. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`EnumerationAnnotation `>& implicit + * **annotation** : smart_ptr< :ref:`EnumerationAnnotation `>\ & implicit -.. _function-ast_add_for_loop_macro_Module_q__implicit_smart_ptr_ls_ForLoopMacro_gr__implicit: +.. _function-ast_add_for_loop_macro_Module_q__implicit_smart_ptr_ls_ForLoopMacro_gr__ref__implicit: .. das:function:: add_for_loop_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstForLoopMacro to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`ForLoopMacro `>& implicit + * **annotation** : smart_ptr< :ref:`ForLoopMacro `>\ & implicit add_function_annotation ^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-ast_add_function_annotation_smart_ptr_ls_Function_gr__implicit_smart_ptr_ls_FunctionAnnotation_gr__implicit: +.. _function-ast_add_function_annotation_smart_ptr_ls_Function_gr__implicit_smart_ptr_ls_FunctionAnnotation_gr__ref__implicit: .. das:function:: add_function_annotation(function: smart_ptr implicit; annotation: smart_ptr& implicit) Adds an annotation to a function and calls apply if applicable. + :Arguments: * **function** : smart_ptr< :ref:`Function `> implicit - * **annotation** : smart_ptr< :ref:`FunctionAnnotation `>& implicit + * **annotation** : smart_ptr< :ref:`FunctionAnnotation `>\ & implicit -.. _function-ast_add_function_annotation_Module_q__implicit_smart_ptr_ls_FunctionAnnotation_gr__implicit: +.. _function-ast_add_function_annotation_Module_q__implicit_smart_ptr_ls_FunctionAnnotation_gr__ref__implicit: .. das:function:: add_function_annotation(module: Module? implicit; annotation: smart_ptr& implicit) -.. _function-ast_add_function_annotation_smart_ptr_ls_Function_gr__implicit_smart_ptr_ls_AnnotationDeclaration_gr__implicit: +.. _function-ast_add_function_annotation_smart_ptr_ls_Function_gr__implicit_smart_ptr_ls_AnnotationDeclaration_gr__ref__implicit: .. das:function:: add_function_annotation(function: smart_ptr implicit; annotation: smart_ptr& implicit) ---- -.. _function-ast_add_global_lint_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__implicit: +.. _function-ast_add_global_lint_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__ref__implicit: .. das:function:: add_global_lint_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstPassMacro adapter to the global lint pass. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`PassMacro `>& implicit + * **annotation** : smart_ptr< :ref:`PassMacro `>\ & implicit -.. _function-ast_add_infer_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__implicit: +.. _function-ast_add_infer_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__ref__implicit: .. das:function:: add_infer_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstPassMacro adapter to the type inference pass. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`PassMacro `>& implicit + * **annotation** : smart_ptr< :ref:`PassMacro `>\ & implicit -.. _function-ast_add_lint_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__implicit: +.. _function-ast_add_lint_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__ref__implicit: .. das:function:: add_lint_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstPassMacro adapter to the lint pass of the current module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`PassMacro `>& implicit + * **annotation** : smart_ptr< :ref:`PassMacro `>\ & implicit .. _function-ast_add_module_option_Module_q__implicit_string_implicit_Type: @@ -5963,6 +6348,7 @@ Adds an AstPassMacro adapter to the lint pass of the current module. Adds a module-specific option accessible via the `options` keyword. + :Arguments: * **module** : :ref:`Module `? implicit * **option** : string implicit @@ -5975,6 +6361,7 @@ Adds a module-specific option accessible via the `options` keyword. Creates an AstBlockAnnotation adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5985,6 +6372,7 @@ Creates an AstBlockAnnotation adapter and adds it to the current module. Creates an AstCallMacro adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -5995,6 +6383,7 @@ Creates an AstCallMacro adapter and adds it to the current module. Creates an AstCaptureMacro adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6005,6 +6394,7 @@ Creates an AstCaptureMacro adapter and adds it to the current module. Creates an AstCommentReader adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6015,6 +6405,7 @@ Creates an AstCommentReader adapter and adds it to the current module. Creates an AstContractAnnotation adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6025,6 +6416,7 @@ Creates an AstContractAnnotation adapter and adds it to the current module. Creates an AstPassMacro adapter and adds it to the current module's dirty infer pass. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6035,6 +6427,7 @@ Creates an AstPassMacro adapter and adds it to the current module's dirty infer Creates an AstEnumerationAnnotation adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6045,6 +6438,7 @@ Creates an AstEnumerationAnnotation adapter and adds it to the current module. Creates an AstForLoopMacro adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6055,6 +6449,7 @@ Creates an AstForLoopMacro adapter and adds it to the current module. Creates an AstFunctionAnnotation adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6065,6 +6460,7 @@ Creates an AstFunctionAnnotation adapter and adds it to the current module. Creates an AstPassMacro adapter and adds it to the current module's global lint pass. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6075,6 +6471,7 @@ Creates an AstPassMacro adapter and adds it to the current module's global lint Creates an AstPassMacro adapter and adds it to the current module's infer pass. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6085,6 +6482,7 @@ Creates an AstPassMacro adapter and adds it to the current module's infer pass. Creates an AstPassMacro adapter and adds it to the current module's lint pass. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6095,6 +6493,7 @@ Creates an AstPassMacro adapter and adds it to the current module's lint pass. Creates an AstPassMacro adapter and adds it to the current module's optimization pass. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6105,6 +6504,7 @@ Creates an AstPassMacro adapter and adds it to the current module's optimization Creates an AstReaderMacro adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6115,6 +6515,7 @@ Creates an AstReaderMacro adapter and adds it to the current module. Creates an AstSimulateMacro adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6125,6 +6526,7 @@ Creates an AstSimulateMacro adapter and adds it to the current module. Creates an AstStructureAnnotation adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6135,6 +6537,7 @@ Creates an AstStructureAnnotation adapter and adds it to the current module. Creates an AstTypeMacro adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6145,6 +6548,7 @@ Creates an AstTypeMacro adapter and adds it to the current module. Creates an AstTypeInfoMacro adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto @@ -6155,118 +6559,128 @@ Creates an AstTypeInfoMacro adapter and adds it to the current module. Creates an AstVariantMacro adapter and adds it to the current module. + :Arguments: * **name** : string * **someClassPtr** : auto -.. _function-ast_add_optimization_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__implicit: +.. _function-ast_add_optimization_macro_Module_q__implicit_smart_ptr_ls_PassMacro_gr__ref__implicit: .. das:function:: add_optimization_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstPassMacro adapter to the optimization pass of a specific module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`PassMacro `>& implicit + * **annotation** : smart_ptr< :ref:`PassMacro `>\ & implicit -.. _function-ast_add_reader_macro_Module_q__implicit_smart_ptr_ls_ReaderMacro_gr__implicit: +.. _function-ast_add_reader_macro_Module_q__implicit_smart_ptr_ls_ReaderMacro_gr__ref__implicit: .. das:function:: add_reader_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstReaderMacro adapter to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`ReaderMacro `>& implicit + * **annotation** : smart_ptr< :ref:`ReaderMacro `>\ & implicit -.. _function-ast_add_simulate_macro_Module_q__implicit_smart_ptr_ls_SimulateMacro_gr__implicit: +.. _function-ast_add_simulate_macro_Module_q__implicit_smart_ptr_ls_SimulateMacro_gr__ref__implicit: .. das:function:: add_simulate_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstSimulateMacro adapter to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`SimulateMacro `>& implicit + * **annotation** : smart_ptr< :ref:`SimulateMacro `>\ & implicit add_structure_annotation ^^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-ast_add_structure_annotation_smart_ptr_ls_Structure_gr__implicit_smart_ptr_ls_StructureAnnotation_gr__implicit: +.. _function-ast_add_structure_annotation_smart_ptr_ls_Structure_gr__implicit_smart_ptr_ls_StructureAnnotation_gr__ref__implicit: .. das:function:: add_structure_annotation(structure: smart_ptr implicit; annotation: smart_ptr& implicit) Adds a structure annotation to the given object, calling apply if applicable. + :Arguments: * **structure** : smart_ptr< :ref:`Structure `> implicit - * **annotation** : smart_ptr< :ref:`StructureAnnotation `>& implicit + * **annotation** : smart_ptr< :ref:`StructureAnnotation `>\ & implicit -.. _function-ast_add_structure_annotation_Module_q__implicit_smart_ptr_ls_StructureAnnotation_gr__implicit: +.. _function-ast_add_structure_annotation_Module_q__implicit_smart_ptr_ls_StructureAnnotation_gr__ref__implicit: .. das:function:: add_structure_annotation(module: Module? implicit; annotation: smart_ptr& implicit) -.. _function-ast_add_structure_annotation_smart_ptr_ls_Structure_gr__implicit_smart_ptr_ls_AnnotationDeclaration_gr__implicit: +.. _function-ast_add_structure_annotation_smart_ptr_ls_Structure_gr__implicit_smart_ptr_ls_AnnotationDeclaration_gr__ref__implicit: .. das:function:: add_structure_annotation(structure: smart_ptr implicit; annotation: smart_ptr& implicit) ---- -.. _function-ast_add_type_macro_Module_q__implicit_smart_ptr_ls_TypeMacro_gr__implicit: +.. _function-ast_add_type_macro_Module_q__implicit_smart_ptr_ls_TypeMacro_gr__ref__implicit: .. das:function:: add_type_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstTypeMacro adapter to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`TypeMacro `>& implicit + * **annotation** : smart_ptr< :ref:`TypeMacro `>\ & implicit -.. _function-ast_add_typeinfo_macro_Module_q__implicit_smart_ptr_ls_TypeInfoMacro_gr__implicit: +.. _function-ast_add_typeinfo_macro_Module_q__implicit_smart_ptr_ls_TypeInfoMacro_gr__ref__implicit: .. das:function:: add_typeinfo_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstTypeInfoMacro adapter to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`TypeInfoMacro `>& implicit + * **annotation** : smart_ptr< :ref:`TypeInfoMacro `>\ & implicit -.. _function-ast_add_variant_macro_Module_q__implicit_smart_ptr_ls_VariantMacro_gr__implicit: +.. _function-ast_add_variant_macro_Module_q__implicit_smart_ptr_ls_VariantMacro_gr__ref__implicit: .. das:function:: add_variant_macro(module: Module? implicit; annotation: smart_ptr& implicit) Adds an AstVariantMacro adapter to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **annotation** : smart_ptr< :ref:`VariantMacro `>& implicit + * **annotation** : smart_ptr< :ref:`VariantMacro `>\ & implicit + +++++++++++++++++++++++++ Adding objects to objects +++++++++++++++++++++++++ - * :ref:`add_alias (module: Module? implicit; structure: smart_ptr\& implicit) : bool ` + * :ref:`add_alias (module: Module? implicit; structure: smart_ptr\& implicit) : bool ` * :ref:`add_enumeration_entry (enum: smart_ptr\ implicit; name: string implicit) : int ` - * :ref:`add_function (module: Module? implicit; function: smart_ptr\& implicit) : bool ` - * :ref:`add_generic (module: Module? implicit; function: smart_ptr\& implicit) : bool ` + * :ref:`add_function (module: Module? implicit; function: smart_ptr\& implicit) : bool ` + * :ref:`add_generic (module: Module? implicit; function: smart_ptr\& implicit) : bool ` * :ref:`add_keyword (module: Module? implicit; keyword: string implicit; needOxfordComma: bool) : bool ` * :ref:`add_module_require (module: Module? implicit; publicModule: Module? implicit; pub: bool) : bool ` - * :ref:`add_structure (module: Module? implicit; structure: smart_ptr\& implicit) : bool ` - * :ref:`add_structure_alias (structure: Structure? implicit; aliasName: string implicit; alias: smart_ptr\ const& implicit) : bool ` + * :ref:`add_structure (module: Module? implicit; structure: smart_ptr\& implicit) : bool ` + * :ref:`add_structure_alias (structure: Structure? implicit; aliasName: string implicit; alias: smart_ptr\ const& implicit) : bool ` * :ref:`add_type_function (module: Module? implicit; keyword: string implicit) : bool ` - * :ref:`add_variable (module: Module? implicit; variable: smart_ptr\& implicit) : bool ` + * :ref:`add_variable (module: Module? implicit; variable: smart_ptr\& implicit) : bool ` -.. _function-ast_add_alias_Module_q__implicit_smart_ptr_ls_TypeDecl_gr__implicit: +.. _function-ast_add_alias_Module_q__implicit_smart_ptr_ls_TypeDecl_gr__ref__implicit: .. das:function:: add_alias(module: Module? implicit; structure: smart_ptr& implicit) : bool Adds a type alias to the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **structure** : smart_ptr< :ref:`TypeDecl `>& implicit + * **structure** : smart_ptr< :ref:`TypeDecl `>\ & implicit .. _function-ast_add_enumeration_entry_smart_ptr_ls_Enumeration_gr__implicit_string_implicit: @@ -6274,29 +6688,32 @@ Adds a type alias to the specified module. Adds a new entry to an enumeration annotation. + :Arguments: * **enum** : smart_ptr< :ref:`Enumeration `> implicit * **name** : string implicit -.. _function-ast_add_function_Module_q__implicit_smart_ptr_ls_Function_gr__implicit: +.. _function-ast_add_function_Module_q__implicit_smart_ptr_ls_Function_gr__ref__implicit: .. das:function:: add_function(module: Module? implicit; function: smart_ptr& implicit) : bool Adds a function to a module, returning false if a duplicate already exists. + :Arguments: * **module** : :ref:`Module `? implicit - * **function** : smart_ptr< :ref:`Function `>& implicit + * **function** : smart_ptr< :ref:`Function `>\ & implicit -.. _function-ast_add_generic_Module_q__implicit_smart_ptr_ls_Function_gr__implicit: +.. _function-ast_add_generic_Module_q__implicit_smart_ptr_ls_Function_gr__ref__implicit: .. das:function:: add_generic(module: Module? implicit; function: smart_ptr& implicit) : bool Adds a generic function to a module, returning false if a duplicate already exists. + :Arguments: * **module** : :ref:`Module `? implicit - * **function** : smart_ptr< :ref:`Function `>& implicit + * **function** : smart_ptr< :ref:`Function `>\ & implicit .. _function-ast_add_keyword_Module_q__implicit_string_implicit_bool: @@ -6305,6 +6722,7 @@ Adds a generic function to a module, returning false if a duplicate already exis Registers a new keyword in the specified module, making it available to the parser. + :Arguments: * **module** : :ref:`Module `? implicit * **keyword** : string implicit @@ -6317,33 +6735,36 @@ Registers a new keyword in the specified module, making it available to the pars Adds module dependencies, similar to the `require` keyword. + :Arguments: * **module** : :ref:`Module `? implicit * **publicModule** : :ref:`Module `? implicit * **pub** : bool -.. _function-ast_add_structure_Module_q__implicit_smart_ptr_ls_Structure_gr__implicit: +.. _function-ast_add_structure_Module_q__implicit_smart_ptr_ls_Structure_gr__ref__implicit: .. das:function:: add_structure(module: Module? implicit; structure: smart_ptr& implicit) : bool Adds a structure to a module, returning false if a duplicate already exists. + :Arguments: * **module** : :ref:`Module `? implicit - * **structure** : smart_ptr< :ref:`Structure `>& implicit + * **structure** : smart_ptr< :ref:`Structure `>\ & implicit -.. _function-ast_add_structure_alias_Structure_q__implicit_string_implicit_smart_ptr_ls_TypeDecl_gr__const_implicit: +.. _function-ast_add_structure_alias_Structure_q__implicit_string_implicit_smart_ptr_ls_TypeDecl_gr__const_ref__implicit: .. das:function:: add_structure_alias(structure: Structure? implicit; aliasName: string implicit; alias: smart_ptr const& implicit) : bool Adds a typedef alias to a structure type in the AST, equivalent to a typedef in the structure body. + :Arguments: * **structure** : :ref:`Structure `? implicit * **aliasName** : string implicit - * **alias** : smart_ptr< :ref:`TypeDecl `>& implicit + * **alias** : smart_ptr< :ref:`TypeDecl `>\ & implicit .. _function-ast_add_type_function_Module_q__implicit_string_implicit: @@ -6351,19 +6772,22 @@ Adds a typedef alias to a structure type in the AST, equivalent to a typedef in Adds a type function keyword, allowing function calls to accept type arguments before regular arguments via the `some_call(regular_args)` syntax. + :Arguments: * **module** : :ref:`Module `? implicit * **keyword** : string implicit -.. _function-ast_add_variable_Module_q__implicit_smart_ptr_ls_Variable_gr__implicit: +.. _function-ast_add_variable_Module_q__implicit_smart_ptr_ls_Variable_gr__ref__implicit: .. das:function:: add_variable(module: Module? implicit; variable: smart_ptr& implicit) : bool Adds a variable to a module, returning false if a duplicate already exists. + :Arguments: * **module** : :ref:`Module `? implicit - * **variable** : smart_ptr< :ref:`Variable `>& implicit + * **variable** : smart_ptr< :ref:`Variable `>\ & implicit + +++++++++++++++++++++++++ Program and module access @@ -6380,24 +6804,29 @@ Program and module access Returns the module currently being compiled. + .. _function-ast_compiling_program: .. das:function:: compiling_program() : smart_ptr Returns the program currently being compiled. + .. _function-ast_this_module: .. das:function:: this_module() : Module? Returns the main module attached to the current context, throwing an error if RTTI is disabled. + .. _function-ast_this_program: .. das:function:: this_program() : smart_ptr Returns the program attached to the current context, or null if RTTI is disabled. + + +++++++++++++++++++++++++++++++++++ Textual descriptions of the objects +++++++++++++++++++++++++++++++++++ @@ -6418,6 +6847,7 @@ Textual descriptions of the objects Returns the name of the corresponding daslang base type as a string. + :Arguments: * **type** : :ref:`Type ` @@ -6430,6 +6860,7 @@ describe Produces a daslang source code string representation of the given AST object. + :Arguments: * **expr** : smart_ptr< :ref:`Function `> .. _function-ast_describe_smart_ptr_ls_Expression_gr_: @@ -6448,6 +6879,7 @@ Produces a daslang source code string representation of the given AST object. Produces a C++ source code string representation of the given TypeDecl. + :Arguments: * **decl** : smart_ptr< :ref:`TypeDecl `> * **substitureRef** : bool @@ -6466,6 +6898,7 @@ Produces a C++ source code string representation of the given TypeDecl. Returns a string description of the Expression matching the corresponding daslang source code. + :Arguments: * **expression** : smart_ptr< :ref:`Expression `> implicit .. _function-ast_describe_function_smart_ptr_ls_Function_gr__implicit: @@ -6474,6 +6907,7 @@ Returns a string description of the Expression matching the corresponding daslan Returns a string description of the Function matching the corresponding daslang function declaration. + :Arguments: * **function** : smart_ptr< :ref:`Function `> implicit .. _function-ast_describe_typedecl_smart_ptr_ls_TypeDecl_gr__implicit_bool_bool_bool: @@ -6482,6 +6916,7 @@ Returns a string description of the Function matching the corresponding daslang Returns a string description of the TypeDecl matching the corresponding daslang type declaration. + :Arguments: * **type** : smart_ptr< :ref:`TypeDecl `> implicit * **extra** : bool @@ -6496,6 +6931,7 @@ Returns a string description of the TypeDecl matching the corresponding daslang Returns a string description of the TypeDecl matching the corresponding C++ type declaration. + :Arguments: * **type** : smart_ptr< :ref:`TypeDecl `> implicit * **substitueRef** : bool @@ -6508,6 +6944,7 @@ Returns a string description of the TypeDecl matching the corresponding C++ type * **choose_smart_ptr** : bool + +++++++++ Searching +++++++++ @@ -6535,6 +6972,7 @@ Searching Finds the name of a bitfield value in the specified type. + :Arguments: * **bit** : smart_ptr< :ref:`TypeDecl `> implicit * **value** : bitfield<> @@ -6545,6 +6983,7 @@ Finds the name of a bitfield value in the specified type. Finds a CallMacro by name in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit * **name** : string implicit @@ -6555,6 +6994,7 @@ Finds a CallMacro by name in the specified module. Returns a Function from the currently compiling program given its mangled name hash. + :Arguments: * **moduleName** : string implicit * **mangledNameHash** : uint64 @@ -6565,6 +7005,7 @@ Returns a Function from the currently compiling program given its mangled name h Finds a module by name in the currently compiling program. + :Arguments: * **name** : string .. _function-ast_find_enum_name_Enumeration_q__implicit_int64: @@ -6573,6 +7014,7 @@ Finds a module by name in the currently compiling program. Finds the name corresponding to an enumeration value in the specified type. + :Arguments: * **enum** : :ref:`Enumeration `? implicit * **value** : int64 @@ -6587,6 +7029,7 @@ find_enum_value Finds the integer value corresponding to an enumeration name in the specified type. + :Arguments: * **enum** : :ref:`Enumeration `? implicit * **value** : string implicit @@ -6603,6 +7046,7 @@ Finds the integer value corresponding to an enumeration name in the specified ty Finds a global or shared variable accessible from the given function, according to visibility and privacy rules. + :Arguments: * **program** : :ref:`Program `? implicit * **function** : :ref:`Function `? implicit @@ -6611,7 +7055,7 @@ Finds a global or shared variable accessible from the given function, according * **seePrivate** : bool - * **block** : block<(array`>>#):void> implicit + * **block** : block<(array`>>\ #):void> implicit find_module @@ -6623,6 +7067,7 @@ find_module Finds a module by name in the specified program. + :Arguments: * **name** : string .. _function-ast_find_module_smart_ptr_ls_Program_gr__string: @@ -6637,6 +7082,7 @@ Finds a module by name in the specified program. Finds a function by name in the specified module using RTTI. + :Arguments: * **module** : :ref:`Module `? implicit * **function** : function @@ -6647,6 +7093,7 @@ Finds a function by name in the specified module using RTTI. Finds a module by name in the specified program using RTTI. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **name** : string implicit @@ -6657,6 +7104,7 @@ Finds a module by name in the specified program using RTTI. Finds the parent structure that declares the specified field. + :Arguments: * **structure** : smart_ptr< :ref:`Structure `> implicit * **name** : string implicit @@ -6667,6 +7115,7 @@ Finds the parent structure that declares the specified field. Returns the FieldDeclaration for a specific field of a structure type, or null if not found. + :Arguments: * **structPtr** : :ref:`Structure `? implicit * **field** : string implicit @@ -6677,6 +7126,7 @@ Returns the FieldDeclaration for a specific field of a structure type, or null i Finds a uniquely named structure in the program, returning it if unique or null if ambiguous. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **name** : string implicit @@ -6687,10 +7137,12 @@ Finds a uniquely named structure in the program, returning it if unique or null Finds a variable by name in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit * **variable** : string implicit + +++++++++ Iterating +++++++++ @@ -6723,6 +7175,7 @@ Iterating Iterates through any `array<>` type in a typeless fashion using `void?` pointers. + :Arguments: * **array** : void? implicit * **stride** : int @@ -6735,6 +7188,7 @@ Iterates through any `array<>` type in a typeless fashion using `void?` pointers Iterates through any `table<>` type in a typeless fashion using `void?` pointers. + :Arguments: * **table** : void? implicit * **keyStride** : int @@ -6749,6 +7203,7 @@ Iterates through any `table<>` type in a typeless fashion using `void?` pointers Iterates through each annotation in the given module in the order they were added. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<(uint64;uint64):void> implicit @@ -6759,9 +7214,10 @@ Iterates through each annotation in the given module in the order they were adde Iterates through every CallMacro adapter in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **block** : block<(string#):void> implicit + * **block** : block<(string\ #):void> implicit .. _function-ast_for_each_enumeration_Module_q__implicit_block_ls_smart_ptr_ls_Enumeration_gr__c_void_gr_: @@ -6769,6 +7225,7 @@ Iterates through every CallMacro adapter in the specified module. Iterates through every enumeration in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<(smart_ptr< :ref:`Enumeration `>):void> implicit @@ -6779,6 +7236,7 @@ Iterates through every enumeration in the specified module. Iterates through every field in a BuiltinStructure handled type. + :Arguments: * **annotation** : :ref:`BasicStructureAnnotation ` implicit * **block** : block<(string;string;smart_ptr< :ref:`TypeDecl `>;uint):void> implicit @@ -6789,6 +7247,7 @@ Iterates through every field in a BuiltinStructure handled type. Iterates through every for-loop macro in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<(smart_ptr< :ref:`ForLoopMacro `>):void> implicit @@ -6799,6 +7258,7 @@ Iterates through every for-loop macro in the specified module. Iterates through each function in the given module, matching all functions if the name is empty. + :Arguments: * **module** : :ref:`Module `? implicit * **name** : string implicit @@ -6815,6 +7275,7 @@ for_each_generic Iterates through each generic function in the given module. + :Arguments: * **module** : :ref:`Module `? implicit * **name** : string implicit @@ -6833,6 +7294,7 @@ Iterates through each generic function in the given module. Iterates through every global variable in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<(smart_ptr< :ref:`Variable `>):void> implicit @@ -6843,6 +7305,7 @@ Iterates through every global variable in the specified module. Iterates through each module in the program in dependency order. + :Arguments: * **program** : :ref:`Program `? implicit * **block** : block<( :ref:`Module `?):void> implicit @@ -6853,6 +7316,7 @@ Iterates through each module in the program in dependency order. Iterates through each function in the given module. + :Arguments: * **module** : :ref:`Module `? implicit * **blk** : block<(smart_ptr< :ref:`Function `>):void> implicit @@ -6863,6 +7327,7 @@ Iterates through each function in the given module. Iterates through each module in the program in no particular order, as they appear in the library group. + :Arguments: * **program** : :ref:`Program `? implicit * **block** : block<( :ref:`Module `?):void> implicit @@ -6873,9 +7338,10 @@ Iterates through each module in the program in no particular order, as they appe Iterates through each reader macro in the given module. + :Arguments: * **module** : :ref:`Module `? implicit - * **block** : block<(string#):void> implicit + * **block** : block<(string\ #):void> implicit .. _function-ast_for_each_structure_Module_q__implicit_block_ls_smart_ptr_ls_Structure_gr__c_void_gr_: @@ -6883,6 +7349,7 @@ Iterates through each reader macro in the given module. Iterates through every structure in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<(smart_ptr< :ref:`Structure `>):void> implicit @@ -6893,6 +7360,7 @@ Iterates through every structure in the specified module. Iterates over all structure aliases defined in the given structure type, invoking the provided block for each alias. + :Arguments: * **structure** : :ref:`Structure `? implicit * **block** : block<(smart_ptr< :ref:`TypeDecl `>):void> implicit @@ -6903,9 +7371,10 @@ Iterates over all structure aliases defined in the given structure type, invokin Iterates through every typedef in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **block** : block<(string#;smart_ptr< :ref:`TypeDecl `>):void> implicit + * **block** : block<(string\ #;smart_ptr< :ref:`TypeDecl `>):void> implicit .. _function-ast_for_each_typeinfo_macro_Module_q__implicit_block_ls_smart_ptr_ls_TypeInfoMacro_gr__c_void_gr_: @@ -6913,6 +7382,7 @@ Iterates through every typedef in the specified module. Iterates through each typeinfo macro in the given module. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<(smart_ptr< :ref:`TypeInfoMacro `>):void> implicit @@ -6923,6 +7393,7 @@ Iterates through each typeinfo macro in the given module. Iterates over all type macros registered in the given module, invoking the provided block for each one. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<(smart_ptr< :ref:`TypeMacro `>):void> implicit @@ -6933,10 +7404,12 @@ Iterates over all type macros registered in the given module, invoking the provi Iterates through each variant macro in the given module. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<(smart_ptr< :ref:`VariantMacro `>):void> implicit + +++++++ Cloning +++++++ @@ -6955,6 +7428,7 @@ Cloning Clones an Expression along with all its subexpressions and corresponding type information. + :Arguments: * **expression** : smart_ptr< :ref:`Expression `> implicit .. _function-ast_clone_file_info_string_implicit_int: @@ -6963,6 +7437,7 @@ Clones an Expression along with all its subexpressions and corresponding type in Clones a FileInfo structure. + :Arguments: * **name** : string implicit * **tab_size** : int @@ -6977,6 +7452,7 @@ clone_function Clones a Function and all of its contents. + :Arguments: * **function** : smart_ptr< :ref:`Function `> implicit .. _function-ast_clone_function_Function_q_: @@ -6991,6 +7467,7 @@ Clones a Function and all of its contents. Returns a deep clone of the specified Structure. + :Arguments: * **structure** : :ref:`Structure `? implicit .. _function-ast_clone_type_smart_ptr_ls_TypeDecl_gr__implicit: @@ -6999,6 +7476,7 @@ Returns a deep clone of the specified Structure. Clones a TypeDecl along with all its subtypes. + :Arguments: * **type** : smart_ptr< :ref:`TypeDecl `> implicit .. _function-ast_clone_variable_smart_ptr_ls_Variable_gr__implicit: @@ -7007,8 +7485,10 @@ Clones a TypeDecl along with all its subtypes. Clones a Variable and all of its contents. + :Arguments: * **variable** : smart_ptr< :ref:`Variable `> implicit + ++++++++++++ Mangled name ++++++++++++ @@ -7033,6 +7513,7 @@ get_mangled_name Returns the mangled name of the specified object. + :Arguments: * **function** : smart_ptr< :ref:`Function `> implicit .. _function-ast_get_mangled_name_smart_ptr_ls_TypeDecl_gr__implicit: @@ -7071,12 +7552,14 @@ Returns the mangled name of the specified object. Parses a mangled name string and creates the corresponding TypeDecl. + :Arguments: * **txt** : string implicit * **lib** : :ref:`ModuleGroup ` implicit * **thisModule** : :ref:`Module `? implicit + +++++++++++++++ Size and offset +++++++++++++++ @@ -7093,6 +7576,7 @@ Size and offset Returns the size of an array from a pointer to an `array<>` object. + :Arguments: * **array** : void? implicit .. _function-ast_any_table_size_void_q__implicit: @@ -7101,6 +7585,7 @@ Returns the size of an array from a pointer to an `array<>` object. Returns the size of a table from a pointer to a `table<>` object. + :Arguments: * **table** : void? implicit .. _function-ast_get_handled_type_field_offset_smart_ptr_ls_TypeAnnotation_gr__implicit_string_implicit: @@ -7109,6 +7594,7 @@ Returns the size of a table from a pointer to a `table<>` object. Returns the byte offset of a field in a ManagedStructure handled type. + :Arguments: * **type** : smart_ptr< :ref:`TypeAnnotation `> implicit * **field** : string implicit @@ -7119,6 +7605,7 @@ Returns the byte offset of a field in a ManagedStructure handled type. Returns the byte offset of a tuple field. + :Arguments: * **typle** : smart_ptr< :ref:`TypeDecl `> implicit * **index** : int @@ -7129,17 +7616,19 @@ Returns the byte offset of a tuple field. Returns the byte offset of a variant field. + :Arguments: * **variant** : smart_ptr< :ref:`TypeDecl `> implicit * **index** : int + +++++++++++ Evaluations +++++++++++ - * :ref:`eval_single_expression (expr: smart_ptr\ const& implicit; ok: bool& implicit) : float4 ` + * :ref:`eval_single_expression (expr: smart_ptr\ const& implicit; ok: bool& implicit) : float4 ` -.. _function-ast_eval_single_expression_smart_ptr_ls_Expression_gr__const_implicit_bool_implicit: +.. _function-ast_eval_single_expression_smart_ptr_ls_Expression_gr__const_ref__implicit_bool_ref__implicit: .. das:function:: eval_single_expression(expr: smart_ptr const& implicit; ok: bool& implicit) : float4 @@ -7148,9 +7637,11 @@ Evaluations Simulates and evaluates a single expression on a separate context. -:Arguments: * **expr** : smart_ptr< :ref:`Expression `>& implicit - * **ok** : bool& implicit +:Arguments: * **expr** : smart_ptr< :ref:`Expression `>\ & implicit + + * **ok** : bool\ & implicit + +++++++++++++++ Error reporting @@ -7164,19 +7655,21 @@ Error reporting Reports an error to the currently compiling program during the active compilation pass. + :Arguments: * **porogram** : smart_ptr< :ref:`Program `> implicit * **at** : :ref:`LineInfo ` implicit * **message** : string implicit + ++++++++++++++++++++ Location and context ++++++++++++++++++++ * :ref:`collect_dependencies (function: smart_ptr\ implicit; block: block\<(array\;array\):void\>) ` - * :ref:`force_at (function: smart_ptr\ const& implicit; at: LineInfo implicit) ` - * :ref:`force_at (expression: smart_ptr\ const& implicit; at: LineInfo implicit) ` + * :ref:`force_at (function: smart_ptr\ const& implicit; at: LineInfo implicit) ` + * :ref:`force_at (expression: smart_ptr\ const& implicit; at: LineInfo implicit) ` * :ref:`get_ast_context (program: smart_ptr\ implicit; expression: smart_ptr\ implicit; block: block\<(bool;AstContext):void\>) ` .. _function-ast_collect_dependencies_smart_ptr_ls_Function_gr__implicit_block_ls_array_ls_Function_q__gr_;array_ls_Variable_q__gr__c_void_gr_: @@ -7185,6 +7678,7 @@ Location and context Collects dependencies of a given function, including other functions it calls and global variables it accesses. + :Arguments: * **function** : smart_ptr< :ref:`Function `> implicit * **block** : block<(array< :ref:`Function `?>;array< :ref:`Variable `?>):void> implicit @@ -7193,17 +7687,18 @@ Collects dependencies of a given function, including other functions it calls an force_at ^^^^^^^^ -.. _function-ast_force_at_smart_ptr_ls_Function_gr__const_implicit_LineInfo_implicit: +.. _function-ast_force_at_smart_ptr_ls_Function_gr__const_ref__implicit_LineInfo_implicit: .. das:function:: force_at(function: smart_ptr const& implicit; at: LineInfo implicit) Replaces line info in an expression, its subexpressions, and their types. -:Arguments: * **function** : smart_ptr< :ref:`Function `>& implicit + +:Arguments: * **function** : smart_ptr< :ref:`Function `>\ & implicit * **at** : :ref:`LineInfo ` implicit -.. _function-ast_force_at_smart_ptr_ls_Expression_gr__const_implicit_LineInfo_implicit: +.. _function-ast_force_at_smart_ptr_ls_Expression_gr__const_ref__implicit_LineInfo_implicit: .. das:function:: force_at(expression: smart_ptr const& implicit; at: LineInfo implicit) @@ -7215,12 +7710,14 @@ Replaces line info in an expression, its subexpressions, and their types. Returns the AstContext for a given expression, including the current function, loops, blocks, scopes, and with sections. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **expression** : smart_ptr< :ref:`Expression `> implicit * **block** : block<(bool; :ref:`AstContext `):void> implicit + +++++++++++ Use queries +++++++++++ @@ -7234,6 +7731,7 @@ Use queries Invokes a block with the list of all functions called by the specified function. + :Arguments: * **func** : smart_ptr< :ref:`Function `> implicit * **block** : block<(smart_ptr< :ref:`Function `>):void> implicit @@ -7244,10 +7742,12 @@ Invokes a block with the list of all functions called by the specified function. Invokes a block with the list of all global variables accessed by the specified function. + :Arguments: * **func** : smart_ptr< :ref:`Function `> implicit * **block** : block<(smart_ptr< :ref:`Variable `>):void> implicit + +++ Log +++ @@ -7260,29 +7760,33 @@ Log Writes a message to the compilation log from a macro during compilation. + :Arguments: * **text** : string implicit + +++++++ Removal +++++++ - * :ref:`remove_structure (module: Module? implicit; structure: smart_ptr\& implicit) : bool ` + * :ref:`remove_structure (module: Module? implicit; structure: smart_ptr\& implicit) : bool ` -.. _function-ast_remove_structure_Module_q__implicit_smart_ptr_ls_Structure_gr__implicit: +.. _function-ast_remove_structure_Module_q__implicit_smart_ptr_ls_Structure_gr__ref__implicit: .. das:function:: remove_structure(module: Module? implicit; structure: smart_ptr& implicit) : bool Removes a structure declaration from the specified module. + :Arguments: * **module** : :ref:`Module `? implicit - * **structure** : smart_ptr< :ref:`Structure `>& implicit + * **structure** : smart_ptr< :ref:`Structure `>\ & implicit + ++++++++++ Properties ++++++++++ - * :ref:`can_access_global_variable (variable: smart_ptr\ const& implicit; module: Module? implicit; thisModule: Module? implicit) : bool ` + * :ref:`can_access_global_variable (variable: smart_ptr\ const& implicit; module: Module? implicit; thisModule: Module? implicit) : bool ` * :ref:`get_aot_arg_prefix (func: Function? implicit; call: ExprCallFunc? implicit; argIndex: int) : string ` * :ref:`get_aot_arg_suffix (func: Function? implicit; call: ExprCallFunc? implicit; argIndex: int) : string ` * :ref:`get_aot_name (func: Function? implicit; call: ExprCallFunc? implicit) : string ` @@ -7300,20 +7804,21 @@ Properties * :ref:`get_vector_length (vec: void? implicit; type: smart_ptr\ implicit) : int ` * :ref:`get_vector_ptr_at_index (vec: void? implicit; type: TypeDecl? implicit; idx: int) : void? ` * :ref:`has_field (type: smart_ptr\ implicit; fieldName: string implicit; constant: bool) : bool ` - * :ref:`is_expr_const (expression: smart_ptr\ const& implicit) : bool ` - * :ref:`is_expr_like_call (expression: smart_ptr\ const& implicit) : bool ` + * :ref:`is_expr_const (expression: smart_ptr\ const& implicit) : bool ` + * :ref:`is_expr_like_call (expression: smart_ptr\ const& implicit) : bool ` * :ref:`is_same_type (leftType: smart_ptr\ implicit; rightType: smart_ptr\ implicit; refMatters: RefMatters; constMatters: ConstMatters; tempMatters: TemporaryMatters) : bool ` * :ref:`is_same_type (argType: smart_ptr\ implicit; passType: smart_ptr\ implicit; refMatters: bool; constMatters: bool; temporaryMatters: bool; allowSubstitute: bool) : bool ` * :ref:`is_temp_type (type: smart_ptr\ implicit; refMatters: bool) : bool ` * :ref:`is_visible_directly (from_module: Module? implicit; which_module: Module? implicit) : bool ` -.. _function-ast_can_access_global_variable_smart_ptr_ls_Variable_gr__const_implicit_Module_q__implicit_Module_q__implicit: +.. _function-ast_can_access_global_variable_smart_ptr_ls_Variable_gr__const_ref__implicit_Module_q__implicit_Module_q__implicit: .. das:function:: can_access_global_variable(variable: smart_ptr const& implicit; module: Module? implicit; thisModule: Module? implicit) : bool Returns true if a global variable is accessible from the specified module. -:Arguments: * **variable** : smart_ptr< :ref:`Variable `>& implicit + +:Arguments: * **variable** : smart_ptr< :ref:`Variable `>\ & implicit * **module** : :ref:`Module `? implicit @@ -7325,6 +7830,7 @@ Returns true if a global variable is accessible from the specified module. Returns the AOT argument prefix string for the specified function. + :Arguments: * **func** : :ref:`Function `? implicit * **call** : :ref:`ExprCallFunc `? implicit @@ -7337,6 +7843,7 @@ Returns the AOT argument prefix string for the specified function. Returns the AOT argument suffix string for the specified function. + :Arguments: * **func** : :ref:`Function `? implicit * **call** : :ref:`ExprCallFunc `? implicit @@ -7349,6 +7856,7 @@ Returns the AOT argument suffix string for the specified function. Returns the AOT-generated name for the specified function. + :Arguments: * **func** : :ref:`Function `? implicit * **call** : :ref:`ExprCallFunc `? implicit @@ -7359,6 +7867,7 @@ Returns the AOT-generated name for the specified function. Returns the module currently being searched for a function by name, correctly resolving special names like `""`, `"_"`, `"*"`, and `"__"`. + :Arguments: * **program** : :ref:`Program `? implicit * **function** : :ref:`Function `? implicit @@ -7371,6 +7880,7 @@ Returns the module currently being searched for a function by name, correctly re Returns the type of a field if the target is a structure, variant, tuple, handled type, or pointer to any of those, or null otherwise. + :Arguments: * **type** : smart_ptr< :ref:`TypeDecl `> implicit * **fieldName** : string implicit @@ -7383,6 +7893,7 @@ Returns the type of a field if the target is a structure, variant, tuple, handle Returns the AOT function prefix string for the specified function. + :Arguments: * **ann** : :ref:`FunctionAnnotation `? implicit * **stg** : :ref:`StringBuilderWriter `? implicit @@ -7395,6 +7906,7 @@ Returns the AOT function prefix string for the specified function. Returns the hash of a function used for AOT matching. + :Arguments: * **fun** : :ref:`Function `? implicit .. _function-ast_get_function_hash_by_id_Function_q__implicit_int_void_q__implicit: @@ -7403,6 +7915,7 @@ Returns the hash of a function used for AOT matching. Returns the hash of a function given its unique identifier. + :Arguments: * **fun** : :ref:`Function `? implicit * **id** : int @@ -7415,6 +7928,7 @@ Returns the hash of a function given its unique identifier. Returns the type of a field in a ManagedStructure handled type. + :Arguments: * **type** : smart_ptr< :ref:`TypeAnnotation `> implicit * **field** : string implicit @@ -7425,6 +7939,7 @@ Returns the type of a field in a ManagedStructure handled type. Returns the type declaration of a field in a ManagedStructure handled type. + :Arguments: * **type** : smart_ptr< :ref:`TypeAnnotation `> implicit * **field** : string implicit @@ -7437,6 +7952,7 @@ Returns the type declaration of a field in a ManagedStructure handled type. Returns the type declaration of the index operator for a handled type. + :Arguments: * **type** : :ref:`TypeAnnotation `? implicit * **src** : :ref:`Expression `? implicit @@ -7449,6 +7965,7 @@ Returns the type declaration of the index operator for a handled type. Returns the AOT prefix string for the specified structure. + :Arguments: * **ann** : :ref:`StructureAnnotation `? implicit * **structure** : :ref:`Structure `? implicit @@ -7463,6 +7980,7 @@ Returns the AOT prefix string for the specified structure. Finds and returns a structure alias type by its alias name. + :Arguments: * **structure** : :ref:`Structure `? implicit * **aliasName** : string implicit @@ -7473,6 +7991,7 @@ Finds and returns a structure alias type by its alias name. Returns the daslang type aliased by a ManagedValue handled type. + :Arguments: * **type** : smart_ptr< :ref:`TypeDecl `> implicit .. _function-ast_get_vector_length_void_q__implicit_smart_ptr_ls_TypeDecl_gr__implicit: @@ -7481,6 +8000,7 @@ Returns the daslang type aliased by a ManagedValue handled type. Returns the length of a vector given a pointer to the vector object and its TypeDeclPtr. + :Arguments: * **vec** : void? implicit * **type** : smart_ptr< :ref:`TypeDecl `> implicit @@ -7491,6 +8011,7 @@ Returns the length of a vector given a pointer to the vector object and its Type Returns a pointer to the vector element at the specified index given a pointer to the vector object and its TypeDeclPtr. + :Arguments: * **vec** : void? implicit * **type** : :ref:`TypeDecl `? implicit @@ -7503,27 +8024,30 @@ Returns a pointer to the vector element at the specified index given a pointer t Returns true if a structure, variant, tuple, handled type, or pointer to any of those has the specified field. + :Arguments: * **type** : smart_ptr< :ref:`TypeDecl `> implicit * **fieldName** : string implicit * **constant** : bool -.. _function-ast_is_expr_const_smart_ptr_ls_Expression_gr__const_implicit: +.. _function-ast_is_expr_const_smart_ptr_ls_Expression_gr__const_ref__implicit: .. das:function:: is_expr_const(expression: smart_ptr const& implicit) : bool Returns true if the expression is or inherits from ExprConst. -:Arguments: * **expression** : smart_ptr< :ref:`Expression `>& implicit -.. _function-ast_is_expr_like_call_smart_ptr_ls_Expression_gr__const_implicit: +:Arguments: * **expression** : smart_ptr< :ref:`Expression `>\ & implicit + +.. _function-ast_is_expr_like_call_smart_ptr_ls_Expression_gr__const_ref__implicit: .. das:function:: is_expr_like_call(expression: smart_ptr const& implicit) : bool Returns true if the expression is or inherits from ExprLooksLikeCall. -:Arguments: * **expression** : smart_ptr< :ref:`Expression `>& implicit + +:Arguments: * **expression** : smart_ptr< :ref:`Expression `>\ & implicit is_same_type @@ -7535,6 +8059,7 @@ is_same_type Compares two types using the given comparison parameters and returns true if they match. + :Arguments: * **leftType** : smart_ptr< :ref:`TypeDecl `> implicit * **rightType** : smart_ptr< :ref:`TypeDecl `> implicit @@ -7557,6 +8082,7 @@ Compares two types using the given comparison parameters and returns true if the Returns true if the specified type can be temporary. + :Arguments: * **type** : smart_ptr< :ref:`TypeDecl `> implicit * **refMatters** : bool @@ -7567,10 +8093,12 @@ Returns true if the specified type can be temporary. Returns true if one module is directly visible from another module. + :Arguments: * **from_module** : :ref:`Module `? implicit * **which_module** : :ref:`Module `? implicit + +++++ Infer +++++ @@ -7584,6 +8112,7 @@ Infer Infers a concrete type from a generic type declaration and a pass type. + :Arguments: * **type** : smart_ptr< :ref:`TypeDecl `> implicit * **passType** : smart_ptr< :ref:`TypeDecl `> implicit @@ -7598,12 +8127,14 @@ Infers a concrete type from a generic type declaration and a pass type. Updates the alias map for the specified type during inference. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **argType** : smart_ptr< :ref:`TypeDecl `> implicit * **passType** : smart_ptr< :ref:`TypeDecl `> implicit + ++++++++++++++ Module queries ++++++++++++++ @@ -7619,6 +8150,7 @@ Module queries Finds an annotation by name in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit * **name** : string implicit @@ -7629,6 +8161,7 @@ Finds an annotation by name in the specified module. Finds a structure by name in the specified module. + :Arguments: * **program** : :ref:`Module `? implicit * **name** : string implicit @@ -7639,6 +8172,7 @@ Finds a structure by name in the specified module. Finds a type annotation by name in the specified module. + :Arguments: * **module** : :ref:`Module `? implicit * **name** : string implicit @@ -7649,37 +8183,41 @@ Finds a type annotation by name in the specified module. Marks a function as modified by a macro so that it will be inferred again. + :Arguments: * **function** : :ref:`Function `? implicit + ++++++++++++++++++ Debug info helpers ++++++++++++++++++ - * :ref:`debug_helper_find_struct_cppname (helper: smart_ptr\ const& implicit; struct_info: StructInfo? implicit) : string ` - * :ref:`debug_helper_find_type_cppname (helper: smart_ptr\ const& implicit; type_info: TypeInfo? implicit) : string ` + * :ref:`debug_helper_find_struct_cppname (helper: smart_ptr\ const& implicit; struct_info: StructInfo? implicit) : string ` + * :ref:`debug_helper_find_type_cppname (helper: smart_ptr\ const& implicit; type_info: TypeInfo? implicit) : string ` * :ref:`debug_helper_iter_enums (helper: smart_ptr\ implicit; blk: block\<(string;EnumInfo?):void\>) ` * :ref:`debug_helper_iter_funcs (helper: smart_ptr\ implicit; blk: block\<(string;FuncInfo?):void\>) ` * :ref:`debug_helper_iter_structs (helper: smart_ptr\ implicit; blk: block\<(string;StructInfo?):void\>) ` * :ref:`debug_helper_iter_types (helper: smart_ptr\ implicit; blk: block\<(string;TypeInfo?):void\>) ` * :ref:`debug_helper_iter_vars (helper: smart_ptr\ implicit; blk: block\<(string;VarInfo?):void\>) ` -.. _function-ast_debug_helper_find_struct_cppname_smart_ptr_ls_DebugInfoHelper_gr__const_implicit_StructInfo_q__implicit: +.. _function-ast_debug_helper_find_struct_cppname_smart_ptr_ls_DebugInfoHelper_gr__const_ref__implicit_StructInfo_q__implicit: .. das:function:: debug_helper_find_struct_cppname(helper: smart_ptr const& implicit; struct_info: StructInfo? implicit) : string Finds a structure in the DebugInfoHelper and returns its C++ name. -:Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `>& implicit + +:Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `>\ & implicit * **struct_info** : :ref:`StructInfo `? implicit -.. _function-ast_debug_helper_find_type_cppname_smart_ptr_ls_DebugInfoHelper_gr__const_implicit_TypeInfo_q__implicit: +.. _function-ast_debug_helper_find_type_cppname_smart_ptr_ls_DebugInfoHelper_gr__const_ref__implicit_TypeInfo_q__implicit: .. das:function:: debug_helper_find_type_cppname(helper: smart_ptr const& implicit; type_info: TypeInfo? implicit) : string Finds a type in the DebugInfoHelper and returns its C++ name. -:Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `>& implicit + +:Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `>\ & implicit * **type_info** : :ref:`TypeInfo `? implicit @@ -7689,6 +8227,7 @@ Finds a type in the DebugInfoHelper and returns its C++ name. Iterates through all enumerations in the DebugInfoHelper, invoking the provided block for each one. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **blk** : block<(string; :ref:`EnumInfo `?):void> implicit @@ -7699,6 +8238,7 @@ Iterates through all enumerations in the DebugInfoHelper, invoking the provided Iterates through all functions in the DebugInfoHelper, invoking the provided block for each one. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **blk** : block<(string; :ref:`FuncInfo `?):void> implicit @@ -7709,6 +8249,7 @@ Iterates through all functions in the DebugInfoHelper, invoking the provided blo Iterates through all structures in the DebugInfoHelper, invoking the provided block for each one. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **blk** : block<(string; :ref:`StructInfo `?):void> implicit @@ -7719,6 +8260,7 @@ Iterates through all structures in the DebugInfoHelper, invoking the provided bl Iterates through all types in the DebugInfoHelper, invoking the provided block for each one. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **blk** : block<(string; :ref:`TypeInfo `?):void> implicit @@ -7729,10 +8271,12 @@ Iterates through all types in the DebugInfoHelper, invoking the provided block f Iterates through all variables in the DebugInfoHelper, invoking the provided block for each one. + :Arguments: * **helper** : smart_ptr< :ref:`DebugInfoHelper `> implicit * **blk** : block<(string; :ref:`VarInfo `?):void> implicit + +++++++++++ AOT support +++++++++++ @@ -7756,6 +8300,7 @@ AOT support Returns true if a `TypeInfo?` is needed for the specified type in a typeinfo expression. + :Arguments: * **macro** : :ref:`TypeInfoMacro `? implicit * **expr** : smart_ptr< :ref:`Expression `> implicit @@ -7766,6 +8311,7 @@ Returns true if a `TypeInfo?` is needed for the specified type in a typeinfo exp Performs the pre-visit step for field access during AOT code generation. + :Arguments: * **ann** : :ref:`TypeAnnotation `? implicit * **ss** : :ref:`StringBuilderWriter `? implicit @@ -7778,6 +8324,7 @@ Performs the pre-visit step for field access during AOT code generation. Performs the pre-visit step for field pointer access during AOT code generation. + :Arguments: * **ann** : :ref:`TypeAnnotation `? implicit * **ss** : :ref:`StringBuilderWriter `? implicit @@ -7790,6 +8337,7 @@ Performs the pre-visit step for field pointer access during AOT code generation. Writes data to the require section of an AOT module. + :Arguments: * **mod** : :ref:`Module `? implicit * **ss** : :ref:`StringBuilderWriter `? implicit @@ -7800,6 +8348,7 @@ Writes data to the require section of an AOT module. Returns the access symbol string for a field, such as `->` for pointer types or `.` for value types. + :Arguments: * **ann** : :ref:`TypeAnnotation `? implicit * **ss** : :ref:`StringBuilderWriter `? implicit @@ -7812,6 +8361,7 @@ Returns the access symbol string for a field, such as `->` for pointer types or Performs the visit step for field access during AOT code generation. + :Arguments: * **ann** : :ref:`TypeAnnotation `? implicit * **ss** : :ref:`StringBuilderWriter `? implicit @@ -7824,6 +8374,7 @@ Performs the visit step for field access during AOT code generation. Returns the initialization semantic hash including dependencies for the entire program. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **init** : uint64 @@ -7834,6 +8385,7 @@ Returns the initialization semantic hash including dependencies for the entire p Returns true if the macro requires an AOT infix operator for the specified handled type. + :Arguments: * **macro** : :ref:`TypeInfoMacro `? implicit * **ss** : :ref:`StringBuilderWriter `? implicit @@ -7846,6 +8398,7 @@ Returns true if the macro requires an AOT infix operator for the specified handl Writes the AOT body code for the specified StructureAnnotation. + :Arguments: * **structure** : :ref:`StructureAnnotation `? implicit * **st** : smart_ptr< :ref:`Structure `> implicit @@ -7860,6 +8413,7 @@ Writes the AOT body code for the specified StructureAnnotation. Writes the AOT macro prefix code for the specified TypeInfoMacro. + :Arguments: * **macro** : :ref:`TypeInfoMacro `? implicit * **ss** : :ref:`StringBuilderWriter `? implicit @@ -7872,6 +8426,7 @@ Writes the AOT macro prefix code for the specified TypeInfoMacro. Writes the AOT macro suffix code for the specified TypeInfoMacro. + :Arguments: * **macro** : :ref:`TypeInfoMacro `? implicit * **ss** : :ref:`StringBuilderWriter `? implicit @@ -7884,6 +8439,7 @@ Writes the AOT macro suffix code for the specified TypeInfoMacro. Writes the AOT suffix code for the specified StructureAnnotation. + :Arguments: * **structure** : :ref:`StructureAnnotation `? implicit * **st** : smart_ptr< :ref:`Structure `> implicit @@ -7892,6 +8448,7 @@ Writes the AOT suffix code for the specified StructureAnnotation. * **writer** : :ref:`StringBuilderWriter `? implicit + +++++++++++++++++++++ String builder writer +++++++++++++++++++++ @@ -7905,6 +8462,7 @@ String builder writer Clears a StringBuilder object given a pointer to it. + :Arguments: * **ss** : :ref:`StringBuilderWriter `? implicit .. _function-ast_string_builder_str_StringBuilderWriter_q__implicit: @@ -7913,6 +8471,7 @@ Clears a StringBuilder object given a pointer to it. Returns the accumulated string from a StringBuilder object given a pointer to it. + :Arguments: * **ss** : :ref:`StringBuilderWriter `? implicit diff --git a/doc/source/stdlib/ast_block_to_loop.rst b/doc/source/stdlib/ast_block_to_loop.rst index ba857b2bed..1e40a1600f 100644 --- a/doc/source/stdlib/ast_block_to_loop.rst +++ b/doc/source/stdlib/ast_block_to_loop.rst @@ -5,6 +5,8 @@ DECS, AST block to loop ======================= +.. das:module:: ast_block_to_loop + The AST_BLOCK_TO_LOOP module provides an AST transformation macro that converts block-based iteration patterns into explicit loop constructs. Used internally by other macro libraries for optimization. @@ -13,6 +15,8 @@ All functions and symbols are in "ast_block_to_loop" module, use require to get require daslib/ast_block_to_loop + + ++++++++++++++++++++++++ Block to loop conversion ++++++++++++++++++++++++ @@ -28,6 +32,7 @@ If `failOnReturn` is true, then returns are not allowed inside the block. If `replaceReturnWithContinue` is true, then `return cond;` are replaced with `if cond; continue;`. If `requireContinueCond` is false, then `return;` is replaced with `continue;`, otherwise it is an error. + :Arguments: * **blk** : smart_ptr< :ref:`Expression `> * **failOnReturn** : bool diff --git a/doc/source/stdlib/ast_boost.rst b/doc/source/stdlib/ast_boost.rst index d248e505b6..9e42289e80 100644 --- a/doc/source/stdlib/ast_boost.rst +++ b/doc/source/stdlib/ast_boost.rst @@ -5,6 +5,8 @@ Boost package for the AST ========================= +.. das:module:: ast_boost + The AST_BOOST module provides high-level utilities for working with the AST. It includes helpers for creating expressions, types, and declarations, quote-based AST construction, and common AST query and transformation @@ -14,6 +16,8 @@ All functions and symbols are in "ast_boost" module, use require to get access t require daslib/ast_boost + + ++++++++++++ Type aliases ++++++++++++ @@ -23,6 +27,7 @@ Type aliases .. das:attribute:: AnnotationDeclarationPtr = smart_ptr Type alias for ``smart_ptr``, used when constructing or attaching annotation declarations to functions, blocks, or structures. + .. _alias-DebugExpressionFlags: .. das:attribute:: bitfield DebugExpressionFlags @@ -30,6 +35,8 @@ Type alias for ``smart_ptr``, used when constructing or a :Fields: * **refCount** (0x1) - Bitfield controlling ``debug_expression`` output — currently has a single ``refCount`` flag that includes smart pointer reference counts in the dump. + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -39,11 +46,14 @@ Function annotations .. das:attribute:: macro The ``[macro]`` function annotation — marks a function to run only during macro module compilation, gating its body behind ``is_compiling_macros``. + .. _handle-ast_boost-tag_function: .. das:attribute:: tag_function The ``[tag_function]`` function annotation — attaches named tags to a function so that ``[tag_function_macro]``-based annotations can discover and process it. + + ++++++++++++++ Variant macros ++++++++++++++ @@ -55,6 +65,8 @@ Variant macros Variant macro that enables improved RTTI type matching in `is` and `as` expressions. Varian macro better_rtti_in_expr + + ++++++++++++++++ Structure macros ++++++++++++++++ @@ -64,106 +76,128 @@ Structure macros .. das:attribute:: function_macro The ``[function_macro]`` structure annotation — registers an ``AstFunctionAnnotation`` subclass as a named function annotation available to the compiler. + .. _handle-ast_boost-block_macro: .. das:attribute:: block_macro The ``[block_macro]`` structure annotation — registers an ``AstBlockAnnotation`` subclass as a named block-level annotation available to the compiler. + .. _handle-ast_boost-structure_macro: .. das:attribute:: structure_macro The ``[structure_macro]`` structure annotation — registers an ``AstStructureAnnotation`` subclass as a named annotation applicable to structures and classes. + .. _handle-ast_boost-enumeration_macro: .. das:attribute:: enumeration_macro The ``[enumeration_macro]`` structure annotation — registers an ``AstEnumerationAnnotation`` subclass as a named annotation applicable to enumerations. + .. _handle-ast_boost-contract: .. das:attribute:: contract The ``[contract]`` structure annotation — registers an ``AstFunctionAnnotation`` subclass as a named function contract that validates arguments or return values. + .. _handle-ast_boost-reader_macro: .. das:attribute:: reader_macro The ``[reader_macro]`` structure annotation — registers an ``AstReaderMacro`` subclass as a named reader macro invoked by the ``%name~...~~`` syntax during parsing. + .. _handle-ast_boost-comment_reader: .. das:attribute:: comment_reader The ``[comment_reader]`` structure annotation — registers an ``AstCommentReader`` subclass as a named comment reader invoked during parsing. + .. _handle-ast_boost-call_macro: .. das:attribute:: call_macro The ``[call_macro]`` structure annotation — registers an ``AstCallMacro`` subclass as a named call-expression macro available during compilation. + .. _handle-ast_boost-typeinfo_macro: .. das:attribute:: typeinfo_macro The ``[typeinfo_macro]`` structure annotation — registers an ``AstTypeInfoMacro`` subclass as a named macro that extends the ``typeinfo(name ...)`` built-in. + .. _handle-ast_boost-variant_macro: .. das:attribute:: variant_macro The ``[variant_macro]`` structure annotation — registers an ``AstVariantMacro`` subclass as a named macro that can customize ``is``, ``as``, and ``?as`` variant operations. + .. _handle-ast_boost-for_loop_macro: .. das:attribute:: for_loop_macro The ``[for_loop_macro]`` structure annotation — registers an ``AstForLoopMacro`` subclass as a named macro that can transform ``for`` loop expressions. + .. _handle-ast_boost-capture_macro: .. das:attribute:: capture_macro The ``[capture_macro]`` structure annotation — registers an ``AstCaptureMacro`` subclass as a named capture macro that can customize lambda capture behavior. + .. _handle-ast_boost-type_macro: .. das:attribute:: type_macro The ``[type_macro]`` structure annotation — registers an ``AstTypeMacro`` subclass as a named macro that can intercept and transform type expressions. + .. _handle-ast_boost-simulate_macro: .. das:attribute:: simulate_macro The ``[simulate_macro]`` structure annotation — registers an ``AstSimulateMacro`` subclass as a named macro invoked during the simulation (code generation) phase. + .. _handle-ast_boost-tag_structure: .. das:attribute:: tag_structure The ``[tag_structure]`` structure annotation — attaches named boolean tags to a structure, allowing macro code to discover and process tagged structures. + .. _handle-ast_boost-tag_function_macro: .. das:attribute:: tag_function_macro The ``[tag_function_macro]`` structure annotation — registers an ``AstFunctionAnnotation`` that is automatically applied to every function carrying a matching ``[tag_function(tag)]`` tag. + .. _handle-ast_boost-infer_macro: .. das:attribute:: infer_macro The ``[infer_macro]`` structure annotation — registers an ``AstPassMacro`` subclass that is invoked during the type inference compilation pass. + .. _handle-ast_boost-dirty_infer_macro: .. das:attribute:: dirty_infer_macro The ``[dirty_infer_macro]`` structure annotation — registers an ``AstPassMacro`` subclass that is invoked during the dirty infer compilation pass. + .. _handle-ast_boost-optimization_macro: .. das:attribute:: optimization_macro The ``[optimization_macro]`` structure annotation — registers an ``AstPassMacro`` subclass that is invoked during the optimization compilation pass. + .. _handle-ast_boost-lint_macro: .. das:attribute:: lint_macro The ``[lint_macro]`` structure annotation — registers an ``AstPassMacro`` subclass that is invoked during the lint compilation pass. + .. _handle-ast_boost-global_lint_macro: .. das:attribute:: global_lint_macro The ``[global_lint_macro]`` structure annotation — registers an ``AstPassMacro`` subclass that is invoked during the global lint compilation pass. + + +++++++ Classes +++++++ @@ -175,12 +209,14 @@ Classes Implements the ``[macro]`` function annotation, which wraps the function body so it only executes during macro module compilation. + .. _function-ast_boost_MacroMacro_rq_apply_MacroMacro_FunctionPtr_ModuleGroup_AnnotationArgumentList_das_string_0xab: .. das:function:: MacroMacro.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool Wraps the annotated function body in an ``is_compiling_macros`` guard and sets ``macroInit`` flag so it only runs during macro module compilation. + :Arguments: * **func** : :ref:`FunctionPtr ` * **group** : :ref:`ModuleGroup ` @@ -196,12 +232,14 @@ Wraps the annotated function body in an ``is_compiling_macros`` guard and sets ` Implements the ``[tag_function]`` function annotation, which attaches named boolean tags to functions so they can be discovered and processed by ``[tag_function_macro]``. + .. _function-ast_boost_TagFunctionAnnotation_rq_apply_TagFunctionAnnotation_FunctionPtr_ModuleGroup_AnnotationArgumentList_das_string_0xba: .. das:function:: TagFunctionAnnotation.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool Validates that all ``[tag_function(...)]`` annotation arguments are tag names (boolean flags) and rejects any non-boolean arguments with an error. + :Arguments: * **func** : :ref:`FunctionPtr ` * **group** : :ref:`ModuleGroup ` @@ -217,12 +255,14 @@ Validates that all ``[tag_function(...)]`` annotation arguments are tag names (b Implements the ``[tag_structure]`` structure annotation, which attaches named boolean tags to structures for later discovery by macro code. + .. _function-ast_boost_TagStructureAnnotation_rq_apply_TagStructureAnnotation_StructurePtr_ModuleGroup_AnnotationArgumentList_das_string_0xc9: .. das:function:: TagStructureAnnotation.apply(str: StructurePtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool Validates that all ``[tag_structure(...)]`` annotation arguments are tag names (boolean flags) and rejects any non-boolean arguments with an error. + :Arguments: * **str** : :ref:`StructurePtr ` * **group** : :ref:`ModuleGroup ` @@ -242,12 +282,14 @@ This is base class for any annotation or macro setup. * **name** : string - Name of the annotation to setup. + .. _function-ast_boost_SetupAnyAnnotation_rq_apply_SetupAnyAnnotation_StructurePtr_ModuleGroup_AnnotationArgumentList_das_string_0x18f: .. das:function:: SetupAnyAnnotation.apply(st: StructurePtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool Generates a macro-init function that constructs an instance of the annotated class and registers it with the compiler under the specified ``name``. + :Arguments: * **st** : :ref:`StructurePtr ` * **group** : :ref:`ModuleGroup ` @@ -262,6 +304,7 @@ Generates a macro-init function that constructs an instance of the annotated cla Populates the registration call arguments — by default adds the annotation ``name`` as a string constant; overridden in subclasses to add extra parameters. + :Arguments: * **st** : :ref:`StructurePtr ` * **cll** : smart_ptr< :ref:`ExprCall `> @@ -273,6 +316,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_function_annotation" - Base class for creating function annotations via the ``[function_macro]`` structure annotation; registers an ``AstFunctionAnnotation`` with the compiler. + .. _struct-ast_boost-SetupBlockAnnotation: .. das:attribute:: SetupBlockAnnotation : SetupAnyAnnotation @@ -280,6 +324,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_block_annotation" - Base class for creating block annotations via the ``[block_macro]`` structure annotation; registers an ``AstBlockAnnotation`` with the compiler. + .. _struct-ast_boost-SetupStructureAnnotation: .. das:attribute:: SetupStructureAnnotation : SetupAnyAnnotation @@ -287,6 +332,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_structure_annotation" - Base class for creating structure annotations via the ``[structure_macro]`` structure annotation; registers an ``AstStructureAnnotation`` with the compiler. + .. _struct-ast_boost-SetupEnumerationAnnotation: .. das:attribute:: SetupEnumerationAnnotation : SetupAnyAnnotation @@ -294,6 +340,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_enumeration_annotation" - Base class for creating enumeration annotations via the ``[enumeration_macro]`` structure annotation; registers an ``AstEnumerationAnnotation`` with the compiler. + .. _struct-ast_boost-SetupContractAnnotation: .. das:attribute:: SetupContractAnnotation : SetupAnyAnnotation @@ -301,6 +348,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_contract_annotation" - Base class for creating function contract annotations via the ``[contract]`` structure annotation; registers an ``AstFunctionAnnotation`` as a contract. + .. _struct-ast_boost-SetupReaderMacro: .. das:attribute:: SetupReaderMacro : SetupAnyAnnotation @@ -308,6 +356,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_reader_macro" - Base class for creating reader macros via the ``[reader_macro]`` structure annotation; registers an ``AstReaderMacro`` with the compiler. + .. _struct-ast_boost-SetupCommentReader: .. das:attribute:: SetupCommentReader : SetupAnyAnnotation @@ -315,6 +364,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_comment_reader" - Base class for creating comment readers via the ``[comment_reader]`` structure annotation; registers an ``AstCommentReader`` with the compiler. + .. _struct-ast_boost-SetupVariantMacro: .. das:attribute:: SetupVariantMacro : SetupAnyAnnotation @@ -322,6 +372,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_variant_macro" - Base class for creating variant macros via the ``[variant_macro]`` structure annotation; registers an ``AstVariantMacro`` with the compiler. + .. _struct-ast_boost-SetupForLoopMacro: .. das:attribute:: SetupForLoopMacro : SetupAnyAnnotation @@ -329,6 +380,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_for_loop_macro" - Base class for creating for-loop macros via the ``[for_loop_macro]`` structure annotation; registers an ``AstForLoopMacro`` with the compiler. + .. _struct-ast_boost-SetupCaptureMacro: .. das:attribute:: SetupCaptureMacro : SetupAnyAnnotation @@ -336,6 +388,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_capture_macro" - Base class for creating capture macros via the ``[capture_macro]`` structure annotation; registers an ``AstCaptureMacro`` with the compiler. + .. _struct-ast_boost-SetupTypeMacro: .. das:attribute:: SetupTypeMacro : SetupAnyAnnotation @@ -343,6 +396,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_type_macro" - Base class for creating type macros via the ``[type_macro]`` structure annotation; registers an ``AstTypeMacro`` with the compiler. + .. _struct-ast_boost-SetupSimulateMacro: .. das:attribute:: SetupSimulateMacro : SetupAnyAnnotation @@ -350,6 +404,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_simulate_macro" - Base class for creating simulate macros via the ``[simulate_macro]`` structure annotation; registers an ``AstSimulateMacro`` with the compiler. + .. _struct-ast_boost-SetupCallMacro: .. das:attribute:: SetupCallMacro : SetupAnyAnnotation @@ -357,6 +412,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_call_macro" - Base class for creating call macros via the ``[call_macro]`` structure annotation; registers an ``AstCallMacro`` with the compiler. + .. _struct-ast_boost-SetupTypeInfoMacro: .. das:attribute:: SetupTypeInfoMacro : SetupAnyAnnotation @@ -364,6 +420,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_typeinfo_macro" - Base class for creating typeinfo macros via the ``[typeinfo_macro]`` structure annotation; registers an ``AstTypeInfoMacro`` with the compiler. + .. _struct-ast_boost-SetupInferMacro: .. das:attribute:: SetupInferMacro : SetupAnyAnnotation @@ -371,6 +428,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_infer_macro" - Base class for creating infer pass macros via the ``[infer_macro]`` structure annotation; registers an ``AstPassMacro`` that runs during the type inference pass. + .. _struct-ast_boost-SetupDirtyInferMacro: .. das:attribute:: SetupDirtyInferMacro : SetupAnyAnnotation @@ -378,6 +436,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_dirty_infer_macro" - Base class for creating dirty-infer pass macros via the ``[dirty_infer_macro]`` structure annotation; registers an ``AstPassMacro`` that runs during the dirty infer pass. + .. _struct-ast_boost-SetupLintMacro: .. das:attribute:: SetupLintMacro : SetupAnyAnnotation @@ -385,6 +444,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_lint_macro" - Base class for creating lint pass macros via the ``[lint_macro]`` structure annotation; registers an ``AstPassMacro`` that runs during the lint pass. + .. _struct-ast_boost-SetupGlobalLintMacro: .. das:attribute:: SetupGlobalLintMacro : SetupAnyAnnotation @@ -392,6 +452,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_global_lint_macro" - Base class for creating global lint pass macros via the ``[global_lint_macro]`` structure annotation; registers an ``AstPassMacro`` that runs during the global lint pass. + .. _struct-ast_boost-SetupOptimizationMacro: .. das:attribute:: SetupOptimizationMacro : SetupAnyAnnotation @@ -399,6 +460,7 @@ Populates the registration call arguments — by default adds the annotation ``n :Fields: * **annotation_function_call** : string = "add_new_optimization_macro" - Base class for creating optimization pass macros via the ``[optimization_macro]`` structure annotation; registers an ``AstPassMacro`` that runs during the optimization pass. + .. _struct-ast_boost-TagFunctionMacro: .. das:attribute:: TagFunctionMacro : SetupAnyAnnotation @@ -410,12 +472,14 @@ Populates the registration call arguments — by default adds the annotation ``n * **tag** : string - Name of the tag. + .. _function-ast_boost_TagFunctionMacro_rq_apply_TagFunctionMacro_StructurePtr_ModuleGroup_AnnotationArgumentList_das_string_0x20e: .. das:function:: TagFunctionMacro.apply(st: StructurePtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool Extends ``SetupAnyAnnotation`` apply to extract the required ``tag`` argument and register a ``setup_tag_annotation`` call that links the annotation to tagged functions. + :Arguments: * **st** : :ref:`StructurePtr ` * **group** : :ref:`ModuleGroup ` @@ -430,6 +494,7 @@ Extends ``SetupAnyAnnotation`` apply to extract the required ``tag`` argument an Overrides the default ``setup_call`` to pass both the annotation ``name`` and the ``tag`` string as arguments to ``setup_tag_annotation``. + :Arguments: * **st** : :ref:`StructurePtr ` * **cll** : smart_ptr< :ref:`ExprCall `> @@ -441,12 +506,14 @@ Overrides the default ``setup_call`` to pass both the annotation ``name`` and th An ``AstVariantMacro`` that replaces ``is``, ``as``, and ``?as`` variant operations on ``Expression`` subclasses with runtime ``__rtti`` string checks and casts. + .. _function-ast_boost_BetterRttiVisitor_rq_visitExprIsVariant_BetterRttiVisitor_ProgramPtr_Module_q__smart_ptr_ls_ExprIsVariant_gr__0x250: .. das:function:: BetterRttiVisitor.visitExprIsVariant(prog: ProgramPtr; mod: Module?; expr: smart_ptr) : ExpressionPtr Visitor override that replaces ``expr is Type`` on ``Expression`` subclasses with an ``__rtti`` string comparison, returning ``true`` if the runtime type matches. + :Arguments: * **prog** : :ref:`ProgramPtr ` * **mod** : :ref:`Module `? @@ -459,6 +526,7 @@ Visitor override that replaces ``expr is Type`` on ``Expression`` subclasses wit Visitor override that replaces ``expr as Type`` on ``Expression`` subclasses with an RTTI-checked cast via ``__rtti``, panicking on mismatch. + :Arguments: * **prog** : :ref:`ProgramPtr ` * **mod** : :ref:`Module `? @@ -471,12 +539,14 @@ Visitor override that replaces ``expr as Type`` on ``Expression`` subclasses wit Visitor override that replaces ``expr ?as Type`` on ``Expression`` subclasses with an RTTI-checked cast via ``__rtti``, returning ``null`` on mismatch instead of panicking. + :Arguments: * **prog** : :ref:`ProgramPtr ` * **mod** : :ref:`Module `? * **expr** : smart_ptr< :ref:`ExprSafeAsVariant `> + ++++++++++ Containers ++++++++++ @@ -496,6 +566,7 @@ emplace_new Moves a newly created ``smart_ptr`` (``Expression``, ``TypeDecl``, ``Variable``, or ``MakeFieldDecl``) into a vector container with correct reference counting. + :Arguments: * **vec** : vector> * **ptr** : smart_ptr< :ref:`TypeDecl `> @@ -514,6 +585,7 @@ Moves a newly created ``smart_ptr`` (``Expression``, ``TypeDecl``, ``Variable``, ---- + +++++++++++++++++++++++++++++++++++ Textual descriptions of the objects +++++++++++++++++++++++++++++++++++ @@ -538,6 +610,7 @@ debug_expression Returns a hierarchical, Lisp-like textual dump of an ``ExpressionPtr`` tree showing RTTI types, field values, and nested sub-expressions for debugging. + :Arguments: * **expr** : :ref:`Expression `? .. _function-ast_boost_debug_expression_ExpressionPtr_DebugExpressionFlags: @@ -556,6 +629,7 @@ describe Returns a human-readable textual representation of an AST object (``AnnotationArgumentList``, ``AnnotationDeclaration``, ``AnnotationList``, ``Variable``, or ``Expression``). + :Arguments: * **vvar** : :ref:`VariablePtr ` .. _function-ast_boost_describe_AnnotationDeclaration: @@ -582,6 +656,7 @@ Returns a human-readable textual representation of an AST object (``AnnotationAr Returns a textual representation of the set bits in a bitfield value, listing the names of all active flags joined by the specified ``merger`` string. + :Arguments: * **bf** : auto * **merger** : string @@ -592,7 +667,9 @@ Returns a textual representation of the set bits in a bitfield value, listing th Returns a compact signature string for a function in the form ``name (arg:Type; ...) : ReturnType``. -:Arguments: * **func** : option< :ref:`FunctionPtr `| :ref:`Function `?> + +:Arguments: * **func** : option< :ref:`FunctionPtr `\ | :ref:`Function `?> + +++++++ Queries @@ -627,6 +704,7 @@ Queries Looks up an ``Annotation`` by name within the specified module during compilation and returns a pointer to it, or ``null`` if not found. + :Arguments: * **mod_name** : string * **ann_name** : string @@ -641,6 +719,7 @@ find_arg Searches an ``AnnotationArgumentList`` for an argument by name and returns its ``RttiValue``; returns ``nothing`` if the argument is not present. + :Arguments: * **args** : :ref:`AnnotationArgumentList ` * **argn** : string @@ -657,6 +736,7 @@ Searches an ``AnnotationArgumentList`` for an argument by name and returns its ` Searches the ``argNames`` of a ``TypeDeclPtr`` (tuple or variant) for the given name and returns its zero-based index, or ``-1`` if not found. + :Arguments: * **typ** : :ref:`TypeDeclPtr ` * **name** : string @@ -667,6 +747,7 @@ Searches the ``argNames`` of a ``TypeDeclPtr`` (tuple or variant) for the given Searches the compiling program for exactly one non-generic function with the given name; returns it or ``null`` if zero or multiple matches exist. + :Arguments: * **mod** : :ref:`Module `? * **name** : string @@ -679,6 +760,7 @@ Searches the compiling program for exactly one non-generic function with the giv Searches the compiling program for exactly one generic function with the given name; returns it or ``null`` if zero or multiple matches exist. + :Arguments: * **mod** : :ref:`Module `? * **name** : string @@ -691,6 +773,7 @@ Searches the compiling program for exactly one generic function with the given n Returns the number of scalar elements in a vector ``Type`` (e.g., 2 for ``float2``/``range``, 3 for ``float3``, 4 for ``float4``), or 0 for non-vector types. + :Arguments: * **bt** : :ref:`Type ` .. _function-ast_boost_getVectorElementSize_Type: @@ -699,6 +782,7 @@ Returns the number of scalar elements in a vector ``Type`` (e.g., 2 for ``float2 Returns the byte size of a single scalar element in a vector ``Type`` — 8 for ``range64``/``urange64``, 4 for all other vector types. + :Arguments: * **bt** : :ref:`Type ` .. _function-ast_boost_getVectorElementType_Type: @@ -707,6 +791,7 @@ Returns the byte size of a single scalar element in a vector ``Type`` — 8 for Returns the scalar ``Type`` of each element in a vector type (e.g., ``tFloat`` for ``float2``, ``tInt`` for ``int3`` and ``range``, ``tInt64`` for ``range64``). + :Arguments: * **bt** : :ref:`Type ` .. _function-ast_boost_getVectorOffset_Type_string: @@ -715,6 +800,7 @@ Returns the scalar ``Type`` of each element in a vector type (e.g., ``tFloat`` f Returns the zero-based element index for a named swizzle component (``x``/``y``/``z``/``w`` or ``r``/``g``/``b``/``a``) within a vector ``Type``, or ``-1`` if out of bounds. + :Arguments: * **bt** : :ref:`Type ` * **ident** : string @@ -729,6 +815,7 @@ get_for_source_index Returns the zero-based index of a given iterator variable or source expression within a ``for`` loop's source list, or ``-1`` if not found. + :Arguments: * **expr** : smart_ptr< :ref:`ExprFor `> * **svar** : :ref:`VariablePtr ` @@ -746,6 +833,7 @@ Returns the zero-based index of a given iterator variable or source expression w Returns a fixed array of all commonly used ``Type`` values — booleans, strings, pointers, numeric scalars, enumerations, bitfields, vectors, and ranges. + isCMRES ^^^^^^^ @@ -755,6 +843,7 @@ isCMRES Returns ``true`` if a ``Function`` returns its result via copy-or-move-result-on-stack (CMRES) semantics rather than through a register. + :Arguments: * **fun** : :ref:`Function `? .. _function-ast_boost_isCMRES_FunctionPtr: @@ -769,6 +858,7 @@ Returns ``true`` if a ``Function`` returns its result via copy-or-move-result-on Returns ``true`` if a ``TypeDeclPtr`` represents a reference type without an explicit ``ref`` flag, meaning it will use copy-or-move-on-stack semantics. + :Arguments: * **blockT** : :ref:`TypeDeclPtr ` .. _function-ast_boost_isExprCallFunc_ExpressionPtr: @@ -777,6 +867,7 @@ Returns ``true`` if a ``TypeDeclPtr`` represents a reference type without an exp Returns ``true`` if the expression's RTTI tag is ``ExprCallFunc``, ``ExprOp``, ``ExprNew``, or ``ExprCall`` — i.e., any function-call-like expression. + :Arguments: * **expr** : :ref:`ExpressionPtr ` .. _function-ast_boost_isExpression_TypeDeclPtr_bool: @@ -785,6 +876,7 @@ Returns ``true`` if the expression's RTTI tag is ``ExprCallFunc``, ``ExprOp``, ` Returns ``true`` if the given ``TypeDeclPtr`` refers to an ``ast`` module handled type whose name starts with ``Expr``, including pointer-to-expression types. + :Arguments: * **t** : :ref:`TypeDeclPtr ` * **top** : bool @@ -795,6 +887,7 @@ Returns ``true`` if the given ``TypeDeclPtr`` refers to an ``ast`` module handle Returns ``true`` if the expression is any ``ExprMakeLocal`` subclass: ``ExprMakeStruct``, ``ExprMakeArray``, ``ExprMakeTuple``, or ``ExprMakeVariant``. + :Arguments: * **expr** : :ref:`ExpressionPtr ` .. _function-ast_boost_isVectorType_Type: @@ -803,6 +896,7 @@ Returns ``true`` if the expression is any ``ExprMakeLocal`` subclass: ``ExprMake Returns ``true`` if the given ``Type`` is a vector, range, or urange type (``int2``..``int4``, ``uint2``..``uint4``, ``float2``..``float4``, ``range``, ``urange``, ``range64``, ``urange64``). + :Arguments: * **typ** : :ref:`Type ` .. _function-ast_boost_is_class_method_StructurePtr_TypeDeclPtr: @@ -811,6 +905,7 @@ Returns ``true`` if the given ``Type`` is a vector, range, or urange type (``int Returns ``true`` if a ``TypeDeclPtr`` field represents a class method — a non-dim ``tFunction`` whose first argument is the class structure (or a parent of it). + :Arguments: * **cinfo** : :ref:`StructurePtr ` * **finfo** : :ref:`TypeDeclPtr ` @@ -821,10 +916,12 @@ Returns ``true`` if a ``TypeDeclPtr`` field represents a class method — a non- Returns ``true`` if ``child`` is the same ``Structure`` as ``parent`` or is transitively inherited from ``parent`` by walking the parent chain. + :Arguments: * **parent** : :ref:`Structure `? * **child** : :ref:`Structure `? + +++++++++++ Annotations +++++++++++ @@ -853,6 +950,7 @@ add_annotation_argument Adds a typed annotation argument (``bool``, ``int``, ``float``, ``string``, or ``AnnotationArgument``) to an ``AnnotationArgumentList`` and returns the new argument index. + :Arguments: * **arguments** : :ref:`AnnotationArgumentList ` * **argName** : string @@ -887,6 +985,7 @@ append_annotation Creates an ``AnnotationDeclaration`` for the named annotation (with optional typed arguments) and attaches it to a ``Function``, ``ExprBlock``, or ``Structure``. + :Arguments: * **blk** : smart_ptr< :ref:`ExprBlock `> * **mod_name** : string @@ -925,13 +1024,14 @@ Creates an ``AnnotationDeclaration`` for the named annotation (with optional typ ---- + +++++++++++++++++++++ Expression generation +++++++++++++++++++++ * :ref:`convert_to_expression (var value: auto ==const) : auto ` * :ref:`convert_to_expression (value: auto ==const; at: LineInfo) : auto ` - * :ref:`convert_to_expression (var value: auto& ==const; at: LineInfo) : auto ` + * :ref:`convert_to_expression (var value: auto& ==const; at: LineInfo) : auto ` * :ref:`convert_to_expression (value: auto ==const) : auto ` * :ref:`make_static_assert_false (text: string; at: LineInfo) : smart_ptr\ ` * :ref:`override_method (var str: StructurePtr; name: string; funcName: string) : bool ` @@ -947,13 +1047,14 @@ convert_to_expression Converts a runtime value of any supported type to an equivalent AST ``ExpressionPtr`` that would produce that value when compiled, using ``typeinfo`` for reflection. + :Arguments: * **value** : auto! .. _function-ast_boost_convert_to_expression_auto__eq__eq_const_LineInfo_0x39c: .. das:function:: convert_to_expression(value: auto ==const; at: LineInfo) : auto -.. _function-ast_boost_convert_to_expression__auto__eq__eq_const_LineInfo_0x393: +.. _function-ast_boost_convert_to_expression__auto_ref___eq__eq_const_LineInfo_0x393: .. das:function:: convert_to_expression(value: auto& ==const; at: LineInfo) : auto @@ -969,6 +1070,7 @@ Converts a runtime value of any supported type to an equivalent AST ``Expression Creates an ``ExprStaticAssert`` expression node that always fails at compile time with the given error message text. + :Arguments: * **text** : string * **at** : :ref:`LineInfo ` @@ -979,6 +1081,7 @@ Creates an ``ExprStaticAssert`` expression node that always fails at compile tim Replaces the initializer of a field named ``name`` in the given structure with an ``@@funcName`` function address cast, effectively overriding that class method. + :Arguments: * **str** : :ref:`StructurePtr ` * **name** : string @@ -991,6 +1094,8 @@ Replaces the initializer of a field named ``name`` in the given structure with a Helper function that panics with ``"invalid 'as' expression or null pointer dereference"`` and returns ``null`` — used as the failure branch in ``as`` variant casts. + + ++++++++ Visitors ++++++++ @@ -1003,10 +1108,12 @@ Visitors Invokes the given ``VisitorAdapter`` on the ``finally`` section of an ``ExprBlock``, allowing macro visitors to inspect or transform finally-block code. + :Arguments: * **blk** : :ref:`ExprBlock `? * **adapter** : smart_ptr< :ref:`VisitorAdapter `> + +++++++++++++++ Type generation +++++++++++++++ @@ -1019,8 +1126,10 @@ Type generation Constructs a ``TypeDeclPtr`` of ``tFunction`` base type from a ``FunctionPtr``, capturing its argument types and names plus the return type. + :Arguments: * **fn** : :ref:`FunctionPtr ` + ++++++++++ Type casts ++++++++++ @@ -1049,6 +1158,7 @@ Type casts Casts an ``Annotation?`` or ``smart_ptr`` to ``FunctionAnnotation?`` via ``reinterpret``, verifying the annotation kind first (panics otherwise). + :Arguments: * **foo** : :ref:`Annotation `? .. _function-ast_boost__rq_as_rq_StructureAnnotation_Annotation_q_: @@ -1057,6 +1167,7 @@ Casts an ``Annotation?`` or ``smart_ptr`` to ``FunctionAnnotation?`` Casts an ``Annotation?`` or ``smart_ptr`` to ``StructureAnnotation?`` via ``reinterpret``, verifying the annotation kind first (panics otherwise). + :Arguments: * **foo** : :ref:`Annotation `? .. _function-ast_boost__rq_is_rq_FunctionAnnotation_Annotation_q_: @@ -1065,6 +1176,7 @@ Casts an ``Annotation?`` or ``smart_ptr`` to ``StructureAnnotation?` Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a ``FunctionAnnotation`` according to its ``isFunctionAnnotation`` property. + :Arguments: * **foo** : :ref:`Annotation `? .. _function-ast_boost__rq_is_rq_StructureAnnotation_Annotation_q_: @@ -1073,6 +1185,7 @@ Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a ``StructureAnnotation`` according to its ``isStructureAnnotation`` property. + :Arguments: * **foo** : :ref:`Annotation `? .. _function-ast_boost__rq_as_rq_BuiltInFunction_Function_q_: @@ -1081,6 +1194,7 @@ Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a Casts a ``Function?`` to ``BuiltInFunction?`` via ``reinterpret``, verifying the target is a built-in function first (panics otherwise). + :Arguments: * **foo** : :ref:`Function `? .. _function-ast_boost__rq_as_rq_ExternalFnBase_Function_q_: @@ -1089,6 +1203,7 @@ Casts a ``Function?`` to ``BuiltInFunction?`` via ``reinterpret``, verifying the Casts a ``Function?`` to ``ExternalFnBase?`` via ``reinterpret``, verifying it is a property-flagged built-in function first (panics otherwise). + :Arguments: * **foo** : :ref:`Function `? .. _function-ast_boost__rq_is_rq_BuiltInFunction_Function_q_: @@ -1097,6 +1212,7 @@ Casts a ``Function?`` to ``ExternalFnBase?`` via ``reinterpret``, verifying it i Returns ``true`` if the given ``Function?`` has the ``builtIn`` flag set, indicating it is a ``BuiltInFunction``; returns ``false`` for any other type. + :Arguments: * **foo** : :ref:`Function `? .. _function-ast_boost__rq_is_rq_ExternalFnBase_Function_q_: @@ -1105,6 +1221,7 @@ Returns ``true`` if the given ``Function?`` has the ``builtIn`` flag set, indica Returns ``true`` if the given ``Function?`` is both ``builtIn`` and has the ``propertyFunction`` flag, indicating it is an ``ExternalFnBase``; returns ``false`` otherwise. + :Arguments: * **foo** : :ref:`Function `? .. _function-ast_boost__rq_is_rq_BuiltInFunction_auto_0x26a: @@ -1113,6 +1230,7 @@ Returns ``true`` if the given ``Function?`` is both ``builtIn`` and has the ``pr Returns ``true`` if the given ``Function?`` has the ``builtIn`` flag set, indicating it is a ``BuiltInFunction``; returns ``false`` for any other type. + :Arguments: * **anything** : auto .. _function-ast_boost__rq_is_rq_ExternalFnBase_auto_0x27a: @@ -1121,6 +1239,7 @@ Returns ``true`` if the given ``Function?`` has the ``builtIn`` flag set, indica Returns ``true`` if the given ``Function?`` is both ``builtIn`` and has the ``propertyFunction`` flag, indicating it is an ``ExternalFnBase``; returns ``false`` otherwise. + :Arguments: * **anything** : auto .. _function-ast_boost__rq_is_rq_FunctionAnnotation_auto_0x28a: @@ -1129,6 +1248,7 @@ Returns ``true`` if the given ``Function?`` is both ``builtIn`` and has the ``pr Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a ``FunctionAnnotation`` according to its ``isFunctionAnnotation`` property. + :Arguments: * **anything** : auto .. _function-ast_boost__rq_is_rq_StructureAnnotation_auto_0x2a6: @@ -1137,6 +1257,7 @@ Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a ``StructureAnnotation`` according to its ``isStructureAnnotation`` property. + :Arguments: * **anything** : auto .. _function-ast_boost__rq_as_rq_FunctionAnnotation_smart_ptr_ls_Annotation_gr_: @@ -1145,6 +1266,7 @@ Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a Casts an ``Annotation?`` or ``smart_ptr`` to ``FunctionAnnotation?`` via ``reinterpret``, verifying the annotation kind first (panics otherwise). + :Arguments: * **foo** : smart_ptr< :ref:`Annotation `> .. _function-ast_boost__rq_as_rq_StructureAnnotation_smart_ptr_ls_Annotation_gr_: @@ -1153,6 +1275,7 @@ Casts an ``Annotation?`` or ``smart_ptr`` to ``FunctionAnnotation?`` Casts an ``Annotation?`` or ``smart_ptr`` to ``StructureAnnotation?`` via ``reinterpret``, verifying the annotation kind first (panics otherwise). + :Arguments: * **foo** : smart_ptr< :ref:`Annotation `> .. _function-ast_boost__rq_is_rq_FunctionAnnotation_smart_ptr_ls_Annotation_gr_: @@ -1161,6 +1284,7 @@ Casts an ``Annotation?`` or ``smart_ptr`` to ``StructureAnnotation?` Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a ``FunctionAnnotation`` according to its ``isFunctionAnnotation`` property. + :Arguments: * **foo** : smart_ptr< :ref:`Annotation `> .. _function-ast_boost__rq_is_rq_StructureAnnotation_smart_ptr_ls_Annotation_gr_: @@ -1169,6 +1293,7 @@ Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a ``StructureAnnotation`` according to its ``isStructureAnnotation`` property. + :Arguments: * **foo** : smart_ptr< :ref:`Annotation `> .. _function-ast_boost_walk_and_convert_uint8_const_q__TypeDeclPtr_LineInfo: @@ -1177,12 +1302,14 @@ Returns ``true`` if the given ``Annotation?`` or ``smart_ptr`` is a Recursively walks raw data bytes using a ``TypeDeclPtr`` schema and builds an equivalent AST expression tree that would reproduce that data when compiled. + :Arguments: * **data** : uint8? * **info** : :ref:`TypeDeclPtr ` * **at** : :ref:`LineInfo ` + +++++ Setup +++++ @@ -1202,6 +1329,7 @@ setup_call_list Creates or locates a compilation-phase setup function (``__setup_macros``) and returns its body ``ExprBlock`` so callers can append registration calls to it. + :Arguments: * **name** : string * **at** : :ref:`LineInfo ` @@ -1224,6 +1352,7 @@ Creates or locates a compilation-phase setup function (``__setup_macros``) and r Creates or locates a macro initialization function (``__setup_macros``) guarded by ``is_compiling_macros`` and returns its body block for appending macro registration code. + :Arguments: * **name** : string * **at** : :ref:`LineInfo ` @@ -1234,6 +1363,7 @@ Creates or locates a macro initialization function (``__setup_macros``) guarded Creates an ``AstFunctionAnnotation`` instance and automatically applies it to every function that carries a matching ``[tag_function(tag)]`` annotation in the module. + :Arguments: * **name** : string * **tag** : string diff --git a/doc/source/stdlib/ast_used.rst b/doc/source/stdlib/ast_used.rst index 30393844cf..530c42d831 100644 --- a/doc/source/stdlib/ast_used.rst +++ b/doc/source/stdlib/ast_used.rst @@ -5,6 +5,8 @@ AST type usage collection ========================= +.. das:module:: ast_used + The AST_USED module implements analysis passes that determine which AST nodes are actually used in the program. This information is used for dead code elimination, tree shaking, and optimizing generated output. @@ -13,6 +15,8 @@ All functions and symbols are in "ast_used" module, use require to get access to require daslib/ast_used + + ++++++++++ Structures ++++++++++ @@ -28,6 +32,8 @@ Collection of all structure and enumeration types that are used in the AST. * **en** : table< :ref:`Enumeration `?;void> - all enumeration types used + + +++++++++++++++++++++++++++ Collecting type information +++++++++++++++++++++++++++ @@ -41,6 +47,7 @@ Collecting type information Goes through list of functions `vfun` and variables `vvar` and collects list of which enumeration and structure types are used in them. Calls `blk` with said list. + :Arguments: * **vfun** : array< :ref:`Function `?> * **vvar** : array< :ref:`Variable `?> diff --git a/doc/source/stdlib/async_boost.rst b/doc/source/stdlib/async_boost.rst index 6604e7bc79..63cb01f886 100644 --- a/doc/source/stdlib/async_boost.rst +++ b/doc/source/stdlib/async_boost.rst @@ -5,6 +5,8 @@ Async/await coroutine macros ============================ +.. das:module:: async_boost + The ASYNC_BOOST module implements an async/await pattern for daslang using channels and coroutines. It provides ``async`` for launching concurrent tasks and ``await`` for waiting on their results, built on top of the job queue @@ -14,6 +16,8 @@ All functions and symbols are in "async_boost" module, use require to get access require daslib/async_boost + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -24,6 +28,7 @@ Function annotations Function annotation that implements coroutine await semantics. + .. _handle-async_boost-AwaitCoroutineMacro: .. das:attribute:: AwaitCoroutineMacro @@ -35,6 +40,7 @@ This macro converts await() expression into:: The idea is that coroutine or generator can continuously yield from another sub-coroutine or generator. + .. _handle-async_boost-async: .. das:attribute:: async @@ -44,6 +50,8 @@ Generator yields bool if its a void function (coroutine), and yields the return async function can wait for another async function using await(). use 'return false' to immediately return from the generator. + + ++++++++ Awaiting ++++++++ @@ -62,6 +70,7 @@ await This function is used to wait for the result of the async function. + :Arguments: * **a** : iterator .. _function-async_boost_await_iterator_ls_variant_ls_res_c_autoT;wait_c_bool_gr__gr_: @@ -76,6 +85,8 @@ This function is used to wait for the result of the async function. This function is used to suspend coroutine until next frame. + + +++++++++++++++++++ Running async tasks +++++++++++++++++++ @@ -89,6 +100,7 @@ Running async tasks This function runs async function until it is finished. + :Arguments: * **a** : iterator .. _function-async_boost_async_run_all_array_ls_iterator_ls_auto_gr__gr_: @@ -97,6 +109,7 @@ This function runs async function until it is finished. This function runs all async function until they are finished (in parallel, starting from the last one). + :Arguments: * **a** : array> diff --git a/doc/source/stdlib/base64.rst b/doc/source/stdlib/base64.rst index b77256d877..8d35d6214d 100644 --- a/doc/source/stdlib/base64.rst +++ b/doc/source/stdlib/base64.rst @@ -5,6 +5,8 @@ Base64 encoding and decoding ============================ +.. das:module:: base64 + The BASE64 module implements Base64 encoding and decoding. It provides ``base64_encode`` and ``base64_decode`` for converting between binary data (strings or ``array``) and Base64 text representation. @@ -28,6 +30,8 @@ Example: :: // encoded: SGVsbG8sIGRhU2NyaXB0IQ== // decoded: Hello, daslang! + + ++++++++ Encoding ++++++++ @@ -42,6 +46,7 @@ Encoding Returns the encoded output size for binary data of length `s`. + :Arguments: * **s** : int @@ -54,6 +59,7 @@ base64_encode Encodes a string to its Base64 text representation. + :Arguments: * **_inp** : string .. _function-base64_base64_encode_array_ls_uint8_gr_array_ls_uint8_gr__hh_: @@ -62,6 +68,7 @@ Encodes a string to its Base64 text representation. ---- + ++++++++ Decoding ++++++++ @@ -76,6 +83,7 @@ Decoding Returns the maximum decoded output size for a Base64 string of length `s`. + :Arguments: * **s** : int @@ -88,6 +96,7 @@ base64_decode Decodes a Base64-encoded string. Returns a tuple of the decoded text and its byte length. + :Arguments: * **_in** : string .. _function-base64_base64_decode_string_array_ls_uint8_gr_: diff --git a/doc/source/stdlib/bitfield_boost.rst b/doc/source/stdlib/bitfield_boost.rst index 9b6601c065..3d17a93164 100644 --- a/doc/source/stdlib/bitfield_boost.rst +++ b/doc/source/stdlib/bitfield_boost.rst @@ -5,6 +5,8 @@ Bitfield operator overloads =========================== +.. das:module:: bitfield_boost + The BITFIELD_BOOST module provides utility macros for working with bitfield types including conversion between bitfield values and strings, and iteration over set bits. @@ -13,74 +15,82 @@ All functions and symbols are in "bitfield_boost" module, use require to get acc require daslib/bitfield_boost + + +++++++++++++++++++++++ Bitfield element access +++++++++++++++++++++++ - * :ref:`auto(TT)&[]&&= (var b: auto(TT)&; i: int; v: bool) : auto ` - * :ref:`auto(TT)&[]= (var b: auto(TT)&; i: int; v: bool) : auto ` - * :ref:`auto(TT)&[]^^= (var b: auto(TT)&; i: int; v: bool) : auto ` - * :ref:`auto(TT)&[]||= (var b: auto(TT)&; i: int; v: bool) : auto ` - * :ref:`auto[] (b: auto; i: int) : bool ` + * :ref:`auto(TT)&[]&&= (var b: auto(TT)&; i: int; v: bool) : auto ` + * :ref:`auto(TT)&[]= (var b: auto(TT)&; i: int; v: bool) : auto ` + * :ref:`auto(TT)&[]^^= (var b: auto(TT)&; i: int; v: bool) : auto ` + * :ref:`auto(TT)&[]||= (var b: auto(TT)&; i: int; v: bool) : auto ` + * :ref:`auto[] (b: auto; i: int) : bool ` -.. _function-bitfield_boost__eq__autoTT_int_bool_0x25: +.. _function-bitfield_boost__lb__rb__ref__ref__eq__autoTT_ref__int_bool_0x25: .. das:function:: auto(TT)&[]&&=(b: auto(TT)&; i: int; v: bool) : auto && assignment for bitfield bit at index i -:Arguments: * **b** : auto(TT)& + +:Arguments: * **b** : auto(TT)\ & * **i** : int * **v** : bool -.. _function-bitfield_boost__eq__autoTT_int_bool_0x17: +.. _function-bitfield_boost__lb__rb__eq__autoTT_ref__int_bool_0x17: .. das:function:: auto(TT)&[]=(b: auto(TT)&; i: int; v: bool) : auto set bitfield bit at index i to v -:Arguments: * **b** : auto(TT)& + +:Arguments: * **b** : auto(TT)\ & * **i** : int * **v** : bool -.. _function-bitfield_boost_^^_eq__autoTT_int_bool_0x3d: +.. _function-bitfield_boost__lb__rb_^^_eq__autoTT_ref__int_bool_0x3d: .. das:function:: auto(TT)&[]^^=(b: auto(TT)&; i: int; v: bool) : auto toggle bitfield bit at index i if v is true -:Arguments: * **b** : auto(TT)& + +:Arguments: * **b** : auto(TT)\ & * **i** : int * **v** : bool -.. _function-bitfield_boost__eq__autoTT_int_bool_0x31: +.. _function-bitfield_boost__lb__rb__eq__autoTT_ref__int_bool_0x31: .. das:function:: auto(TT)&[]||=(b: auto(TT)&; i: int; v: bool) : auto || assignment for bitfield bit at index i -:Arguments: * **b** : auto(TT)& + +:Arguments: * **b** : auto(TT)\ & * **i** : int * **v** : bool -.. _function-bitfield_boost__auto_int_0x11: +.. _function-bitfield_boost__lb__rb__auto_int_0x11: .. das:function:: auto[](b: auto; i: int) : bool get bitfield bit at index i + :Arguments: * **b** : auto * **i** : int + +++++++++ Iteration +++++++++ @@ -93,6 +103,7 @@ Iteration Iterates over each bit of a bitfield value, yielding true or false for each bit. + :Arguments: * **b** : auto diff --git a/doc/source/stdlib/bitfield_trait.rst b/doc/source/stdlib/bitfield_trait.rst index b50ab69298..c06e05ef57 100644 --- a/doc/source/stdlib/bitfield_trait.rst +++ b/doc/source/stdlib/bitfield_trait.rst @@ -5,6 +5,8 @@ Bitfield name traits ==================== +.. das:module:: bitfield_trait + The BITFIELD_TRAIT module implements reflection utilities for bitfield types: converting bitfield values to and from human-readable strings, iterating over individual set bits, and constructing bitfield values from string names. @@ -13,6 +15,8 @@ All functions and symbols are in "bitfield_trait" module, use require to get acc require daslib/bitfield_trait + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -28,6 +32,7 @@ This macro converts each(bitfield) to the following code:: ... return false + .. _handle-bitfield_trait-EachBitNameBitfieldMacro: .. das:attribute:: EachBitNameBitfieldMacro @@ -39,6 +44,8 @@ This macro converts each(bitfield) to the following code:: ... return false + + +++++++++ Iteration +++++++++ @@ -52,6 +59,7 @@ Iteration Iterates over the names of a bitfield type, yielding each bit as a bitfield value (1ul << bitIndex). + :Arguments: * **argT** : auto .. _function-bitfield_trait_each_bit_name_auto_0x39: @@ -60,6 +68,7 @@ Iterates over the names of a bitfield type, yielding each bit as a bitfield valu Iterates over the names of a bitfield type, yielding each bit name as a string. + :Arguments: * **argT** : auto diff --git a/doc/source/stdlib/bool_array.rst b/doc/source/stdlib/bool_array.rst index 6edb379742..faea5e562a 100644 --- a/doc/source/stdlib/bool_array.rst +++ b/doc/source/stdlib/bool_array.rst @@ -5,6 +5,8 @@ Packed boolean array ==================== +.. das:module:: bool_array + The BOOL_ARRAY module provides a compact boolean array implementation using bit-packing. Each boolean value uses a single bit instead of a byte, providing an 8x memory reduction compared to ``array``. @@ -13,6 +15,8 @@ All functions and symbols are in "bool_array" module, use require to get access require daslib/bool_array + + ++++++++++ Structures ++++++++++ @@ -24,56 +28,63 @@ Structures A dynamic array of booleans, stored as bits. + .. _function-bool_array_finalize_BoolArray_0x16: .. das:function:: BoolArray.finalize() Releases the memory used by the BoolArray. -.. _function-bool_array__BoolArray_int_0x1a: + +.. _function-bool_array__lb__rb__BoolArray_int_0x1a: .. das:function:: BoolArray.[](index: int) : bool Get the boolean value at the given index. + :Arguments: * **index** : int -.. _function-bool_array__eq__BoolArray_int_bool_0x23: +.. _function-bool_array__lb__rb__eq__BoolArray_int_bool_0x23: .. das:function:: BoolArray.[]=(index: int; value: bool) Set the boolean value at the given index. + :Arguments: * **index** : int * **value** : bool -.. _function-bool_array_^^_eq__BoolArray_int_bool_0x30: +.. _function-bool_array__lb__rb_^^_eq__BoolArray_int_bool_0x30: .. das:function:: BoolArray.[]^^=(index: int; value: bool) Perform XOR operation on the boolean value at the given index. + :Arguments: * **index** : int * **value** : bool -.. _function-bool_array__eq__BoolArray_int_bool_0x3b: +.. _function-bool_array__lb__rb__ref__ref__eq__BoolArray_int_bool_0x3b: .. das:function:: BoolArray.[]&&=(index: int; value: bool) Perform AND operation on the boolean value at the given index. + :Arguments: * **index** : int * **value** : bool -.. _function-bool_array__eq__BoolArray_int_bool_0x46: +.. _function-bool_array__lb__rb__eq__BoolArray_int_bool_0x46: .. das:function:: BoolArray.[]||=(index: int; value: bool) Perform OR operation on the boolean value at the given index. + :Arguments: * **index** : int * **value** : bool @@ -84,12 +95,14 @@ Perform OR operation on the boolean value at the given index. Clear the BoolArray. + .. _function-bool_array_BoolArray_rq_reserve_BoolArray_int_0x57: .. das:function:: BoolArray.reserve(capacity: int) Reserve capacity for the BoolArray. + :Arguments: * **capacity** : int .. _function-bool_array_BoolArray_rq_resize_BoolArray_int_0x60: @@ -98,6 +111,7 @@ Reserve capacity for the BoolArray. Resize the BoolArray to the new size. + :Arguments: * **newSize** : int .. _function-bool_array_BoolArray_rq_push_BoolArray_bool_0x71: @@ -106,6 +120,7 @@ Resize the BoolArray to the new size. Push a new boolean value to the end of the BoolArray. + :Arguments: * **value** : bool .. _function-bool_array_BoolArray_rq_push_BoolArray_bool_int_0x83: @@ -114,6 +129,7 @@ Push a new boolean value to the end of the BoolArray. Push a new boolean value at the given index in the BoolArray. + :Arguments: * **value** : bool * **at** : int @@ -124,18 +140,21 @@ Push a new boolean value at the given index in the BoolArray. Pop the last boolean value from the BoolArray and return it. + .. _function-bool_array_BoolArray_rq_length_BoolArray_0x96: .. das:function:: BoolArray.length() : int Get the length of the BoolArray. + .. _function-bool_array_BoolArray_rq_erase_BoolArray_int_0x9b: .. das:function:: BoolArray.erase(index: int) Erase the boolean value at the given index from the BoolArray. + :Arguments: * **index** : int .. _function-bool_array_BoolArray_rq_insert_BoolArray_int_bool_0xb6: @@ -144,6 +163,7 @@ Erase the boolean value at the given index from the BoolArray. Insert a boolean value at the given index in the BoolArray. + :Arguments: * **index** : int * **value** : bool @@ -154,6 +174,7 @@ Insert a boolean value at the given index in the BoolArray. Convert the BoolArray to a string representation. + .. _function-bool_array_BoolArray_rq_data_pointer_BoolArray_0xe4: .. das:function:: BoolArray.data_pointer() : uint? @@ -163,6 +184,7 @@ Convert the BoolArray to a string representation. Get the data pointer of the BoolArray. + .. _function-bool_array_BoolArray_rq_data_pointer_BoolArray_0xea: .. das:function:: BoolArray.data_pointer() : uint const? @@ -172,6 +194,8 @@ Get the data pointer of the BoolArray. Get the data pointer of the BoolArray. + + +++++++++ Iteration +++++++++ @@ -184,6 +208,7 @@ Iteration Returns an iterator over all boolean values in the BoolArray. + :Arguments: * **self** : :ref:`BoolArray ` diff --git a/doc/source/stdlib/builtin.rst b/doc/source/stdlib/builtin.rst index dab0b2a0fb..fb92fae55e 100644 --- a/doc/source/stdlib/builtin.rst +++ b/doc/source/stdlib/builtin.rst @@ -5,6 +5,8 @@ Built-in runtime ================ +.. das:module:: _builtin + The BUILTIN module contains core runtime functions available in all daslang programs without explicit ``require``. It includes: @@ -42,6 +44,8 @@ Example: :: // length = 2 // arr[0] = 10 + + ++++++++++++ Type aliases ++++++++++++ @@ -65,6 +69,8 @@ This bitfield specifies how exactly values are to be printed * **fixedPoint** (0x20) - always output fixed point precision for floating point values + + +++++++++ Constants +++++++++ @@ -75,114 +81,134 @@ Constants Maximum number of arguments a function can accept, used to pre-allocate stack space for function call arguments. + .. _global-builtin-INT_MIN: .. das:attribute:: INT_MIN = -2147483648 Minimum representable value of a signed 32-bit integer (`int`), equal to -2147483648. + .. _global-builtin-INT_MAX: .. das:attribute:: INT_MAX = 2147483647 Maximum representable value of a signed 32-bit integer (`int`), equal to 2147483647. + .. _global-builtin-UINT_MAX: .. das:attribute:: UINT_MAX = 0xffffffff Maximum representable value of an unsigned 32-bit integer (`uint`), equal to 4294967295. + .. _global-builtin-LONG_MIN: .. das:attribute:: LONG_MIN = -9223372036854775808 Minimum representable value of a signed 64-bit integer (`int64`). + .. _global-builtin-LONG_MAX: .. das:attribute:: LONG_MAX = 9223372036854775807 Maximum representable value of a signed 64-bit integer (`int64`). + .. _global-builtin-ULONG_MAX: .. das:attribute:: ULONG_MAX = 0xffffffffffffffff Maximum representable value of an unsigned 64-bit integer (`uint64`). + .. _global-builtin-FLT_MIN: .. das:attribute:: FLT_MIN = 1.1754944e-38f Smallest positive non-zero normalized value of the `float` type; for the most negative value use `-FLT_MAX`. + .. _global-builtin-FLT_MAX: .. das:attribute:: FLT_MAX = 3.4028235e+38f Maximum finite representable value of the `float` (32-bit floating-point) type. + .. _global-builtin-DBL_MIN: .. das:attribute:: DBL_MIN = 2.2250738585072014e-308lf Smallest positive non-zero normalized value of the `double` type; for the most negative value use `-DBL_MAX`. + .. _global-builtin-DBL_MAX: .. das:attribute:: DBL_MAX = 1.7976931348623157e+308lf Maximum finite representable value of the `double` (64-bit floating-point) type. + .. _global-builtin-LOG_CRITICAL: .. das:attribute:: LOG_CRITICAL = 50000 Log level constant for critical errors such as panics, fatal failures, and shutdown notifications. + .. _global-builtin-LOG_ERROR: .. das:attribute:: LOG_ERROR = 40000 Log level constant for recoverable error conditions that do not require immediate shutdown. + .. _global-builtin-LOG_WARNING: .. das:attribute:: LOG_WARNING = 30000 Log level constant for warnings about potential problems, API misuse, or non-fatal error conditions. + .. _global-builtin-LOG_INFO: .. das:attribute:: LOG_INFO = 20000 Log level constant for general informational messages about normal program operation. + .. _global-builtin-LOG_DEBUG: .. das:attribute:: LOG_DEBUG = 10000 Log level constant for debug-level diagnostic messages useful during development. + .. _global-builtin-LOG_TRACE: .. das:attribute:: LOG_TRACE = 0 Log level constant for the most verbose tracing and diagnostic output, typically used for detailed debugging. + .. _global-builtin-VEC_SEP: .. das:attribute:: VEC_SEP = "," Read-only string constant used as the separator between vector components when printing; defaults to `","`. + .. _global-builtin-print_flags_debugger: .. das:attribute:: print_flags_debugger = bitfield(0xf) Predefined set of print_flags configured to match the output formatting used by the `debug` function. + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -194,6 +220,8 @@ Handled structures Helper structure to facilitate calculating hash values. + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -204,192 +232,225 @@ Function annotations Attaches arbitrary key-value annotation arguments to a function, typically used by macros to tag functions with metadata. + .. _handle-builtin-generic: .. das:attribute:: generic Forces a function to be treated as generic regardless of its argument types, causing it to be instanced in each calling module. + .. _handle-builtin-_macro: .. das:attribute:: _macro Marks a function to be executed during the macro compilation pass, similar to `[init]` but running at macro time. + .. _handle-builtin-macro_function: .. das:attribute:: macro_function Marks a function as part of the macro subsystem, excluding it from the final compiled context unless it is explicitly referenced. + .. _handle-builtin-hint: .. das:attribute:: hint Provides optimization hints to the compiler for the annotated function via annotation arguments. + .. _handle-builtin-jit: .. das:attribute:: jit Explicitly forces the annotated function to be compiled using the JIT compiler, overriding default compilation decisions. + .. _handle-builtin-no_jit: .. das:attribute:: no_jit Prevents JIT compilation for the annotated function, forcing it to run in interpreted mode. + .. _handle-builtin-nodiscard: .. das:attribute:: nodiscard Enforces that the return value of the function must be used by the caller; discarding the result produces a compilation error. + .. _handle-builtin-deprecated: .. das:attribute:: deprecated Marks a function as deprecated, causing a compilation warning when referenced and excluding it from the final compiled context. + .. _handle-builtin-alias_cmres: .. das:attribute:: alias_cmres Declares that the function always aliases cmres (copy-or-move result), disabling cmres return optimizations for it. + .. _handle-builtin-never_alias_cmres: .. das:attribute:: never_alias_cmres Declares that the function never aliases cmres (copy-or-move result), disabling aliasing safety checks for the return value. + .. _handle-builtin-export: .. das:attribute:: export Forces a function to be exported and retained in the final compiled context, even if it is not directly called. + .. _handle-builtin-pinvoke: .. das:attribute:: pinvoke Marks a function as a platform invoke (pinvoke) entry, routing its calls through the pinvoke interop machinery. + .. _handle-builtin-no_lint: .. das:attribute:: no_lint Skips all lint-pass checks for the annotated function, suppressing any lint warnings or errors it would produce. + .. _handle-builtin-sideeffects: .. das:attribute:: sideeffects Declares that the function has side effects, preventing the compiler from optimizing away or reordering its calls. + .. _handle-builtin-run: .. das:attribute:: run Forces the function to be evaluated at compile time, ensuring its body executes during compilation rather than at runtime. + .. _handle-builtin-unsafe_operation: .. das:attribute:: unsafe_operation Marks a function as an unsafe operation, requiring callers to wrap the call in an `unsafe` block. + .. _handle-builtin-unsafe_outside_of_for: .. das:attribute:: unsafe_outside_of_for Marks a function as unsafe to call outside of a source-level `for` loop, enforcing iterator-context usage. + .. _handle-builtin-unsafe_when_not_clone_array: .. das:attribute:: unsafe_when_not_clone_array Marks a function as unsafe to call outside of an array `clone` operation, restricting its usage context. + .. _handle-builtin-no_aot: .. das:attribute:: no_aot Prevents ahead-of-time (AOT) C++ code generation for the annotated function, keeping it interpreted only. + .. _handle-builtin-init: .. das:attribute:: init Registers a function to be called automatically during context initialization, before any user code runs. + .. _handle-builtin-finalize: .. das:attribute:: finalize Registers a function to be called automatically when the context is shut down, for cleanup and resource release. + .. _handle-builtin-hybrid: .. das:attribute:: hybrid Marks a function as a hybrid call target so that AOT generates indirect calls to it, allowing the function to be patched without recompiling dependent AOT code. + .. _handle-builtin-unsafe_deref: .. das:attribute:: unsafe_deref Optimization annotation that removes null-pointer checks, bounds checks on array and string indexing, and similar safety validations. + .. _handle-builtin-skip_lock_check: .. das:attribute:: skip_lock_check Optimization annotation that disables runtime lock-check validation for the annotated function. + .. _handle-builtin-unused_argument: .. das:attribute:: unused_argument Suppresses unused-argument warnings or errors for specific function parameters, providing a workaround when strict code policies are enabled. + .. _handle-builtin-local_only: .. das:attribute:: local_only Restricts a function to accept only local `make` expressions such as structure initializers and tuple constructors. + .. _handle-builtin-expect_any_vector: .. das:attribute:: expect_any_vector Contract annotation restricting a function argument to accept only `das::vector` template types. + .. _handle-builtin-expect_dim: .. das:attribute:: expect_dim Contract annotation requiring a function argument to be a fixed-size (statically dimensioned) array. + .. _handle-builtin-expect_ref: .. das:attribute:: expect_ref Contract annotation requiring a function argument to be passed by reference. + .. _handle-builtin-type_function: .. das:attribute:: type_function Marks a function as a type function, meaning it operates on types at compile time and does not generate runtime code. + .. _handle-builtin-builtin_array_sort: .. das:attribute:: builtin_array_sort Internal function annotation that provides the sorting implementation used by the built-in `sort` function. + + +++++++++++ Call macros +++++++++++ @@ -400,72 +461,85 @@ Call macros Propagates the `unsafe` requirement to the calling function, making any function that calls it also require an `unsafe` block. + .. _call-macro-builtin-concept_assert: .. das:attribute:: concept_assert Compile-time assertion that reports the error at the call site of the asserted function rather than at the assert line itself. + .. _call-macro-builtin-__builtin_table_set_insert: .. das:attribute:: __builtin_table_set_insert Internal function annotation that implements the low-level key insertion for set-style tables (tables with keys only). + .. _call-macro-builtin-__builtin_table_key_exists: .. das:attribute:: __builtin_table_key_exists Internal function annotation that implements the low-level key presence check for the `key_exists` operation. + .. _call-macro-builtin-static_assert: .. das:attribute:: static_assert Compile-time assertion that produces a compilation error with an optional message when the condition is false. + .. _call-macro-builtin-verify: .. das:attribute:: verify Assertion that preserves the evaluated expression even when asserts are disabled, ensuring side effects are never optimized out. + .. _call-macro-builtin-debug: .. das:attribute:: debug Prints the human-readable representation of a value to the log and returns that same value, allowing inline debugging in expressions. + .. _call-macro-builtin-assert: .. das:attribute:: assert Runtime assertion that panics with an optional error message when the first argument evaluates to false; can be disabled globally. + .. _call-macro-builtin-memzero: .. das:attribute:: memzero Fills a region of memory with zeros, used internally for default-initializing values. + .. _call-macro-builtin-__builtin_table_find: .. das:attribute:: __builtin_table_find Internal function annotation that implements the low-level table lookup for the `find` operation. + .. _call-macro-builtin-invoke: .. das:attribute:: invoke Invokes a block, function pointer, or lambda, dispatching the call through the appropriate calling convention. + .. _call-macro-builtin-__builtin_table_erase: .. das:attribute:: __builtin_table_erase Internal function annotation that implements the low-level table entry removal for the `erase` operation. + + +++++++++++++ Reader macros +++++++++++++ @@ -476,6 +550,8 @@ Reader macros Reader macro that returns the raw string content without processing escape sequences, e.g. `%_esc~\n\r~%_esc` yields the literal four characters `\`, `n`, `\`, `r`. + + +++++++++++++++ Typeinfo macros +++++++++++++++ @@ -486,6 +562,8 @@ Typeinfo macros Typeinfo macro that generates RTTI `TypeInfo` metadata required for class initialization and reflection. + + +++++++++++++ Handled types +++++++++++++ @@ -496,12 +574,15 @@ Handled types Handled type wrapping `das::string` (typically `std::string`), providing heap-allocated mutable string storage. + .. _handle-builtin-clock: .. das:attribute:: clock Handled type wrapping `das::Time`, which encapsulates the C `time_t` value for calendar time representation. + + ++++++++++++++++ Structure macros ++++++++++++++++ @@ -512,42 +593,50 @@ Structure macros No-op structure annotation that holds annotation arguments as metadata without affecting code generation. + .. _handle-builtin-no_default_initializer: .. das:attribute:: no_default_initializer Prevents the compiler from generating a default initializer for the annotated structure. + .. _handle-builtin-macro_interface: .. das:attribute:: macro_interface Marks a class hierarchy as a macro interface, preventing it and its descendants from being exported by default. + .. _handle-builtin-skip_field_lock_check: .. das:attribute:: skip_field_lock_check Optimization annotation that disables runtime lock checks when accessing fields of the annotated structure. + .. _handle-builtin-cpp_layout: .. das:attribute:: cpp_layout Forces the structure to use C++ memory layout rules (alignment and padding) instead of native daslang layout. + .. _handle-builtin-safe_when_uninitialized: .. das:attribute:: safe_when_uninitialized Declares that the structure is safe to access before explicit initialization, suppressing uninitialized-use errors. + .. _handle-builtin-persistent: .. das:attribute:: persistent Allocates the structure on the C++ heap (via `new`) instead of the daslang context heap, allowing it to outlive the context. + + ++++++++++ Containers ++++++++++ @@ -566,7 +655,7 @@ Containers * :ref:`each (a: array\#) : iterator\ ` * :ref:`each (str: string) : iterator\ ` * :ref:`each (a: array\) : iterator\ ` - * :ref:`each (a: auto(TT)[]) : iterator\ ` + * :ref:`each (a: auto(TT)[]) : iterator\ ` * :ref:`each (lam: lambda\<(var arg:auto(argT)):bool\>) : iterator\ ` * :ref:`each (rng: range) : iterator\ ` * :ref:`each (rng: urange64) : iterator\ ` @@ -574,15 +663,15 @@ Containers * :ref:`each (rng: urange) : iterator\ ` * :ref:`each_enum (tt: auto(TT)) : iterator\ ` * :ref:`each_ref (lam: lambda\<(var arg:auto(argT)?):bool\>) : iterator\ ` - * :ref:`emplace (var Arr: array\; var value: numT&; at: int) : auto ` - * :ref:`emplace (var Arr: array\; var value: numT&) : auto ` - * :ref:`emplace (var Tab: table\; at: keyT|keyT#; var val: valT[]&) : auto ` + * :ref:`emplace (var Arr: array\; var value: numT&; at: int) : auto ` + * :ref:`emplace (var Arr: array\; var value: numT&) : auto ` + * :ref:`emplace (var Tab: table\; at: keyT|keyT#; var val: valT[]&) : auto ` * :ref:`emplace (var Tab: table\; key: auto; value: auto) : auto ` - * :ref:`emplace (var Tab: table\; at: keyT|keyT#; var val: valT&) : auto ` - * :ref:`emplace (var Tab: table\\>; at: keyT|keyT#; var val: smart_ptr\&) : auto ` + * :ref:`emplace (var Tab: table\; at: keyT|keyT#; var val: valT&) : auto ` + * :ref:`emplace (var Tab: table\\>; at: keyT|keyT#; var val: smart_ptr\&) : auto ` * :ref:`emplace (var a: array\; value: auto) : auto ` - * :ref:`emplace (var Arr: array\; var value: numT[]) : auto ` - * :ref:`emplace (var Arr: array\; var value: numT[]) : auto ` + * :ref:`emplace (var Arr: array\; var value: numT[]) : auto ` + * :ref:`emplace (var Arr: array\; var value: numT[]) : auto ` * :ref:`emplace_default (var tab: table\; key: keyT|keyT#) ` * :ref:`emplace_new (var Arr: array\\>; var value: smart_ptr\) : auto ` * :ref:`emplace_new (var tab: table\\>; key: kT; var value: smart_ptr\) : auto ` @@ -595,38 +684,38 @@ Containers * :ref:`erase (var Arr: array\; at: int) : auto ` * :ref:`erase (var Arr: array\; at: int; count: int) : auto ` * :ref:`erase (var Tab: table\; at: string#) : bool ` - * :ref:`erase_if (var arr: array\; blk: block\<(key:TT const):bool\>|block\<(var key:TT&):bool\>) : auto ` + * :ref:`erase_if (var arr: array\; blk: block\<(key:TT const):bool\>|block\<(var key:TT&):bool\>) : auto ` * :ref:`find_index (arr: array\|array\#; key: TT) : auto ` * :ref:`find_index (var arr: iterator\; key: TT) : auto ` - * :ref:`find_index (arr: auto(TT)[]|auto(TT)[]#; key: TT) : auto ` + * :ref:`find_index (arr: auto(TT)[]|auto(TT)[]#; key: TT) : auto ` * :ref:`find_index_if (var arr: iterator\; blk: block\<(key:TT):bool\>) : auto ` * :ref:`find_index_if (arr: array\|array\#; blk: block\<(key:TT):bool\>) : auto ` - * :ref:`find_index_if (arr: auto(TT)[]|auto(TT)[]#; blk: block\<(key:TT):bool\>) : auto ` + * :ref:`find_index_if (arr: auto(TT)[]|auto(TT)[]#; blk: block\<(key:TT):bool\>) : auto ` * :ref:`get (Tab: table\; at: keyT|keyT#; blk: block\<(p:valT):void\>) : auto ` - * :ref:`get (Tab: table\#; at: keyT|keyT#; blk: block\<(p:valT const&#):void\>) : auto ` - * :ref:`get (var Tab: table\; at: keyT|keyT#; blk: block\<(var p:valT&):void\>) : auto ` - * :ref:`get (var Tab: table\#; at: keyT|keyT#; blk: block\<(var p:valT&#):void\>) : auto ` - * :ref:`get (Tab: table\#; at: keyT|keyT#; blk: block\<(p:valT const[-2]&#):void\>) : auto ` - * :ref:`get (var Tab: table\; at: keyT|keyT#; blk: block\<(var p:valT[-2]&):void\>) : auto ` - * :ref:`get (Tab: table\; at: keyT|keyT#; blk: block\<(p:valT const[-2]&):void\>) : auto ` + * :ref:`get (Tab: table\#; at: keyT|keyT#; blk: block\<(p:valT const&#):void\>) : auto ` + * :ref:`get (var Tab: table\; at: keyT|keyT#; blk: block\<(var p:valT&):void\>) : auto ` + * :ref:`get (var Tab: table\#; at: keyT|keyT#; blk: block\<(var p:valT&#):void\>) : auto ` + * :ref:`get (Tab: table\#; at: keyT|keyT#; blk: block\<(p:valT const[-2]&#):void\>) : auto ` + * :ref:`get (var Tab: table\; at: keyT|keyT#; blk: block\<(var p:valT[-2]&):void\>) : auto ` + * :ref:`get (Tab: table\; at: keyT|keyT#; blk: block\<(p:valT const[-2]&):void\>) : auto ` * :ref:`get (Tab: table\; at: keyT|keyT#; blk: block\<(var p:void?):void\>) : auto ` - * :ref:`get (var Tab: table\#; at: keyT|keyT#; blk: block\<(var p:valT[-2]&#):void\>) : auto ` - * :ref:`get_value (var Tab: table\; at: keyT|keyT#) : valT[-2] ` + * :ref:`get (var Tab: table\#; at: keyT|keyT#; blk: block\<(var p:valT[-2]&#):void\>) : auto ` + * :ref:`get_value (var Tab: table\; at: keyT|keyT#) : valT[-2] ` * :ref:`get_value (var Tab: table\; at: keyT|keyT#) : valT ` * :ref:`get_value (Tab: table\; at: keyT|keyT#) : valT ` * :ref:`get_value (var Tab: table\\>; at: keyT|keyT#) : smart_ptr\ ` - * :ref:`get_with_default (var Tab: table\; at: keyT|keyT#; blk: block\<(var p:valT&):void\>) ` + * :ref:`get_with_default (var Tab: table\; at: keyT|keyT#; blk: block\<(var p:valT&):void\>) ` * :ref:`has_value (var a: iterator\; key: auto) : auto ` * :ref:`has_value (a: auto; key: auto) : auto ` * :ref:`insert (var Tab: table\; at: keyT|keyT#) : auto ` * :ref:`insert (var Tab: table\; at: keyT|keyT#; val: valT ==const|valT const# ==const) : auto ` - * :ref:`insert (var Tab: table\; at: keyT|keyT#; var val: valT[] ==const|valT[]# ==const) : auto ` + * :ref:`insert (var Tab: table\; at: keyT|keyT#; var val: valT[] ==const|valT[]# ==const) : auto ` * :ref:`insert (var Tab: table\; at: keyT|keyT#; var val: valT ==const|valT# ==const) : auto ` - * :ref:`insert (var Tab: table\; at: keyT|keyT#; val: valT const[] ==const|valT const[]# ==const) : auto ` + * :ref:`insert (var Tab: table\; at: keyT|keyT#; val: valT const[] ==const|valT const[]# ==const) : auto ` * :ref:`insert_clone (var Tab: table\; at: keyT|keyT#; var val: valT ==const|valT# ==const) : auto ` * :ref:`insert_clone (var Tab: table\; at: keyT|keyT#; val: valT ==const|valT const# ==const) : auto ` - * :ref:`insert_clone (var Tab: table\; at: keyT|keyT#; var val: valT[] ==const|valT[]# ==const) : auto ` - * :ref:`insert_clone (var Tab: table\; at: keyT|keyT#; val: valT const[] ==const|valT const[]# ==const) : auto ` + * :ref:`insert_clone (var Tab: table\; at: keyT|keyT#; var val: valT[] ==const|valT[]# ==const) : auto ` + * :ref:`insert_clone (var Tab: table\; at: keyT|keyT#; val: valT const[] ==const|valT const[]# ==const) : auto ` * :ref:`insert_default (var tab: table\; key: keyT|keyT#; value: valT ==const|valT const# ==const) ` * :ref:`insert_default (var tab: table\; key: keyT|keyT#) ` * :ref:`insert_default (var tab: table\; key: TT|TT#; var value: QQ ==const|QQ# ==const) ` @@ -642,14 +731,14 @@ Containers * :ref:`lock (Tab: table\|table\#; blk: block\<(t:table\#):void\>) : auto ` * :ref:`lock_forever (var Tab: table\|table\#) : table\# ` * :ref:`modify (var Tab: table\; at: keyT|keyT#; blk: block\<(p:valT):valT\>) ` - * :ref:`move_to_local (var a: auto(TT)&) : TT ` - * :ref:`move_to_ref (var a: auto&; var b: auto) : auto ` - * :ref:`next (var it: iterator\; var value: TT&) : bool ` + * :ref:`move_to_local (var a: auto(TT)&) : TT ` + * :ref:`move_to_ref (var a: auto&; var b: auto) : auto ` + * :ref:`next (var it: iterator\; var value: TT&) : bool ` * :ref:`nothing (var it: iterator\) : iterator\ ` * :ref:`pop (var Arr: array\) : auto ` - * :ref:`push (var Arr: array\; varr: numT const[] ==const) : auto ` - * :ref:`push (var Arr: array\; varr: numT[]) : auto ` - * :ref:`push (var Arr: array\; var varr: numT[] ==const) : auto ` + * :ref:`push (var Arr: array\; varr: numT const[] ==const) : auto ` + * :ref:`push (var Arr: array\; varr: numT[]) : auto ` + * :ref:`push (var Arr: array\; var varr: numT[] ==const) : auto ` * :ref:`push (var Arr: array\; varr: array\) : auto ` * :ref:`push (var Arr: array\; value: numT ==const) : auto ` * :ref:`push (var Arr: array\; var value: numT ==const; at: int) : auto ` @@ -657,14 +746,14 @@ Containers * :ref:`push (var Arr: array\; var varr: array\) : auto ` * :ref:`push (var Arr: array\; value: numT ==const; at: int) : auto ` * :ref:`push_clone (var A: auto(CT); b: auto(TT)|auto(TT)#) : auto ` - * :ref:`push_clone (var Arr: array\; var varr: numT[]) : auto ` - * :ref:`push_clone (var Arr: array\; varr: numT const[] ==const) : auto ` + * :ref:`push_clone (var Arr: array\; var varr: numT[]) : auto ` + * :ref:`push_clone (var Arr: array\; varr: numT const[] ==const) : auto ` * :ref:`push_clone (var Arr: array\; var value: numT ==const|numT# ==const) : auto ` - * :ref:`push_clone (var Arr: array\; var varr: numT[] ==const) : auto ` + * :ref:`push_clone (var Arr: array\; var varr: numT[] ==const) : auto ` * :ref:`push_clone (var Arr: array\; var value: numT ==const|numT# ==const; at: int) : auto ` * :ref:`push_clone (var Arr: array\; value: numT ==const|numT const# ==const; at: int) : auto ` * :ref:`push_clone (var Arr: array\; value: numT ==const|numT const# ==const) : auto ` - * :ref:`push_clone (var Arr: array\; varr: numT const[] ==const) : auto ` + * :ref:`push_clone (var Arr: array\; varr: numT const[] ==const) : auto ` * :ref:`remove_value (var arr: array\|array\#; key: TT) : bool ` * :ref:`reserve (var Tab: table\; newSize: int) : auto ` * :ref:`reserve (var Arr: array\; newSize: int) : auto ` @@ -674,28 +763,28 @@ Containers * :ref:`resize_no_init (var Arr: array\; newSize: int) : auto ` * :ref:`sort (var a: array\|array\#) : auto ` * :ref:`sort (var a: array\|array\#; cmp: block\<(x:TT;y:TT):bool\>) : auto ` - * :ref:`sort (var a: auto(TT)[]|auto(TT)[]#) : auto ` - * :ref:`sort (var a: auto(TT)[]|auto(TT)[]#; cmp: block\<(x:TT;y:TT):bool\>) : auto ` - * :ref:`subarray (a: auto(TT)[]; r: urange) : auto ` + * :ref:`sort (var a: auto(TT)[]|auto(TT)[]#) : auto ` + * :ref:`sort (var a: auto(TT)[]|auto(TT)[]#; cmp: block\<(x:TT;y:TT):bool\>) : auto ` + * :ref:`subarray (a: auto(TT)[]; r: urange) : auto ` * :ref:`subarray (a: array\; r: urange) : auto ` * :ref:`subarray (a: array\; r: range) : auto ` * :ref:`subarray (var a: array\; r: range) : auto ` - * :ref:`subarray (a: auto(TT)[]; r: range) : auto ` - * :ref:`to_array (a: auto(TT)[]) : array\ ` + * :ref:`subarray (a: auto(TT)[]; r: range) : auto ` + * :ref:`to_array (a: auto(TT)[]) : array\ ` * :ref:`to_array (var it: iterator\) : array\ ` * :ref:`to_array_move (var a: auto(TT) ==const) : array\ ` - * :ref:`to_array_move (var a: auto(TT)[]) : array\ ` + * :ref:`to_array_move (var a: auto(TT)[]) : array\ ` * :ref:`to_array_move (a: auto(TT) ==const) : array\ ` - * :ref:`to_table (a: tuple\[]) : table\ ` - * :ref:`to_table (a: auto(keyT)[]) : table\ ` - * :ref:`to_table_move (var a: tuple\[]) : table\ ` + * :ref:`to_table (a: tuple\[]) : table\ ` + * :ref:`to_table (a: auto(keyT)[]) : table\ ` + * :ref:`to_table_move (var a: tuple\[]) : table\ ` * :ref:`to_table_move (var a: tuple\) : table\ ` * :ref:`to_table_move (var a: array\\>) : table\ ` - * :ref:`to_table_move (a: auto(keyT)[]) : table\ ` + * :ref:`to_table_move (a: auto(keyT)[]) : table\ ` * :ref:`to_table_move (a: array\) : table\ ` * :ref:`to_table_move (a: auto(keyT)) : table\ ` - * :ref:`values (var a: table\ ==const|table\# ==const) : iterator\ ` - * :ref:`values (a: table\ ==const|table\ const# ==const) : iterator\ ` + * :ref:`values (var a: table\ ==const|table\# ==const) : iterator\ ` + * :ref:`values (a: table\ ==const|table\ const# ==const) : iterator\ ` * :ref:`values (a: table\ ==const|table\ const# ==const) : iterator\ ` * :ref:`values (a: table\ ==const|table\ const# ==const) : auto ` * :ref:`values (var a: table\ ==const|table\# ==const) : auto ` @@ -711,7 +800,8 @@ back Accesses and returns a const temporary reference to the last element of the temporary dynamic array `a`. -:Arguments: * **a** : array#! + +:Arguments: * **a** : array\ #! .. _function-builtin_back_array_ls_autoTT_gr_: @@ -745,6 +835,7 @@ capacity Returns the current capacity of the `table` — the number of key-value pairs it can hold before triggering a reallocation. + :Arguments: * **table** : table implicit .. _function-builtin_capacity_array_ls_anything_gr_: @@ -763,6 +854,7 @@ clear Removes all elements from the dynamic `array`, leaving it empty with a size of 0. + :Arguments: * **array** : array implicit .. _function-builtin_clear_table_ls_autoKT,_autoVT_gr_: @@ -777,6 +869,7 @@ Removes all elements from the dynamic `array`, leaving it empty with a size of 0 Copies the value `a` and returns it as a new local value on the stack, which can be used to work around aliasing issues where a reference might be invalidated. + :Arguments: * **a** : auto(TT) @@ -789,7 +882,8 @@ each Creates an iterator that yields temporary references to each element of the temporary dynamic array `a`. -:Arguments: * **a** : array# + +:Arguments: * **a** : array\ # .. _function-builtin_each_string: @@ -799,7 +893,7 @@ Creates an iterator that yields temporary references to each element of the temp .. das:function:: each(a: array) : iterator -.. _function-builtin_each_autoTT_0x59e: +.. _function-builtin_each_autoTT_lb__rb__0x59e: .. das:function:: each(a: auto(TT)[]) : iterator @@ -834,6 +928,7 @@ Creates an iterator that yields temporary references to each element of the temp Creates an iterator that yields every value of the enumeration type inferred from `tt`, allowing iteration over all members of an enum. + :Arguments: * **tt** : auto(TT) .. _function-builtin_each_ref_lambda_ls_var_arg_c_autoargT_q__c_bool_gr_: @@ -842,29 +937,31 @@ Creates an iterator that yields every value of the enumeration type inferred fro Wraps a lambda `lam` — which receives a mutable pointer argument and returns a bool indicating whether to continue — into an iterator that yields references to each value rather than copies. + :Arguments: * **lam** : lambda<(arg:auto(argT)?):bool> emplace ^^^^^^^ -.. _function-builtin_emplace_array_ls_autonumT_gr__numT_int: +.. _function-builtin_emplace_array_ls_autonumT_gr__numT_ref__int: .. das:function:: emplace(Arr: array; value: numT&; at: int) : auto Moves `value` into the dynamic array `Arr` at index `at` using move semantics, shifting subsequent elements forward. + :Arguments: * **Arr** : array - * **value** : numT& + * **value** : numT\ & * **at** : int -.. _function-builtin_emplace_array_ls_autonumT_gr__numT: +.. _function-builtin_emplace_array_ls_autonumT_gr__numT_ref_: .. das:function:: emplace(Arr: array; value: numT&) : auto -.. _function-builtin_emplace_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT: +.. _function-builtin_emplace_table_ls_autokeyT,_autovalT_lb__rb__gr__keyTkeyT_hh__valT_lb__rb__ref_: .. das:function:: emplace(Tab: table; at: keyT|keyT#; val: valT[]&) : auto @@ -872,11 +969,11 @@ Moves `value` into the dynamic array `Arr` at index `at` using move semantics, s .. das:function:: emplace(Tab: table; key: auto; value: auto) : auto -.. _function-builtin_emplace_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT: +.. _function-builtin_emplace_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT_ref_: .. das:function:: emplace(Tab: table; at: keyT|keyT#; val: valT&) : auto -.. _function-builtin_emplace_table_ls_autokeyT,_smart_ptr_ls_autovalT_gr__gr__keyTkeyT_hh__smart_ptr_ls_valT_gr_: +.. _function-builtin_emplace_table_ls_autokeyT,_smart_ptr_ls_autovalT_gr__gr__keyTkeyT_hh__smart_ptr_ls_valT_gr__ref_: .. das:function:: emplace(Tab: table>; at: keyT|keyT#; val: smart_ptr&) : auto @@ -884,11 +981,11 @@ Moves `value` into the dynamic array `Arr` at index `at` using move semantics, s .. das:function:: emplace(a: array; value: auto) : auto -.. _function-builtin_emplace_array_ls_autonumT_gr__numT: +.. _function-builtin_emplace_array_ls_autonumT_gr__numT_lb__rb_: .. das:function:: emplace(Arr: array; value: numT[]) : auto -.. _function-builtin_emplace_array_ls_autonumT_gr__numT: +.. _function-builtin_emplace_array_ls_autonumT_lb__rb__gr__numT_lb__rb_: .. das:function:: emplace(Arr: array; value: numT[]) : auto @@ -900,9 +997,10 @@ Moves `value` into the dynamic array `Arr` at index `at` using move semantics, s Constructs a new default-initialized element in the table `tab` at the given `key`, only if that key does not already exist. + :Arguments: * **tab** : table - * **key** : option + * **key** : option emplace_new @@ -914,6 +1012,7 @@ emplace_new Moves a smart pointer `value` into the end of the array `Arr`, constructing the entry in-place and returning a reference to it. + :Arguments: * **Arr** : array> * **value** : smart_ptr @@ -934,6 +1033,7 @@ empty Checks whether the string `str` is empty (null or zero-length) and returns `true` if so. + :Arguments: * **str** : string implicit .. _function-builtin_empty_das_string_implicit: @@ -964,9 +1064,10 @@ erase Removes the entry with key `at` from the table `Tab`, returning `true` if the key was found and erased. + :Arguments: * **Tab** : table - * **at** : option + * **at** : option .. _function-builtin_erase_array_ls_autonumT_gr__int: @@ -982,15 +1083,16 @@ Removes the entry with key `at` from the table `Tab`, returning `true` if the ke ---- -.. _function-builtin_erase_if_array_ls_autoTT_gr__block_ls_key_c_TT_const_c_bool_gr_block_ls_var_key_c_TT_c_bool_gr_: +.. _function-builtin_erase_if_array_ls_autoTT_gr__block_ls_key_c_TT_const_c_bool_gr_block_ls_var_key_c_TT_ref__c_bool_gr_: .. das:function:: erase_if(arr: array; blk: block<(key:TT const):bool>|block<(var key:TT&):bool>) : auto Iterates over the array `arr` and removes all elements for which the block `blk` returns `true`. + :Arguments: * **arr** : array - * **blk** : option|block<(key:TT&):bool>> + * **blk** : option\ | block<(key:TT\ &):bool>> find_index @@ -1002,7 +1104,8 @@ find_index Searches the dynamic array `arr` for the first occurrence of `key` and returns its index, or -1 if not found. -:Arguments: * **arr** : option|array#> + +:Arguments: * **arr** : option\ | array\ #> * **key** : TT @@ -1010,7 +1113,7 @@ Searches the dynamic array `arr` for the first occurrence of `key` and returns i .. das:function:: find_index(arr: iterator; key: TT) : auto -.. _function-builtin_find_index_autoTTautoTT_hh__TT: +.. _function-builtin_find_index_autoTT_lb__rb_autoTT_lb__rb__hh__TT: .. das:function:: find_index(arr: auto(TT)[]|auto(TT)[]#; key: TT) : auto @@ -1026,6 +1129,7 @@ find_index_if Consumes elements from the iterator `arr` and returns the index of the first element for which the block `blk` returns `true`, or -1 if no match is found. + :Arguments: * **arr** : iterator * **blk** : block<(key:TT):bool> @@ -1034,7 +1138,7 @@ Consumes elements from the iterator `arr` and returns the index of the first ele .. das:function:: find_index_if(arr: array|array#; blk: block<(key:TT):bool>) : auto -.. _function-builtin_find_index_if_autoTTautoTT_hh__block_ls_key_c_TT_c_bool_gr_: +.. _function-builtin_find_index_if_autoTT_lb__rb_autoTT_lb__rb__hh__block_ls_key_c_TT_c_bool_gr_: .. das:function:: find_index_if(arr: auto(TT)[]|auto(TT)[]#; blk: block<(key:TT):bool>) : auto @@ -1050,33 +1154,34 @@ get Looks up `at` in the table `Tab` and, if found, invokes `blk` with a reference to the value; returns `true` if the key existed, `false` otherwise. + :Arguments: * **Tab** : table! - * **at** : option + * **at** : option - * **blk** : block<(p:valT&):void> + * **blk** : block<(p:valT\ &):void> -.. _function-builtin_get_table_ls_autokeyT,_autovalT_gr__hh__keyTkeyT_hh__block_ls_p_c_valT_const_hh__c_void_gr_: +.. _function-builtin_get_table_ls_autokeyT,_autovalT_gr__hh__keyTkeyT_hh__block_ls_p_c_valT_const_ref__hh__c_void_gr_: .. das:function:: get(Tab: table#; at: keyT|keyT#; blk: block<(p:valT const&#):void>) : auto -.. _function-builtin_get__table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__block_ls_var_p_c_valT_c_void_gr_: +.. _function-builtin_get__table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__block_ls_var_p_c_valT_ref__c_void_gr_: .. das:function:: get(Tab: table; at: keyT|keyT#; blk: block<(var p:valT&):void>) : auto -.. _function-builtin_get__table_ls_autokeyT,_autovalT_gr__hh__keyTkeyT_hh__block_ls_var_p_c_valT_hh__c_void_gr_: +.. _function-builtin_get__table_ls_autokeyT,_autovalT_gr__hh__keyTkeyT_hh__block_ls_var_p_c_valT_ref__hh__c_void_gr_: .. das:function:: get(Tab: table#; at: keyT|keyT#; blk: block<(var p:valT&#):void>) : auto -.. _function-builtin_get_table_ls_autokeyT,_autovalT_gr__hh__keyTkeyT_hh__block_ls_p_c_valT_const-2_hh__c_void_gr_: +.. _function-builtin_get_table_ls_autokeyT,_autovalT_lb__rb__gr__hh__keyTkeyT_hh__block_ls_p_c_valT_const_lb_-2_rb__ref__hh__c_void_gr_: .. das:function:: get(Tab: table#; at: keyT|keyT#; blk: block<(p:valT const[-2]&#):void>) : auto -.. _function-builtin_get__table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__block_ls_var_p_c_valT-2_c_void_gr_: +.. _function-builtin_get__table_ls_autokeyT,_autovalT_lb__rb__gr__keyTkeyT_hh__block_ls_var_p_c_valT_lb_-2_rb__ref__c_void_gr_: .. das:function:: get(Tab: table; at: keyT|keyT#; blk: block<(var p:valT[-2]&):void>) : auto -.. _function-builtin_get_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__block_ls_p_c_valT_const-2_c_void_gr_: +.. _function-builtin_get_table_ls_autokeyT,_autovalT_lb__rb__gr__keyTkeyT_hh__block_ls_p_c_valT_const_lb_-2_rb__ref__c_void_gr_: .. das:function:: get(Tab: table; at: keyT|keyT#; blk: block<(p:valT const[-2]&):void>) : auto @@ -1084,7 +1189,7 @@ Looks up `at` in the table `Tab` and, if found, invokes `blk` with a reference t .. das:function:: get(Tab: table; at: keyT|keyT#; blk: block<(var p:void?):void>) : auto -.. _function-builtin_get__table_ls_autokeyT,_autovalT_gr__hh__keyTkeyT_hh__block_ls_var_p_c_valT-2_hh__c_void_gr_: +.. _function-builtin_get__table_ls_autokeyT,_autovalT_lb__rb__gr__hh__keyTkeyT_hh__block_ls_var_p_c_valT_lb_-2_rb__ref__hh__c_void_gr_: .. das:function:: get(Tab: table#; at: keyT|keyT#; blk: block<(var p:valT[-2]&#):void>) : auto @@ -1094,15 +1199,16 @@ Looks up `at` in the table `Tab` and, if found, invokes `blk` with a reference t get_value ^^^^^^^^^ -.. _function-builtin_get_value_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh_: +.. _function-builtin_get_value_table_ls_autokeyT,_autovalT_lb__rb__gr__keyTkeyT_hh_: .. das:function:: get_value(Tab: table; at: keyT|keyT#) : valT[-2] Retrieves the fixed-size array value associated with key `at` from the mutable table `Tab`. + :Arguments: * **Tab** : table - * **at** : option + * **at** : option .. _function-builtin_get_value__table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh_: @@ -1118,17 +1224,18 @@ Retrieves the fixed-size array value associated with key `at` from the mutable t ---- -.. _function-builtin_get_with_default__table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__block_ls_var_p_c_valT_c_void_gr_: +.. _function-builtin_get_with_default__table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__block_ls_var_p_c_valT_ref__c_void_gr_: .. das:function:: get_with_default(Tab: table; at: keyT|keyT#; blk: block<(var p:valT&):void>) Looks up key `at` in the table `Tab`, inserting a default-initialized entry if the key is absent, then invokes `blk` with a mutable reference to the value. + :Arguments: * **Tab** : table! - * **at** : option + * **at** : option - * **blk** : block<(p:valT&):void> + * **blk** : block<(p:valT\ &):void> has_value @@ -1140,6 +1247,7 @@ has_value Consumes elements from the iterator `a` and returns `true` if any element equals `key`. + :Arguments: * **a** : iterator * **key** : auto @@ -1160,15 +1268,16 @@ insert Inserts the key `at` into the set-style table `Tab` (a table with `void` values), effectively adding to a set. + :Arguments: * **Tab** : table - * **at** : option + * **at** : option .. _function-builtin_insert_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT__eq__eq_constvalT_const_hh___eq__eq_const: .. das:function:: insert(Tab: table; at: keyT|keyT#; val: valT ==const|valT const# ==const) : auto -.. _function-builtin_insert_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT__eq__eq_constvalT_hh___eq__eq_const: +.. _function-builtin_insert_table_ls_autokeyT,_autovalT_lb__rb__gr__keyTkeyT_hh__valT_lb__rb___eq__eq_constvalT_lb__rb__hh___eq__eq_const: .. das:function:: insert(Tab: table; at: keyT|keyT#; val: valT[] ==const|valT[]# ==const) : auto @@ -1176,7 +1285,7 @@ Inserts the key `at` into the set-style table `Tab` (a table with `void` values) .. das:function:: insert(Tab: table; at: keyT|keyT#; val: valT ==const|valT# ==const) : auto -.. _function-builtin_insert_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT_const__eq__eq_constvalT_const_hh___eq__eq_const: +.. _function-builtin_insert_table_ls_autokeyT,_autovalT_lb__rb__gr__keyTkeyT_hh__valT_const_lb__rb___eq__eq_constvalT_const_lb__rb__hh___eq__eq_const: .. das:function:: insert(Tab: table; at: keyT|keyT#; val: valT const[] ==const|valT const[]# ==const) : auto @@ -1192,21 +1301,22 @@ insert_clone Inserts or updates an entry in the table `Tab` at key `at` by cloning the mutable value `val` into the table. + :Arguments: * **Tab** : table - * **at** : option + * **at** : option - * **val** : option + * **val** : option .. _function-builtin_insert_clone_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT__eq__eq_constvalT_const_hh___eq__eq_const: .. das:function:: insert_clone(Tab: table; at: keyT|keyT#; val: valT ==const|valT const# ==const) : auto -.. _function-builtin_insert_clone_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT__eq__eq_constvalT_hh___eq__eq_const: +.. _function-builtin_insert_clone_table_ls_autokeyT,_autovalT_lb__rb__gr__keyTkeyT_hh__valT_lb__rb___eq__eq_constvalT_lb__rb__hh___eq__eq_const: .. das:function:: insert_clone(Tab: table; at: keyT|keyT#; val: valT[] ==const|valT[]# ==const) : auto -.. _function-builtin_insert_clone_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__valT_const__eq__eq_constvalT_const_hh___eq__eq_const: +.. _function-builtin_insert_clone_table_ls_autokeyT,_autovalT_lb__rb__gr__keyTkeyT_hh__valT_const_lb__rb___eq__eq_constvalT_const_lb__rb__hh___eq__eq_const: .. das:function:: insert_clone(Tab: table; at: keyT|keyT#; val: valT const[] ==const|valT const[]# ==const) : auto @@ -1222,11 +1332,12 @@ insert_default Inserts key `key` with the given const `value` into table `tab` only if the key does not already exist; existing entries are left unchanged. + :Arguments: * **tab** : table - * **key** : option + * **key** : option - * **value** : option + * **value** : option .. _function-builtin_insert_default_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh_: @@ -1248,9 +1359,10 @@ key_exists Checks whether the key `at` exists in the table `Tab` and returns `true` if found. -:Arguments: * **Tab** : option|table#> - * **at** : option +:Arguments: * **Tab** : option\ | table\ #> + + * **at** : option .. _function-builtin_key_exists_table_ls_autokeyT;autovalT_gr_table_ls_autokeyT;autovalT_gr__hh__string_hh_: @@ -1268,7 +1380,8 @@ keys Creates an iterator over all keys of the mutable table `a`, allowing enumeration of the table's key set. -:Arguments: * **a** : option!|table#!> + +:Arguments: * **a** : option!\ | table\ #!> .. _function-builtin_keys_table_ls_autokeyT;autovalT_gr___eq__eq_consttable_ls_autokeyT;autovalT_gr__const_hh___eq__eq_const: @@ -1286,7 +1399,8 @@ length Returns the number of elements currently stored in a table or dynamic array `a`. -:Arguments: * **a** : option + +:Arguments: * **a** : option .. _function-builtin_length_array_ls_anything_gr_: @@ -1308,9 +1422,10 @@ lock Locks a constant array for the duration of `blk`, preventing structural modifications while providing read-only access through a temporary reference. -:Arguments: * **a** : option!|array#!> - * **blk** : block<(x:array#):auto> +:Arguments: * **a** : option!\ | array\ #!> + + * **blk** : block<(x:array\ #):auto> .. _function-builtin_lock_array_ls_autoTT_gr___eq__eq_constarray_ls_autoTT_gr__hh___eq__eq_const_block_ls_var_x_c_array_ls_TT_gr__hh__c_auto_gr_: @@ -1328,7 +1443,8 @@ Locks a constant array for the duration of `blk`, preventing structural modifica Permanently locks a table, preventing any future insertions, deletions, or structural modifications, and returns a temporary reference to it. -:Arguments: * **Tab** : option|table#> + +:Arguments: * **Tab** : option\ | table\ #> .. _function-builtin_modify__table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh__block_ls_p_c_valT_c_valT_gr_: @@ -1336,39 +1452,43 @@ Permanently locks a table, preventing any future insertions, deletions, or struc Looks up `at` in `Tab` and, if found, invokes `blk` with the current value, replacing it with the value returned by the block. + :Arguments: * **Tab** : table! - * **at** : option + * **at** : option - * **blk** : block<(p:valT&):valT> + * **blk** : block<(p:valT\ &):valT> -.. _function-builtin_move_to_local_autoTT_0x428: +.. _function-builtin_move_to_local_autoTT_ref__0x428: .. das:function:: move_to_local(a: auto(TT)&) : TT Moves the value referenced by `a` onto the stack as a local copy and returns it, clearing the original; useful for resolving aliasing issues. -:Arguments: * **a** : auto(TT)& -.. _function-builtin_move_to_ref_auto_auto_0x80c: +:Arguments: * **a** : auto(TT)\ & + +.. _function-builtin_move_to_ref_auto_ref__auto_0x80c: .. das:function:: move_to_ref(a: auto&; b: auto) : auto Moves `b` into the reference `a`; if `b` is a value type rather than a reference, it is copied instead of moved. -:Arguments: * **a** : auto& + +:Arguments: * **a** : auto\ & * **b** : auto -.. _function-builtin_next_iterator_ls_autoTT_gr__TT: +.. _function-builtin_next_iterator_ls_autoTT_gr__TT_ref_: .. das:function:: next(it: iterator; value: TT&) : bool Advances the iterator `it` and stores the next element in `value`, returning true if an element was retrieved or false if the iterator is exhausted or null. + :Arguments: * **it** : iterator - * **value** : TT& + * **value** : TT\ & .. _function-builtin_nothing_iterator_ls_autoTT_gr_: @@ -1376,6 +1496,7 @@ Advances the iterator `it` and stores the next element in `value`, returning tru Produces an empty iterator of the same element type as `it` that yields no elements. + :Arguments: * **it** : iterator .. _function-builtin_pop_array_ls_autonumT_gr_: @@ -1384,27 +1505,29 @@ Produces an empty iterator of the same element type as `it` that yields no eleme Removes and discards the last element of `Arr`, reducing its length by one. + :Arguments: * **Arr** : array push ^^^^ -.. _function-builtin_push_array_ls_autonumT_gr__numT_const__eq__eq_const: +.. _function-builtin_push_array_ls_autonumT_lb__rb__gr__numT_const_lb__rb___eq__eq_const: .. das:function:: push(Arr: array; varr: numT const[] ==const) : auto Appends a constant fixed-size array element `varr` to the end of `Arr`, an array of fixed-size arrays. + :Arguments: * **Arr** : array * **varr** : numT[-1]! -.. _function-builtin_push_array_ls_autonumT_gr__numT: +.. _function-builtin_push_array_ls_autonumT_gr__numT_lb__rb_: .. das:function:: push(Arr: array; varr: numT[]) : auto -.. _function-builtin_push_array_ls_autonumT_gr___numT__eq__eq_const: +.. _function-builtin_push_array_ls_autonumT_lb__rb__gr___numT_lb__rb___eq__eq_const: .. das:function:: push(Arr: array; varr: numT[] ==const) : auto @@ -1444,15 +1567,16 @@ push_clone Clones and appends element `b` to the container `A`, using deep copy semantics rather than move or shallow copy. + :Arguments: * **A** : auto(CT) - * **b** : option + * **b** : option -.. _function-builtin_push_clone_array_ls_autonumT_gr__numT: +.. _function-builtin_push_clone_array_ls_autonumT_lb__rb__gr__numT_lb__rb_: .. das:function:: push_clone(Arr: array; varr: numT[]) : auto -.. _function-builtin_push_clone_array_ls_autonumT_gr__numT_const__eq__eq_const: +.. _function-builtin_push_clone_array_ls_autonumT_gr__numT_const_lb__rb___eq__eq_const: .. das:function:: push_clone(Arr: array; varr: numT const[] ==const) : auto @@ -1460,7 +1584,7 @@ Clones and appends element `b` to the container `A`, using deep copy semantics r .. das:function:: push_clone(Arr: array; value: numT ==const|numT# ==const) : auto -.. _function-builtin_push_clone_array_ls_autonumT_gr___numT__eq__eq_const: +.. _function-builtin_push_clone_array_ls_autonumT_gr___numT_lb__rb___eq__eq_const: .. das:function:: push_clone(Arr: array; varr: numT[] ==const) : auto @@ -1476,7 +1600,7 @@ Clones and appends element `b` to the container `A`, using deep copy semantics r .. das:function:: push_clone(Arr: array; value: numT ==const|numT const# ==const) : auto -.. _function-builtin_push_clone_array_ls_autonumT_gr__numT_const__eq__eq_const: +.. _function-builtin_push_clone_array_ls_autonumT_lb__rb__gr__numT_const_lb__rb___eq__eq_const: .. das:function:: push_clone(Arr: array; varr: numT const[] ==const) : auto @@ -1488,7 +1612,8 @@ Clones and appends element `b` to the container `A`, using deep copy semantics r Searches `arr` for the first element equal to `key` and removes it, returning true if an element was found and removed or false otherwise. -:Arguments: * **arr** : option|array#> + +:Arguments: * **arr** : option\ | array\ #> * **key** : TT @@ -1502,6 +1627,7 @@ reserve Pre-allocates memory in `Tab` to hold at least `newSize` entries without rehashing, improving performance of subsequent insertions. + :Arguments: * **Tab** : table * **newSize** : int @@ -1518,6 +1644,7 @@ Pre-allocates memory in `Tab` to hold at least `newSize` entries without rehashi Resizes dynamic array `Arr` to `newSize` elements; new elements beyond the previous length are zero-initialized, and excess elements are removed. + :Arguments: * **Arr** : array * **newSize** : int @@ -1532,6 +1659,7 @@ resize_and_init Resizes dynamic array `Arr` to `newSize` elements, initializing any newly added elements with the provided `initValue`. + :Arguments: * **Arr** : array * **newSize** : int @@ -1550,6 +1678,7 @@ Resizes dynamic array `Arr` to `newSize` elements, initializing any newly added Resizes dynamic array `Arr` to `newSize` elements without initializing newly added entries, leaving their memory contents undefined. + :Arguments: * **Arr** : array * **newSize** : int @@ -1564,17 +1693,18 @@ sort Sorts a dynamic array in place in ascending order using the default comparison for its element type. -:Arguments: * **a** : option|array#> + +:Arguments: * **a** : option\ | array\ #> .. _function-builtin_sort_array_ls_autoTT_gr_array_ls_autoTT_gr__hh__block_ls_x_c_TT;y_c_TT_c_bool_gr_: .. das:function:: sort(a: array|array#; cmp: block<(x:TT;y:TT):bool>) : auto -.. _function-builtin_sort_autoTTautoTT_hh_: +.. _function-builtin_sort_autoTT_lb__rb_autoTT_lb__rb__hh_: .. das:function:: sort(a: auto(TT)[]|auto(TT)[]#) : auto -.. _function-builtin_sort_autoTTautoTT_hh__block_ls_x_c_TT;y_c_TT_c_bool_gr_: +.. _function-builtin_sort_autoTT_lb__rb_autoTT_lb__rb__hh__block_ls_x_c_TT;y_c_TT_c_bool_gr_: .. das:function:: sort(a: auto(TT)[]|auto(TT)[]#; cmp: block<(x:TT;y:TT):bool>) : auto @@ -1584,12 +1714,13 @@ Sorts a dynamic array in place in ascending order using the default comparison f subarray ^^^^^^^^ -.. _function-builtin_subarray_autoTT_urange_0x7c2: +.. _function-builtin_subarray_autoTT_lb__rb__urange_0x7c2: .. das:function:: subarray(a: auto(TT)[]; r: urange) : auto Creates and returns a new dynamic array containing a copy of elements from fixed-size array `a` within the unsigned range `r`. + :Arguments: * **a** : auto(TT)[-1] * **r** : urange @@ -1606,7 +1737,7 @@ Creates and returns a new dynamic array containing a copy of elements from fixed .. das:function:: subarray(a: array; r: range) : auto -.. _function-builtin_subarray_autoTT_range_0x7b1: +.. _function-builtin_subarray_autoTT_lb__rb__range_0x7b1: .. das:function:: subarray(a: auto(TT)[]; r: range) : auto @@ -1616,12 +1747,13 @@ Creates and returns a new dynamic array containing a copy of elements from fixed to_array ^^^^^^^^ -.. _function-builtin_to_array_autoTT_0x5e9: +.. _function-builtin_to_array_autoTT_lb__rb__0x5e9: .. das:function:: to_array(a: auto(TT)[]) : array Converts a fixed-size array `a` into a new dynamic array by cloning each element. + :Arguments: * **a** : auto(TT)[-1] .. _function-builtin_to_array_iterator_ls_autoTT_gr_: @@ -1640,9 +1772,10 @@ to_array_move Converts a mutable container `a` into a new dynamic array, moving elements when possible instead of cloning. + :Arguments: * **a** : auto(TT)! -.. _function-builtin_to_array_move_autoTT_0x5f3: +.. _function-builtin_to_array_move_autoTT_lb__rb__0x5f3: .. das:function:: to_array_move(a: auto(TT)[]) : array @@ -1656,15 +1789,16 @@ Converts a mutable container `a` into a new dynamic array, moving elements when to_table ^^^^^^^^ -.. _function-builtin_to_table_tuple_ls_autokeyT;autovalT_gr_: +.. _function-builtin_to_table_tuple_ls_autokeyT;autovalT_gr__lb__rb_: .. das:function:: to_table(a: tuple[]) : table Converts a fixed-size array of key-value tuples `a` into a `table` by cloning each key and value. + :Arguments: * **a** : tuple[-1] -.. _function-builtin_to_table_autokeyT_0x635: +.. _function-builtin_to_table_autokeyT_lb__rb__0x635: .. das:function:: to_table(a: auto(keyT)[]) : table @@ -1674,12 +1808,13 @@ Converts a fixed-size array of key-value tuples `a` into a `table` b to_table_move ^^^^^^^^^^^^^ -.. _function-builtin_to_table_move_tuple_ls_autokeyT;autovalT_gr_: +.. _function-builtin_to_table_move_tuple_ls_autokeyT;autovalT_gr__lb__rb_: .. das:function:: to_table_move(a: tuple[]) : table Converts a mutable fixed-size array of key-value tuples `a` into a `table`, moving elements when possible. + :Arguments: * **a** : tuple[-1] .. _function-builtin_to_table_move_tuple_ls_autokeyT;autovalT_gr_: @@ -1690,7 +1825,7 @@ Converts a mutable fixed-size array of key-value tuples `a` into a `table>) : table -.. _function-builtin_to_table_move_autokeyT_0x63e: +.. _function-builtin_to_table_move_autokeyT_lb__rb__0x63e: .. das:function:: to_table_move(a: auto(keyT)[]) : table @@ -1708,15 +1843,16 @@ Converts a mutable fixed-size array of key-value tuples `a` into a `table ==const|table# ==const) : iterator Returns a mutable iterator over all fixed-size array values in a mutable `table`, yielding each array by reference. -:Arguments: * **a** : option!|table#!> -.. _function-builtin_values_table_ls_autokeyT;autovalT_gr___eq__eq_consttable_ls_autokeyT;autovalT_gr__const_hh___eq__eq_const: +:Arguments: * **a** : option!\ | table\ #!> + +.. _function-builtin_values_table_ls_autokeyT;autovalT_lb__rb__gr___eq__eq_consttable_ls_autokeyT;autovalT_lb__rb__gr__const_hh___eq__eq_const: .. das:function:: values(a: table ==const|table const# ==const) : iterator @@ -1738,6 +1874,7 @@ Returns a mutable iterator over all fixed-size array values in a mutable `table< ---- + ++++++++++++++++++++++++ das::string manipulation ++++++++++++++++++++++++ @@ -1750,9 +1887,11 @@ das::string manipulation Provides zero-copy read access to the contents of a `das_string` by invoking `block` with a temporary string reference, avoiding allocation. + :Arguments: * **src** : :ref:`das_string ` implicit - * **block** : block<(string#):void> implicit + * **block** : block<(string\ #):void> implicit + ++++++++++++++ Heap reporting @@ -1777,18 +1916,21 @@ Heap reporting Returns the total number of heap allocations performed by the current context since it was created. + .. _function-builtin_heap_allocation_stats: .. das:function:: heap_allocation_stats() : urange64 Returns heap allocation statistics as a `urange64`, where the `x` component is total bytes allocated and the `y` component is total bytes freed. + .. _function-builtin_heap_bytes_allocated: .. das:function:: heap_bytes_allocated() : uint64 Returns the number of bytes currently in use on the heap (allocated minus freed), not counting reserved but unused memory. + .. _function-builtin_heap_collect_bool_bool: .. das:function:: heap_collect(string_heap: bool = true; validate: bool = false) @@ -1798,6 +1940,7 @@ Returns the number of bytes currently in use on the heap (allocated minus freed) Triggers garbage collection on the context heap; when `string_heap` is `true` the string heap is also collected, and when `validate` is `true` additional validation checks are performed. + :Arguments: * **string_heap** : bool * **validate** : bool @@ -1808,18 +1951,21 @@ Triggers garbage collection on the context heap; when `string_heap` is `true` th Returns the number of generations (depth of the allocation chain) in the context's regular heap. + .. _function-builtin_heap_report: .. das:function:: heap_report() Prints a diagnostic report of current heap usage and allocation statistics to the output log. + .. _function-builtin_memory_report_bool: .. das:function:: memory_report(errorsOnly: bool) Prints a report of memory allocations for the current context; when `errorsOnly` is true, only GC-related errors are included. + :Arguments: * **errorsOnly** : bool .. _function-builtin_string_heap_allocation_count: @@ -1828,30 +1974,36 @@ Prints a report of memory allocations for the current context; when `errorsOnly` Returns the total number of individual string allocations performed on the current context's string heap. + .. _function-builtin_string_heap_allocation_stats: .. das:function:: string_heap_allocation_stats() : urange64 Returns string heap allocation statistics as a `urange64` where `x` is total bytes allocated and `y` is total bytes deleted. + .. _function-builtin_string_heap_bytes_allocated: .. das:function:: string_heap_bytes_allocated() : uint64 Returns the total number of bytes currently allocated in the current context's string heap. + .. _function-builtin_string_heap_depth: .. das:function:: string_heap_depth() : int Returns the number of generational layers (depth) in the current context's string heap. + .. _function-builtin_string_heap_report: .. das:function:: string_heap_report() Prints a detailed report of string heap usage, including allocation counts and byte statistics, to the log output. + + ++++++++++++++++++ GC0 infrastructure ++++++++++++++++++ @@ -1868,12 +2020,14 @@ GC0 infrastructure Clears the entire gc0 storage, invalidating all previously saved pointers and smart pointers stored within it. + .. _function-builtin_gc0_restore_ptr_string_implicit: .. das:function:: gc0_restore_ptr(name: string implicit) : void? Retrieves a raw pointer previously saved in gc0 storage under the specified `name`, returning `null` if not found. + :Arguments: * **name** : string implicit .. _function-builtin_gc0_restore_smart_ptr_string_implicit: @@ -1882,6 +2036,7 @@ Retrieves a raw pointer previously saved in gc0 storage under the specified `nam Retrieves a `smart_ptr` previously saved in gc0 storage under the specified `name`. + :Arguments: * **name** : string implicit .. _function-builtin_gc0_save_ptr_string_implicit_void_q__implicit: @@ -1890,6 +2045,7 @@ Retrieves a `smart_ptr` previously saved in gc0 storage under the specifie Stores a raw pointer `data` into gc0 storage under the specified `name`, allowing it to be retrieved later with `gc0_restore_ptr`. + :Arguments: * **name** : string implicit * **data** : void? implicit @@ -1900,10 +2056,12 @@ Stores a raw pointer `data` into gc0 storage under the specified `name`, allowin Stores a `smart_ptr` `data` into gc0 storage under the specified `name`, allowing it to be retrieved later with `gc0_restore_smart_ptr`. + :Arguments: * **name** : string implicit * **data** : smart_ptr implicit + ++++++++++++++++++++++++ Smart ptr infrastructure ++++++++++++++++++++++++ @@ -1912,11 +2070,11 @@ Smart ptr infrastructure * :ref:`get_const_ptr (src: smart_ptr\) : TT? ` * :ref:`get_ptr (var src: smart_ptr\ ==const) : TT? ` * :ref:`get_ptr (src: smart_ptr\ ==const) : TT? ` - * :ref:`move (dest: smart_ptr\& implicit; src: void? implicit) ` - * :ref:`move (dest: smart_ptr\& implicit; src: smart_ptr\& implicit) ` - * :ref:`move_new (dest: smart_ptr\& implicit; src: smart_ptr\ implicit) ` - * :ref:`smart_ptr_clone (dest: smart_ptr\& implicit; src: void? implicit) ` - * :ref:`smart_ptr_clone (dest: smart_ptr\& implicit; src: smart_ptr\ implicit) ` + * :ref:`move (dest: smart_ptr\& implicit; src: void? implicit) ` + * :ref:`move (dest: smart_ptr\& implicit; src: smart_ptr\& implicit) ` + * :ref:`move_new (dest: smart_ptr\& implicit; src: smart_ptr\ implicit) ` + * :ref:`smart_ptr_clone (dest: smart_ptr\& implicit; src: void? implicit) ` + * :ref:`smart_ptr_clone (dest: smart_ptr\& implicit; src: smart_ptr\ implicit) ` * :ref:`smart_ptr_is_valid (dest: smart_ptr\ implicit) : bool ` * :ref:`smart_ptr_use_count (ptr: smart_ptr\ implicit) : uint ` @@ -1926,6 +2084,7 @@ Smart ptr infrastructure Increments the reference count of the smart pointer `src` and returns a new smart_ptr that shares ownership of the same object. + :Arguments: * **src** : smart_ptr .. _function-builtin_get_const_ptr_smart_ptr_ls_autoTT_gr_: @@ -1934,6 +2093,7 @@ Increments the reference count of the smart pointer `src` and returns a new smar Extracts a constant raw pointer of type `TT?` from the given `smart_ptr`, without affecting reference counting. + :Arguments: * **src** : smart_ptr @@ -1946,6 +2106,7 @@ get_ptr Extracts a mutable raw pointer of type `TT?` from the given mutable `smart_ptr`, without affecting reference counting. + :Arguments: * **src** : smart_ptr! .. _function-builtin_get_ptr_smart_ptr_ls_autoTT_gr___eq__eq_const: @@ -1958,29 +2119,31 @@ Extracts a mutable raw pointer of type `TT?` from the given mutable `smart_ptr& implicit; src: void? implicit) Moves a raw pointer `src` into the smart pointer `dest`, nullifying the previous contents of `dest` and transferring ownership of `src`. -:Arguments: * **dest** : smart_ptr& implicit + +:Arguments: * **dest** : smart_ptr\ & implicit * **src** : void? implicit -.. _function-builtin_move_smart_ptr_ls_void_gr__implicit_smart_ptr_ls_void_gr__implicit: +.. _function-builtin_move_smart_ptr_ls_void_gr__ref__implicit_smart_ptr_ls_void_gr__ref__implicit: .. das:function:: move(dest: smart_ptr& implicit; src: smart_ptr& implicit) ---- -.. _function-builtin_move_new_smart_ptr_ls_void_gr__implicit_smart_ptr_ls_void_gr__implicit: +.. _function-builtin_move_new_smart_ptr_ls_void_gr__ref__implicit_smart_ptr_ls_void_gr__implicit: .. das:function:: move_new(dest: smart_ptr& implicit; src: smart_ptr implicit) Moves a newly constructed smart pointer value `src` into `dest`, used to initialize a `smart_ptr` from a `new` expression. -:Arguments: * **dest** : smart_ptr& implicit + +:Arguments: * **dest** : smart_ptr\ & implicit * **src** : smart_ptr implicit @@ -1988,17 +2151,18 @@ Moves a newly constructed smart pointer value `src` into `dest`, used to initial smart_ptr_clone ^^^^^^^^^^^^^^^ -.. _function-builtin_smart_ptr_clone_smart_ptr_ls_void_gr__implicit_void_q__implicit: +.. _function-builtin_smart_ptr_clone_smart_ptr_ls_void_gr__ref__implicit_void_q__implicit: .. das:function:: smart_ptr_clone(dest: smart_ptr& implicit; src: void? implicit) Clones a raw pointer `src` into smart pointer `dest`, incrementing the internal reference count to share ownership. -:Arguments: * **dest** : smart_ptr& implicit + +:Arguments: * **dest** : smart_ptr\ & implicit * **src** : void? implicit -.. _function-builtin_smart_ptr_clone_smart_ptr_ls_void_gr__implicit_smart_ptr_ls_void_gr__implicit: +.. _function-builtin_smart_ptr_clone_smart_ptr_ls_void_gr__ref__implicit_smart_ptr_ls_void_gr__implicit: .. das:function:: smart_ptr_clone(dest: smart_ptr& implicit; src: smart_ptr implicit) @@ -2010,6 +2174,7 @@ Clones a raw pointer `src` into smart pointer `dest`, incrementing the internal Checks whether the smart pointer `dest` holds a non-null reference to valid data, returning true if it does. + :Arguments: * **dest** : smart_ptr implicit .. _function-builtin_smart_ptr_use_count_smart_ptr_ls_void_gr__implicit: @@ -2018,8 +2183,10 @@ Checks whether the smart pointer `dest` holds a non-null reference to valid data Returns the current reference count of the object managed by `ptr`, indicating how many smart pointers share ownership. + :Arguments: * **ptr** : smart_ptr implicit + ++++++++++++++++++++ Macro infrastructure ++++++++++++++++++++ @@ -2037,18 +2204,21 @@ Macro infrastructure Returns `true` if the current context is in the process of being compiled, allowing compile-time logic to distinguish from runtime execution. + .. _function-builtin_is_compiling_macros: .. das:function:: is_compiling_macros() : bool Returns `true` if the current context is being compiled and the compiler is currently executing the macro pass. + .. _function-builtin_is_compiling_macros_in_module_string_implicit: .. das:function:: is_compiling_macros_in_module(name: string implicit) : bool Returns `true` if the current context is being compiled during the macro pass and the compiler is processing the module specified by `name`. + :Arguments: * **name** : string implicit .. _function-builtin_is_folding: @@ -2057,18 +2227,22 @@ Returns `true` if the current context is being compiled during the macro pass an Returns `true` if the compiler is currently performing its constant folding optimization pass. + .. _function-builtin_is_in_completion: .. das:function:: is_in_completion() : bool Returns `true` if the compiler is running in completion mode, generating lexical information for a text editor's code-completion system. + .. _function-builtin_is_reporting_compilation_errors: .. das:function:: is_reporting_compilation_errors() : bool Returns `true` if the context failed to compile and the inference pass is currently reporting compilation errors. + + ++++++++ Profiler ++++++++ @@ -2084,18 +2258,21 @@ Profiler Collects profiling information gathered by the built-in line profiler and returns it as a formatted string containing execution counts and timing data. + .. _function-builtin_dump_profile_info: .. das:function:: dump_profile_info() Prints the execution counts and timing data for all lines collected by the built-in line profiler to the standard output. + .. _function-builtin_profile_int_string_implicit_block_ls__c_void_gr_: .. das:function:: profile(count: int; category: string implicit; block: block<():void>) : float Executes `block` a total of `count` times under the given `category` label, prints the timing, and returns the minimum elapsed time in seconds across all iterations. + :Arguments: * **count** : int * **category** : string implicit @@ -2108,6 +2285,8 @@ Executes `block` a total of `count` times under the given `category` label, prin Resets all counters and accumulated data in the built-in profiler to zero. + + +++++++++++++++++++++ System infrastructure +++++++++++++++++++++ @@ -2134,18 +2313,21 @@ System infrastructure Checks whether ahead-of-time (AOT) compilation is enabled for the current program and returns true if it is. + .. _function-builtin_breakpoint: .. das:function:: breakpoint() Triggers a debugger breakpoint by calling `os_debugbreakpoint`, which is a link-time dependency expected to be provided by the host application or debugger tool. + .. _function-builtin_error_string_implicit: .. das:function:: error(text: string implicit) Outputs the string `text` to the context's error stream, similar to `print` but directed to the error output channel. + :Arguments: * **text** : string implicit .. _function-builtin_eval_main_loop_block_ls__c_void_gr_: @@ -2154,6 +2336,7 @@ Outputs the string `text` to the context's error stream, similar to `print` but Executes the application main loop by repeatedly invoking `block` until it returns `false`; on Emscripten targets, uses the platform-specific main loop mechanism instead. + :Arguments: * **block** : block implicit .. _function-builtin_get_das_root: @@ -2162,24 +2345,28 @@ Executes the application main loop by repeatedly invoking `block` until it retur Returns the file-system path to the daslang root directory, where `daslib` and other standard libraries are located. + .. _function-builtin_is_in_aot: .. das:function:: is_in_aot() : bool Returns `true` if the compiler is currently generating ahead-of-time (AOT) compiled code. + .. _function-builtin_is_intern_strings: .. das:function:: is_intern_strings() : bool Returns `true` if string interning is enabled in the current context, meaning identical strings share the same memory. + .. _function-builtin_panic_string_implicit: .. das:function:: panic(text: string implicit) will cause panic. The program will be terminated if there is no recover. Panic is not an error handling mechanism and can not be used as such. It is indeed panic, fatal error. It is not supposed that program can completely correctly recover from panic, recover construction is provided so program can try to correctly shut-down or report fatal error. If there is no recover within the script, it will be called in calling eval (in C++ callee code). + :Arguments: * **text** : string implicit .. _function-builtin_print_string_implicit: @@ -2188,6 +2375,7 @@ will cause panic. The program will be terminated if there is no recover. Panic i Outputs `text` to the current context's log, typically printing to standard output. + :Arguments: * **text** : string implicit .. _function-builtin_sprint_any_print_flags: @@ -2196,6 +2384,7 @@ Outputs `text` to the current context's log, typically printing to standard outp Converts `value` to its string representation using the specified `flags` to control formatting, and returns the result as a string. + :Arguments: * **value** : any * **flags** : :ref:`print_flags ` @@ -2206,6 +2395,7 @@ Converts `value` to its string representation using the specified `flags` to con Serializes `value` directly to a JSON string, bypassing intermediate representation for speed; set `humanReadable` to true for indented output. + :Arguments: * **value** : any * **humanReadable** : bool @@ -2216,6 +2406,7 @@ Serializes `value` directly to a JSON string, bypassing intermediate representat Prints the current call stack to the log; set `args` to include function arguments and `vars` to include local variable values in the output. + :Arguments: * **args** : bool * **vars** : bool @@ -2226,12 +2417,14 @@ Prints the current call stack to the log; set `args` to include function argumen Immediately terminates execution of the current daslang context. + .. _function-builtin_to_compiler_log_string_implicit: .. das:function:: to_compiler_log(text: string implicit) Outputs `text` to the compiler's log stream, typically used from within macro code during compilation. + :Arguments: * **text** : string implicit .. _function-builtin_to_log_int_string_implicit: @@ -2240,10 +2433,12 @@ Outputs `text` to the compiler's log stream, typically used from within macro co Outputs `text` to the logging infrastructure at the specified `level` (e.g. LOG_INFO, LOG_ERROR), rather than to standard output. + :Arguments: * **level** : int * **text** : string implicit + +++++++++++++++++++ Memory manipulation +++++++++++++++++++ @@ -2283,6 +2478,7 @@ hash Computes a 64-bit FNV-1a hash of the given `int8` value and returns it as `uint64`. + :Arguments: * **value** : int8 .. _function-builtin_hash_any: @@ -2349,6 +2545,7 @@ intptr Converts a `smart_ptr` `p` to its `uint64` integer representation, useful for pointer arithmetic or serialization. + :Arguments: * **p** : smart_ptr .. _function-builtin_intptr_void_q_: @@ -2367,9 +2564,10 @@ lock_data Locks a constant array and invokes `blk` with a read-only pointer `p` to the array's contiguous data and its size `s`, allowing direct memory-level read access. -:Arguments: * **a** : option!|array#!> - * **blk** : block<(p:TT?#;s:int):auto> +:Arguments: * **a** : option!\ | array\ #!> + + * **blk** : block<(p:TT?\ #;s:int):auto> .. _function-builtin_lock_data_array_ls_autoTT_gr___eq__eq_constarray_ls_autoTT_gr__hh___eq__eq_const_block_ls_var_p_c_TT_q__hh_;s_c_int_c_auto_gr_: @@ -2386,11 +2584,12 @@ Locks a constant array and invokes `blk` with a read-only pointer `p` to the arr Constructs a temporary mutable array of type `TT` over raw memory at `data` with `len` elements, and passes it to `blk` without copying the underlying data. + :Arguments: * **data** : void? * **len** : int - * **blk** : block<(arg:array#):auto> + * **blk** : block<(arg:array\ #):auto> .. _function-builtin_map_to_ro_array_void_q__int_block_ls_arg_c_array_ls_autoTT_gr__hh__c_auto_gr_: @@ -2401,11 +2600,12 @@ Constructs a temporary mutable array of type `TT` over raw memory at `data` with Constructs a temporary read-only array of type `TT` over raw memory at `data` with `len` elements, and passes it to `blk` without copying the underlying data. + :Arguments: * **data** : void? * **len** : int - * **blk** : block<(arg:array#):auto> + * **blk** : block<(arg:array\ #):auto> .. _function-builtin_memcmp_void_q__implicit_void_q__implicit_int: @@ -2416,6 +2616,7 @@ Constructs a temporary read-only array of type `TT` over raw memory at `data` wi Compares `size` bytes of memory at `left` and `right`, returning -1 if `left` is less, 1 if `left` is greater, or 0 if both regions are identical. + :Arguments: * **left** : void? implicit * **right** : void? implicit @@ -2431,6 +2632,7 @@ Compares `size` bytes of memory at `left` and `right`, returning -1 if `left` is Copies `size` bytes of memory from the address pointed to by `right` into the address pointed to by `left`. + :Arguments: * **left** : void? implicit * **right** : void? implicit @@ -2446,6 +2648,7 @@ Copies `size` bytes of memory from the address pointed to by `right` into the ad Overwrites the internal type discriminator of `variant` to `index`, changing which alternative the variant is considered to hold. + :Arguments: * **variant** : variant<> implicit * **index** : int @@ -2456,8 +2659,10 @@ Overwrites the internal type discriminator of `variant` to `index`, changing whi Returns the zero-based index indicating which alternative the variant currently holds. + :Arguments: * **arg0** : variant<> implicit + +++++++++++++++++ Binary serializer +++++++++++++++++ @@ -2471,6 +2676,7 @@ Binary serializer Deserializes `obj` from the binary representation stored in `data` (an array of uint8 bytes). Obsolete — use `daslib/archive` instead. + :Arguments: * **obj** : auto * **data** : array implicit @@ -2481,9 +2687,11 @@ Deserializes `obj` from the binary representation stored in `data` (an array of Serializes `obj` into a binary representation and passes the resulting uint8 byte array to the block `subexpr`. Obsolete — use `daslib/archive` instead. + :Arguments: * **obj** : auto - * **subexpr** : block<(data:array#):void> + * **subexpr** : block<(data:array\ #):void> + +++++++++++++++++++++ Path and command line @@ -2497,6 +2705,8 @@ Path and command line Returns an array of strings containing the command-line arguments passed to the program. + + +++++++++++++ Time and date +++++++++++++ @@ -2513,12 +2723,14 @@ Time and date Returns the current calendar time as a `clock` value representing the number of seconds since 00:00 UTC, January 1, 1970 (the Unix epoch). + .. _function-builtin_get_time_nsec_int64: .. das:function:: get_time_nsec(ref: int64) : int64 Computes the elapsed time in nanoseconds since the reference point `ref`, which is typically obtained from `ref_time_ticks`. + :Arguments: * **ref** : int64 .. _function-builtin_get_time_usec_int64: @@ -2527,6 +2739,7 @@ Computes the elapsed time in nanoseconds since the reference point `ref`, which Computes the elapsed time in microseconds since the reference point `ref`, which is typically obtained from `ref_time_ticks`. + :Arguments: * **ref** : int64 .. _function-builtin_mktime_int_int_int_int_int_int: @@ -2535,6 +2748,7 @@ Computes the elapsed time in microseconds since the reference point `ref`, which Converts the calendar date and time specified by `year`, `month`, `mday`, `hour`, `min`, and `sec` into a `clock` value representing time since epoch. + :Arguments: * **year** : int * **month** : int @@ -2553,6 +2767,8 @@ Converts the calendar date and time specified by `year`, `month`, `mday`, `hour` Captures the current high-resolution time in ticks, suitable for measuring elapsed intervals with `get_time_usec`. + + ++++++++++++++++ Platform queries ++++++++++++++++ @@ -2568,24 +2784,29 @@ Platform queries Checks whether the current build is configured as a DLL (dynamic library) build, which determines if daslib symbols are available for the JIT compiler. + .. _function-builtin_get_architecture_name: .. das:function:: get_architecture_name() : string Returns the name of the CPU architecture the program is running on, such as `"x86_64"`, `"x86"`, `"arm64"`, `"arm"`, `"wasm32"`, or `"unknown"`. + .. _function-builtin_get_context_share_counter: .. das:function:: get_context_share_counter() : uint64 Returns the use-count of the shared context, which is incremented each time a thread accesses it; useful for tracking concurrent context usage. + .. _function-builtin_get_platform_name: .. das:function:: get_platform_name() : string Returns the name of the operating system the program is running on, such as `"windows"`, `"linux"`, `"darwin"`, `"emscripten"`, or `"unknown"`. + + +++++++++++++++++ String formatting +++++++++++++++++ @@ -2611,6 +2832,7 @@ fmt Formats a `uint8` value as a string using the given `format` specifier (following libfmt / C++20 `std::format` syntax). + :Arguments: * **format** : string implicit * **value** : uint8 @@ -2653,19 +2875,22 @@ Formats a `uint8` value as a string using the given `format` specifier (followin ---- + ++++++++++++++++++++ Argument consumption ++++++++++++++++++++ - * :ref:`consume_argument (var a: auto(TT)&) : TT& ` + * :ref:`consume_argument (var a: auto(TT)&) : TT& ` -.. _function-builtin_consume_argument_autoTT_0x843: +.. _function-builtin_consume_argument_autoTT_ref__0x843: .. das:function:: consume_argument(a: auto(TT)&) : TT& Marks argument `a` as consumed, signaling to the compiler that it will not be used after this call, which enables move optimizations and avoids unnecessary clones. Equivalent to the `<-arg` syntax. -:Arguments: * **a** : auto(TT)& + +:Arguments: * **a** : auto(TT)\ & + +++++++++++++ Lock checking @@ -2681,6 +2906,7 @@ Lock checking Returns the current internal lock count for the given `array`, indicating how many active locks prevent it from being resized. + :Arguments: * **array** : array implicit .. _function-builtin_set_verify_array_locks_array_ls_anything_gr__bool: @@ -2692,6 +2918,7 @@ Returns the current internal lock count for the given `array`, indicating how ma Enables or disables runtime lock verification for the given `array`; when `check` is false, lock safety checks are skipped as a performance optimization. + :Arguments: * **array** : array implicit * **check** : bool @@ -2705,18 +2932,20 @@ Enables or disables runtime lock verification for the given `array`; when `check Enables or disables runtime lock verification for the given `table`; when `check` is false, lock safety checks are skipped as a performance optimization. + :Arguments: * **table** : table implicit * **check** : bool + +++++++++++++++++++++++ Lock checking internals +++++++++++++++++++++++ * :ref:`_at_with_lockcheck (var Tab: table\; at: keyT|keyT#) : valT& ` - * :ref:`_move_with_lockcheck (var a: auto(valA)&; var b: auto(valB)&) : auto ` - * :ref:`_return_with_lockcheck (var a: auto(valT)& ==const) : auto& ` - * :ref:`_return_with_lockcheck (a: auto(valT) const& ==const) : auto& ` + * :ref:`_move_with_lockcheck (var a: auto(valA)&; var b: auto(valB)&) : auto ` + * :ref:`_return_with_lockcheck (var a: auto(valT)& ==const) : auto& ` + * :ref:`_return_with_lockcheck (a: auto(valT) const& ==const) : auto& ` .. _function-builtin__at_with_lockcheck_table_ls_autokeyT,_autovalT_gr__keyTkeyT_hh_: @@ -2724,46 +2953,50 @@ Lock checking internals Looks up and returns a reference to the element at key `at` in the table `Tab`, while verifying that `Tab` and its lockable sub-elements are not locked. + :Arguments: * **Tab** : table - * **at** : option + * **at** : option -.. _function-builtin__move_with_lockcheck_autovalA_autovalB_0x20: +.. _function-builtin__move_with_lockcheck_autovalA_ref__autovalB_ref__0x20: .. das:function:: _move_with_lockcheck(a: auto(valA)&; b: auto(valB)&) : auto Moves the contents of `b` into `a`, verifying that neither `a` nor `b` (nor any of their lockable sub-elements) is currently locked. -:Arguments: * **a** : auto(valA)& - * **b** : auto(valB)& +:Arguments: * **a** : auto(valA)\ & + + * **b** : auto(valB)\ & _return_with_lockcheck ^^^^^^^^^^^^^^^^^^^^^^ -.. _function-builtin__return_with_lockcheck__autovalT__eq__eq_const_0x32: +.. _function-builtin__return_with_lockcheck__autovalT_ref___eq__eq_const_0x32: .. das:function:: _return_with_lockcheck(a: auto(valT)& ==const) : auto& Passes through and returns a mutable reference to `a`, verifying that `a` and all of its lockable sub-elements are not currently locked. -:Arguments: * **a** : auto(valT)&! -.. _function-builtin__return_with_lockcheck_autovalT_const__eq__eq_const_0x3b: +:Arguments: * **a** : auto(valT)\ &! + +.. _function-builtin__return_with_lockcheck_autovalT_const_ref___eq__eq_const_0x3b: .. das:function:: _return_with_lockcheck(a: auto(valT) const& ==const) : auto& ---- + ++++++++++++++ Bit operations ++++++++++++++ - * :ref:`__bit_set (value: bitfield& implicit; mask: bitfield; on: bool) ` - * :ref:`__bit_set (value: bitfield8:uint8\<\>& implicit; mask: bitfield8:uint8\<\>; on: bool) ` - * :ref:`__bit_set (value: bitfield64:uint64\<\>& implicit; mask: bitfield64:uint64\<\>; on: bool) ` - * :ref:`__bit_set (value: bitfield16:uint16\<\>& implicit; mask: bitfield16:uint16\<\>; on: bool) ` + * :ref:`__bit_set (value: bitfield& implicit; mask: bitfield; on: bool) ` + * :ref:`__bit_set (value: bitfield8:uint8\<\>& implicit; mask: bitfield8:uint8\<\>; on: bool) ` + * :ref:`__bit_set (value: bitfield64:uint64\<\>& implicit; mask: bitfield64:uint64\<\>; on: bool) ` + * :ref:`__bit_set (value: bitfield16:uint16\<\>& implicit; mask: bitfield16:uint16\<\>; on: bool) ` * :ref:`clz (bits: uint64) : uint64 ` * :ref:`clz (bits: uint) : uint ` * :ref:`ctz (bits: uint64) : uint64 ` @@ -2776,27 +3009,28 @@ Bit operations __bit_set ^^^^^^^^^ -.. _function-builtin___bit_set_bitfield_implicit_bitfield_bool: +.. _function-builtin___bit_set_bitfield_ref__implicit_bitfield_bool: .. das:function:: __bit_set(value: bitfield& implicit; mask: bitfield; on: bool) Sets or clears the bits specified by `mask` in the bitfield `value`, turning them on if `on` is true or off if `on` is false. -:Arguments: * **value** : bitfield<>& implicit + +:Arguments: * **value** : bitfield<>\ & implicit * **mask** : bitfield<> * **on** : bool -.. _function-builtin___bit_set_bitfield8_c_uint8_ls__gr__implicit_bitfield8_c_uint8_ls__gr__bool: +.. _function-builtin___bit_set_bitfield8_c_uint8_ls__gr__ref__implicit_bitfield8_c_uint8_ls__gr__bool: .. das:function:: __bit_set(value: bitfield8:uint8<>& implicit; mask: bitfield8:uint8<>; on: bool) -.. _function-builtin___bit_set_bitfield64_c_uint64_ls__gr__implicit_bitfield64_c_uint64_ls__gr__bool: +.. _function-builtin___bit_set_bitfield64_c_uint64_ls__gr__ref__implicit_bitfield64_c_uint64_ls__gr__bool: .. das:function:: __bit_set(value: bitfield64:uint64<>& implicit; mask: bitfield64:uint64<>; on: bool) -.. _function-builtin___bit_set_bitfield16_c_uint16_ls__gr__implicit_bitfield16_c_uint16_ls__gr__bool: +.. _function-builtin___bit_set_bitfield16_c_uint16_ls__gr__ref__implicit_bitfield16_c_uint16_ls__gr__bool: .. das:function:: __bit_set(value: bitfield16:uint16<>& implicit; mask: bitfield16:uint16<>; on: bool) @@ -2812,6 +3046,7 @@ clz Counts the number of leading zero bits in the 64-bit unsigned integer `bits`, returning 64 if the value is zero. + :Arguments: * **bits** : uint64 .. _function-builtin_clz_uint: @@ -2830,6 +3065,7 @@ ctz Counts the number of trailing zero bits in the 64-bit unsigned integer `bits`, returning 64 if the value is zero. + :Arguments: * **bits** : uint64 .. _function-builtin_ctz_uint: @@ -2844,6 +3080,7 @@ Counts the number of trailing zero bits in the 64-bit unsigned integer `bits`, r Multiplies two 64-bit unsigned integers `a` and `b`, returning the full 128-bit result as a `urange64` containing the low and high 64-bit halves. + :Arguments: * **a** : uint64 * **b** : uint64 @@ -2858,6 +3095,7 @@ popcnt Counts and returns the number of set (1) bits in the 64-bit unsigned integer `bits`. + :Arguments: * **bits** : uint64 .. _function-builtin_popcnt_uint: @@ -2866,6 +3104,7 @@ Counts and returns the number of set (1) bits in the 64-bit unsigned integer `bi ---- + +++++++++ Intervals +++++++++ @@ -2885,6 +3124,7 @@ interval Constructs a `urange` value from the two `uint` endpoints `arg0` (inclusive) and `arg1` (exclusive). + :Arguments: * **arg0** : uint * **arg1** : uint @@ -2903,6 +3143,7 @@ Constructs a `urange` value from the two `uint` endpoints `arg0` (inclusive) and ---- + ++++ RTTI ++++ @@ -2915,8 +3156,10 @@ RTTI Examines the RTTI (runtime type information) associated with the class at `ptr` and returns the size in bytes of its TypeInfo structure. + :Arguments: * **ptr** : void? implicit + +++++++++++++++++ Lock verification +++++++++++++++++ @@ -2932,8 +3175,10 @@ Lock verification Enables or disables runtime lock verification for all arrays and tables in the current context; returns the previous verification state. + :Arguments: * **check** : bool + +++++++++++++++++++++++++++++++ Initialization and finalization +++++++++++++++++++++++++++++++ @@ -2946,15 +3191,17 @@ Initialization and finalization Creates a temporary `das_string` and passes it to the block, automatically managing its lifetime for the duration of the call. + :Arguments: * **arg0** : block<( :ref:`das_string `):void> implicit + ++++++++++ Algorithms ++++++++++ * :ref:`count (start: int = 0; step: int = 1) : iterator\ ` * :ref:`iter_range (foo: auto) : auto ` - * :ref:`swap (var a: auto(TT)&; var b: auto(TT)&) : auto ` + * :ref:`swap (var a: auto(TT)&; var b: auto(TT)&) : auto ` * :ref:`ucount (start: uint = 0x0; step: uint = 0x1) : iterator\ ` .. _function-builtin_count_int_int: @@ -2963,6 +3210,7 @@ Algorithms Creates an infinite iterator that yields integer values starting from `start` and incrementing by `step` on each iteration, intended for use as a counter alongside other sequences in a `for` loop. + :Arguments: * **start** : int * **step** : int @@ -2973,17 +3221,19 @@ Creates an infinite iterator that yields integer values starting from `start` an Creates a `range` from `0` to the length of the given iterable `foo`, useful for index-based iteration over containers. + :Arguments: * **foo** : auto -.. _function-builtin_swap_autoTT_autoTT_0x7a9: +.. _function-builtin_swap_autoTT_ref__autoTT_ref__0x7a9: .. das:function:: swap(a: auto(TT)&; b: auto(TT)&) : auto Exchanges the values of `a` and `b` in place, leaving each variable holding the other's former value. -:Arguments: * **a** : auto(TT)& - * **b** : auto(TT)& +:Arguments: * **a** : auto(TT)\ & + + * **b** : auto(TT)\ & .. _function-builtin_ucount_uint_uint: @@ -2991,10 +3241,12 @@ Exchanges the values of `a` and `b` in place, leaving each variable holding the Creates an infinite iterator over unsigned integers beginning at `start` and incrementing by `step` on each iteration. + :Arguments: * **start** : uint * **step** : uint + ++++++ Memset ++++++ @@ -3014,6 +3266,7 @@ Memset Fills memory at `left` with `count` copies of the 128-bit `uint4` vector `value`. + :Arguments: * **left** : void? implicit * **value** : uint4 @@ -3029,6 +3282,7 @@ Fills memory at `left` with `count` copies of the 128-bit `uint4` vector `value` Fills memory at `left` with `count` copies of the 16-bit `value`. + :Arguments: * **left** : void? implicit * **value** : uint16 @@ -3044,6 +3298,7 @@ Fills memory at `left` with `count` copies of the 16-bit `value`. Fills memory at `left` with `count` copies of the 32-bit `value`. + :Arguments: * **left** : void? implicit * **value** : uint @@ -3059,6 +3314,7 @@ Fills memory at `left` with `count` copies of the 32-bit `value`. Fills memory at `left` with `count` copies of the 64-bit `value`. + :Arguments: * **left** : void? implicit * **value** : uint64 @@ -3074,12 +3330,14 @@ Fills memory at `left` with `count` copies of the 64-bit `value`. Fills memory at `left` with `count` copies of the 8-bit `value`, equivalent to the C `memset` function. + :Arguments: * **left** : void? implicit * **value** : uint8 * **count** : int + ++++++ Malloc ++++++ @@ -3097,6 +3355,7 @@ Malloc Frees memory previously allocated with `malloc`, following C-style manual memory management semantics. + :Arguments: * **ptr** : void? implicit .. _function-builtin_malloc_uint64: @@ -3108,6 +3367,7 @@ Frees memory previously allocated with `malloc`, following C-style manual memory Allocates a block of uninitialized memory of the specified `size` in bytes, C-style, and returns a raw pointer to it; must be freed with `free`. + :Arguments: * **size** : uint64 .. _function-builtin_malloc_usable_size_void_q__implicit: @@ -3119,8 +3379,10 @@ Allocates a block of uninitialized memory of the specified `size` in bytes, C-st Returns the usable size in bytes of the memory block pointed to by `ptr`, as reported by the underlying allocator. + :Arguments: * **ptr** : void? implicit + +++++++++++++++++++ Compilation and AOT +++++++++++++++++++ @@ -3136,18 +3398,21 @@ Compilation and AOT Returns the file name of the source file currently being compiled, useful for compile-time metaprogramming and diagnostics. + .. _function-builtin_compiling_module_name: .. das:function:: compiling_module_name() : string Returns the name of the module currently being compiled, useful for compile-time metaprogramming and diagnostics. + .. _function-builtin_reset_aot: .. das:function:: reset_aot() Notifies the compiler that ahead-of-time code generation has finished, restoring normal compilation mode. + .. _function-builtin_set_aot: .. das:function:: set_aot() @@ -3155,3 +3420,4 @@ Notifies the compiler that ahead-of-time code generation has finished, restoring Notifies the compiler that ahead-of-time code generation is now in progress. + diff --git a/doc/source/stdlib/class_boost.rst b/doc/source/stdlib/class_boost.rst index 9411123ab0..9dca859ffd 100644 --- a/doc/source/stdlib/class_boost.rst +++ b/doc/source/stdlib/class_boost.rst @@ -5,6 +5,8 @@ Class method macros =================== +.. das:module:: class_boost + The CLASS_BOOST module provides macros for extending class functionality, including the ``[serialize_as_class]`` annotation for automatic serialization and common class patterns like abstract method enforcement. @@ -13,6 +15,8 @@ All functions and symbols are in "class_boost" module, use require to get access require daslib/class_boost + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -25,6 +29,7 @@ Turns a static method into a class method by adding a ``self`` argument of the class type as the first argument, and wrapping the function body in ``with (self) { ... }``. Applied via ``[class_method]`` annotation. + .. _handle-class_boost-explicit_const_class_method: .. das:attribute:: explicit_const_class_method @@ -33,3 +38,4 @@ Same as ``[class_method]`` but marks the ``self`` parameter with ``explicitConst allowing overloading of const and non-const class methods. + diff --git a/doc/source/stdlib/constexpr.rst b/doc/source/stdlib/constexpr.rst index ed5857a527..2737b4fdf8 100644 --- a/doc/source/stdlib/constexpr.rst +++ b/doc/source/stdlib/constexpr.rst @@ -5,6 +5,8 @@ Constant expression checker and substitution ============================================ +.. das:module:: constant_expression + The CONSTANT_EXPRESSION module provides the ``[constant_expression]`` function annotation. Functions marked with this annotation are evaluated at compile time when all arguments are constants, replacing the call with the computed @@ -14,6 +16,8 @@ All functions and symbols are in "constant_expression" module, use require to ge require daslib/constant_expression + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -33,6 +37,7 @@ This macro implements a constexpr function argument checker. Given list of argum foo("blah", 1) foo("ouch", BOO) // compilation error: `a is not a constexpr, BOO` + .. _handle-constant_expression-constant_expression: .. das:attribute:: constant_expression @@ -48,6 +53,8 @@ For example:: print("constant string is = {constString}\n") // note - constString here is not an argument + + +++++++++++++ Macro helpers +++++++++++++ @@ -60,6 +67,7 @@ Macro helpers This macro function returns true if the expression is a constant expression + :Arguments: * **expr** : :ref:`ExpressionPtr ` diff --git a/doc/source/stdlib/consume.rst b/doc/source/stdlib/consume.rst index 6929fd6ed9..27c6ddf35c 100644 --- a/doc/source/stdlib/consume.rst +++ b/doc/source/stdlib/consume.rst @@ -5,6 +5,8 @@ Consume argument optimization ============================= +.. das:module:: consume + The CONSUME module implements the ``consume`` pattern, which moves ownership of containers and other moveable values while leaving the source in a default-constructed state. This enables efficient ownership transfer. @@ -13,6 +15,8 @@ All functions and symbols are in "consume" module, use require to get access to require daslib/consume + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -25,3 +29,4 @@ This annotation ensures that all arguments to the function are passed as moved v For example [consume(a,b)] ensures that both a and b are passed as moved values. + diff --git a/doc/source/stdlib/contracts.rst b/doc/source/stdlib/contracts.rst index 45bbebb9df..fd526160db 100644 --- a/doc/source/stdlib/contracts.rst +++ b/doc/source/stdlib/contracts.rst @@ -5,6 +5,8 @@ Miscellaneous contract annotations ================================== +.. das:module:: contracts + The CONTRACTS module provides compile-time type constraints for generic function arguments. Annotations like ``[expect_any_array]``, ``[expect_any_enum]``, ``[expect_any_numeric]``, and ``[expect_any_struct]`` restrict which types @@ -40,6 +42,8 @@ Example: :: // scalar // array + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -50,36 +54,42 @@ Function annotations [expect_any_array(argname)] contract, which only accepts array, T[], or das`vector + .. _handle-contracts-expect_any_enum: .. das:attribute:: expect_any_enum [expect_any_enum(argname)] contract, which only accepts enumerations + .. _handle-contracts-expect_any_bitfield: .. das:attribute:: expect_any_bitfield [expect_any_bitfield(argname)] contract, which only accepts bitfields + .. _handle-contracts-expect_any_vector_type: .. das:attribute:: expect_any_vector_type [expect_any_vector_type(argname)] contract, which only accepts vector types, i.e. int2, float3, range, etc + .. _handle-contracts-expect_any_struct: .. das:attribute:: expect_any_struct [expect_any_struct(argname)] contract, which only accepts structs (but not classes) + .. _handle-contracts-expect_any_numeric: .. das:attribute:: expect_any_numeric [expect_any_numeric(argname)] contract, which only accepts numeric types (int, float, etc) + .. _handle-contracts-expect_any_workhorse: .. das:attribute:: expect_any_workhorse @@ -87,60 +97,71 @@ Function annotations [expect_any_workhorse(argname)] contract, which only accepts workhorse types (int, float, etc) Workhorse types are: bool,int*,uint*,float*,double,range and urange, range64 and urange64, string,enumeration,and non-smart pointers + .. _handle-contracts-expect_any_workhorse_raw: .. das:attribute:: expect_any_workhorse_raw [expect_any_workhorse_raw(argname)] contract, which only accepts workhorse types which are raw (not pointer or bool) + .. _handle-contracts-expect_any_tuple: .. das:attribute:: expect_any_tuple [expect_any_tuple(argname)] contract, which only accepts tuples + .. _handle-contracts-expect_any_variant: .. das:attribute:: expect_any_variant [expect_any_variant(argname)] contract, which only accepts variants + .. _handle-contracts-expect_any_function: .. das:attribute:: expect_any_function [expect_any_function(argname)] contract, which only accepts functions + .. _handle-contracts-expect_any_lambda: .. das:attribute:: expect_any_lambda [expect_any_lambda(argname)] contract, which only accepts lambdas + .. _handle-contracts-expect_ref: .. das:attribute:: expect_ref [expect_ref(argname)] contract, which only accepts references + .. _handle-contracts-expect_pointer: .. das:attribute:: expect_pointer [expect_pointer(argname)] contract, which only accepts pointers + .. _handle-contracts-expect_class: .. das:attribute:: expect_class [expect_class(argname)] contract, which only accepts class instances + .. _handle-contracts-expect_value_handle: .. das:attribute:: expect_value_handle [expect_value_handle(argname)] contract, which only accepts value handles + + ++++++++++++ Type queries ++++++++++++ @@ -153,6 +174,7 @@ Type queries returns true if the given type declaration is a das::vector template bound on C++ side + :Arguments: * **td** : :ref:`TypeDeclPtr ` diff --git a/doc/source/stdlib/coroutines.rst b/doc/source/stdlib/coroutines.rst index 97831ec6a0..b18609a3e5 100644 --- a/doc/source/stdlib/coroutines.rst +++ b/doc/source/stdlib/coroutines.rst @@ -5,6 +5,8 @@ Coroutines and additional generator support =========================================== +.. das:module:: coroutines + The COROUTINES module provides coroutine infrastructure including the ``[coroutine]`` function annotation, ``yield_from`` for delegating to sub-coroutines, and ``co_await`` for composing asynchronous generators. @@ -48,6 +50,8 @@ Example: :: // output: // 0 1 1 2 3 5 8 13 21 34 + + ++++++++++++ Type aliases ++++++++++++ @@ -58,12 +62,15 @@ Type aliases A coroutine is a generator that yields bool to indicate if it is still running. + .. _alias-Coroutines: .. das:attribute:: Coroutines = array> An array of coroutines. + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -78,6 +85,8 @@ which can be resumed and suspended. The function is converted into a generator. Generator yields bool if its a void coroutine, and yields the return type otherwise. If return type is specified coroutine can serve as an advanced form of a generator. + + +++++++++++ Call macros +++++++++++ @@ -90,6 +99,7 @@ This macro converts co_continue to yield true. The idea is that coroutine without specified type is underneath a coroutine which yields bool. That way co_continue() does not distract from the fact that it is a generator. + .. _call-macro-coroutines-co_await: .. das:attribute:: co_await @@ -101,6 +111,7 @@ This macro converts co_await(sub_coroutine) into:: The idea is that coroutine or generator can wait for a sub-coroutine to finish. + .. _call-macro-coroutines-yeild_from: .. das:attribute:: yeild_from @@ -112,6 +123,8 @@ This macro converts yield_from(THAT) expression into:: The idea is that coroutine or generator can continuously yield from another sub-coroutine or generator. + + ++++++++++++++++++++++++++++++ Top level coroutine evaluation ++++++++++++++++++++++++++++++ @@ -125,6 +138,7 @@ Top level coroutine evaluation This function runs coroutine until it is finished. + :Arguments: * **a** : :ref:`Coroutine ` .. _function-coroutines_cr_run_all_Coroutines: @@ -133,6 +147,7 @@ This function runs coroutine until it is finished. This function runs all coroutines until they are finished. + :Arguments: * **a** : :ref:`Coroutines ` diff --git a/doc/source/stdlib/cpp_bind.rst b/doc/source/stdlib/cpp_bind.rst index 23df97932d..2db8379f60 100644 --- a/doc/source/stdlib/cpp_bind.rst +++ b/doc/source/stdlib/cpp_bind.rst @@ -5,6 +5,8 @@ C++ bindings generator ====================== +.. das:module:: cpp_bind + The CPP_BIND module provides utilities for generating daslang bindings to C++ code. It helps generate module registration code, type annotations, and function wrappers for exposing C++ APIs to daslang programs. @@ -13,6 +15,8 @@ All functions and symbols are in "cpp_bind" module, use require to get access to require daslib/cpp_bind + + ++++++++++++++++++++++ Generation of bindings ++++++++++++++++++++++ @@ -28,6 +32,7 @@ Intended use:: log_cpp_class_adapter(cppFileNameDotInc, "daslangClassName", typeinfo(ast_typedecl type)) + :Arguments: * **cpp_file** : :ref:`file ` * **name** : string diff --git a/doc/source/stdlib/cuckoo_hash_table.rst b/doc/source/stdlib/cuckoo_hash_table.rst index c99835b39e..fd178d07a1 100644 --- a/doc/source/stdlib/cuckoo_hash_table.rst +++ b/doc/source/stdlib/cuckoo_hash_table.rst @@ -5,6 +5,8 @@ Cuckoo hash table ================= +.. das:module:: cuckoo_hash_table + The CUCKOO_HASH_TABLE module implements a cuckoo hash table data structure. Cuckoo hashing provides worst-case O(1) lookup time by using multiple hash functions and displacing existing entries on collision. @@ -13,6 +15,8 @@ All functions and symbols are in "cuckoo_hash_table" module, use require to get require daslib/cuckoo_hash_table + + +++++++++++ Type macros +++++++++++ @@ -27,6 +31,7 @@ Type macros * **hashFunction1Name** (String = "hash_extra") + ++++++++++++++ Hash functions ++++++++++++++ @@ -40,6 +45,7 @@ Hash functions this hash function converts and workhorse key to a 64 bit hash + :Arguments: * **data** : auto .. _function-cuckoo_hash_table_hash_extra_auto_0x1d: @@ -48,6 +54,7 @@ this hash function converts and workhorse key to a 64 bit hash Returns a secondary hash derived from the upper 32 bits of the primary hash, used for cuckoo hashing. + :Arguments: * **data** : auto diff --git a/doc/source/stdlib/dap.rst b/doc/source/stdlib/dap.rst index b207173550..11ed909259 100644 --- a/doc/source/stdlib/dap.rst +++ b/doc/source/stdlib/dap.rst @@ -5,6 +5,8 @@ Debug Adapter Protocol data structures ====================================== +.. das:module:: dap + The DAP module implements the Debug Adapter Protocol (DAP) for integrating daslang with external debuggers. It provides the message types, serialization, and communication infrastructure needed for IDE debugging support. @@ -13,6 +15,8 @@ All functions and symbols are in "dap" module, use require to get access to it. require daslib/dap + + ++++++++++ Structures ++++++++++ @@ -24,6 +28,7 @@ Structures Arguments for the DAP initialize request. + .. _struct-dap-DisconnectArguments: .. das:attribute:: DisconnectArguments @@ -37,6 +42,7 @@ Arguments for the DAP disconnect request. * **suspendDebuggee** : bool - Whether to suspend the debuggee when disconnecting. + .. _struct-dap-Capabilities: .. das:attribute:: Capabilities @@ -60,6 +66,7 @@ Debugger capabilities reported in the initialize response. * **supportsDataBreakpoints** : bool - Whether the adapter supports data breakpoints. + .. _struct-dap-DataBreakpoint: .. das:attribute:: DataBreakpoint @@ -79,6 +86,7 @@ A data breakpoint that triggers on memory access. * **enabled** : bool - Whether the breakpoint is enabled. + .. _struct-dap-SetDataBreakpointsArguments: .. das:attribute:: SetDataBreakpointsArguments @@ -88,6 +96,7 @@ Arguments for the setDataBreakpoints request. :Fields: * **breakpoints** : array< :ref:`DataBreakpoint `> - Array of data breakpoints to set. + .. _struct-dap-DataBreakpointInfoArguments: .. das:attribute:: DataBreakpointInfoArguments @@ -99,6 +108,7 @@ Arguments for the dataBreakpointInfo request. * **name** : string - Name of the variable. + .. _struct-dap-DataBreakpointInfoResponse: .. das:attribute:: DataBreakpointInfoResponse @@ -110,6 +120,7 @@ Response body for the dataBreakpointInfo request. * **description** : string - Human-readable description of the data. + .. _struct-dap-SourceBreakpoint: .. das:attribute:: SourceBreakpoint @@ -119,6 +130,7 @@ A breakpoint specified by source location line number. :Fields: * **line** : double - Line number of the breakpoint. + .. _struct-dap-Source: .. das:attribute:: Source @@ -130,6 +142,7 @@ A source file descriptor with name and path. * **path** : string - Full file-system path of the source. + .. _struct-dap-SetBreakpointsArguments: .. das:attribute:: SetBreakpointsArguments @@ -143,6 +156,7 @@ Arguments for the setBreakpoints request. * **sourceModified** : bool - Whether the source has been modified since last build. + .. _struct-dap-Breakpoint: .. das:attribute:: Breakpoint @@ -160,6 +174,7 @@ A breakpoint with verification status and location. * **message** : string - Optional message about the breakpoint state. + .. _struct-dap-SetBreakpointsResponse: .. das:attribute:: SetBreakpointsResponse @@ -169,6 +184,7 @@ Response body for the setBreakpoints request. :Fields: * **breakpoints** : array< :ref:`Breakpoint `> - Array of breakpoints with their verification status. + .. _struct-dap-Thread: .. das:attribute:: Thread @@ -180,6 +196,7 @@ A thread with an identifier and name. * **name** : string - Human-readable name of the thread. + .. _struct-dap-ThreadsResponseBody: .. das:attribute:: ThreadsResponseBody @@ -189,6 +206,7 @@ Response body for the threads request. :Fields: * **threads** : array< :ref:`Thread `> - Array of threads. + .. _struct-dap-StackTraceArguments: .. das:attribute:: StackTraceArguments @@ -202,6 +220,7 @@ Arguments for the stackTrace request. * **levels** : double - Maximum number of frames to return. + .. _struct-dap-StackFrame: .. das:attribute:: StackFrame @@ -219,6 +238,7 @@ A stack frame with source location and identifier. * **column** : double - Column number in the source file. + .. _struct-dap-StackTraceResponseBody: .. das:attribute:: StackTraceResponseBody @@ -230,6 +250,7 @@ Response body for the stackTrace request. * **totalFrames** : double - Total number of frames available. + .. _struct-dap-ScopesArguments: .. das:attribute:: ScopesArguments @@ -239,6 +260,7 @@ Arguments for the scopes request. :Fields: * **frameId** : double - Stack frame for which to retrieve scopes. + .. _struct-dap-Scope: .. das:attribute:: Scope @@ -250,6 +272,7 @@ A named variable scope with a variables reference. * **variablesReference** : double - Reference used to retrieve the variables of this scope. + .. _struct-dap-ScopesResponseBody: .. das:attribute:: ScopesResponseBody @@ -259,6 +282,7 @@ Response body for the scopes request. :Fields: * **scopes** : array< :ref:`Scope `> - Array of scopes for the given frame. + .. _struct-dap-VariablesArguments: .. das:attribute:: VariablesArguments @@ -272,6 +296,7 @@ Arguments for the variables request. * **count** : double - Number of variables to return (for paging). + .. _struct-dap-Variable: .. das:attribute:: Variable @@ -289,6 +314,7 @@ A variable with name, value, and type information. * **indexedVariables** : double - Number of indexed child variables. + .. _struct-dap-VariablesResponseBody: .. das:attribute:: VariablesResponseBody @@ -298,6 +324,7 @@ Response body for the variables request. :Fields: * **variables** : array< :ref:`Variable `> - Array of variables. + .. _struct-dap-OutputEventBody: .. das:attribute:: OutputEventBody @@ -309,6 +336,7 @@ Body of the output event for debugger console messages. * **output** : string - The output text. + .. _struct-dap-ContinueArguments: .. das:attribute:: ContinueArguments @@ -318,6 +346,7 @@ Arguments for the continue request. :Fields: * **threadId** : double - Thread to continue. + .. _struct-dap-PauseArguments: .. das:attribute:: PauseArguments @@ -327,6 +356,7 @@ Arguments for the pause request. :Fields: * **threadId** : double - Thread to pause. + .. _struct-dap-StepInArguments: .. das:attribute:: StepInArguments @@ -336,6 +366,7 @@ Arguments for the stepIn request. :Fields: * **threadId** : double - Thread to step into. + .. _struct-dap-NextArguments: .. das:attribute:: NextArguments @@ -345,6 +376,7 @@ Arguments for the next (step over) request. :Fields: * **threadId** : double - Thread to step over. + .. _struct-dap-StepOutArguments: .. das:attribute:: StepOutArguments @@ -354,6 +386,7 @@ Arguments for the stepOut request. :Fields: * **threadId** : double - Thread to step out of. + .. _struct-dap-EvaluateArguments: .. das:attribute:: EvaluateArguments @@ -367,6 +400,7 @@ Arguments for the evaluate request. * **context** : string - Context in which the expression is evaluated (e.g. watch, repl, hover). + .. _struct-dap-EvaluateResponse: .. das:attribute:: EvaluateResponse @@ -382,6 +416,7 @@ Response body for the evaluate request. * **indexedVariables** : double - Number of indexed child variables in the result. + .. _struct-dap-BreakpointEvent: .. das:attribute:: BreakpointEvent @@ -393,6 +428,7 @@ Event body indicating a breakpoint status change. * **breakpoint** : :ref:`Breakpoint ` - The breakpoint whose status changed. + .. _struct-dap-ThreadEvent: .. das:attribute:: ThreadEvent @@ -404,6 +440,8 @@ Event body indicating a thread started or exited. * **threadId** : double - Thread identifier. + + ++++++++++++++++++++ JSON deserialization ++++++++++++++++++++ @@ -432,6 +470,7 @@ JSON deserialization Constructs a ContinueArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_DataBreakpoint_JsonValue_q_: @@ -440,6 +479,7 @@ Constructs a ContinueArguments from a JSON value. Constructs a DataBreakpoint from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_DataBreakpointInfoArguments_JsonValue_q_: @@ -448,6 +488,7 @@ Constructs a DataBreakpoint from a JSON value. Constructs a DataBreakpointInfoArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_DisconnectArguments_JsonValue_q_: @@ -456,6 +497,7 @@ Constructs a DataBreakpointInfoArguments from a JSON value. Constructs a DisconnectArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_EvaluateArguments_JsonValue_q_: @@ -464,6 +506,7 @@ Constructs a DisconnectArguments from a JSON value. Constructs an EvaluateArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_InitializeRequestArguments_JsonValue_q_: @@ -472,6 +515,7 @@ Constructs an EvaluateArguments from a JSON value. Constructs an InitializeRequestArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_NextArguments_JsonValue_q_: @@ -480,6 +524,7 @@ Constructs an InitializeRequestArguments from a JSON value. Constructs a NextArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_PauseArguments_JsonValue_q_: @@ -488,6 +533,7 @@ Constructs a NextArguments from a JSON value. Constructs a PauseArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_ScopesArguments_JsonValue_q_: @@ -496,6 +542,7 @@ Constructs a PauseArguments from a JSON value. Constructs a ScopesArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_SetBreakpointsArguments_JsonValue_q_: @@ -504,6 +551,7 @@ Constructs a ScopesArguments from a JSON value. Constructs a SetBreakpointsArguments from a JSON value, parsing source and breakpoints. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_SetDataBreakpointsArguments_JsonValue_q_: @@ -512,6 +560,7 @@ Constructs a SetBreakpointsArguments from a JSON value, parsing source and break Constructs a SetDataBreakpointsArguments from a JSON value, parsing the breakpoints array. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_Source_JsonValue_q_: @@ -520,6 +569,7 @@ Constructs a SetDataBreakpointsArguments from a JSON value, parsing the breakpoi Constructs a Source from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_SourceBreakpoint_JsonValue_q_: @@ -528,6 +578,7 @@ Constructs a Source from a JSON value. Constructs a SourceBreakpoint from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_StackTraceArguments_JsonValue_q_: @@ -536,6 +587,7 @@ Constructs a SourceBreakpoint from a JSON value. Constructs a StackTraceArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_StepInArguments_JsonValue_q_: @@ -544,6 +596,7 @@ Constructs a StackTraceArguments from a JSON value. Constructs a StepInArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_StepOutArguments_JsonValue_q_: @@ -552,6 +605,7 @@ Constructs a StepInArguments from a JSON value. Constructs a StepOutArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? .. _function-dap_VariablesArguments_JsonValue_q_: @@ -560,8 +614,10 @@ Constructs a StepOutArguments from a JSON value. Constructs a VariablesArguments from a JSON value. + :Arguments: * **data** : :ref:`JsonValue `? + ++++++++++++++++++ JSON serialization ++++++++++++++++++ @@ -579,6 +635,7 @@ JV Converts an EvaluateResponse struct to its DAP JSON representation. + :Arguments: * **data** : :ref:`EvaluateResponse ` .. _function-dap_JV_Variable: @@ -587,6 +644,7 @@ Converts an EvaluateResponse struct to its DAP JSON representation. ---- + ++++++++++++++++++++ JSON field accessors ++++++++++++++++++++ @@ -603,6 +661,7 @@ JSON field accessors Returns the string value of a JSON value, or `defVal` if not a string. + :Arguments: * **val** : :ref:`JsonValue `? * **defVal** : string @@ -613,6 +672,7 @@ Returns the string value of a JSON value, or `defVal` if not a string. Returns a boolean JSON field by name, or `defVal` if not found. + :Arguments: * **val** : :ref:`JsonValue `? * **id** : string @@ -625,6 +685,7 @@ Returns a boolean JSON field by name, or `defVal` if not found. Returns a nested JSON object field by name, or null if not found. + :Arguments: * **val** : :ref:`JsonValue `? * **id** : string @@ -635,6 +696,7 @@ Returns a nested JSON object field by name, or null if not found. Returns a numeric JSON field by name, or `defVal` if not found. + :Arguments: * **val** : :ref:`JsonValue `? * **id** : string @@ -647,6 +709,7 @@ Returns a numeric JSON field by name, or `defVal` if not found. Returns a string JSON field by name, or `defVal` if not found. + :Arguments: * **val** : :ref:`JsonValue `? * **id** : string diff --git a/doc/source/stdlib/das_source_formatter.rst b/doc/source/stdlib/das_source_formatter.rst index 8fa74cf456..15532cd7a4 100644 --- a/doc/source/stdlib/das_source_formatter.rst +++ b/doc/source/stdlib/das_source_formatter.rst @@ -5,6 +5,8 @@ Source code formatter ===================== +.. das:module:: das_source_formatter + The DAS_SOURCE_FORMATTER module implements source code formatting for daslang. It can parse and re-emit daslang source code with consistent indentation, spacing, and line breaking rules. Used by editor integrations and code @@ -14,12 +16,14 @@ All functions and symbols are in "das_source_formatter" module, use require to g require daslib/das_source_formatter + + ++++++++++ Formatting ++++++++++ * :ref:`format_source (file_data: array\) : string ` - * :ref:`format_source_string (file_data: string const& implicit) : string ` + * :ref:`format_source_string (file_data: string const& implicit) : string ` .. _function-das_source_formatter_format_source_array_ls_uint8_gr_: @@ -27,14 +31,16 @@ Formatting Formats daslang source code given as a byte array and returns the formatted result. + :Arguments: * **file_data** : array implicit -.. _function-das_source_formatter_format_source_string_string_const_implicit: +.. _function-das_source_formatter_format_source_string_string_const_ref__implicit: .. das:function:: format_source_string(file_data: string const& implicit) : string Formats a daslang source code string and returns the formatted result. -:Arguments: * **file_data** : string& implicit + +:Arguments: * **file_data** : string\ & implicit diff --git a/doc/source/stdlib/das_source_formatter_fio.rst b/doc/source/stdlib/das_source_formatter_fio.rst index e1da03f5ee..2d35dfb913 100644 --- a/doc/source/stdlib/das_source_formatter_fio.rst +++ b/doc/source/stdlib/das_source_formatter_fio.rst @@ -5,6 +5,8 @@ File-based source code formatter ================================ +.. das:module:: das_source_formatter_fio + The DAS_SOURCE_FORMATTER_FIO module extends the source formatter with file I/O capabilities, enabling formatting of daslang source files on disk. It reads, formats, and writes back source files in place or to new locations. @@ -13,6 +15,8 @@ All functions and symbols are in "das_source_formatter_fio" module, use require require daslib/das_source_formatter_fio + + +++++++++++++++ File formatting +++++++++++++++ @@ -26,6 +30,7 @@ File formatting Reads a daslang source file, formats it, and writes the result back if changed. + :Arguments: * **file_name** : string .. _function-das_source_formatter_fio_format_files_array_ls_string_gr_: @@ -34,6 +39,7 @@ Reads a daslang source file, formats it, and writes the result back if changed. Formats multiple daslang source files in place. + :Arguments: * **file_names** : array diff --git a/doc/source/stdlib/debug_eval.rst b/doc/source/stdlib/debug_eval.rst index 44b6c748e6..61cacb4b20 100644 --- a/doc/source/stdlib/debug_eval.rst +++ b/doc/source/stdlib/debug_eval.rst @@ -5,6 +5,8 @@ Debug expression evaluator ========================== +.. das:module:: debug_eval + The DEBUG_EVAL module provides runtime expression evaluation for debugging purposes. It can evaluate daslang expressions in the context of a running program, supporting variable inspection and interactive debugging. @@ -13,6 +15,8 @@ All functions and symbols are in "debug_eval" module, use require to get access require daslib/debug_eval + + ++++++++++ Structures ++++++++++ @@ -32,6 +36,8 @@ Result of evaluating a debug expression. * **error** : string - Error message, empty if evaluation succeeded. + + ++++++++++ Evaluation ++++++++++ @@ -44,6 +50,7 @@ Evaluation Evaluates a debug expression string with the given variable context and returns the result. + :Arguments: * **context** : table`> * **expr** : string diff --git a/doc/source/stdlib/decs.rst b/doc/source/stdlib/decs.rst index 74914bd804..e766bcf998 100644 --- a/doc/source/stdlib/decs.rst +++ b/doc/source/stdlib/decs.rst @@ -5,6 +5,8 @@ DECS, Daslang entity component system ===================================== +.. das:module:: decs + The DECS module implements a Data-oriented Entity Component System. Entities are identified by integer IDs and store components as typed data. Systems query and process entities by their component signatures, @@ -16,6 +18,8 @@ All functions and symbols are in "decs" module, use require to get access to it. require daslib/decs + + ++++++++++++ Type aliases ++++++++++++ @@ -26,30 +30,36 @@ Type aliases Hash value of the ECS component type + .. _alias-TypeHash: .. das:attribute:: TypeHash = uint64 Hash value of the individual type + .. _alias-DeferEval: .. das:attribute:: DeferEval = lambda<(var act:DeferAction):void> Lambda which holds deferred action. Typically creation of destruction of an entity. + .. _alias-ComponentMap: .. das:attribute:: ComponentMap = array Table of component values for individual entity. + .. _alias-PassFunction: .. das:attribute:: PassFunction = function One of the callbacks which form individual pass. + + +++++++++ Constants +++++++++ @@ -60,6 +70,8 @@ Constants Entity ID which represents invalid entity. + + ++++++++++ Structures ++++++++++ @@ -94,6 +106,7 @@ Consists of type name and collection of type-specific routines to control type v * **gc** : function<(src:array):lambda> - function to perform GC marking on the component value + .. _struct-decs-Component: .. das:attribute:: Component @@ -113,6 +126,7 @@ Single ECS component. Contains component name, data, and data layout. * **gc_dummy** : lambda - this is here so that GC can find real representation of data + .. _struct-decs-EntityId: .. das:attribute:: EntityId @@ -122,6 +136,7 @@ Single ECS component. Contains component name, data, and data layout. * **generation** : int - index of the entity + .. _struct-decs-Archetype: .. das:attribute:: Archetype @@ -137,6 +152,7 @@ ECS archetype. Archetype is unique combination of components. * **eidIndex** : int - index of the 'eid' component in the components array + .. _struct-decs-ComponentValue: .. das:attribute:: ComponentValue @@ -150,6 +166,7 @@ Value of the component during creation or transformation. * **data** : float4[4] - raw data of the component + .. _struct-decs-EcsRequestPos: .. das:attribute:: EcsRequestPos @@ -161,6 +178,7 @@ Location of the ECS request in the code (source file and line number). * **line** : uint - line number + .. _struct-decs-EcsRequest: .. das:attribute:: EcsRequest @@ -179,6 +197,7 @@ Caches list of archetypes, which match the request. * **at** : :ref:`EcsRequestPos ` - location of the request in the code + .. _struct-decs-DecsState: .. das:attribute:: DecsState @@ -201,6 +220,7 @@ Contains archetypes, entities and entity free-list, entity lookup table, all arc * **queryLookup** : table< :ref:`ComponentHash `;int> - lookup of ECS request by its hash + .. _struct-decs-DecsPass: .. das:attribute:: DecsPass @@ -213,6 +233,8 @@ Contains pass name and list of all pass callbacks. * **calls** : array< :ref:`PassFunction `> - list of all pass callbacks + + +++++++++++++++++++++ Comparison and access +++++++++++++++++++++ @@ -230,6 +252,7 @@ Access to component value by name. For example:: create_entity <| @ ( eid, cmp ) cmp.pos := float3(i) // same as cmp |> set("pos",float3(i)) + :Arguments: * **cmp** : :ref:`ComponentMap ` * **name** : string @@ -240,6 +263,7 @@ Access to component value by name. For example:: Inequality operator for entity IDs. + :Arguments: * **a** : :ref:`EntityId ` implicit * **b** : :ref:`EntityId ` implicit @@ -250,10 +274,12 @@ Inequality operator for entity IDs. Equality operator for entity IDs. + :Arguments: * **a** : :ref:`EntityId ` implicit * **b** : :ref:`EntityId ` implicit + ++++++++++++++++++++++ Access (get/set/clone) ++++++++++++++++++++++ @@ -307,6 +333,7 @@ clone Sets individual component value. Verifies that the value is of the correct type. + :Arguments: * **cv** : :ref:`ComponentValue ` * **val** : bool @@ -440,6 +467,7 @@ get Creates temporary array of component given specific name and type of component. If component is not found - panic. + :Arguments: * **arch** : :ref:`Archetype ` * **name** : string @@ -461,6 +489,7 @@ If the entity is dead or the component is not found, returns ``defval``. The type of the component is inferred from the type of ``defval``. Panics if the component exists but its type does not match. + :Arguments: * **eid** : :ref:`EntityId ` * **name** : string @@ -477,6 +506,7 @@ has Returns true if component map has specified component. + :Arguments: * **cmp** : :ref:`ComponentMap ` * **name** : string @@ -493,6 +523,7 @@ Returns true if component map has specified component. Removes specified value from the component map. + :Arguments: * **cmp** : :ref:`ComponentMap ` * **name** : string @@ -508,6 +539,7 @@ set Set component value specified by name and type. If value already exists, it is overwritten. If already existing value type is not the same - panic. + :Arguments: * **cmp** : :ref:`ComponentMap ` * **name** : string @@ -520,6 +552,7 @@ If value already exists, it is overwritten. If already existing value type is no ---- + +++++++++++++ Entity status +++++++++++++ @@ -533,6 +566,7 @@ Entity status Returns the total number of alive entities across all archetypes. + .. _function-decs_is_alive_EntityId: .. das:function:: is_alive(eid: EntityId) : bool @@ -540,8 +574,10 @@ Returns the total number of alive entities across all archetypes. Returns true if the entity is alive (exists and has not been deleted). An entity is alive when its id is within bounds and its generation matches the lookup table. + :Arguments: * **eid** : :ref:`EntityId ` + +++++++++++++++++++++++ Debug and serialization +++++++++++++++++++++++ @@ -557,12 +593,14 @@ Debug and serialization Prints out state of the ECS system. + .. _function-decs_describe_CTypeInfo: .. das:function:: describe(info: CTypeInfo) : string Returns textual description of the type. + :Arguments: * **info** : :ref:`CTypeInfo ` .. _function-decs_finalize_Component: @@ -571,6 +609,7 @@ Returns textual description of the type. Deletes component. + :Arguments: * **cmp** : :ref:`Component ` .. _function-decs_serialize_Archive_Component: @@ -579,10 +618,12 @@ Deletes component. Serializes component value. + :Arguments: * **arch** : :ref:`Archive ` * **src** : :ref:`Component ` + ++++++ Stages ++++++ @@ -597,6 +638,7 @@ Stages Finishes all deferred actions. + .. _function-decs_decs_stage_string: .. das:function:: decs_stage(name: string) @@ -604,6 +646,7 @@ Finishes all deferred actions. Invokes specific ECS pass. `commit` is called before and after the invocation. + :Arguments: * **name** : string .. _function-decs_register_decs_stage_call_string_PassFunction: @@ -612,10 +655,12 @@ Invokes specific ECS pass. Registration of a single pass callback. This is a low-level function, used by decs_boost macros. + :Arguments: * **name** : string * **pcall** : :ref:`PassFunction ` + ++++++++++++++++ Deferred actions ++++++++++++++++ @@ -630,6 +675,7 @@ Deferred actions Creates deferred action to create entity. + :Arguments: * **blk** : lambda<(eid: :ref:`EntityId `;cmp: :ref:`ComponentMap `):void> .. _function-decs_delete_entity_EntityId_implicit: @@ -638,6 +684,7 @@ Creates deferred action to create entity. Creates deferred action to delete entity specified by id. + :Arguments: * **entityid** : :ref:`EntityId ` implicit .. _function-decs_update_entity_EntityId_implicit_lambda_ls_eid_c_EntityId;var_cmp_c_ComponentMap_c_void_gr_: @@ -646,10 +693,12 @@ Creates deferred action to delete entity specified by id. Creates deferred action to update entity specified by id. + :Arguments: * **entityid** : :ref:`EntityId ` implicit * **blk** : lambda<(eid: :ref:`EntityId `;cmp: :ref:`ComponentMap `):void> + ++++++++++++ GC and reset ++++++++++++ @@ -665,6 +714,7 @@ GC and reset Low level callback to be called after the garbage collection. This is a low-level function typically used by `live`. + .. _function-decs_before_gc: .. das:function:: before_gc() @@ -672,12 +722,15 @@ This is a low-level function typically used by `live`. Low level callback to be called before the garbage collection. This is a low-level function typically used by `live`. + .. _function-decs_restart: .. das:function:: restart() Restarts ECS by erasing all deferred actions and entire state. + + +++++++++ Iteration +++++++++ @@ -690,7 +743,7 @@ Iteration * :ref:`get_default_ro (arch: Archetype; name: string; value: auto(TT)) : iterator\ ` * :ref:`get_optional (arch: Archetype; name: string; value: auto(TT)?) : iterator\ ` * :ref:`get_ro (arch: Archetype; name: string; value: auto(TT)) : array\ ` - * :ref:`get_ro (arch: Archetype; name: string; value: auto(TT)[]) : array\ ` + * :ref:`get_ro (arch: Archetype; name: string; value: auto(TT)[]) : array\ ` .. _function-decs_decs_array_autoTT_array_ls_uint8_gr__int_0x2c4: @@ -701,6 +754,7 @@ Iteration Low level function returns temporary array of component given specific type of component. + :Arguments: * **atype** : auto(TT) * **src** : array @@ -718,6 +772,7 @@ for_each_archetype Invokes block for each entity of each archetype that can be processed by the request. Request is returned by a specified function. + :Arguments: * **hash** : :ref:`ComponentHash ` * **erq** : function @@ -738,6 +793,7 @@ Invokes block for each entity of each archetype that can be processed by the req Request is returned by a specified function. If block returns true, iteration is stopped. + :Arguments: * **hash** : :ref:`ComponentHash ` * **erq** : function @@ -751,6 +807,7 @@ If block returns true, iteration is stopped. Invokes block for the specific entity id, given request. Request is returned by a specified function. + :Arguments: * **eid** : :ref:`EntityId ` implicit * **hash** : :ref:`ComponentHash ` @@ -766,6 +823,7 @@ Request is returned by a specified function. Returns const iterator of component given specific name and type of component. If component is not found - iterator will keep returning the specified value. + :Arguments: * **arch** : :ref:`Archetype ` * **name** : string @@ -779,6 +837,7 @@ If component is not found - iterator will keep returning the specified value. Returns const iterator of component given specific name and type of component. If component is not found - iterator will keep returning default value for the component type. + :Arguments: * **arch** : :ref:`Archetype ` * **name** : string @@ -795,18 +854,20 @@ get_ro Returns const temporary array of component given specific name and type of component for regular components. + :Arguments: * **arch** : :ref:`Archetype ` * **name** : string * **value** : auto(TT) -.. _function-decs_get_ro_Archetype_string_autoTT_0x2fb: +.. _function-decs_get_ro_Archetype_string_autoTT_lb__rb__0x2fb: .. das:function:: get_ro(arch: Archetype; name: string; value: auto(TT)[]) : array ---- + +++++++ Request +++++++ @@ -822,6 +883,7 @@ Request Constructs EcsRequestPos from rtti::LineInfo. + :Arguments: * **at** : :ref:`LineInfo ` .. _function-decs_compile_request_EcsRequest: @@ -830,6 +892,7 @@ Constructs EcsRequestPos from rtti::LineInfo. Compiles ECS request, by creating request hash. + :Arguments: * **erq** : :ref:`EcsRequest ` .. _function-decs_lookup_request_EcsRequest: @@ -838,6 +901,7 @@ Compiles ECS request, by creating request hash. Looks up ECS request in the request cache. + :Arguments: * **erq** : :ref:`EcsRequest ` .. _function-decs_verify_request_EcsRequest: @@ -846,6 +910,7 @@ Looks up ECS request in the request cache. Verifies ECS request. Returns pair of boolean (true for OK) and error message. + :Arguments: * **erq** : :ref:`EcsRequest ` diff --git a/doc/source/stdlib/decs_boost.rst b/doc/source/stdlib/decs_boost.rst index f77a0d4a8f..355c05fd79 100644 --- a/doc/source/stdlib/decs_boost.rst +++ b/doc/source/stdlib/decs_boost.rst @@ -5,6 +5,8 @@ Boost package for DECS ====================== +.. das:module:: decs_boost + The DECS_BOOST module provides convenience macros and syntactic sugar for the DECS entity component system, including simplified component registration, entity creation, and system definition patterns. @@ -36,6 +38,8 @@ Example: :: // output: // hero at 1,2,3 + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -46,17 +50,19 @@ Function annotations This annotation provides list of required components for entity. + .. _handle-decs_boost-REQUIRE_NOT: .. das:attribute:: REQUIRE_NOT This annotation provides list of components, which are required to not be part of the entity. + .. _handle-decs_boost-decs: .. das:attribute:: decs -This macro converts a function into a DECS pass stage query. Possible arguments are `stage`, 'REQUIRE', and `REQUIRE_NOT`. +This macro converts a function into a DECS pass stage query. Possible arguments are `stage`, `REQUIRE`, and `REQUIRE_NOT`. It has all other properties of a `query` (like ability to operate on templates). For example:: [decs(stage=update_ai, REQUIRE=ai_turret)] @@ -65,6 +71,8 @@ It has all other properties of a `query` (like ability to operate on templates). In the example above a query is added to the `update_ai` stage. The query also requires that each entity passed to it has an `ai_turret` property. + + +++++++++++ Call macros +++++++++++ @@ -73,9 +81,11 @@ Call macros .. das:attribute:: query -This macro implements 'query` functionality. There are 2 types of queries: - * query(...) - returns a list of entities matching the query - * query(eid) - returns a single entity matching the eid +This macro implements `query` functionality. There are 2 types of queries: + +* query(...) - returns a list of entities matching the query +* query(eid) - returns a single entity matching the eid + For example:: query() <| $ ( eid:EntityId; pos, vel : float3 ) @@ -86,6 +96,7 @@ Here is another example:: query(kaboom) <| $ ( var pos:float3&; vel:float3; col:uint=13u ) pos += vel + The query above will add the velocity to the position of an entity with eid kaboom. Query can have `REQUIRE` and `REQUIRE_NOT` clauses:: @@ -118,14 +129,17 @@ Note: apart from tagging structure as a template, the macro also generates `appl create_entity <| @ ( eid, cmp ) apply_decs_template(cmp, [[Particle pos=float3(i), vel=float3(i+1)]]) + .. _call-macro-decs_boost-find_query: .. das:attribute:: find_query -This macro implements 'find_query` functionality. +This macro implements `find_query` functionality. It is similar to `query` in most ways, with the main differences being: - * there is no eid-based find query - * the find_query stops once the first match is found + +* there is no eid-based find query +* the find_query stops once the first match is found + For example:: let found = find_query <| $ ( pos,dim:float3; obstacle:Obstacle ) @@ -138,17 +152,21 @@ For example:: In the example above the find_query will return `true` once the first intersection is found. Note: if return is missing, or end of find_query block is reached - its assumed that find_query did not find anything, and will return false. + .. _call-macro-decs_boost-from_decs: .. das:attribute:: from_decs This macro converts a DECS query into an iterator>. For example:: + let it = from_decs($(index:int; text:string){}) for (item in it) { // process item print("Entity {item.index}: {item.text}\n") } + Internally it generates the following code:: + let it = invoke($() { var res : array> query($(index:int; text:string) { @@ -156,6 +174,8 @@ Internally it generates the following code:: }) return res.to_sequence() + + ++++++++++++++++ Structure macros ++++++++++++++++ @@ -168,3 +188,4 @@ This macro creates a template for the given structure. `apply_decs_template` and `remove_decs_template` functions are generated for the structure type. + diff --git a/doc/source/stdlib/decs_state.rst b/doc/source/stdlib/decs_state.rst index 11f9f044b4..f746b6798f 100644 --- a/doc/source/stdlib/decs_state.rst +++ b/doc/source/stdlib/decs_state.rst @@ -5,6 +5,8 @@ DECS debug state reporting ========================== +.. das:module:: decs_state + The DECS_STATE module extends DECS with state machine support for entities. It provides state transition management, allowing entities to change behavior based on their current state. @@ -17,3 +19,4 @@ All functions and symbols are in "decs_state" module, use require to get access require daslib/decs_state + diff --git a/doc/source/stdlib/defer.rst b/doc/source/stdlib/defer.rst index c092181fe0..f89c0b2232 100644 --- a/doc/source/stdlib/defer.rst +++ b/doc/source/stdlib/defer.rst @@ -5,6 +5,8 @@ defer and defer_delete macros ============================= +.. das:module:: defer + The DEFER module implements the ``defer`` pattern — the ability to schedule cleanup code to run at scope exit, similar to Go's ``defer``. The deferred block is moved to the ``finally`` section of the enclosing scope at compile time. @@ -30,6 +32,8 @@ Example: :: // middle // cleanup runs last + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -41,6 +45,8 @@ Function annotations This macro converts defer() <| block expression into {}, and move block to the finally section of the current block + + +++++++++++ Call macros +++++++++++ @@ -52,6 +58,8 @@ Call macros This macro converts defer_delete() expression into {}, and add delete expression to the finally section of the current block + + +++++ Defer +++++ @@ -70,8 +78,10 @@ defer a block of code. For example:: Will close the file when 'a' is out of scope. + :Arguments: * **blk** : block + ++++ Stub ++++ @@ -85,3 +95,4 @@ Stub helper function which does nothing and will be optimized out + diff --git a/doc/source/stdlib/dynamic_cast_rtti.rst b/doc/source/stdlib/dynamic_cast_rtti.rst index ecc43b8ff6..3086ac921a 100644 --- a/doc/source/stdlib/dynamic_cast_rtti.rst +++ b/doc/source/stdlib/dynamic_cast_rtti.rst @@ -5,6 +5,8 @@ Dynamic RTTI type casts ======================= +.. das:module:: dynamic_cast_rtti + The DYNAMIC_CAST_RTTI module implements runtime dynamic casting between class types using RTTI information. It provides safe downcasting with null results on type mismatch, similar to C++ ``dynamic_cast``. @@ -13,6 +15,8 @@ All functions and symbols are in "dynamic_cast_rtti" module, use require to get require daslib/dynamic_cast_rtti + + ++++++++++++++ Variant macros ++++++++++++++ @@ -23,6 +27,8 @@ Variant macros Variant macro that implements class dynamic casting via `is` and `as`. + + +++++++++++++ Dynamic casts +++++++++++++ @@ -37,6 +43,7 @@ Dynamic casts Casts a class instance to the target type using RTTI, returns null if the cast fails. + :Arguments: * **instance** : auto * **otherclass** : auto(TT) @@ -47,6 +54,7 @@ Casts a class instance to the target type using RTTI, returns null if the cast f Casts a class instance to the target type using RTTI, panics if the cast fails. + :Arguments: * **instance** : auto * **otherclass** : auto(TT) @@ -57,6 +65,7 @@ Casts a class instance to the target type using RTTI, panics if the cast fails. Returns true if the class instance is an instance of the specified class using RTTI. + :Arguments: * **instance** : auto(TCLS)? * **otherclass** : auto(TT) diff --git a/doc/source/stdlib/enum_trait.rst b/doc/source/stdlib/enum_trait.rst index f8167ae9af..601cbdf493 100644 --- a/doc/source/stdlib/enum_trait.rst +++ b/doc/source/stdlib/enum_trait.rst @@ -5,6 +5,8 @@ Enumeration traits ================== +.. das:module:: enum_trait + The ENUM_TRAIT module provides reflection utilities for enumerations: iterating over all values, converting between enum values and strings, and building lookup tables. The ``[string_to_enum]`` annotation generates a string constructor @@ -37,6 +39,8 @@ Example: :: // blue // fallback = red + + +++++++++++++++ Typeinfo macros +++++++++++++++ @@ -47,12 +51,15 @@ Typeinfo macros Implements typeinfo(enum_names EnumOrEnumType) which returns array of strings with enumValue names. + .. _call-macro-enum_trait-enum_length: .. das:attribute:: enum_length Implements typeinfo(enum_length EnumOrEnumType) which returns total number of elements in enumeration. + + ++++++++++++++++++++ Handled enumerations ++++++++++++++++++++ @@ -63,6 +70,8 @@ Handled enumerations Enumeration annotation which implements string constructor for enumeration. + + +++++++++++++++++++++ Enumeration iteration +++++++++++++++++++++ @@ -75,8 +84,10 @@ Enumeration iteration Returns an iterator over all values of the given enumeration type. + :Arguments: * **tt** : auto(TT) + ++++++++++++++++++++++ Enumeration conversion ++++++++++++++++++++++ @@ -93,6 +104,7 @@ Enumeration conversion converts enum type to a table of name => value pairs usage: let t = enum_to_table(type) + :Arguments: * **ent** : auto(EnumT) .. _function-enum_trait_string_auto_0x21: @@ -102,6 +114,7 @@ converts enum type to a table of name => value pairs converts enum value to string usage: let s = string(EnumValue) + :Arguments: * **arg** : auto @@ -115,6 +128,7 @@ to_enum converts string to enum value, panics if not found usage: let e = to_enum(type,"EnumValueName") + :Arguments: * **ent** : auto(EnumT) * **name** : string diff --git a/doc/source/stdlib/export_constructor.rst b/doc/source/stdlib/export_constructor.rst index 38ecde63ff..cf9e550abd 100644 --- a/doc/source/stdlib/export_constructor.rst +++ b/doc/source/stdlib/export_constructor.rst @@ -5,6 +5,8 @@ Export constructor ================== +.. das:module:: export_constructor + The EXPORT_CONSTRUCTOR module provides the ``[export_constructor]`` annotation for struct types. Annotated structs automatically generate an exported constructor function that can be called from other modules or from C++ code. @@ -13,6 +15,8 @@ All functions and symbols are in "export_constructor" module, use require to get require daslib/export_constructor + + ++++++++++++++++ Structure macros ++++++++++++++++ @@ -24,3 +28,4 @@ Structure macros implements 'export_constructor' macro, adds function make`{StructureName} which makes a new instance of a class or structure + diff --git a/doc/source/stdlib/faker.rst b/doc/source/stdlib/faker.rst index 600e008913..60de857001 100644 --- a/doc/source/stdlib/faker.rst +++ b/doc/source/stdlib/faker.rst @@ -5,6 +5,8 @@ Faker ===== +.. das:module:: faker + Random test-data generator. The ``Faker`` struct produces random values for every built-in type @@ -15,6 +17,8 @@ All functions and symbols are in "faker" module, use require to get access to it require daslib/faker + + ++++++++++ Structures ++++++++++ @@ -34,6 +38,8 @@ Instance of the faker with all the settings inside. * **max_long_string** : uint = 0x1000 - maximal length of generated string + + +++++++++++ Constructor +++++++++++ @@ -46,8 +52,10 @@ Constructor Constructs a Faker instance with the given random number generator. + :Arguments: * **rng** : iterator + +++++++++++++ Random values +++++++++++++ @@ -85,6 +93,7 @@ Random values Generates random double. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_float_Faker: @@ -93,6 +102,7 @@ Generates random double. Generates random float. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_float2_Faker: @@ -101,6 +111,7 @@ Generates random float. Generates random float2. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_float3_Faker: @@ -109,6 +120,7 @@ Generates random float2. Generates random float3. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_float3x3_Faker: @@ -117,6 +129,7 @@ Generates random float3. Generates random float3x3. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_float3x4_Faker: @@ -125,6 +138,7 @@ Generates random float3x3. Generates random float3x4. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_float4_Faker: @@ -133,6 +147,7 @@ Generates random float3x4. Generates random float4. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_float4x4_Faker: @@ -141,6 +156,7 @@ Generates random float4. Generates random float4x4. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_int_Faker: @@ -149,6 +165,7 @@ Generates random float4x4. Generates random integer. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_int16_Faker: @@ -157,6 +174,7 @@ Generates random integer. Generates random int16. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_int2_Faker: @@ -165,6 +183,7 @@ Generates random int16. Generates random int2. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_int3_Faker: @@ -173,6 +192,7 @@ Generates random int2. Generates random int3. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_int4_Faker: @@ -181,6 +201,7 @@ Generates random int3. Generates random int4. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_int64_Faker: @@ -189,6 +210,7 @@ Generates random int4. Generates random int64 + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_int8_Faker: @@ -197,6 +219,7 @@ Generates random int64 Generates random int8. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_range_Faker: @@ -205,6 +228,7 @@ Generates random int8. Generates random range. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_range64_Faker: @@ -213,6 +237,7 @@ Generates random range. Generates random range64. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_uint_Faker: @@ -221,6 +246,7 @@ Generates random range64. Generates random unsigned integer. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_uint16_Faker: @@ -229,6 +255,7 @@ Generates random unsigned integer. Generates random uint16. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_uint2_Faker: @@ -237,6 +264,7 @@ Generates random uint16. Generates random uint2. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_uint3_Faker: @@ -245,6 +273,7 @@ Generates random uint2. Generates random uint3. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_uint4_Faker: @@ -253,6 +282,7 @@ Generates random uint3. Generates random uint4. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_uint64_Faker: @@ -261,6 +291,7 @@ Generates random uint4. Generates random uint64 + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_uint8_Faker: @@ -269,6 +300,7 @@ Generates random uint64 Generates random uint8. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_urange_Faker: @@ -277,6 +309,7 @@ Generates random uint8. Generates random urange. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_random_urange64_Faker: @@ -285,8 +318,10 @@ Generates random urange. Generates random urange64. + :Arguments: * **faker** : :ref:`Faker ` + ++++++++++++++ Random strings ++++++++++++++ @@ -310,6 +345,7 @@ Random strings Generates random char. (1 to 255 range) + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_any_enum_Faker_autoTT_0x13e: @@ -318,6 +354,7 @@ Generates random char. (1 to 255 range) Generates random enumeration value. + :Arguments: * **faker** : :ref:`Faker ` * **enum_value** : auto(TT) @@ -328,6 +365,7 @@ Generates random enumeration value. Generates random file name. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_any_float_Faker: @@ -336,6 +374,7 @@ Generates random file name. Generates random float string. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_any_hex_Faker: @@ -344,6 +383,7 @@ Generates random float string. Generates random integer hex string. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_any_int_Faker: @@ -352,6 +392,7 @@ Generates random integer hex string. Generates random integer string. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_any_set_Faker: @@ -360,6 +401,7 @@ Generates random integer string. Generates random set (uint[8]) + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_any_string_Faker: @@ -368,6 +410,7 @@ Generates random set (uint[8]) Generates a string of random characters. The string is anywhere between 0 and regex::re_gen_get_rep_limit() characters long. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_any_uint_Faker: @@ -376,6 +419,7 @@ Generates a string of random characters. The string is anywhere between 0 and re Generates random unsigned integer string. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_long_string_Faker: @@ -384,6 +428,7 @@ Generates random unsigned integer string. Generates a long string of random characters. The string is anywhere between 0 and faker.max_long_string characters long. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_number_Faker: @@ -392,6 +437,7 @@ Generates a long string of random characters. The string is anywhere between 0 a Generates random number string. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_positive_int_Faker: @@ -400,8 +446,10 @@ Generates random number string. Generates random positive integer string. + :Arguments: * **faker** : :ref:`Faker ` + +++++++++++++ Date and time +++++++++++++ @@ -419,6 +467,7 @@ Date and time Generates random date string. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_day_Faker: @@ -427,6 +476,7 @@ Generates random date string. Generates random day string. + :Arguments: * **faker** : :ref:`Faker ` .. _function-faker_is_leap_year_uint: @@ -435,6 +485,7 @@ Generates random day string. Returns true if year is leap year. + :Arguments: * **year** : uint .. _function-faker_month_Faker: @@ -443,6 +494,7 @@ Returns true if year is leap year. Generates random month string. + :Arguments: * **faker** : :ref:`Faker ` @@ -455,6 +507,7 @@ week_day Returns week day for given date. + :Arguments: * **year** : uint * **month** : uint diff --git a/doc/source/stdlib/fio.rst b/doc/source/stdlib/fio.rst index b5af1a8274..9afb28de4f 100644 --- a/doc/source/stdlib/fio.rst +++ b/doc/source/stdlib/fio.rst @@ -5,6 +5,8 @@ File input output library ========================= +.. das:module:: fio + The FIO module implements file input/output and filesystem operations. It provides functions for reading and writing files (``fopen``, ``fread``, ``fwrite``), directory management (``mkdir``, ``dir``), path manipulation (``join_path``, @@ -33,6 +35,8 @@ Example: :: // output: // hello, daslang! + + ++++++++++++ Type aliases ++++++++++++ @@ -42,6 +46,8 @@ Type aliases .. das:attribute:: file = FILE const? Type alias for FILE const? used as the standard file handle parameter type across fio functions. + + +++++++++ Constants +++++++++ @@ -51,16 +57,19 @@ Constants .. das:attribute:: seek_set = 0 Constant for fseek that positions the file pointer relative to the beginning of the file by the given offset. + .. _global-fio-seek_cur: .. das:attribute:: seek_cur = 1 Constant for fseek that positions the file pointer relative to its current position by the given offset. + .. _global-fio-seek_end: .. das:attribute:: seek_end = 2 Constant for fseek that positions the file pointer relative to the end of the file by the given offset. + .. _global-fio-df_magic: .. das:attribute:: df_magic = 0x12345678 @@ -68,6 +77,8 @@ Constant for fseek that positions the file pointer relative to the end of the fi Magic number constant used to identify daslang binary file format. df_magic:uint const + + ++++++++++ Structures ++++++++++ @@ -83,6 +94,8 @@ Obsolete header structure used by fsave and fload for binary serialization with * **size** : int - Total size in bytes of the serialized data following this header. + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -98,6 +111,7 @@ Handled structures Returns the size of the file in bytes. + .. _function-fio__dot__rq_atime_FStat_implicit: .. das:function:: FStat implicit.atime() : clock @@ -105,6 +119,7 @@ Returns the size of the file in bytes. Returns the last access time of the file as a clock value. + .. _function-fio__dot__rq_ctime_FStat_implicit: .. das:function:: FStat implicit.ctime() : clock @@ -112,6 +127,7 @@ Returns the last access time of the file as a clock value. Returns the creation time of the file as a clock value. + .. _function-fio__dot__rq_mtime_FStat_implicit: .. das:function:: FStat implicit.mtime() : clock @@ -119,6 +135,7 @@ Returns the creation time of the file as a clock value. Returns the last modification time of the file as a clock value. + .. _function-fio__dot__rq_is_reg_FStat_implicit: .. das:function:: FStat implicit.is_reg() : bool @@ -126,6 +143,7 @@ Returns the last modification time of the file as a clock value. Returns true if the file status indicates a regular file. + .. _function-fio__dot__rq_is_dir_FStat_implicit: .. das:function:: FStat implicit.is_dir() : bool @@ -133,6 +151,7 @@ Returns true if the file status indicates a regular file. Returns true if the file status indicates a directory. + :Properties: * **size** : uint64 * **atime** : :ref:`clock ` @@ -148,6 +167,8 @@ Returns true if the file status indicates a directory. :Fields: * **is_valid** : bool - `stat` and `fstat` return file information in this structure. + + +++++++++++++ Handled types +++++++++++++ @@ -157,6 +178,8 @@ Handled types .. das:attribute:: FILE Opaque handle wrapping the platform-specific C FILE type used by all low-level file I/O functions. + + +++++++++++++++++ File manipulation +++++++++++++++++ @@ -198,6 +221,7 @@ File manipulation Closes the given FILE pointer and releases its associated resources, equivalent to C fclose. + :Arguments: * **file** : :ref:`FILE `? implicit .. _function-fio_feof_FILE_const_q__implicit: @@ -206,6 +230,7 @@ Closes the given FILE pointer and releases its associated resources, equivalent Returns true if the end-of-file indicator has been set on the given FILE pointer, equivalent to C feof. + :Arguments: * **file** : :ref:`FILE `? implicit .. _function-fio_fflush_FILE_const_q__implicit: @@ -214,6 +239,7 @@ Returns true if the end-of-file indicator has been set on the given FILE pointer Flushes any buffered output data for the given FILE pointer to the underlying file, equivalent to C fflush. + :Arguments: * **file** : :ref:`FILE `? implicit .. _function-fio_fgets_FILE_const_q__implicit: @@ -222,6 +248,7 @@ Flushes any buffered output data for the given FILE pointer to the underlying fi Reads and returns the next line as a string from the given FILE pointer, equivalent to C fgets. + :Arguments: * **file** : :ref:`FILE `? implicit @@ -234,6 +261,7 @@ fload Obsolete; loads binary data from a file into the provided buffer or passes it as an array of uint8 to a block. + :Arguments: * **file** : :ref:`file ` * **size** : int @@ -252,9 +280,10 @@ Obsolete; loads binary data from a file into the provided buffer or passes it as Memory-maps the contents of the given FILE pointer and provides the data as an array of uint8 inside the block. + :Arguments: * **file** : :ref:`FILE `? implicit - * **block** : block<(array#):void> implicit + * **block** : block<(array\ #):void> implicit fopen @@ -266,6 +295,7 @@ fopen Opens the file at the given path with the specified mode string, returning a FILE pointer or invoking a block with a file handle. + :Arguments: * **name** : string * **mode** : string @@ -284,6 +314,7 @@ Opens the file at the given path with the specified mode string, returning a FIL Writes the given text string to the specified FILE pointer, equivalent to print but targeting a file. + :Arguments: * **file** : :ref:`FILE `? implicit * **text** : string implicit @@ -298,6 +329,7 @@ fread Reads data from a file into a buffer, an array, or returns the full contents as a string, with block-based overloads available. + :Arguments: * **f** : :ref:`file ` * **buf** : auto(BufType) implicit @@ -322,6 +354,7 @@ Reads data from a file into a buffer, an array, or returns the full contents as Obsolete; saves the provided buffer data to a file in binary format. + :Arguments: * **f** : :ref:`file ` * **buf** : auto(BufType) @@ -332,6 +365,7 @@ Obsolete; saves the provided buffer data to a file in binary format. Repositions the file pointer of the given FILE to the specified offset relative to the mode (seek_set, seek_cur, or seek_end) and returns the new position. + :Arguments: * **file** : :ref:`FILE `? implicit * **offset** : int64 @@ -348,6 +382,7 @@ fstat Retrieves file metadata such as size and timestamps into an FStat structure from a file handle, equivalent to C fstat. + :Arguments: * **file** : :ref:`FILE `? implicit * **stat** : :ref:`FStat ` implicit @@ -364,24 +399,28 @@ Retrieves file metadata such as size and timestamps into an FStat structure from Returns the FILE pointer corresponding to the standard error stream. + .. _function-fio_fstdin: .. das:function:: fstdin() : FILE const? Returns the FILE pointer corresponding to the standard input stream. + .. _function-fio_fstdout: .. das:function:: fstdout() : FILE const? Returns the FILE pointer corresponding to the standard output stream. + .. _function-fio_ftell_FILE_const_q__implicit: .. das:function:: ftell(file: FILE const? implicit) : int64 Returns the current byte offset of the file pointer for the given FILE, equivalent to C ftell. + :Arguments: * **file** : :ref:`FILE `? implicit @@ -394,6 +433,7 @@ fwrite Writes a string, typed buffer, or array of data to the specified file handle. + :Arguments: * **f** : :ref:`file ` * **buf** : array implicit @@ -414,12 +454,14 @@ Writes a string, typed buffer, or array of data to the specified file handle. Reads and returns the next character from standard input as an integer, equivalent to C getchar. + .. _function-fio_remove_string_implicit: .. das:function:: remove(name: string implicit) : bool Deletes the file at the specified path and returns true if it was removed successfully. + :Arguments: * **name** : string implicit .. _function-fio_rename_string_implicit_string_implicit: @@ -428,6 +470,7 @@ Deletes the file at the specified path and returns true if it was removed succes Renames or moves a file from old_name to new_name and returns true on success. + :Arguments: * **old_name** : string implicit * **new_name** : string implicit @@ -442,6 +485,7 @@ stat Retrieves file metadata such as size and timestamps for the file at the given path, returning an FStat structure or populating one by reference. + :Arguments: * **path** : string .. _function-fio_stat_string_implicit_FStat_implicit: @@ -450,6 +494,7 @@ Retrieves file metadata such as size and timestamps for the file at the given pa ---- + +++++++++++++++++ Path manipulation +++++++++++++++++ @@ -464,6 +509,7 @@ Path manipulation Extracts and returns the final component of a file path, equivalent to POSIX basename. + :Arguments: * **name** : string implicit .. _function-fio_dir_name_string_implicit: @@ -472,6 +518,7 @@ Extracts and returns the final component of a file path, equivalent to POSIX bas Extracts and returns the directory component of a file path, equivalent to POSIX dirname. + :Arguments: * **name** : string implicit .. _function-fio_get_full_file_name_string_implicit: @@ -480,8 +527,10 @@ Extracts and returns the directory component of a file path, equivalent to POSIX Returns the fully resolved and normalized absolute path for the given file path string. + :Arguments: * **path** : string implicit + ++++++++++++++++++++++ Directory manipulation ++++++++++++++++++++++ @@ -498,6 +547,7 @@ Directory manipulation Changes the current working directory to the specified path and returns true on success. + :Arguments: * **path** : string implicit .. _function-fio_dir_string_block_ls_filename_c_string_c_void_gr_: @@ -506,6 +556,7 @@ Changes the current working directory to the specified path and returns true on Iterates over all entries in the directory at the given path, invoking the block with each filename. + :Arguments: * **path** : string * **blk** : block<(filename:string):void> @@ -516,12 +567,14 @@ Iterates over all entries in the directory at the given path, invoking the block Returns the absolute path of the current working directory as a string. + .. _function-fio_mkdir_string_implicit: .. das:function:: mkdir(path: string implicit) : bool Creates a single directory at the specified path and returns true if it was created successfully. + :Arguments: * **path** : string implicit .. _function-fio_mkdir_rec_string: @@ -530,8 +583,10 @@ Creates a single directory at the specified path and returns true if it was crea Recursively creates the directory at the specified path along with any missing parent directories, returning true on success. + :Arguments: * **path** : string + ++++++++++++++++++++ OS specific routines ++++++++++++++++++++ @@ -553,6 +608,7 @@ OS specific routines Terminates the program immediately with the specified integer exit code, equivalent to C exit. + :Arguments: * **exitCode** : int .. _function-fio_get_env_variable_string_implicit: @@ -561,6 +617,7 @@ Terminates the program immediately with the specified integer exit code, equival Returns the string value of the environment variable with the given name, or an empty string if undefined. + :Arguments: * **var** : string implicit .. _function-fio_has_env_variable_string_implicit: @@ -569,6 +626,7 @@ Returns the string value of the environment variable with the given name, or an Returns true if an environment variable with the given name is defined in the current process environment. + :Arguments: * **var** : string implicit .. _function-fio_popen_string_implicit_block_ls_FILE_const_q__c_void_gr_: @@ -580,6 +638,7 @@ Returns true if an environment variable with the given name is defined in the cu Opens a pipe to the given shell command, provides the resulting FILE pointer to the block, and returns the process exit code. + :Arguments: * **command** : string implicit * **scope** : block<( :ref:`FILE `?):void> implicit @@ -593,6 +652,7 @@ Opens a pipe to the given shell command, provides the resulting FILE pointer to Opens a pipe to the given shell command in binary mode, provides the resulting FILE pointer to the block, and returns the process exit code. + :Arguments: * **command** : string implicit * **scope** : block<( :ref:`FILE `?):void> implicit @@ -603,6 +663,7 @@ Opens a pipe to the given shell command in binary mode, provides the resulting F Escapes and sanitizes a command-line argument string to prevent shell injection. + :Arguments: * **var** : string implicit .. _function-fio_sleep_uint: @@ -611,8 +672,10 @@ Escapes and sanitizes a command-line argument string to prevent shell injection. Suspends execution of the current thread for the specified number of milliseconds. + :Arguments: * **msec** : uint + +++++++++++++++ Dynamic modules +++++++++++++++ @@ -631,6 +694,7 @@ register_dynamic_module Loads a shared library from the given path and registers it as a daslang module under the specified name, making it available for require. + :Arguments: * **path** : string implicit * **name** : string implicit @@ -647,6 +711,7 @@ Loads a shared library from the given path and registers it as a daslang module Registers a path prefix mapping for a module, redirecting file resolution from the src prefix to the dst prefix. + :Arguments: * **mod_name** : string implicit * **src** : string implicit diff --git a/doc/source/stdlib/flat_hash_table.rst b/doc/source/stdlib/flat_hash_table.rst index f92ddbce84..aaecc0703e 100644 --- a/doc/source/stdlib/flat_hash_table.rst +++ b/doc/source/stdlib/flat_hash_table.rst @@ -5,6 +5,8 @@ Flat hash table =============== +.. das:module:: flat_hash_table + The FLAT_HASH_TABLE module implements a flat (open addressing) hash table. It stores all entries in a single contiguous array, providing cache-friendly access patterns and good performance for small to medium-sized tables. @@ -35,6 +37,8 @@ Example: :: // m[2] = two // after clear: 0 + + +++++++++++ Type macros +++++++++++ diff --git a/doc/source/stdlib/functional.rst b/doc/source/stdlib/functional.rst index 460c32a779..60b8428546 100644 --- a/doc/source/stdlib/functional.rst +++ b/doc/source/stdlib/functional.rst @@ -5,6 +5,8 @@ Functional programming library ============================== +.. das:module:: functional + The FUNCTIONAL module implements lazy iterator adapters and higher-order function utilities including ``filter``, ``map``, ``reduce``, ``fold``, ``scan``, ``flatten``, ``flat_map``, ``enumerate``, ``chain``, ``pairwise``, @@ -34,6 +36,8 @@ Example: :: // output: // 0 2 4 + + +++++++++++++++ Transformations +++++++++++++++ @@ -60,6 +64,7 @@ filter iterates over `src` and yields only those elements for which `blk` returns true + :Arguments: * **src** : iterator * **blk** : function<(what:TT):bool> @@ -80,6 +85,7 @@ flat_map maps each element to an iterator, then flattens the results one level + :Arguments: * **src** : iterator * **blk** : lambda<(what:TT):auto(QQ)> @@ -96,6 +102,7 @@ maps each element to an iterator, then flattens the results one level iterates over `it`, then iterates over each element of each element of `it` and yields it + :Arguments: * **it** : iterator @@ -108,6 +115,7 @@ map iterates over `src` and yields the result of `blk` for each element + :Arguments: * **src** : iterator * **blk** : function<(what:TT):auto(QQ)> @@ -128,6 +136,7 @@ scan yields every intermediate accumulator value, starting from `seed` + :Arguments: * **src** : iterator * **seed** : auto(AGG) @@ -150,6 +159,7 @@ sorted iterates over input and returns it sorted version + :Arguments: * **it** : iterator .. _function-functional_sorted_array_ls_auto_gr_: @@ -158,6 +168,7 @@ iterates over input and returns it sorted version ---- + +++++++++++ Aggregation +++++++++++ @@ -187,6 +198,7 @@ all iterates over `it` and yields true if all elements are true + :Arguments: * **it** : iterator .. _function-functional_all_auto_0xb5: @@ -205,6 +217,7 @@ any iterates over `it` and yields true if any element is true + :Arguments: * **it** : auto .. _function-functional_any_iterator_ls_autoTT_gr_: @@ -223,6 +236,7 @@ fold combines elements left-to-right starting from `seed` + :Arguments: * **it** : iterator * **seed** : auto(AGG) @@ -250,6 +264,7 @@ reduce iterates over `it` and yields the reduced (combined) result of `blk` for each element and previous reduction result + :Arguments: * **it** : iterator * **blk** : function<(left:TT;right:TT):TT> @@ -274,6 +289,7 @@ reduce_or_default like reduce, but returns `default_value` on empty input + :Arguments: * **it** : iterator * **blk** : function<(left:TT;right:TT):TT> @@ -297,8 +313,10 @@ like reduce, but returns `default_value` on empty input iterates over `it` and yields the sum of all elements same as reduce(it, @(a,b) => a + b) + :Arguments: * **it** : iterator + ++++++++++++++++ Search and split ++++++++++++++++ @@ -323,6 +341,7 @@ find returns the first element for which `blk` returns true, or `default_value` + :Arguments: * **src** : iterator * **blk** : function<(what:TT):bool> @@ -349,6 +368,7 @@ find_index returns the index of the first element for which `blk` returns true, or -1 + :Arguments: * **src** : iterator * **blk** : lambda<(what:TT):bool> @@ -373,6 +393,7 @@ partition splits elements into `(matching, non_matching)` arrays + :Arguments: * **src** : iterator * **blk** : lambda<(what:TT):bool> @@ -387,6 +408,7 @@ splits elements into `(matching, non_matching)` arrays ---- + +++++++++ Iteration +++++++++ @@ -406,6 +428,7 @@ Iteration prints `x` to the output with `extra` appended, then returns `x` unchanged. Non-destructive — safe to use in expression chains. + :Arguments: * **x** : auto * **extra** : string @@ -416,6 +439,7 @@ Non-destructive — safe to use in expression chains. yields tuples of `(index, element)` for each element in `src` + :Arguments: * **src** : iterator @@ -428,6 +452,7 @@ for_each invokes `blk` on every element of `src` + :Arguments: * **src** : iterator * **blk** : function<(what:TT):void> @@ -452,6 +477,7 @@ tap yields every element unchanged, calling `blk` on each as a side-effect + :Arguments: * **src** : iterator * **blk** : function<(what:TT):void> @@ -462,6 +488,7 @@ yields every element unchanged, calling `blk` on each as a side-effect ---- + ++++++++++ Generators ++++++++++ @@ -481,6 +508,7 @@ Generators yields all elements of `a`, then all elements of `b` + :Arguments: * **a** : iterator * **b** : iterator @@ -491,6 +519,7 @@ yields all elements of `a`, then all elements of `b` endlessly iterates over `src` + :Arguments: * **src** : iterator .. _function-functional_islice_iterator_ls_autoTT_gr__int_int: @@ -499,6 +528,7 @@ endlessly iterates over `src` iterates over `src` and yields only the elements in the range [start,stop) + :Arguments: * **src** : iterator * **start** : int @@ -515,6 +545,7 @@ iterate yields `seed`, `f(seed)`, `f(f(seed))`, ... infinitely. + :Arguments: * **seed** : auto(TT) * **blk** : function<(what:TT):TT> @@ -531,6 +562,7 @@ yields `seed`, `f(seed)`, `f(f(seed))`, ... infinitely. yields consecutive pairs: `(a,b)`, `(b,c)`, `(c,d)`, ... + :Arguments: * **src** : iterator .. _function-functional_repeat_autoTT_int_0x113: @@ -539,6 +571,7 @@ yields consecutive pairs: `(a,b)`, `(b,c)`, `(c,d)`, ... yields `value` `count` times. If `count` is negative, repeats forever. + :Arguments: * **value** : auto(TT) * **count** : int @@ -549,10 +582,12 @@ yields `value` `count` times. If `count` is negative, repeats forever. yields `value` by reference `count` times + :Arguments: * **value** : auto(TT) * **total** : int + ++++++++++ Predicates ++++++++++ @@ -567,6 +602,7 @@ Predicates yields true if `a` and `b` are equal + :Arguments: * **a** : auto * **b** : auto @@ -577,6 +613,7 @@ yields true if `a` and `b` are equal yields true if `a` and `b` are not equal + :Arguments: * **a** : auto * **b** : auto @@ -587,6 +624,7 @@ yields true if `a` and `b` are not equal yields !x + :Arguments: * **x** : auto diff --git a/doc/source/stdlib/fuzzer.rst b/doc/source/stdlib/fuzzer.rst index 00e2fccbed..19b04c82f9 100644 --- a/doc/source/stdlib/fuzzer.rst +++ b/doc/source/stdlib/fuzzer.rst @@ -5,6 +5,8 @@ Fuzzer ====== +.. das:module:: fuzzer + The FUZZER module implements fuzz testing infrastructure for daslang programs. It generates random inputs for functions and verifies they do not crash or produce unexpected errors, helping discover edge cases and robustness issues. @@ -13,6 +15,8 @@ All functions and symbols are in "fuzzer" module, use require to get access to i require daslib/fuzzer + + ++++++++++++ Fuzzer tests ++++++++++++ @@ -58,6 +62,7 @@ fuzz run block however many times ignore panic, so that we can see that runtime crashes + :Arguments: * **fuzz_count** : int * **blk** : block @@ -75,6 +80,7 @@ ignore panic, so that we can see that runtime crashes fuzzes generic function that takes single numeric or vector argument. arguments are: int, uint, int64, uint64 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -88,6 +94,7 @@ arguments are: int, uint, int64, uint64 fuzzes generic function that takes single numeric or vector argument. arguments are: uint, uint64 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -101,6 +108,7 @@ arguments are: uint, uint64 fuzzes generic function that takes two numeric or vector arguments. arguments are: int, uint, float, double, int64, uint64, string + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -119,6 +127,7 @@ run block however many times do not ignore panic, so that we can see where the runtime fails this is here so that `fuzz` can be easily replaced with `fuzz_debug` for the purpose of debugging + :Arguments: * **fuzz_count** : int * **blk** : block @@ -136,6 +145,7 @@ this is here so that `fuzz` can be easily replaced with `fuzz_debug` for the pur fuzzes generic function that takes two numeric or vector arguments. arguments are: int, uint, int64, uint64, float, double, string, int2, int3, int4, uint2, uint3, uint4, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -149,6 +159,7 @@ arguments are: int, uint, int64, uint64, float, double, string, int2, int3, int4 fuzzes generic function that takes single numeric or vector argument. arguments are: float, double, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -162,6 +173,7 @@ arguments are: float, double, float2, float3, float4 fuzzes generic function that takes two numeric or vector arguments. arguments are: float, double, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -175,6 +187,7 @@ arguments are: float, double, float2, float3, float4 fuzzes generic function that takes three numeric or vector arguments. arguments are: float, double, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -188,6 +201,7 @@ arguments are: float, double, float2, float3, float4 fuzzes generic function that takes single numeric or vector argument. arguments are: float, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -201,6 +215,7 @@ arguments are: float, float2, float3, float4 fuzzes generic function that takes two numeric or vector arguments. arguments are: float, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -214,6 +229,7 @@ arguments are: float, float2, float3, float4 fuzzes generic function that takes two numeric or vector arguments. arguments are: int, uint, int2, int3, int4, uint2, uint3, uint4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -227,6 +243,7 @@ arguments are: int, uint, int2, int3, int4, uint2, uint3, uint4 fuzzes generic function that takes single numeric or vector argument. arguments are: int, uint, int8, uint8, int16, uint16, int64, uint64, float, double + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -240,6 +257,7 @@ arguments are: int, uint, int8, uint8, int16, uint16, int64, uint64, float, doub fuzzes generic function that takes single numeric or vector argument. arguments are: int, uint, float, double, string, int2, int3, int4, uint2, uint3, uint4, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -253,6 +271,7 @@ arguments are: int, uint, float, double, string, int2, int3, int4, uint2, uint3, fuzzes generic function that takes two numeric or vector arguments. arguments are: int, uint, float, double, int2, int3, int4, uint2, uint3, uint4, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -266,6 +285,7 @@ arguments are: int, uint, float, double, int2, int3, int4, uint2, uint3, uint4, fuzzes generic function that takes two numeric or vector arguments. arguments are: int, uint, float, double, int2, int3, int4, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -279,6 +299,7 @@ arguments are: int, uint, float, double, int2, int3, int4, float2, float3, float fuzzes generic function that takes single numeric or vector argument. arguments are: int, uint, float, double, string, int2, int3, int4, uint2, uint3, uint4, float2, float3, float4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -292,6 +313,7 @@ arguments are: int, uint, float, double, string, int2, int3, int4, uint2, uint3, fuzzes generic function that takes single numeric or vector argument. arguments are: int, uint, float, double + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -305,6 +327,7 @@ arguments are: int, uint, float, double fuzzes generic function that takes two numeric or vector arguments. arguments are: int, uint, float, double + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -318,6 +341,7 @@ arguments are: int, uint, float, double fuzzes generic function that takes three numeric or vector arguments. arguments are: int, uint, float, double + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -331,6 +355,7 @@ arguments are: int, uint, float, double fuzzes generic function that takes four numeric or vector arguments. arguments are: int, uint, float, double + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -344,6 +369,7 @@ arguments are: int, uint, float, double fuzzes generic function that takes vector and matching scalar on the left arguments pairs are: int2,int; int3,int; uint2,uint; uint3,uint; uint4,uint; int4,int; float2,float; float3,float; float4,float + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -357,6 +383,7 @@ arguments pairs are: int2,int; int3,int; uint2,uint; uint3,uint; uint4,uint; int fuzzes generic function that takes vector and matching scalar on the right arguments pairs are: int2,int; int3,int; uint2,uint; uint3,uint; uint4,uint; int4,int; float2,float; float3,float; float4,float + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -370,6 +397,7 @@ arguments pairs are: int2,int; int3,int; uint2,uint; uint3,uint; uint4,uint; int fuzzes generic function that takes numeric or vector argument, with matching rotate type on the right. arguments are: int, uint + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -383,6 +411,7 @@ arguments are: int, uint fuzzes generic function that takes numeric or vector argument, with matching shift type on the right. arguments are: int, uint, int2, int3, int4, uint2, uint3, uint4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -396,6 +425,7 @@ arguments are: int, uint, int2, int3, int4, uint2, uint3, uint4 fuzzes generic function that takes three numeric or vector arguments. arguments are: float2, float3, float4, int2, int3, int4, uint2, uint3, uint4 second argument is float, int, uint accordingly + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` @@ -409,6 +439,7 @@ arguments are: float2, float3, float4, int2, int3, int4, uint2, uint3, uint4 sec fuzzes generic function that takes three numeric or vector arguments. arguments are: float2, float3, float4, int2, int3, int4, uint2, uint3, uint4 + :Arguments: * **t** : auto * **fake** : :ref:`Faker ` diff --git a/doc/source/stdlib/generic_return.rst b/doc/source/stdlib/generic_return.rst index e1890652f1..8890256a55 100644 --- a/doc/source/stdlib/generic_return.rst +++ b/doc/source/stdlib/generic_return.rst @@ -5,6 +5,8 @@ Generic return type instantiation ================================= +.. das:module:: generic_return + The GENERIC_RETURN module provides the ``[generic_return]`` annotation that allows generic functions to automatically deduce their return type from the body. This simplifies writing generic utility functions by eliminating @@ -14,6 +16,8 @@ All functions and symbols are in "generic_return" module, use require to get acc require daslib/generic_return + + +++++++++++ Call macros +++++++++++ @@ -25,3 +29,4 @@ Call macros Replaces generic_return(expr) with a block that calls expr and returns its result, handling void, copyable, and movable return types. + diff --git a/doc/source/stdlib/handmade/structure-regex-ReNode.rst b/doc/source/stdlib/handmade/structure-regex-ReNode.rst index c55ee5ae40..e1875b5145 100644 --- a/doc/source/stdlib/handmade/structure-regex-ReNode.rst +++ b/doc/source/stdlib/handmade/structure-regex-ReNode.rst @@ -15,5 +15,5 @@ Character set for character class matching Index for character class matching Minimum repetition count for counted quantifiers Maximum repetition count for counted quantifiers (-1 means unlimited) -Whether this quantifier uses lazy matching (*?, +?, ??, {n,m}?) +Whether this quantifier uses lazy matching (``*?``, ``+?``, ``??``, ``{n,m}?``) Tail of the string \ No newline at end of file diff --git a/doc/source/stdlib/handmade/structure_annotation-ast-ExprSetInsert.rst b/doc/source/stdlib/handmade/structure_annotation-ast-ExprSetInsert.rst index 7279c974c0..8392f1ec19 100644 --- a/doc/source/stdlib/handmade/structure_annotation-ast-ExprSetInsert.rst +++ b/doc/source/stdlib/handmade/structure_annotation-ast-ExprSetInsert.rst @@ -1,4 +1,4 @@ -Set insert expression, i.e. tab |> insert(key). +Set insert expression, i.e. ``tab |> insert(key)``. Location of the expression in source code Type of the expression Runtime type information of the class of the expression (i.e "ExprConstant", "ExprCall", etc) diff --git a/doc/source/stdlib/handmade/typedef-ast-MoreFunctionFlags.rst b/doc/source/stdlib/handmade/typedef-ast-MoreFunctionFlags.rst index e5c294b5a9..0e85ac72ec 100644 --- a/doc/source/stdlib/handmade/typedef-ast-MoreFunctionFlags.rst +++ b/doc/source/stdlib/handmade/typedef-ast-MoreFunctionFlags.rst @@ -1,6 +1,6 @@ additional properties of the `Function` object. Function is a macro function. -Converts das string arguments to C++ char *. Empty string, which is null in das, is converted to "". +Converts das string arguments to C++ ``char *``. Empty string, which is null in das, is converted to "". Function hash depends on arguments. Function is late initialized. Function is requested to be JIT compiled. diff --git a/doc/source/stdlib/if_not_null.rst b/doc/source/stdlib/if_not_null.rst index 135d85dbd1..2a75970c95 100644 --- a/doc/source/stdlib/if_not_null.rst +++ b/doc/source/stdlib/if_not_null.rst @@ -5,6 +5,8 @@ if_not_null macro ================= +.. das:module:: if_not_null + The IF_NOT_NULL module provides a null-safe call macro. The expression ``ptr |> if_not_null <| call(args)`` expands to a null check followed by a dereferenced call: ``if (ptr != null) { call(*ptr, args) }``. @@ -13,6 +15,8 @@ All functions and symbols are in "if_not_null" module, use require to get access require daslib/if_not_null + + +++++++++++ Call macros +++++++++++ @@ -33,3 +37,4 @@ to:: + diff --git a/doc/source/stdlib/instance_function.rst b/doc/source/stdlib/instance_function.rst index 9c38973197..25400ecc45 100644 --- a/doc/source/stdlib/instance_function.rst +++ b/doc/source/stdlib/instance_function.rst @@ -5,6 +5,8 @@ instance_function function annotation ===================================== +.. das:module:: instance_function + The INSTANCE_FUNCTION module provides the ``[instance_function]`` annotation for creating bound method-like functions. It captures the ``self`` reference at call time, enabling object-oriented dispatch patterns in daslang. @@ -13,6 +15,8 @@ All functions and symbols are in "instance_function" module, use require to get require daslib/instance_function + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -30,3 +34,4 @@ In the followin example body of the function inst will be replaced with body of def inst {} + diff --git a/doc/source/stdlib/interfaces.rst b/doc/source/stdlib/interfaces.rst index a498c10eef..fd8b40c77a 100644 --- a/doc/source/stdlib/interfaces.rst +++ b/doc/source/stdlib/interfaces.rst @@ -5,6 +5,8 @@ Interfaces ========== +.. das:module:: interfaces + The INTERFACES module implements interface-based polymorphism for daslang. It provides the ``[interface]`` annotation for defining abstract interfaces with virtual method tables, supporting multiple implementations and dynamic @@ -40,6 +42,8 @@ Example: :: // output: // Hello, world! + + ++++++++++++++++ Structure macros ++++++++++++++++ @@ -51,6 +55,7 @@ Structure macros Verifies that the annotated class is a valid interface — it may only contain function-typed fields (no data members). Applied via ``[interface]`` annotation. + .. _handle-interfaces-implements: .. das:attribute:: implements @@ -60,3 +65,4 @@ interface method calls to the struct's own methods, and adds a ``get`InterfaceNa method that lazily constructs the proxy. Applied via ``[implements(InterfaceName)]``. + diff --git a/doc/source/stdlib/is_local.rst b/doc/source/stdlib/is_local.rst index 4e7f20c291..3d3d64c807 100644 --- a/doc/source/stdlib/is_local.rst +++ b/doc/source/stdlib/is_local.rst @@ -5,6 +5,8 @@ is_local_xxx ast helpers ======================== +.. das:module:: is_local + The IS_LOCAL module provides compile-time checks for whether a variable is locally allocated (on the stack) versus heap-allocated. This enables writing generic code that optimizes differently based on allocation strategy. @@ -13,6 +15,8 @@ All functions and symbols are in "is_local" module, use require to get access to require daslib/is_local + + ++++++++++++ Scope checks ++++++++++++ @@ -29,6 +33,7 @@ Scope checks Returns true if the expression is local to the current scope. + :Arguments: * **expr** : :ref:`ExpressionPtr ` .. _function-is_local_is_local_or_global_expr_ExpressionPtr: @@ -37,6 +42,7 @@ Returns true if the expression is local to the current scope. Returns true if expression is local to the current scope or global scope. + :Arguments: * **expr** : :ref:`ExpressionPtr ` .. _function-is_local_is_scope_expr_ExpressionPtr: @@ -45,6 +51,7 @@ Returns true if expression is local to the current scope or global scope. Returns true if the expression is a scoped expression, i.e. eventually points to a variable. + :Arguments: * **expr** : :ref:`ExpressionPtr ` .. _function-is_local_is_shared_expr_ExpressionPtr: @@ -53,6 +60,7 @@ Returns true if the expression is a scoped expression, i.e. eventually points to Returns true if the expression refers to a global shared variable. + :Arguments: * **expr** : :ref:`ExpressionPtr ` .. _function-is_local_is_temp_safe_ExpressionPtr: @@ -62,6 +70,7 @@ Returns true if the expression refers to a global shared variable. Returns true if the expression had no calls, [] or table [] operators of any kind. This is used to check expression can be safely casted to temp type. + :Arguments: * **expr** : :ref:`ExpressionPtr ` diff --git a/doc/source/stdlib/jobque.rst b/doc/source/stdlib/jobque.rst index aa7ba277f4..2ca3c2f096 100644 --- a/doc/source/stdlib/jobque.rst +++ b/doc/source/stdlib/jobque.rst @@ -5,6 +5,8 @@ Jobs and threads ================ +.. das:module:: jobque + The JOBQUE module provides low-level job queue and threading primitives. It includes thread-safe channels for inter-thread communication, lock boxes for shared data access, job status tracking, and fine-grained thread @@ -36,6 +38,8 @@ Example: :: // after inc = 11 // after dec = 10 + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -50,18 +54,21 @@ Handled structures Whether the job has completed execution. + .. _function-jobque__dot__rq_isValid_JobStatus_implicit: .. das:function:: JobStatus implicit.isValid() : bool Whether the job status object refers to a valid, active job. + .. _function-jobque__dot__rq_size_JobStatus_implicit: .. das:function:: JobStatus implicit.size() : int Returns the current entry count of the JobStatus or Channel. + :Properties: * **isReady** : bool * **isValid** : bool @@ -71,6 +78,7 @@ Returns the current entry count of the JobStatus or Channel. Job status indicator (ready or not, as well as entry count). + .. _handle-jobque-Channel: .. das:attribute:: Channel @@ -81,12 +89,14 @@ Returns the current entry count of the JobStatus or Channel. Whether the channel or pipe contains no remaining elements. + .. _function-jobque__dot__rq_total_Channel_implicit: .. das:function:: Channel implicit.total() : int Total number of elements that have been added to the pipe. + :Properties: * **isEmpty** : bool * **total** : int @@ -94,6 +104,7 @@ Total number of elements that have been added to the pipe. Channel provides a way to communicate between multiple contexts, including threads and jobs. Channel has internal entry count. + .. _handle-jobque-LockBox: .. das:attribute:: LockBox @@ -101,6 +112,7 @@ Total number of elements that have been added to the pipe. Lockbox. Similar to channel, only for single object. + .. _handle-jobque-Atomic32: .. das:attribute:: Atomic32 @@ -108,6 +120,7 @@ Total number of elements that have been added to the pipe. Atomic 32 bit integer. + .. _handle-jobque-Atomic64: .. das:attribute:: Atomic64 @@ -115,6 +128,8 @@ Total number of elements that have been added to the pipe. Atomic 64 bit integer. + + +++++++++++++++++++++++++++ Channel, JobStatus, Lockbox +++++++++++++++++++++++++++ @@ -122,15 +137,15 @@ Channel, JobStatus, Lockbox * :ref:`add_ref (status: JobStatus? implicit) ` * :ref:`append (channel: JobStatus? implicit; size: int) : int ` * :ref:`channel_create () : Channel? ` - * :ref:`channel_remove (channel: Channel?& implicit) ` + * :ref:`channel_remove (channel: Channel?& implicit) ` * :ref:`job_status_create () : JobStatus? ` - * :ref:`job_status_remove (jobStatus: JobStatus?& implicit) ` + * :ref:`job_status_remove (jobStatus: JobStatus?& implicit) ` * :ref:`join (job: JobStatus? implicit) ` * :ref:`lock_box_create () : LockBox? ` - * :ref:`lock_box_remove (box: LockBox?& implicit) ` + * :ref:`lock_box_remove (box: LockBox?& implicit) ` * :ref:`notify (job: JobStatus? implicit) ` - * :ref:`notify_and_release (job: JobStatus?& implicit) ` - * :ref:`release (status: JobStatus?& implicit) ` + * :ref:`notify_and_release (job: JobStatus?& implicit) ` + * :ref:`release (status: JobStatus?& implicit) ` .. _function-jobque_add_ref_JobStatus_q__implicit: @@ -138,6 +153,7 @@ Channel, JobStatus, Lockbox Increases the reference count of a ``JobStatus`` or ``Channel``, preventing premature deletion. + :Arguments: * **status** : :ref:`JobStatus `? implicit .. _function-jobque_append_JobStatus_q__implicit_int: @@ -146,6 +162,7 @@ Increases the reference count of a ``JobStatus`` or ``Channel``, preventing prem Increases the entry count of the channel, signaling that new work has been added. + :Arguments: * **channel** : :ref:`JobStatus `? implicit * **size** : int @@ -159,7 +176,8 @@ Increases the entry count of the channel, signaling that new work has been added Creates a new ``Channel`` for inter-thread communication and synchronization. -.. _function-jobque_channel_remove_Channel_q__implicit: + +.. _function-jobque_channel_remove_Channel_q__ref__implicit: .. das:function:: channel_remove(channel: Channel?& implicit) @@ -168,7 +186,8 @@ Creates a new ``Channel`` for inter-thread communication and synchronization. Destroys a ``Channel`` and releases its resources. -:Arguments: * **channel** : :ref:`Channel `?& implicit + +:Arguments: * **channel** : :ref:`Channel `?\ & implicit .. _function-jobque_job_status_create: @@ -176,7 +195,8 @@ Destroys a ``Channel`` and releases its resources. Creates a new ``JobStatus`` object for tracking the completion state of asynchronous jobs. -.. _function-jobque_job_status_remove_JobStatus_q__implicit: + +.. _function-jobque_job_status_remove_JobStatus_q__ref__implicit: .. das:function:: job_status_remove(jobStatus: JobStatus?& implicit) @@ -185,7 +205,8 @@ Creates a new ``JobStatus`` object for tracking the completion state of asynchro Destroys a ``JobStatus`` object and releases its resources. -:Arguments: * **jobStatus** : :ref:`JobStatus `?& implicit + +:Arguments: * **jobStatus** : :ref:`JobStatus `?\ & implicit .. _function-jobque_join_JobStatus_q__implicit: @@ -193,6 +214,7 @@ Destroys a ``JobStatus`` object and releases its resources. Blocks the current thread until the job or channel's entry count reaches zero, indicating all work is complete. + :Arguments: * **job** : :ref:`JobStatus `? implicit .. _function-jobque_lock_box_create: @@ -201,7 +223,8 @@ Blocks the current thread until the job or channel's entry count reaches zero, i Creates a new ``LockBox`` for thread-safe shared access to a single value. -.. _function-jobque_lock_box_remove_LockBox_q__implicit: + +.. _function-jobque_lock_box_remove_LockBox_q__ref__implicit: .. das:function:: lock_box_remove(box: LockBox?& implicit) @@ -210,7 +233,8 @@ Creates a new ``LockBox`` for thread-safe shared access to a single value. Destroys a ``LockBox`` and releases its resources. -:Arguments: * **box** : :ref:`LockBox `?& implicit + +:Arguments: * **box** : :ref:`LockBox `?\ & implicit .. _function-jobque_notify_JobStatus_q__implicit: @@ -218,23 +242,27 @@ Destroys a ``LockBox`` and releases its resources. Decreases the channel's entry count, signaling that one unit of work has completed. + :Arguments: * **job** : :ref:`JobStatus `? implicit -.. _function-jobque_notify_and_release_JobStatus_q__implicit: +.. _function-jobque_notify_and_release_JobStatus_q__ref__implicit: .. das:function:: notify_and_release(job: JobStatus?& implicit) Decreases the entry count and the reference count of a ``Channel`` or ``JobStatus`` in a single operation. -:Arguments: * **job** : :ref:`JobStatus `?& implicit -.. _function-jobque_release_JobStatus_q__implicit: +:Arguments: * **job** : :ref:`JobStatus `?\ & implicit + +.. _function-jobque_release_JobStatus_q__ref__implicit: .. das:function:: release(status: JobStatus?& implicit) Decreases the reference count of a ``JobStatus`` or ``Channel``; the object is deleted when the count reaches zero. -:Arguments: * **status** : :ref:`JobStatus `?& implicit + +:Arguments: * **status** : :ref:`JobStatus `?\ & implicit + +++++++ Queries @@ -250,18 +278,22 @@ Queries Returns the total number of hardware threads allocated to the job system. + .. _function-jobque_get_total_hw_threads: .. das:function:: get_total_hw_threads() : int Returns the total number of hardware threads available on the system. + .. _function-jobque_is_job_que_shutting_down: .. das:function:: is_job_que_shutting_down() : bool Returns ``true`` if the job queue infrastructure is shutting down or has not been initialized. + + ++++++++++++++++++++ Internal invocations ++++++++++++++++++++ @@ -276,6 +308,7 @@ Internal invocations Creates a new debugger tick thread for servicing debug connections. + :Arguments: * **block** : block implicit .. _function-jobque_new_job_invoke_lambda_ls__c_void_gr__function_ls__c_void_gr__int: @@ -284,6 +317,7 @@ Creates a new debugger tick thread for servicing debug connections. Clones the current context, moves the attached lambda into it, and submits it to the job queue. + :Arguments: * **lambda** : lambda * **function** : function @@ -296,12 +330,14 @@ Clones the current context, moves the attached lambda into it, and submits it to Clones the current context, moves the attached lambda into it, and runs it on a new dedicated thread. + :Arguments: * **lambda** : lambda * **function** : function * **lambdaSize** : int + ++++++++++++ Construction ++++++++++++ @@ -322,6 +358,7 @@ with_channel Creates a ``Channel`` scoped to the given block and automatically destroys it afterward. + :Arguments: * **block** : block<( :ref:`Channel `?):void> implicit .. _function-jobque_with_channel_int_block_ls_Channel_q__c_void_gr_: @@ -336,6 +373,7 @@ Creates a ``Channel`` scoped to the given block and automatically destroys it af Ensures job queue infrastructure is initialized for the duration of the block. + :Arguments: * **block** : block implicit .. _function-jobque_with_job_status_int_block_ls_JobStatus_q__c_void_gr_: @@ -344,6 +382,7 @@ Ensures job queue infrastructure is initialized for the duration of the block. Creates a ``JobStatus`` scoped to the given block and automatically destroys it afterward. + :Arguments: * **total** : int * **block** : block<( :ref:`JobStatus `?):void> implicit @@ -354,16 +393,18 @@ Creates a ``JobStatus`` scoped to the given block and automatically destroys it Creates a ``LockBox`` scoped to the given block and automatically destroys it afterward. + :Arguments: * **block** : block<( :ref:`LockBox `?):void> implicit + ++++++ Atomic ++++++ * :ref:`atomic32_create () : Atomic32? ` - * :ref:`atomic32_remove (atomic: Atomic32?& implicit) ` + * :ref:`atomic32_remove (atomic: Atomic32?& implicit) ` * :ref:`atomic64_create () : Atomic64? ` - * :ref:`atomic64_remove (atomic: Atomic64?& implicit) ` + * :ref:`atomic64_remove (atomic: Atomic64?& implicit) ` * :ref:`dec (atomic: Atomic32? implicit) : int ` * :ref:`dec (atomic: Atomic64? implicit) : int64 ` * :ref:`get (atomic: Atomic32? implicit) : int ` @@ -381,7 +422,8 @@ Atomic Creates an ``Atomic32`` — a thread-safe 32-bit integer for lock-free concurrent access. -.. _function-jobque_atomic32_remove_Atomic32_q__implicit: + +.. _function-jobque_atomic32_remove_Atomic32_q__ref__implicit: .. das:function:: atomic32_remove(atomic: Atomic32?& implicit) @@ -390,7 +432,8 @@ Creates an ``Atomic32`` — a thread-safe 32-bit integer for lock-free concurren Destroys an ``Atomic32`` and releases its resources. -:Arguments: * **atomic** : :ref:`Atomic32 `?& implicit + +:Arguments: * **atomic** : :ref:`Atomic32 `?\ & implicit .. _function-jobque_atomic64_create: @@ -398,7 +441,8 @@ Destroys an ``Atomic32`` and releases its resources. Creates an ``Atomic64`` — a thread-safe 64-bit integer for lock-free concurrent access. -.. _function-jobque_atomic64_remove_Atomic64_q__implicit: + +.. _function-jobque_atomic64_remove_Atomic64_q__ref__implicit: .. das:function:: atomic64_remove(atomic: Atomic64?& implicit) @@ -407,7 +451,8 @@ Creates an ``Atomic64`` — a thread-safe 64-bit integer for lock-free concurren Destroys an ``Atomic64`` and releases its resources. -:Arguments: * **atomic** : :ref:`Atomic64 `?& implicit + +:Arguments: * **atomic** : :ref:`Atomic64 `?\ & implicit dec @@ -419,6 +464,7 @@ dec Atomically decrements the integer value and returns the result. + :Arguments: * **atomic** : :ref:`Atomic32 `? implicit .. _function-jobque_dec_Atomic64_q__implicit: @@ -437,6 +483,7 @@ get Returns the current value of the atomic integer. + :Arguments: * **atomic** : :ref:`Atomic32 `? implicit .. _function-jobque_get_Atomic64_q__implicit: @@ -455,6 +502,7 @@ inc Atomically increments the integer value and returns the result. + :Arguments: * **atomic** : :ref:`Atomic32 `? implicit .. _function-jobque_inc_Atomic64_q__implicit: @@ -473,6 +521,7 @@ set Sets the atomic integer to the specified value. + :Arguments: * **atomic** : :ref:`Atomic32 `? implicit * **value** : int @@ -489,6 +538,7 @@ Sets the atomic integer to the specified value. Creates an ``Atomic32`` scoped to the given block and automatically destroys it afterward. + :Arguments: * **block** : block<( :ref:`Atomic32 `?):void> implicit .. _function-jobque_with_atomic64_block_ls_Atomic64_q__c_void_gr_: @@ -497,6 +547,7 @@ Creates an ``Atomic32`` scoped to the given block and automatically destroys it Creates an ``Atomic64`` scoped to the given block and automatically destroys it afterward. + :Arguments: * **block** : block<( :ref:`Atomic64 `?):void> implicit diff --git a/doc/source/stdlib/jobque_boost.rst b/doc/source/stdlib/jobque_boost.rst index 9e3e1972f0..4b5c11a727 100644 --- a/doc/source/stdlib/jobque_boost.rst +++ b/doc/source/stdlib/jobque_boost.rst @@ -5,6 +5,8 @@ Boost package for jobs and threads ================================== +.. das:module:: jobque_boost + The JOBQUE_BOOST module provides high-level job queue abstractions built on the low-level ``jobque`` primitives. It includes ``with_job``, ``with_job_status``, and channel-based patterns for simplified concurrent programming. @@ -35,6 +37,8 @@ Example: :: // from thread // thread done + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -47,6 +51,7 @@ this macro handles `new_job` and `new_thread` calls. the call is replaced with `new_job_invoke` and `new_thread_invoke` accordingly. a cloning infrastructure is generated for the lambda, which is invoked in the new context. + .. _handle-jobque_boost-ParallelForJobMacro: .. das:attribute:: ParallelForJobMacro @@ -54,6 +59,7 @@ a cloning infrastructure is generated for the lambda, which is invoked in the ne Base macro for parallel_for, parallel_for_each, and parallel_map. Wraps the block body in ``new_job`` and redirects to the runtime implementation. + .. _handle-jobque_boost-ParallelForEachJobMacro: .. das:attribute:: ParallelForEachJobMacro @@ -61,6 +67,7 @@ Wraps the block body in ``new_job`` and redirects to the runtime implementation. This macro handles `parallel_for_each`. Wraps block body in ``new_job`` and redirects to ``_parallel_for_each``. + .. _handle-jobque_boost-ParallelMapJobMacro: .. das:attribute:: ParallelMapJobMacro @@ -68,6 +75,8 @@ Wraps block body in ``new_job`` and redirects to ``_parallel_for_each``. This macro handles `parallel_map`. Wraps block body in ``new_job`` and redirects to ``_parallel_map``. + + +++++++++++ Invocations +++++++++++ @@ -85,6 +94,7 @@ Create a new job. * new job is added to the job queue. * once new job is invoked, lambda is invoked on the new context on the job thread. + :Arguments: * **l** : lambda .. _function-jobque_boost_new_thread_lambda_ls__c_void_gr_: @@ -97,8 +107,10 @@ Create a new thread * new thread is created. * lambda is invoked on the new context on the new thread. + :Arguments: * **l** : lambda + +++++++++ Iteration +++++++++ @@ -119,6 +131,7 @@ this iterator is used to iterate over the channel in order it was pushed. iterator stops once channel is depleted (internal entry counter is 0) iteration can happen on multiple threads or jobs at the same time. + :Arguments: * **channel** : :ref:`Channel `? * **tinfo** : auto(TT) @@ -131,6 +144,7 @@ this iterator is used to iterate over the channel in order it was pushed. iterator stops once channel is depleted (internal entry counter is 0) iteration can happen on multiple threads or jobs at the same time. + :Arguments: * **channel** : :ref:`Channel `? * **tinfo** : auto(TT) @@ -146,9 +160,10 @@ reads input from the channel (in order it was pushed) and invokes the block on e stops once channel is depleted (internal entry counter is 0) this can happen on multiple threads or jobs at the same time. + :Arguments: * **channel** : :ref:`Channel `? - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> .. _function-jobque_boost_for_each_clone_Channel_q__block_ls_res_c_autoTT_hh__c_void_gr_: @@ -158,9 +173,11 @@ reads input from the channel (in order it was pushed) and invokes the block on e stops once channel is depleted (internal entry counter is 0) this can happen on multiple threads or jobs at the same time. + :Arguments: * **channel** : :ref:`Channel `? - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> + ++++++++++++ Passing data @@ -177,6 +194,7 @@ Passing data pushes value to the channel (at the end) + :Arguments: * **channel** : :ref:`Channel `? * **data** : auto? @@ -187,6 +205,7 @@ pushes value to the channel (at the end) pushes values to the channel (at the end) + :Arguments: * **channel** : :ref:`Channel `? * **data** : array @@ -197,6 +216,7 @@ pushes values to the channel (at the end) clones data and pushes values to the channel (at the end) + :Arguments: * **channel** : :ref:`Channel `? * **data** : array @@ -207,10 +227,12 @@ clones data and pushes values to the channel (at the end) clones data and pushes value to the channel (at the end) + :Arguments: * **channel** : :ref:`Channel `? * **data** : auto(TT) + ++++++++++++++ Receiving data ++++++++++++++ @@ -233,9 +255,10 @@ Receiving data reads input from the channel (in order it was pushed) and invokes the block on each input. afterwards input is consumed + :Arguments: * **ch** : :ref:`Channel `? - * **blk** : block<(arg:auto(TT)#):void> + * **blk** : block<(arg:auto(TT)\ #):void> .. _function-jobque_boost_gather_and_forward_Channel_q__Channel_q__block_ls_arg_c_autoTT_hh__c_void_gr_: @@ -244,11 +267,12 @@ afterwards input is consumed reads input from the channel (in order it was pushed) and invokes the block on each input. afterwards input is consumed + :Arguments: * **ch** : :ref:`Channel `? * **toCh** : :ref:`Channel `? - * **blk** : block<(arg:auto(TT)#):void> + * **blk** : block<(arg:auto(TT)\ #):void> .. _function-jobque_boost_gather_ex_Channel_q__block_ls_arg_c_autoTT_hh_;info_c_TypeInfo_const_q_;var_ctx_c_Context_c_void_gr_: @@ -257,9 +281,10 @@ afterwards input is consumed reads input from the channel (in order it was pushed) and invokes the block on each input. afterwards input is consumed + :Arguments: * **ch** : :ref:`Channel `? - * **blk** : block<(arg:auto(TT)#;info: :ref:`TypeInfo `?;ctx: :ref:`Context `):void> + * **blk** : block<(arg:auto(TT)\ #;info: :ref:`TypeInfo `?;ctx: :ref:`Context `):void> .. _function-jobque_boost_peek_Channel_q__block_ls_arg_c_autoTT_hh__c_void_gr_: @@ -268,9 +293,10 @@ afterwards input is consumed reads input from the channel (in order it was pushed) and invokes the block on each input. afterwards input is not consumed + :Arguments: * **ch** : :ref:`Channel `? - * **blk** : block<(arg:auto(TT)#):void> + * **blk** : block<(arg:auto(TT)\ #):void> .. _function-jobque_boost_pop_and_clone_one_Channel_q__block_ls_res_c_autoTT_hh__c_void_gr_: @@ -278,9 +304,10 @@ afterwards input is not consumed reads one command from channel + :Arguments: * **channel** : :ref:`Channel `? - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> .. _function-jobque_boost_pop_one_Channel_q__block_ls_res_c_autoTT_hh__c_void_gr_: @@ -291,9 +318,10 @@ reads one command from channel reads one command from channel + :Arguments: * **channel** : :ref:`Channel `? - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> .. _function-jobque_boost_pop_with_timeout_Channel_q__int_block_ls_res_c_autoTT_hh__c_void_gr_: @@ -302,11 +330,12 @@ reads one command from channel Pop from channel with timeout in milliseconds. Returns true if an item was available within the timeout, false if timed out or channel exhausted. + :Arguments: * **channel** : :ref:`Channel `? * **timeout_ms** : int - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> .. _function-jobque_boost_pop_with_timeout_clone_Channel_q__int_block_ls_res_c_autoTT_hh__c_void_gr_: @@ -315,11 +344,12 @@ Returns true if an item was available within the timeout, false if timed out or Pop from channel with timeout and clone. Returns true if an item was available within the timeout. The popped value is cloned to the current context before invoking the block. + :Arguments: * **channel** : :ref:`Channel `? * **timeout_ms** : int - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> .. _function-jobque_boost_try_pop_Channel_q__block_ls_res_c_autoTT_hh__c_void_gr_: @@ -328,9 +358,10 @@ The popped value is cloned to the current context before invoking the block. Non-blocking pop from channel. Returns true if an item was available, false if channel was empty. Does not wait for data — returns immediately. + :Arguments: * **channel** : :ref:`Channel `? - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> .. _function-jobque_boost_try_pop_clone_Channel_q__block_ls_res_c_autoTT_hh__c_void_gr_: @@ -339,19 +370,21 @@ Does not wait for data — returns immediately. Non-blocking pop with clone from channel. Returns true if an item was available, false if channel was empty. The popped value is cloned to the current context before invoking the block. + :Arguments: * **channel** : :ref:`Channel `? - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> + +++++++++++++++ Synchronization +++++++++++++++ - * :ref:`done (var status: JobStatus?&) ` + * :ref:`done (var status: JobStatus?&) ` * :ref:`with_wait_group (blk: block\<(var status:JobStatus?):void\>) ` * :ref:`with_wait_group (count: int; blk: block\<(var status:JobStatus?):void\>) ` -.. _function-jobque_boost_done_JobStatus_q_: +.. _function-jobque_boost_done_JobStatus_q__ref_: .. das:function:: done(status: JobStatus?&) @@ -359,7 +392,8 @@ Mark one unit of work as done in a wait group. Alias for ``notify_and_release``. Decrements the notification counter and releases the reference. Sets the pointer to null, preventing double-release. -:Arguments: * **status** : :ref:`JobStatus `?& + +:Arguments: * **status** : :ref:`JobStatus `?\ & with_wait_group @@ -373,6 +407,7 @@ Creates a wait group starting at count 0 with auto-join. Use ``append`` to dynamically add expected notifications before dispatching work. The block returns only after all notifications have been received. + :Arguments: * **blk** : block<(status: :ref:`JobStatus `?):void> .. _function-jobque_boost_with_wait_group_int_block_ls_var_status_c_JobStatus_q__c_void_gr_: @@ -381,6 +416,7 @@ The block returns only after all notifications have been received. ---- + ++++++++++++++++++ Parallel execution ++++++++++++++++++ @@ -402,6 +438,7 @@ via ``new_job`` and call ``wg |> notify_and_release`` when each job finishes. ``parallel_for`` blocks until all notifications are received (via internal ``with_wait_group``). Requires ``with_job_que`` context. + :Arguments: * **range_begin** : int * **range_end** : int @@ -421,6 +458,7 @@ The block should dispatch ``new_job`` calls that process ``arr[i]`` for ``i`` in then call ``wg |> notify_and_release``. Blocks until all jobs finish. Requires ``with_job_que`` context. + :Arguments: * **arr** : array * **num_jobs** : int @@ -437,6 +475,7 @@ on the calling thread with ``(chunk_begin_idx, chunk_end_idx, results_channel, w Blocks until all jobs finish. Results are available in ``results_channel`` after this call returns. Requires ``with_job_que`` context. + :Arguments: * **arr** : array * **num_jobs** : int @@ -451,6 +490,7 @@ Requires ``with_job_que`` context. this one is stub for _parallel_for + :Arguments: * **range_begin** : int * **range_end** : int @@ -468,6 +508,7 @@ Partitions array indices ``[0..length(arr))`` into ``num_jobs`` chunks. The block body is automatically wrapped in ``new_job``. Blocks until all jobs finish. Requires ``with_job_que`` context. + :Arguments: * **arr** : array * **num_jobs** : int @@ -483,6 +524,7 @@ The block body is automatically wrapped in ``new_job``. Blocks until all jobs finish. Results are available in ``results_channel`` after this call returns. Requires ``with_job_que`` context. + :Arguments: * **arr** : array * **num_jobs** : int @@ -491,6 +533,7 @@ Requires ``with_job_que`` context. * **blk** : block<(job_begin:int;job_end:int;ch: :ref:`Channel `?;wg: :ref:`JobStatus `?):void> + ++++++++++++++++++ LockBox operations ++++++++++++++++++ @@ -507,6 +550,7 @@ LockBox operations clear value from the lock box + :Arguments: * **box** : :ref:`LockBox `? * **type_** : auto(TT) @@ -517,9 +561,10 @@ clear value from the lock box reads value from the lock box and invokes the block on it + :Arguments: * **box** : :ref:`LockBox `? - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> set @@ -531,6 +576,7 @@ set sets value to the lock box + :Arguments: * **box** : :ref:`LockBox `? * **data** : auto? @@ -547,9 +593,11 @@ sets value to the lock box update value in the lock box and invokes the block on it + :Arguments: * **box** : :ref:`LockBox `? - * **blk** : block<(res:auto(TT)#):void> + * **blk** : block<(res:auto(TT)\ #):void> + ++++++++++++++++++++++++ Internal capture details @@ -568,6 +616,7 @@ Internal capture details this function is used to capture a channel that is used by the jobque. + :Arguments: * **ch** : :ref:`Channel `? .. _function-jobque_boost_capture_jobque_job_status_JobStatus_q_: @@ -576,6 +625,7 @@ this function is used to capture a channel that is used by the jobque. this function is used to capture a job status that is used by the jobque. + :Arguments: * **js** : :ref:`JobStatus `? .. _function-jobque_boost_capture_jobque_lock_box_LockBox_q_: @@ -584,6 +634,7 @@ this function is used to capture a job status that is used by the jobque. this function is used to capture a lock box that is used by the jobque. + :Arguments: * **js** : :ref:`LockBox `? .. _function-jobque_boost_release_capture_jobque_channel_Channel_q_: @@ -592,6 +643,7 @@ this function is used to capture a lock box that is used by the jobque. this function is used to release a channel that is used by the jobque. + :Arguments: * **ch** : :ref:`Channel `? .. _function-jobque_boost_release_capture_jobque_job_status_JobStatus_q_: @@ -600,6 +652,7 @@ this function is used to release a channel that is used by the jobque. this function is used to release a job status that is used by the jobque. + :Arguments: * **js** : :ref:`JobStatus `? .. _function-jobque_boost_release_capture_jobque_lock_box_LockBox_q_: @@ -608,6 +661,7 @@ this function is used to release a job status that is used by the jobque. this function is used to release a lock box that is used by the jobque. + :Arguments: * **js** : :ref:`LockBox `? diff --git a/doc/source/stdlib/json.rst b/doc/source/stdlib/json.rst index 74ef34a59a..3ae637e90b 100644 --- a/doc/source/stdlib/json.rst +++ b/doc/source/stdlib/json.rst @@ -5,6 +5,8 @@ JSON manipulation library ========================= +.. das:module:: json + The JSON module implements JSON parsing and serialization. It provides ``read_json`` for parsing JSON text into a ``JsonValue`` tree, ``write_json`` for serializing back to text, and ``JV`` helpers for constructing @@ -34,6 +36,8 @@ Example: :: // output: // json: [1,2,3] + + ++++++++++++ Type aliases ++++++++++++ @@ -59,6 +63,7 @@ Single JSON element. * **_null** : void? - JSON null + .. _alias-Token: .. das:attribute:: variant Token @@ -80,6 +85,8 @@ JSON input stream token. * **_error** : string - error token + + ++++++++++ Structures ++++++++++ @@ -93,6 +100,7 @@ JSON value, wraps any JSON element. :Fields: * **value** : :ref:`JsValue ` - value of the JSON element + .. _struct-json-TokenAt: .. das:attribute:: TokenAt @@ -106,6 +114,8 @@ JSON parsing token. Contains token and its position. * **row** : int - token position in the input stream + + ++++++++++++++++ Value conversion ++++++++++++++++ @@ -140,6 +150,7 @@ JV Creates `JsonValue` out of string value. + :Arguments: * **v** : string .. _function-json_JV_double: @@ -218,12 +229,14 @@ Creates `JsonValue` out of string value. Creates `JsonValue` representing `null`. + + ++++++++++++++ Read and write ++++++++++++++ - * :ref:`read_json (text: array\; var error: string&) : JsonValue? ` - * :ref:`read_json (text: string implicit; var error: string&) : JsonValue? ` + * :ref:`read_json (text: array\; var error: string&) : JsonValue? ` + * :ref:`read_json (text: string implicit; var error: string&) : JsonValue? ` * :ref:`write_json (val: JsonValue?#) : string ` * :ref:`write_json (val: JsonValue?) : string ` @@ -231,18 +244,19 @@ Read and write read_json ^^^^^^^^^ -.. _function-json_read_json_array_ls_uint8_gr__string: +.. _function-json_read_json_array_ls_uint8_gr__string_ref_: .. das:function:: read_json(text: array; error: string&) : JsonValue? reads JSON from the `text` array of uint8. if `error` is not empty, it contains the parsing error message. + :Arguments: * **text** : array - * **error** : string& + * **error** : string\ & -.. _function-json_read_json_string_implicit_string: +.. _function-json_read_json_string_implicit_string_ref_: .. das:function:: read_json(text: string implicit; error: string&) : JsonValue? @@ -258,7 +272,8 @@ write_json Overload accepting temporary type -:Arguments: * **val** : :ref:`JsonValue `?# + +:Arguments: * **val** : :ref:`JsonValue `?\ # .. _function-json_write_json_JsonValue_q_: @@ -266,6 +281,7 @@ Overload accepting temporary type ---- + +++++++++++++++ JSON properties +++++++++++++++ @@ -280,6 +296,7 @@ JSON properties if `value` is true, then duplicate keys are allowed in objects. the later key overwrites the earlier one. + :Arguments: * **value** : bool .. _function-json_set_no_empty_arrays_bool: @@ -288,6 +305,7 @@ if `value` is true, then duplicate keys are allowed in objects. the later key ov if `value` is true, then empty arrays are not written at all + :Arguments: * **value** : bool .. _function-json_set_no_trailing_zeros_bool: @@ -296,8 +314,10 @@ if `value` is true, then empty arrays are not written at all if `value` is true, then numbers are written without trailing zeros. + :Arguments: * **value** : bool + +++++++++++ Broken JSON +++++++++++ @@ -314,6 +334,7 @@ fixes broken json. so far supported 3. extra , at the end of object or array 4. /uXXXXXX sequences in the middle of white space + :Arguments: * **bad** : string diff --git a/doc/source/stdlib/json_boost.rst b/doc/source/stdlib/json_boost.rst index 2d2f5b9411..80634a776b 100644 --- a/doc/source/stdlib/json_boost.rst +++ b/doc/source/stdlib/json_boost.rst @@ -5,6 +5,8 @@ Boost package for JSON ====================== +.. das:module:: json_boost + The JSON_BOOST module extends JSON support with operator overloads for convenient field access (``?[]``), null-coalescing (``??``), and automatic struct-to-JSON conversion macros (``from_JsValue``, ``to_JsValue``). @@ -39,6 +41,8 @@ Example: :: // name = Alice // age = 30 + + ++++++++++ Structures ++++++++++ @@ -60,6 +64,8 @@ Per-field serialization options for JSON struct conversion. * **optional** : bool - whether the field is optional + + +++++++++++++ Reader macros +++++++++++++ @@ -69,12 +75,15 @@ Reader macros .. das:attribute:: json This macro implements embedding of the JSON object into the program:: - var jsv = %json~ - { - "name": "main_window", - "value": 500, - "size": [1,2,3] - } %% + + var jsv = %json~ + { + "name": "main_window", + "value": 500, + "size": [1,2,3] + } %% + + ++++++++++++++ Variant macros @@ -87,21 +96,23 @@ Variant macros This macro is used to implement `is json_value` and `as json_value` runtime checks. It essentially substitutes `value as name` with `value.value as name` and `value is name` with `value.value is name`. + + ++++++++++++++++ Value conversion ++++++++++++++++ - * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto; val9: auto) : JsonValue? ` - * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto) : JsonValue? ` - * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto) : JsonValue? ` - * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto; val9: auto; val10: auto) : JsonValue? ` - * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto) : JsonValue? ` - * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto) : JsonValue? ` - * :ref:`JV (val1: auto; val2: auto) : JsonValue? ` - * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto) : JsonValue? ` - * :ref:`JV (val1: auto; val2: auto; val3: auto) : JsonValue? ` - * :ref:`JV (v: auto(VecT)) : auto ` - * :ref:`JV (value: auto(TT)) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto; val9: auto) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto; val9: auto; val10: auto) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto) : JsonValue? ` + * :ref:`JV (val1: auto; val2: auto; val3: auto) : JsonValue? ` + * :ref:`JV (v: auto(VecT)) : auto ` + * :ref:`JV (value: auto(TT)) : JsonValue? ` * :ref:`from_JV (v: JsonValue const?; ent: uint16; defV: uint16 = uint16(0)) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: uint8; defV: uint8 = uint8(0)) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: int8; defV: int8 = int8(0)) : auto ` @@ -110,14 +121,14 @@ Value conversion * :ref:`from_JV (v: JsonValue const?; ent: uint; defV: uint = 0x0) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: int; defV: int = 0) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: bitfield16:uint16\<\>; defV: bitfield16 = bitfield16()) : auto ` - * :ref:`from_JV (v: JsonValue const?; ent: auto(VecT); defV: VecT = VecT()) : auto ` + * :ref:`from_JV (v: JsonValue const?; ent: auto(VecT); defV: VecT = VecT()) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: bitfield64:uint64\<\>; defV: bitfield64 = bitfield64()) : auto ` - * :ref:`from_JV (v: JsonValue const?; anything: auto(TT)) : auto ` + * :ref:`from_JV (v: JsonValue const?; anything: auto(TT)) : auto ` * :ref:`from_JV (v: JsonValue const?; anything: table\) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: int64; defV: int64 = 0) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: float; defV: float = 0f) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: string; defV: string = "") : auto ` - * :ref:`from_JV (v: JsonValue const?; ent: auto(EnumT); defV: EnumT = EnumT()) : EnumT ` + * :ref:`from_JV (v: JsonValue const?; ent: auto(EnumT); defV: EnumT = EnumT()) : EnumT ` * :ref:`from_JV (v: JsonValue const?; ent: bool; defV: bool = false) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: double; defV: double = 0lf) : auto ` * :ref:`from_JV (v: JsonValue const?; ent: uint64; defV: uint64 = 0x0) : auto ` @@ -127,12 +138,13 @@ Value conversion JV ^^ -.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_auto_auto_auto_0x2b4: +.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_auto_auto_auto_0x2b5: .. das:function:: JV(val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto; val9: auto) : JsonValue? Creates array of nine JsonValues. + :Arguments: * **val1** : auto * **val2** : auto @@ -151,43 +163,43 @@ Creates array of nine JsonValues. * **val9** : auto -.. _function-json_boost_JV_auto_auto_auto_auto_0x29b: +.. _function-json_boost_JV_auto_auto_auto_auto_0x29c: .. das:function:: JV(val1: auto; val2: auto; val3: auto; val4: auto) : JsonValue? -.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_auto_0x2aa: +.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_auto_0x2ab: .. das:function:: JV(val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto) : JsonValue? -.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_auto_auto_auto_auto_0x2b9: +.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_auto_auto_auto_auto_0x2ba: .. das:function:: JV(val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto; val9: auto; val10: auto) : JsonValue? -.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_0x2a5: +.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_0x2a6: .. das:function:: JV(val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto) : JsonValue? -.. _function-json_boost_JV_auto_auto_auto_auto_auto_0x2a0: +.. _function-json_boost_JV_auto_auto_auto_auto_auto_0x2a1: .. das:function:: JV(val1: auto; val2: auto; val3: auto; val4: auto; val5: auto) : JsonValue? -.. _function-json_boost_JV_auto_auto_0x291: +.. _function-json_boost_JV_auto_auto_0x292: .. das:function:: JV(val1: auto; val2: auto) : JsonValue? -.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_auto_auto_0x2af: +.. _function-json_boost_JV_auto_auto_auto_auto_auto_auto_auto_auto_0x2b0: .. das:function:: JV(val1: auto; val2: auto; val3: auto; val4: auto; val5: auto; val6: auto; val7: auto; val8: auto) : JsonValue? -.. _function-json_boost_JV_auto_auto_auto_0x296: +.. _function-json_boost_JV_auto_auto_auto_0x297: .. das:function:: JV(val1: auto; val2: auto; val3: auto) : JsonValue? -.. _function-json_boost_JV_autoVecT_0x17c: +.. _function-json_boost_JV_autoVecT_0x17d: .. das:function:: JV(v: auto(VecT)) : auto -.. _function-json_boost_JV_autoTT_0x21e: +.. _function-json_boost_JV_autoTT_0x21f: .. das:function:: JV(value: auto(TT)) : JsonValue? @@ -203,6 +215,7 @@ from_JV Parse a JSON value and return the corresponding native value. + :Arguments: * **v** : :ref:`JsonValue `? * **ent** : uint16 @@ -237,7 +250,7 @@ Parse a JSON value and return the corresponding native value. .. das:function:: from_JV(v: JsonValue const?; ent: bitfield16:uint16<>; defV: bitfield16 = bitfield16()) : auto -.. _function-json_boost_from_JV_JsonValue_const_q__autoVecT_VecT_0x188: +.. _function-json_boost_from_JV_JsonValue_const_q__autoVecT_VecT_0x189: .. das:function:: from_JV(v: JsonValue const?; ent: auto(VecT); defV: VecT = VecT()) : auto @@ -245,7 +258,7 @@ Parse a JSON value and return the corresponding native value. .. das:function:: from_JV(v: JsonValue const?; ent: bitfield64:uint64<>; defV: bitfield64 = bitfield64()) : auto -.. _function-json_boost_from_JV_JsonValue_const_q__autoTT_0x1c6: +.. _function-json_boost_from_JV_JsonValue_const_q__autoTT_0x1c7: .. das:function:: from_JV(v: JsonValue const?; anything: auto(TT)) : auto @@ -265,7 +278,7 @@ Parse a JSON value and return the corresponding native value. .. das:function:: from_JV(v: JsonValue const?; ent: string; defV: string = "") : auto -.. _function-json_boost_from_JV_JsonValue_const_q__autoEnumT_EnumT_0xf5: +.. _function-json_boost_from_JV_JsonValue_const_q__autoEnumT_EnumT_0xf6: .. das:function:: from_JV(v: JsonValue const?; ent: auto(EnumT); defV: EnumT = EnumT()) : EnumT @@ -287,16 +300,17 @@ Parse a JSON value and return the corresponding native value. ---- + ++++++++++++++++++++++++ Element access operators ++++++++++++++++++++++++ * :ref:`JsonValue const? ==const?. (a: JsonValue const? ==const; key: string) : JsonValue? ` - * :ref:`JsonValue const? ==const?[] (a: JsonValue const? ==const; key: string) : JsonValue? ` - * :ref:`JsonValue const? ==const?[] (a: JsonValue const? ==const; idx: int) : JsonValue? ` + * :ref:`JsonValue const? ==const?[] (a: JsonValue const? ==const; key: string) : JsonValue? ` + * :ref:`JsonValue const? ==const?[] (a: JsonValue const? ==const; idx: int) : JsonValue? ` * :ref:`JsonValue? ==const?. (var a: JsonValue? ==const; key: string) : JsonValue? ` - * :ref:`JsonValue? ==const?[] (var a: JsonValue? ==const; idx: int) : JsonValue? ` - * :ref:`JsonValue? ==const?[] (var a: JsonValue? ==const; key: string) : JsonValue? ` + * :ref:`JsonValue? ==const?[] (var a: JsonValue? ==const; idx: int) : JsonValue? ` + * :ref:`JsonValue? ==const?[] (var a: JsonValue? ==const; key: string) : JsonValue? ` .. _function-json_boost__q__dot__JsonValue_const_q___eq__eq_const_string: @@ -304,6 +318,7 @@ Element access operators Returns the value of the key in the JSON object, if it exists. + :Arguments: * **a** : :ref:`JsonValue `?! * **key** : string @@ -312,17 +327,18 @@ Returns the value of the key in the JSON object, if it exists. JsonValue const? ==const?[] ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-json_boost__q__JsonValue_const_q___eq__eq_const_string: +.. _function-json_boost__q__lb__rb__JsonValue_const_q___eq__eq_const_string: .. das:function:: JsonValue const? ==const?[](a: JsonValue const? ==const; key: string) : JsonValue? Returns the value of the key in the JSON object, if it exists. + :Arguments: * **a** : :ref:`JsonValue `?! * **key** : string -.. _function-json_boost__q__JsonValue_const_q___eq__eq_const_int: +.. _function-json_boost__q__lb__rb__JsonValue_const_q___eq__eq_const_int: .. das:function:: JsonValue const? ==const?[](a: JsonValue const? ==const; idx: int) : JsonValue? @@ -334,6 +350,7 @@ Returns the value of the key in the JSON object, if it exists. Returns the value of the key in the JSON object, if it exists. + :Arguments: * **a** : :ref:`JsonValue `?! * **key** : string @@ -342,22 +359,24 @@ Returns the value of the key in the JSON object, if it exists. JsonValue? ==const?[] ^^^^^^^^^^^^^^^^^^^^^ -.. _function-json_boost__q___JsonValue_q___eq__eq_const_int: +.. _function-json_boost__q__lb__rb___JsonValue_q___eq__eq_const_int: .. das:function:: JsonValue? ==const?[](a: JsonValue? ==const; idx: int) : JsonValue? Returns the value of the index in the JSON array, if it exists. + :Arguments: * **a** : :ref:`JsonValue `?! * **idx** : int -.. _function-json_boost__q___JsonValue_q___eq__eq_const_string: +.. _function-json_boost__q__lb__rb___JsonValue_q___eq__eq_const_string: .. das:function:: JsonValue? ==const?[](a: JsonValue? ==const; key: string) : JsonValue? ---- + +++++++++++++++++++++++++ Null coalescing operators +++++++++++++++++++++++++ @@ -385,6 +404,7 @@ JsonValue const??? Returns the value of the JSON object, if it exists, otherwise returns the default value. + :Arguments: * **a** : :ref:`JsonValue `? * **val** : float @@ -435,6 +455,7 @@ Returns the value of the JSON object, if it exists, otherwise returns the defaul ---- + ++++++++++++++++ Value extraction ++++++++++++++++ @@ -448,6 +469,7 @@ Value extraction Returns the value of the JSON object, if it exists. + :Arguments: * **a** : :ref:`JsonValue `?! .. _function-json_boost__q__dot__rq_value__JsonValue_q___eq__eq_const: @@ -456,8 +478,10 @@ Returns the value of the JSON object, if it exists. Returns the value of the JSON object, if it exists. + :Arguments: * **a** : :ref:`JsonValue `?! + ++++++++++++++++++ Annotation parsing ++++++++++++++++++ @@ -470,6 +494,7 @@ Annotation parsing Parse JSON field annotations and return the corresponding JsonFieldState. + :Arguments: * **name** : string * **annotation** : array`>> diff --git a/doc/source/stdlib/linq.rst b/doc/source/stdlib/linq.rst index a628b2a629..67859bdc28 100644 --- a/doc/source/stdlib/linq.rst +++ b/doc/source/stdlib/linq.rst @@ -5,6 +5,8 @@ LINQ ==== +.. das:module:: linq + The LINQ module provides query-style operations on sequences: filtering (``where_``), projection (``select``), sorting (``order``, ``order_by``), deduplication (``distinct``), pagination (``skip``, ``take``), aggregation @@ -33,6 +35,8 @@ Example: :: // output: // 0 2 4 6 8 + + ++++++++++++ Sorting data ++++++++++++ @@ -79,6 +83,7 @@ order Sorts an iterator + :Arguments: * **a** : iterator .. _function-linq_order_iterator_ls_autoTT_gr__block_ls_v1_c_TT;v2_c_TT_c_bool_gr_: @@ -105,6 +110,7 @@ order_by Sorts an array + :Arguments: * **a** : array * **key** : auto @@ -125,6 +131,7 @@ order_by_descending Sorts an iterator in descending order + :Arguments: * **a** : iterator * **key** : auto @@ -141,6 +148,7 @@ Sorts an iterator in descending order Sorts an array in descending order in place + :Arguments: * **buffer** : array * **key** : auto @@ -151,6 +159,7 @@ Sorts an array in descending order in place Sorts an iterator in descending order and returns an array + :Arguments: * **a** : iterator * **key** : auto @@ -161,6 +170,7 @@ Sorts an iterator in descending order and returns an array Sorts an array in place + :Arguments: * **buffer** : array * **key** : auto @@ -171,6 +181,7 @@ Sorts an array in place Sorts an iterator and returns an array + :Arguments: * **a** : iterator * **key** : auto @@ -185,6 +196,7 @@ order_descending Sorts an iterator in descending order + :Arguments: * **a** : iterator .. _function-linq_order_descending_array_ls_autoTT_gr__block_ls_v1_c_TT;v2_c_TT_c_bool_gr_: @@ -211,6 +223,7 @@ order_descending_inplace Sorts an array in descending order in place + :Arguments: * **buffer** : array .. _function-linq_order_descending_inplace_array_ls_autoTT_gr__block_ls_v1_c_TT;v2_c_TT_c_bool_gr_: @@ -229,6 +242,7 @@ order_descending_to_array Sorts an iterator in descending order and returns an array + :Arguments: * **a** : iterator * **fun** : block<(v1:TT;v2:TT):bool> @@ -249,6 +263,7 @@ order_inplace Sorts an array in place + :Arguments: * **buffer** : array .. _function-linq_order_inplace_array_ls_autoTT_gr__block_ls_v1_c_TT;v2_c_TT_c_bool_gr_: @@ -267,6 +282,7 @@ order_to_array Sorts an iterator and returns an array + :Arguments: * **a** : iterator * **fun** : block<(v1:TT;v2:TT):bool> @@ -287,6 +303,7 @@ order_unique_folded sort and remove duplicate elements from an iterator + :Arguments: * **a** : iterator .. _function-linq_order_unique_folded_array_ls_autoTT_gr_: @@ -301,6 +318,7 @@ sort and remove duplicate elements from an iterator sort and remove duplicate elements from an array + :Arguments: * **a** : array @@ -313,6 +331,7 @@ reverse Reverses an array + :Arguments: * **a** : array .. _function-linq_reverse_iterator_ls_autoTT_gr_: @@ -327,6 +346,7 @@ Reverses an array Reverses an array in place + :Arguments: * **buffer** : array .. _function-linq_reverse_to_array_iterator_ls_autoTT_gr_: @@ -335,8 +355,10 @@ Reverses an array in place Reverses an iterator and returns an array + :Arguments: * **a** : iterator + ++++++++++++++ Set operations ++++++++++++++ @@ -387,6 +409,7 @@ distinct Returns distinct elements from an array + :Arguments: * **a** : array .. _function-linq_distinct_iterator_ls_autoTT_gr_: @@ -405,6 +428,7 @@ distinct_by Returns distinct elements from an array based on a key + :Arguments: * **a** : array * **key** : block<(arg:TT):auto> @@ -421,6 +445,7 @@ Returns distinct elements from an array based on a key Returns distinct elements from an array based on a key in place + :Arguments: * **a** : array * **key** : block<(arg:TT):auto> @@ -431,6 +456,7 @@ Returns distinct elements from an array based on a key in place Returns distinct elements from an iterator based on a key and returns an array + :Arguments: * **a** : iterator * **key** : block<(arg:TT):auto> @@ -441,6 +467,7 @@ Returns distinct elements from an iterator based on a key and returns an array Returns distinct elements from an array in place + :Arguments: * **a** : array .. _function-linq_distinct_to_array_iterator_ls_autoTT_gr_: @@ -449,6 +476,7 @@ Returns distinct elements from an array in place Returns distinct elements from an iterator and returns an array + :Arguments: * **a** : iterator @@ -461,6 +489,7 @@ except Returns elements from the first iterator that are not in the second iterator + :Arguments: * **src** : iterator * **exclude** : iterator @@ -481,6 +510,7 @@ except_by Returns elements from the first array that are not in the second array by key + :Arguments: * **src** : array * **exclude** : array @@ -499,6 +529,7 @@ Returns elements from the first array that are not in the second array by key Returns elements from the first iterator that are not in the second iterator by key and returns an array + :Arguments: * **src** : iterator * **exclude** : iterator @@ -511,6 +542,7 @@ Returns elements from the first iterator that are not in the second iterator by Returns elements from the first iterator that are not in the second iterator and returns an array + :Arguments: * **src** : iterator * **exclude** : iterator @@ -525,6 +557,7 @@ intersect Returns elements that are present in both arrays + :Arguments: * **srca** : array * **srcb** : array @@ -545,6 +578,7 @@ intersect_by Returns elements that are present in both arrays by key + :Arguments: * **srca** : array * **srcb** : array @@ -563,6 +597,7 @@ Returns elements that are present in both arrays by key Returns elements that are present in both iterators by key and returns an array + :Arguments: * **srca** : iterator * **srcb** : iterator @@ -575,6 +610,7 @@ Returns elements that are present in both iterators by key and returns an array Returns elements that are present in both iterators and returns an array + :Arguments: * **srca** : iterator * **srcb** : iterator @@ -589,6 +625,7 @@ union Returns distinct elements from the concatenation of two iterators + :Arguments: * **srca** : iterator * **srcb** : iterator @@ -609,6 +646,7 @@ union_by Returns distinct elements from the concatenation of two arrays by key + :Arguments: * **srca** : array * **srcb** : array @@ -627,6 +665,7 @@ Returns distinct elements from the concatenation of two arrays by key Returns distinct elements from the concatenation of two iterators by key and returns an array + :Arguments: * **srca** : iterator * **srcb** : iterator @@ -639,6 +678,7 @@ Returns distinct elements from the concatenation of two iterators by key and ret Returns distinct elements from the concatenation of two iterators and returns an array + :Arguments: * **srca** : iterator * **srcb** : iterator @@ -653,6 +693,7 @@ unique sort and remove duplicate elements from an array + :Arguments: * **a** : array .. _function-linq_unique_iterator_ls_autoTT_gr_: @@ -671,6 +712,7 @@ unique_by sort and remove duplicate elements from an array based on a key + :Arguments: * **a** : array * **key** : block<(arg:TT):auto> @@ -687,6 +729,7 @@ sort and remove duplicate elements from an array based on a key remove duplicate elements from an array based on a key in place + :Arguments: * **a** : array * **key** : block<(arg:TT):auto> @@ -697,6 +740,7 @@ remove duplicate elements from an array based on a key in place sort and remove duplicate elements from an iterator based on a key and returns an array + :Arguments: * **a** : iterator * **key** : block<(arg:TT):auto> @@ -707,6 +751,7 @@ sort and remove duplicate elements from an iterator based on a key and returns a remove duplicate elements from sorted array in place + :Arguments: * **a** : array .. _function-linq_unique_key_auto_0x1fe: @@ -715,6 +760,7 @@ remove duplicate elements from sorted array in place generates unique key of workhorse type for the value + :Arguments: * **a** : auto .. _function-linq_unique_to_array_iterator_ls_autoTT_gr_: @@ -723,8 +769,10 @@ generates unique key of workhorse type for the value sort and remove duplicate elements from an iterator and returns an array + :Arguments: * **a** : iterator + ++++++++++++++++++++++++ Concatenation operations ++++++++++++++++++++++++ @@ -752,6 +800,7 @@ append Appends a value to the end of an array + :Arguments: * **arr** : array * **value** : TT @@ -768,6 +817,7 @@ Appends a value to the end of an array Appends a value to the end of an array in place + :Arguments: * **arr** : array * **value** : TT @@ -778,6 +828,7 @@ Appends a value to the end of an array in place Appends a value to the end of an iterator and returns an array + :Arguments: * **it** : iterator * **value** : TT @@ -792,6 +843,7 @@ concat Concatenates two iterators + :Arguments: * **a** : iterator * **b** : iterator @@ -808,6 +860,7 @@ Concatenates two iterators Concatenates two arrays in place + :Arguments: * **a** : array * **b** : array @@ -818,6 +871,7 @@ Concatenates two arrays in place Concatenates two iterators and returns an array + :Arguments: * **a** : iterator * **b** : iterator @@ -832,6 +886,7 @@ prepend Prepends a value to the beginning of an iterator + :Arguments: * **it** : iterator * **value** : TT @@ -848,6 +903,7 @@ Prepends a value to the beginning of an iterator Prepends a value to the beginning of an array in place + :Arguments: * **arr** : array * **value** : TT @@ -858,10 +914,12 @@ Prepends a value to the beginning of an array in place Prepends a value to the beginning of an iterator and returns an array + :Arguments: * **it** : iterator * **value** : TT + +++++++++++++++++++++ Generation operations +++++++++++++++++++++ @@ -877,6 +935,7 @@ Generation operations Returns the elements of the iterator, or a default value if the iterator is empty + :Arguments: * **src** : iterator .. _function-linq_empty_autoTT_0x8d5: @@ -885,6 +944,7 @@ Returns the elements of the iterator, or a default value if the iterator is empt Returns an empty iterator of the specified type + :Arguments: * **typ** : auto(TT) .. _function-linq_range_sequence_int_int: @@ -893,6 +953,7 @@ Returns an empty iterator of the specified type Generates a sequence of integers within a specified range + :Arguments: * **start** : int * **count** : int @@ -903,10 +964,12 @@ Generates a sequence of integers within a specified range Generates a sequence that contains one repeated value + :Arguments: * **element** : auto(TT) * **count** : int + ++++++++++++++++++++++ Aggregation operations ++++++++++++++++++++++ @@ -950,6 +1013,7 @@ aggregate Aggregates elements in an iterator using a seed and a function + :Arguments: * **src** : iterator * **seed** : auto(AGG) @@ -972,6 +1036,7 @@ average Averages elements in an array + :Arguments: * **src** : array .. _function-linq_average_iterator_ls_autoTT_gr_: @@ -990,6 +1055,7 @@ count Counts elements in an array that satisfy a predicate + :Arguments: * **a** : array * **predicate** : block<(arg:TT):bool> @@ -1018,6 +1084,7 @@ long_count Counts elements in an array, using a long integer + :Arguments: * **a** : array .. _function-linq_long_count_iterator_ls_autoTT_gr_: @@ -1036,6 +1103,7 @@ max Finds the maximum element in an iterator + :Arguments: * **src** : iterator .. _function-linq_max_array_ls_autoTT_gr_: @@ -1054,6 +1122,7 @@ max_by Finds the maximum element in an iterator by key + :Arguments: * **src** : iterator * **key** : auto @@ -1074,6 +1143,7 @@ min Finds the minimum element in an iterator + :Arguments: * **src** : iterator .. _function-linq_min_array_ls_autoTT_gr_: @@ -1092,6 +1162,7 @@ min_by Finds the minimum element in an array by key + :Arguments: * **src** : array * **key** : auto @@ -1112,6 +1183,7 @@ min_max Finds the minimum and maximum elements in an iterator + :Arguments: * **src** : iterator .. _function-linq_min_max_array_ls_autoTT_gr_: @@ -1130,6 +1202,7 @@ min_max_average Finds the minimum, maximum, and average elements in an array + :Arguments: * **src** : array .. _function-linq_min_max_average_iterator_ls_autoTT_gr_: @@ -1148,6 +1221,7 @@ min_max_average_by Finds the minimum, maximum, and average elements in an array by key + :Arguments: * **src** : array * **key** : auto @@ -1168,6 +1242,7 @@ min_max_by Finds the minimum and maximum elements in an iterator by key + :Arguments: * **src** : iterator * **key** : auto @@ -1188,6 +1263,7 @@ sum Sums elements in an array + :Arguments: * **src** : array .. _function-linq_sum_iterator_ls_autoTT_gr_: @@ -1196,6 +1272,7 @@ Sums elements in an array ---- + ++++++++++++++ Filtering data ++++++++++++++ @@ -1214,6 +1291,7 @@ where_ Filters elements in an array based on a predicate + :Arguments: * **src** : array * **predicate** : block<(arg:TT):bool> @@ -1230,10 +1308,12 @@ Filters elements in an array based on a predicate Filters elements in an iterator based on a predicate and returns an array + :Arguments: * **src** : iterator * **predicate** : block<(arg:TT):bool> + +++++++++++++++++ Partitioning data +++++++++++++++++ @@ -1278,6 +1358,7 @@ chunk Splits an array into chunks of a specified size + :Arguments: * **src** : array * **size** : int @@ -1294,6 +1375,7 @@ Splits an array into chunks of a specified size Splits an iterator into chunks of a specified size and returns an array + :Arguments: * **src** : iterator * **size** : int @@ -1308,6 +1390,7 @@ skip Yields all but the first `total` elements + :Arguments: * **src** : iterator * **total** : int @@ -1324,6 +1407,7 @@ Yields all but the first `total` elements Removes the first `total` elements from an array in place + :Arguments: * **arr** : array * **total** : int @@ -1338,6 +1422,7 @@ skip_last Yields all but the last `total` elements from an iterator + :Arguments: * **src** : iterator * **total** : int @@ -1354,6 +1439,7 @@ Yields all but the last `total` elements from an iterator Removes the last `total` elements from an array in place + :Arguments: * **arr** : array * **total** : int @@ -1364,6 +1450,7 @@ Removes the last `total` elements from an array in place Yields all but the last `total` elements from an iterator and returns an array + :Arguments: * **src** : iterator * **total** : int @@ -1374,6 +1461,7 @@ Yields all but the last `total` elements from an iterator and returns an array Yields all but the first `total` elements and returns an array + :Arguments: * **src** : iterator * **total** : int @@ -1388,6 +1476,7 @@ skip_while Skips all elements of an array while the predicate is true + :Arguments: * **src** : array * **predicate** : block<(arg:TT):bool> @@ -1404,6 +1493,7 @@ Skips all elements of an array while the predicate is true Skips all elements of an iterator while the predicate is true and returns an array + :Arguments: * **src** : iterator * **predicate** : block<(arg:TT):bool> @@ -1418,6 +1508,7 @@ take Yields a range of elements from an array + :Arguments: * **src** : array * **from** : range @@ -1446,6 +1537,7 @@ take_inplace Keeps only a range of elements in an array in place + :Arguments: * **arr** : array * **from** : range @@ -1466,6 +1558,7 @@ take_last Yields only the last `total` elements from an iterator + :Arguments: * **src** : iterator * **total** : int @@ -1482,6 +1575,7 @@ Yields only the last `total` elements from an iterator Keeps only the last `total` elements in an array in place + :Arguments: * **arr** : array * **total** : int @@ -1492,6 +1586,7 @@ Keeps only the last `total` elements in an array in place Yields only the last `total` elements from an iterator and returns an array + :Arguments: * **src** : iterator * **total** : int @@ -1506,6 +1601,7 @@ take_to_array Yields only the first `total` elements and returns an array + :Arguments: * **src** : iterator * **total** : int @@ -1526,6 +1622,7 @@ take_while Yields only the elements of an iterator while the predicate is true + :Arguments: * **src** : iterator * **predicate** : block<(arg:TT):bool> @@ -1542,10 +1639,12 @@ Yields only the elements of an iterator while the predicate is true Yields only the elements of an iterator while the predicate is true and returns an array + :Arguments: * **src** : iterator * **predicate** : block<(arg:TT):bool> + +++++++++++++++++++++++++ Join and group operations +++++++++++++++++++++++++ @@ -1570,6 +1669,7 @@ group_by Groups the elements of an iterator according to a specified key selector function + :Arguments: * **source** : iterator * **key** : auto @@ -1590,6 +1690,7 @@ Groups the elements of an iterator according to a specified key selector functio Groups the elements of an iterator according to a specified key selector function and returns an array + :Arguments: * **source** : iterator * **key** : auto @@ -1608,6 +1709,7 @@ group_join we pass TA, and sequence of TB to 'result' + :Arguments: * **srca** : iterator * **srcb** : iterator @@ -1630,6 +1732,7 @@ we pass TA, and sequence of TB to 'result' we pass TA, and sequence of TB to 'result' + :Arguments: * **srca** : iterator * **srcb** : iterator @@ -1650,6 +1753,7 @@ join Joins two arrays based on matching keys (inner join) + :Arguments: * **srca** : array * **srcb** : array @@ -1672,6 +1776,7 @@ Joins two arrays based on matching keys (inner join) Joins two iterators based on matching keys (inner join) and returns an array + :Arguments: * **srca** : iterator * **srcb** : iterator @@ -1682,6 +1787,7 @@ Joins two iterators based on matching keys (inner join) and returns an array * **result** : auto + +++++++++++++ Querying data +++++++++++++ @@ -1705,6 +1811,7 @@ all Returns true if all elements in the array satisfy the predicate + :Arguments: * **src** : array * **predicate** : block<(arg:TT):bool> @@ -1725,6 +1832,7 @@ any Returns true if any element in the array satisfies the predicate + :Arguments: * **src** : array * **predicate** : block<(arg:TT):bool> @@ -1753,6 +1861,7 @@ contains Returns true if the element is present in the iterator + :Arguments: * **src** : iterator * **element** : TT @@ -1763,6 +1872,7 @@ Returns true if the element is present in the iterator ---- + ++++++++++++++++++ Element operations ++++++++++++++++++ @@ -1794,6 +1904,7 @@ element_at Returns the element at the specified index + :Arguments: * **src** : iterator * **index** : int @@ -1814,6 +1925,7 @@ element_at_or_default Returns the element at the specified index, or a default value if the index is out of range + :Arguments: * **src** : iterator * **index** : int @@ -1834,6 +1946,7 @@ first Returns the first element of an iterator + :Arguments: * **src** : iterator .. _function-linq_first_array_ls_autoTT_gr_: @@ -1852,6 +1965,7 @@ first_or_default Returns the first element of an array, or a default value if the array is empty + :Arguments: * **src** : array * **defaultValue** : TT @@ -1872,6 +1986,7 @@ last Returns the last element of an iterator + :Arguments: * **src** : iterator .. _function-linq_last_array_ls_autoTT_gr_: @@ -1890,6 +2005,7 @@ last_or_default Returns the last element of an array, or a default value if the array is empty + :Arguments: * **src** : array * **defaultValue** : TT @@ -1910,6 +2026,7 @@ single Returns the only element of an array, and throws if there is not exactly one element + :Arguments: * **src** : array .. _function-linq_single_iterator_ls_autoTT_gr_: @@ -1928,6 +2045,7 @@ single_or_default Returns the only element of an iterator, or a default value if there is not exactly one element + :Arguments: * **src** : iterator * **defaultValue** : TT @@ -1938,6 +2056,7 @@ Returns the only element of an iterator, or a default value if there is not exac ---- + ++++++++++++++++++++ Transform operations ++++++++++++++++++++ @@ -1974,6 +2093,7 @@ select Projects each element of an array into a new form + :Arguments: * **src** : array .. _function-linq_select_iterator_ls_autoTT_gr_: @@ -2000,6 +2120,7 @@ select_many Projects each element of an iterator to an iterator and flattens the resulting iterators into one iterator + :Arguments: * **src** : iterator * **result_selector** : auto @@ -2028,6 +2149,7 @@ select_many_to_array Projects each element of an iterator to an iterator and flattens the resulting iterators into one array + :Arguments: * **src** : iterator * **collection_selector** : auto @@ -2050,6 +2172,7 @@ select_to_array Projects each element of an iterator into a new form using a selector function and returns an array + :Arguments: * **src** : iterator * **result_selector** : auto @@ -2070,6 +2193,7 @@ zip Merges two iterators into an iterator of tuples + :Arguments: * **a** : iterator * **b** : iterator @@ -2106,6 +2230,7 @@ zip_to_array Merges three iterators into an array of tuples + :Arguments: * **a** : iterator * **b** : iterator @@ -2122,6 +2247,7 @@ Merges three iterators into an array of tuples ---- + +++++++++++++++++++++ Conversion operations +++++++++++++++++++++ @@ -2137,6 +2263,7 @@ Conversion operations Converts an array to an iterator + :Arguments: * **a** : array .. _function-linq_to_sequence_move_array_ls_autoTT_gr_: @@ -2145,6 +2272,7 @@ Converts an array to an iterator Converts an array to an iterator, captures input + :Arguments: * **a** : array @@ -2157,6 +2285,7 @@ to_table Converts an array to a table + :Arguments: * **a** : array * **key** : block<(v:TT):auto> @@ -2169,6 +2298,7 @@ Converts an array to a table ---- + ++++++++++++++++++++ Comparators and keys ++++++++++++++++++++ @@ -2193,6 +2323,7 @@ less Compares two tuples, returns true if first is less than second + :Arguments: * **a** : tuple * **b** : tuple @@ -2225,6 +2356,7 @@ sequence_equal Checks if two sequences are equal + :Arguments: * **first** : iterator * **second** : iterator @@ -2245,6 +2377,7 @@ sequence_equal_by Checks if two sequences are equal by key + :Arguments: * **first** : iterator * **second** : iterator diff --git a/doc/source/stdlib/linq_boost.rst b/doc/source/stdlib/linq_boost.rst index 916795ca72..56727ba880 100644 --- a/doc/source/stdlib/linq_boost.rst +++ b/doc/source/stdlib/linq_boost.rst @@ -5,6 +5,8 @@ Boost module for LINQ ===================== +.. das:module:: linq_boost + The LINQ_BOOST module extends LINQ with pipe-friendly macros using underscore syntax for inline predicates and selectors. Expressions like ``arr |> _where(_ > 3) |> _select(_ * 2)`` provide concise functional pipelines. @@ -33,6 +35,8 @@ Example: :: // output: // 0 2 4 6 8 + + +++++++++++ Call macros +++++++++++ @@ -46,6 +50,7 @@ that expands into order_by(iterator, $(_) => expression) for example:: each(foo)._order_by(_.id) + .. _call-macro-linq_boost-_union_by: .. das:attribute:: _union_by @@ -55,6 +60,7 @@ that expands into union_by(iterator1, iterator2, $(_) => expression) for example:: each(foo1)._union_by(each(foo2), _.id) + .. _call-macro-linq_boost-_take_while: .. das:attribute:: _take_while @@ -64,6 +70,7 @@ that expands into take_while(iterator, $(_) => expression) for example:: each(foo)._take_while(_ < 5) + .. _call-macro-linq_boost-_all: .. das:attribute:: _all @@ -73,6 +80,7 @@ that expands into all(iterator, $(_) => expression) for example:: each(foo)._all(_ < 5) + .. _call-macro-linq_boost-_distinct_by_to_array: .. das:attribute:: _distinct_by_to_array @@ -82,6 +90,7 @@ that expands into distinct_by_to_array(iterator, $(_) => expression) for example:: each(foo)._distinct_by_to_array(_.id) + .. _call-macro-linq_boost-_order_by_to_array: .. das:attribute:: _order_by_to_array @@ -91,6 +100,7 @@ that expands into order_by_to_array(iterator, $(_) => expression) for example:: each(foo)._order_by_to_array(_.id) + .. _call-macro-linq_boost-_except_by: .. das:attribute:: _except_by @@ -100,6 +110,7 @@ that expands into except_by(iterator1, iterator2, $(_) => expression) for example:: each(foo1)._except_by(each(foo2), _.id) + .. _call-macro-linq_boost-_min_max_average_by: .. das:attribute:: _min_max_average_by @@ -109,6 +120,7 @@ that expands into min_max_average_by(iterator, $(_) => expression) for example:: each(foo)._min_max_average_by(_.value) + .. _call-macro-linq_boost-_min_by: .. das:attribute:: _min_by @@ -118,6 +130,7 @@ that expands into min_by(iterator, $(_) => expression) for example:: each(foo)._min_by(_.value) + .. _call-macro-linq_boost-_select_to_array: .. das:attribute:: _select_to_array @@ -127,6 +140,7 @@ that expands into select_to_array(iterator, $(_) => expression) for example:: each(foo)._select_to_array(_ * 2) + .. _call-macro-linq_boost-_union_by_to_array: .. das:attribute:: _union_by_to_array @@ -136,6 +150,7 @@ that expands into union_by_to_array(iterator1, iterator2, $(_) => expression) for example:: each(foo1)._union_by_to_array(each(foo2), _.id) + .. _call-macro-linq_boost-_unique_by_to_array: .. das:attribute:: _unique_by_to_array @@ -145,6 +160,7 @@ that expands into unique_by_to_array(iterator, $(_) => expression) for example:: each(foo)._unique_by_to_array(_.id) + .. _call-macro-linq_boost-_count: .. das:attribute:: _count @@ -154,6 +170,7 @@ that expands into count(iterator, $(_) => expression) for example:: each(foo)._count(_ > 3) + .. _call-macro-linq_boost-_max_by: .. das:attribute:: _max_by @@ -163,6 +180,7 @@ that expands into max_by(iterator, $(_) => expression) for example:: each(foo)._max_by(_.value) + .. _call-macro-linq_boost-_any: .. das:attribute:: _any @@ -172,6 +190,7 @@ that expands into any(iterator, $(_) => expression) for example:: each(foo)._any(_ < 5) + .. _call-macro-linq_boost-_except_by_to_array: .. das:attribute:: _except_by_to_array @@ -181,6 +200,7 @@ that expands into except_by_to_array(iterator1, iterator2, $(_) => expression) for example:: each(foo1)._except_by_to_array(each(foo2), _.id) + .. _call-macro-linq_boost-_order_by_descending: .. das:attribute:: _order_by_descending @@ -190,6 +210,7 @@ that expands into order_by_descending(iterator, $(_) => expression) for example:: each(foo)._order_by_descending(_.id) + .. _call-macro-linq_boost-_order_by_descending_to_array: .. das:attribute:: _order_by_descending_to_array @@ -199,6 +220,7 @@ that expands into order_by_descending_to_array(iterator, $(_) => expression) for example:: each(foo)._order_by_descending_to_array(_.id) + .. _call-macro-linq_boost-_distinct_by: .. das:attribute:: _distinct_by @@ -208,6 +230,7 @@ that expands into distinct_by(iterator, $(_) => expression) for example:: each(foo)._distinct_by(_.id) + .. _call-macro-linq_boost-_select: .. das:attribute:: _select @@ -217,6 +240,7 @@ that expands into select(iterator, $(_) => expression) for example:: each(foo)._select(_ * 2) + .. _call-macro-linq_boost-_intersect_by_to_array: .. das:attribute:: _intersect_by_to_array @@ -226,6 +250,7 @@ that expands into intersect_by_to_array(iterator1, iterator2, $(_) => expression for example:: each(foo1)._intersect_by_to_array(each(foo2), _.id) + .. _call-macro-linq_boost-_min_max_by: .. das:attribute:: _min_max_by @@ -235,6 +260,7 @@ that expands into min_max_by(iterator, $(_) => expression) for example:: each(foo)._min_max_by(_.value) + .. _call-macro-linq_boost-_intersect_by: .. das:attribute:: _intersect_by @@ -244,6 +270,7 @@ that expands into intersect_by(iterator1, iterator2, $(_) => expression) for example:: each(foo1)._intersect_by(each(foo2), _.id) + .. _call-macro-linq_boost-_where_to_array: .. das:attribute:: _where_to_array @@ -253,6 +280,7 @@ that expands into where_to_array(iterator, $(_) => expression) for example:: each(foo)._where_to_array(_ < 5) + .. _call-macro-linq_boost-_skip_while: .. das:attribute:: _skip_while @@ -262,6 +290,7 @@ that expands into skip_while(iterator, $(_) => expression) for example:: each(foo)._skip_while(_ < 5) + .. _call-macro-linq_boost-_where: .. das:attribute:: _where @@ -271,6 +300,7 @@ that expands into where_(iterator, $(_) => expression) for example:: each(foo)._where(_ < 5) + .. _call-macro-linq_boost-_unique_by: .. das:attribute:: _unique_by @@ -280,15 +310,19 @@ that expands into unique_by(iterator, $(_) => expression) for example:: each(foo)._unique_by(_.id) + .. _call-macro-linq_boost-_fold: .. das:attribute:: _fold implements _fold(expression) that folds LINQ expressions into optimized sequnences for example:: - _fold(each(foo)._where(_ > 5)._select(_ * 2)) + + _fold(each(foo)._where(_ > 5)._select(_ * 2)) + expands into a single comprehension that does all operations in one pass + .. _call-macro-linq_boost-_sequence_equal_by: .. das:attribute:: _sequence_equal_by @@ -299,3 +333,4 @@ for example:: each(foo1)._sequence_equal_by(each(foo2), _.id) + diff --git a/doc/source/stdlib/lint.rst b/doc/source/stdlib/lint.rst index 5647dbbe5b..5c9775d94a 100644 --- a/doc/source/stdlib/lint.rst +++ b/doc/source/stdlib/lint.rst @@ -5,6 +5,8 @@ Paranoid lint pass ================== +.. das:module:: lint + The LINT module implements static analysis checks for daslang code. It provides customizable lint rules that detect common mistakes, style violations, and potential bugs at compile time. @@ -15,6 +17,8 @@ All functions and symbols are in "lint" module, use require to get access to it. require daslib/lint + + +++++++++++++++ Lint operations +++++++++++++++ @@ -27,6 +31,7 @@ Lint operations Runs the paranoid lint visitor on the program to check for common coding issues. + :Arguments: * **prog** : :ref:`ProgramPtr ` * **compile_time_errors** : bool diff --git a/doc/source/stdlib/lpipe.rst b/doc/source/stdlib/lpipe.rst index 8de65f5822..d2f203c98a 100644 --- a/doc/source/stdlib/lpipe.rst +++ b/doc/source/stdlib/lpipe.rst @@ -5,6 +5,8 @@ lpipe macro =========== +.. das:module:: lpipe + The LPIPE module provides the ``lpipe`` macro for passing multiple block arguments to a single function call. While ``<|`` handles the first block argument, ``lpipe`` adds subsequent blocks on following lines. @@ -35,6 +37,8 @@ Example: :: // first // second + + +++++++++++ Call macros +++++++++++ @@ -55,3 +59,4 @@ This macro will implement the lpipe function. It allows piping blocks the previo print("block2\n") + diff --git a/doc/source/stdlib/macro_boost.rst b/doc/source/stdlib/macro_boost.rst index 97cf7f944f..69105594e2 100644 --- a/doc/source/stdlib/macro_boost.rst +++ b/doc/source/stdlib/macro_boost.rst @@ -5,6 +5,8 @@ Boost package for macro manipulations ===================================== +.. das:module:: macro_boost + The MACRO_BOOST module provides utility macros for macro authors, including pattern matching on AST nodes, code generation helpers, and common transformation patterns used when writing compile-time code. @@ -13,6 +15,8 @@ All functions and symbols are in "macro_boost" module, use require to get access require daslib/macro_boost + + ++++++++++ Structures ++++++++++ @@ -30,6 +34,8 @@ Stored captured variable together with the `ExprVar` which uses it * **eref** : bool - this one indicates if its used by reference and does not come from argument. its only used in JIT + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -43,6 +49,8 @@ This macro convert macro_verify(expr,message,prog,at) to the following code:: macro_error(prog,at,message) return [[ExpressionPtr]] + + +++++++++++ Call macros +++++++++++ @@ -53,6 +61,8 @@ Call macros this is similar to regular return <-, but it does not check for locks + + ++++++++++++++++++++++ Implementation details ++++++++++++++++++++++ @@ -65,6 +75,7 @@ Implementation details Same as verify, only the check will produce macro error, followed by return [[ExpressionPtr]] + :Arguments: * **expr** : bool * **prog** : :ref:`ProgramPtr ` @@ -73,6 +84,7 @@ Same as verify, only the check will produce macro error, followed by return [[Ex * **message** : string + ++++++++++++++ Block analysis ++++++++++++++ @@ -87,6 +99,7 @@ Block analysis Collect all captured variables in the expression. + :Arguments: * **expr** : :ref:`ExpressionPtr ` .. _function-macro_boost_collect_finally_ExpressionPtr_bool: @@ -97,6 +110,7 @@ Collect all finally blocks in the expression. Returns array of ExprBlock? with all the blocks which have `finally` section Does not go into 'make_block' expression, such as `lambda`, or 'block' expressions + :Arguments: * **expr** : :ref:`ExpressionPtr ` * **alwaysFor** : bool @@ -108,6 +122,7 @@ Does not go into 'make_block' expression, such as `lambda`, or 'block' expressio Collect all labels in the expression. Returns array of integer with label indices Does not go into 'make_block' expression, such as `lambda`, or 'block' expressions + :Arguments: * **expr** : :ref:`ExpressionPtr ` diff --git a/doc/source/stdlib/match.rst b/doc/source/stdlib/match.rst index cf59c878cd..58b162bd8b 100644 --- a/doc/source/stdlib/match.rst +++ b/doc/source/stdlib/match.rst @@ -5,6 +5,8 @@ Pattern matching ================ +.. das:module:: match + The MATCH module implements pattern matching on variants, structs, tuples, arrays, and scalar values. Supports variable capture, wildcards, guard expressions, and alternation. ``static_match`` enforces exhaustive matching @@ -47,6 +49,8 @@ Example: :: // green // other + + +++++++++++ Call macros +++++++++++ @@ -57,24 +61,29 @@ Call macros Implements `match` macro. + .. _call-macro-match-static_match: .. das:attribute:: static_match Implements `static_match` macro. + .. _call-macro-match-multi_match: .. das:attribute:: multi_match Implements `multi_match` macro. + .. _call-macro-match-static_multi_match: .. das:attribute:: static_multi_match Implements `static_multi_match` macro. + + ++++++++++++++++ Structure macros ++++++++++++++++ @@ -86,6 +95,7 @@ Structure macros Implements `match_as_is` annotation. This annotation is used to mark that structure can be matched with different type via is and as machinery. + .. _handle-match-match_copy: .. das:attribute:: match_copy @@ -94,3 +104,4 @@ Implements `match_copy` annotation. This annotation is used to mark that structure can be matched with different type via match_copy machinery. + diff --git a/doc/source/stdlib/math.rst b/doc/source/stdlib/math.rst index 673a191095..db9a3902be 100644 --- a/doc/source/stdlib/math.rst +++ b/doc/source/stdlib/math.rst @@ -5,6 +5,8 @@ Math library ============ +.. das:module:: math + The MATH module contains floating point math functions and constants (trigonometry, exponentials, clamping, interpolation, noise, and vector/matrix operations). Floating point math in general is not bit-precise: the compiler may optimize @@ -41,6 +43,8 @@ Example: :: // max(3, 7) = 7 // length = 1 + + +++++++++ Constants +++++++++ @@ -50,21 +54,26 @@ Constants .. das:attribute:: PI = 3.1415927f The single-precision float constant pi (3.14159265...), representing the ratio of a circle's circumference to its diameter. + .. _global-math-DBL_PI: .. das:attribute:: DBL_PI = 3.141592653589793lf The double-precision constant pi (3.141592653589793...), representing the ratio of a circle's circumference to its diameter. + .. _global-math-FLT_EPSILON: .. das:attribute:: FLT_EPSILON = 1.1920929e-07f The smallest single-precision float value epsilon such that 1.0f + epsilon != 1.0f, approximately 1.1920929e-7. + .. _global-math-DBL_EPSILON: .. das:attribute:: DBL_EPSILON = 2.220446049250313e-16lf The smallest double-precision value epsilon such that 1.0 + epsilon != 1.0, approximately 2.2204460492503131e-16. + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -84,6 +93,7 @@ floating point matrix with 4 rows and 4 columns * **w** : float4 - 3rd row + .. _handle-math-float3x4: .. das:attribute:: float3x4 @@ -99,6 +109,7 @@ floating point matrix with 4 rows and 3 columns * **w** : float3 - 3rd row + .. _handle-math-float3x3: .. das:attribute:: float3x3 @@ -112,6 +123,8 @@ floating point matrix with 3 rows and 3 columns * **z** : float3 - 2nd row + + ++++++++++++++++++++++++++++++++++++++++++ all numerics (uint*, int*, float*, double) ++++++++++++++++++++++++++++++++++++++++++ @@ -157,6 +170,7 @@ max Returns the component-wise maximum of two values, supporting scalar double, float, int, int64, uint, uint64 and vector float2, float3, float4 types. + :Arguments: * **x** : int * **y** : int @@ -229,6 +243,7 @@ min Returns the component-wise minimum of two values, supporting scalar double, float, int, int64, uint, uint64 and vector float2, float3, float4 types. + :Arguments: * **x** : uint3 * **y** : uint3 @@ -291,6 +306,7 @@ Returns the component-wise minimum of two values, supporting scalar double, floa ---- + +++++++++++++++++ float* and double +++++++++++++++++ @@ -411,8 +427,8 @@ float* and double * :ref:`sin (x: float3) : float3 ` * :ref:`sin (x: float2) : float2 ` * :ref:`sin (x: float) : float ` - * :ref:`sincos (x: float; s: float& implicit; c: float& implicit) ` - * :ref:`sincos (x: double; s: double& implicit; c: double& implicit) ` + * :ref:`sincos (x: float; s: float& implicit; c: float& implicit) ` + * :ref:`sincos (x: double; s: double& implicit; c: double& implicit) ` * :ref:`sqrt (x: double) : double ` * :ref:`sqrt (x: float4) : float4 ` * :ref:`sqrt (x: float3) : float3 ` @@ -434,6 +450,7 @@ abs Returns the absolute value of the argument, computed component-wise for float2, float3, float4, int2, int3, and int4 vector types, and per-element for scalar float, double, int, and int64 types. + :Arguments: * **x** : float3 .. _function-math_abs_uint: @@ -504,6 +521,7 @@ acos Returns the arccosine of x in radians; the input must be in the range [-1, 1] and the result is in the range [0, pi]; works with float and double. + :Arguments: * **x** : float4 .. _function-math_acos_float2: @@ -534,6 +552,7 @@ asin Returns the arcsine of x in radians; the input must be in the range [-1, 1] and the result is in the range [-pi/2, pi/2]; works with float and double. + :Arguments: * **x** : float .. _function-math_asin_double: @@ -564,6 +583,7 @@ atan Returns the arctangent of x in radians, with the result in the range [-pi/2, pi/2]; works with float and double. + :Arguments: * **x** : float2 .. _function-math_atan_float4: @@ -594,6 +614,7 @@ atan2 Returns the arctangent of y/x in radians, using the signs of both arguments to determine the correct quadrant; the result is in the range [-pi, pi]; works with float and double. + :Arguments: * **y** : float3 * **x** : float3 @@ -626,6 +647,7 @@ ceil Returns the smallest integral value not less than x (rounds toward positive infinity), computed component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : float4 .. _function-math_ceil_float3: @@ -652,6 +674,7 @@ cos Returns the cosine of x, where x is specified in radians; works with float and double. + :Arguments: * **x** : double .. _function-math_cos_float4: @@ -682,6 +705,7 @@ exp Returns e raised to the power of x (the base-e exponential), computed component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : float4 .. _function-math_exp_double: @@ -712,6 +736,7 @@ exp2 Returns 2 raised to the power of x, computed component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : float4 .. _function-math_exp2_float3: @@ -742,6 +767,7 @@ floor Returns the largest integral value not greater than x (rounds toward negative infinity), computed component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : float .. _function-math_floor_float2: @@ -768,6 +794,7 @@ is_finite Returns true if x is a finite value (not infinity and not NaN), checked component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : float .. _function-math_is_finite_double: @@ -786,6 +813,7 @@ is_nan Returns true if x is NaN (Not a Number), checked component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : float .. _function-math_is_nan_double: @@ -804,6 +832,7 @@ log Returns the natural (base-e) logarithm of x; the input must be positive; computed component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : float4 .. _function-math_log_float3: @@ -834,6 +863,7 @@ log2 Returns the base-2 logarithm of x; the input must be positive; computed component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : double .. _function-math_log2_float4: @@ -864,6 +894,7 @@ pow Returns x raised to the power of y for scalar double, float, or vector float2, float3, float4 types; domain requires x >= 0 for non-integer y values. + :Arguments: * **x** : double * **y** : double @@ -896,6 +927,7 @@ rcp Returns the reciprocal (1/x) of a scalar float or each component of a float2, float3, or float4 vector. + :Arguments: * **x** : double .. _function-math_rcp_float4: @@ -926,6 +958,7 @@ safe_acos Returns the arccosine of x in radians, clamping the input to the valid domain [-1, 1] to prevent NaN results from out-of-range values. + :Arguments: * **x** : double .. _function-math_safe_acos_float2: @@ -956,6 +989,7 @@ safe_asin Returns the arcsine of x in radians, clamping the input to the valid domain [-1, 1] to prevent NaN results from out-of-range values. + :Arguments: * **x** : float3 .. _function-math_safe_asin_float4: @@ -986,6 +1020,7 @@ saturate Clamps the scalar double, float, or each component of a float2, float3, float4 vector to the [0, 1] range, returning 0 for values below 0 and 1 for values above 1. + :Arguments: * **x** : float4 .. _function-math_saturate_float3: @@ -1012,6 +1047,7 @@ sign Returns the sign of x component-wise: -1 for negative, 0 for zero, or 1 for positive. For unsigned types, the result is 0 or 1. + :Arguments: * **x** : uint .. _function-math_sign_uint2: @@ -1082,6 +1118,7 @@ sin Returns the sine of the angle x given in radians for double or float, with output in the range [-1, 1]. + :Arguments: * **x** : double .. _function-math_sin_float4: @@ -1106,19 +1143,20 @@ Returns the sine of the angle x given in radians for double or float, with outpu sincos ^^^^^^ -.. _function-math_sincos_float_float_implicit_float_implicit: +.. _function-math_sincos_float_float_ref__implicit_float_ref__implicit: .. das:function:: sincos(x: float; s: float& implicit; c: float& implicit) Computes both the sine and cosine of the angle x in radians simultaneously, writing the results to output parameters s and c, for float or double types. + :Arguments: * **x** : float - * **s** : float& implicit + * **s** : float\ & implicit - * **c** : float& implicit + * **c** : float\ & implicit -.. _function-math_sincos_double_double_implicit_double_implicit: +.. _function-math_sincos_double_double_ref__implicit_double_ref__implicit: .. das:function:: sincos(x: double; s: double& implicit; c: double& implicit) @@ -1134,6 +1172,7 @@ sqrt Returns the square root of a scalar double, float, or each component of a float2, float3, or float4 vector; input must be non-negative. + :Arguments: * **x** : double .. _function-math_sqrt_float4: @@ -1164,6 +1203,7 @@ tan Returns the tangent of the angle x given in radians for double or float; undefined at odd multiples of pi/2. + :Arguments: * **x** : double .. _function-math_tan_float4: @@ -1184,6 +1224,7 @@ Returns the tangent of the angle x given in radians for double or float; undefin ---- + +++++++++++ float* only +++++++++++ @@ -1250,6 +1291,7 @@ atan2_est Returns a fast estimated arctangent of y/x in radians, using the signs of both arguments to determine the correct quadrant; trades some precision for speed. + :Arguments: * **y** : float * **x** : float @@ -1278,6 +1320,7 @@ atan_est Returns a fast estimated arctangent of x in radians, trading some precision for speed; the result approximates the range [-pi/2, pi/2]. + :Arguments: * **x** : float2 .. _function-math_atan_est_float4: @@ -1304,6 +1347,7 @@ ceili Returns the smallest integer not less than x (rounds toward positive infinity), converting the float argument to an int result. + :Arguments: * **x** : float4 .. _function-math_ceili_float: @@ -1330,6 +1374,7 @@ Returns the smallest integer not less than x (rounds toward positive infinity), Returns the component-wise arithmetic negation of a matrix, flipping the sign of every element; works with float3x3, float3x4, and float4x4 matrix types. + :Arguments: * **x** : :ref:`float3x3 ` implicit .. _function-math_-_float3x4_implicit: @@ -1338,6 +1383,7 @@ Returns the component-wise arithmetic negation of a matrix, flipping the sign of Returns the component-wise arithmetic negation of a matrix, flipping the sign of every element; works with float3x3, float3x4, and float4x4 matrix types. + :Arguments: * **x** : :ref:`float3x4 ` implicit .. _function-math_-_float4x4_implicit: @@ -1346,6 +1392,7 @@ Returns the component-wise arithmetic negation of a matrix, flipping the sign of Returns the component-wise arithmetic negation of a matrix, flipping the sign of every element; works with float3x3, float3x4, and float4x4 matrix types. + :Arguments: * **x** : :ref:`float4x4 ` implicit @@ -1358,6 +1405,7 @@ floori Returns the largest integer not greater than x (rounds toward negative infinity), converting the float argument to an int result. + :Arguments: * **x** : float .. _function-math_floori_float2: @@ -1388,6 +1436,7 @@ fract Returns the fractional part of x (equivalent to x - floor(x)), computed component-wise for float2, float3, and float4 vector types; works with float and double scalars. + :Arguments: * **x** : float3 .. _function-math_fract_float4: @@ -1414,6 +1463,7 @@ rcp_est Returns a fast hardware estimate of the reciprocal (1/x) of a scalar float or each component of a float2, float3, or float4 vector, trading precision for speed. + :Arguments: * **x** : float4 .. _function-math_rcp_est_float2: @@ -1440,6 +1490,7 @@ round Rounds each component of the scalar double, float, or vector float2, float3, float4 value x to the nearest integer, with halfway cases rounded to the nearest even value. + :Arguments: * **x** : float4 .. _function-math_round_float3: @@ -1466,6 +1517,7 @@ roundi Rounds the float x to the nearest integer value and returns the result as an int. + :Arguments: * **x** : float4 .. _function-math_roundi_float2: @@ -1496,6 +1548,7 @@ rsqrt Returns the reciprocal square root (1/sqrt(x)) of a scalar float or each component of a float2, float3, or float4 vector. + :Arguments: * **x** : float4 .. _function-math_rsqrt_float2: @@ -1522,6 +1575,7 @@ rsqrt_est Returns a fast hardware estimate of the reciprocal square root (1/sqrt(x)) of a scalar float or each component of a float2, float3, or float4 vector, trading precision for speed. + :Arguments: * **x** : float3 .. _function-math_rsqrt_est_float4: @@ -1548,6 +1602,7 @@ trunci Truncates the float x toward zero to the nearest integer and returns the result as an int. + :Arguments: * **x** : double .. _function-math_trunci_float: @@ -1568,6 +1623,7 @@ Truncates the float x toward zero to the nearest integer and returns the result ---- + +++++++++++ float3 only +++++++++++ @@ -1596,6 +1652,7 @@ float3 only Returns the cross product of two float3 vectors, producing a float3 vector perpendicular to both inputs with magnitude equal to the area of the parallelogram they span. + :Arguments: * **x** : float3 * **y** : float3 @@ -1610,6 +1667,7 @@ distance Returns the Euclidean distance between two vectors as a float scalar; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float2 * **y** : float2 @@ -1634,6 +1692,7 @@ distance_sq Returns the squared Euclidean distance between two vectors as a float scalar, avoiding the square root for faster distance comparisons; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float3 * **y** : float3 @@ -1658,6 +1717,7 @@ inv_distance Returns the reciprocal of the Euclidean distance between two vectors (1 / distance(x, y)) as a float; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float3 * **y** : float3 @@ -1682,6 +1742,7 @@ inv_distance_sq Returns the reciprocal of the squared Euclidean distance between two vectors (1 / distance_sq(x, y)) as a float; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float4 * **y** : float4 @@ -1706,6 +1767,7 @@ reflect Computes the reflection of float2 or float3 vector v off a surface with unit normal n, returning the reflected vector as v - 2*dot(v,n)*n. + :Arguments: * **v** : float3 * **n** : float3 @@ -1726,6 +1788,7 @@ refract Computes the refraction direction of vector v through a surface with unit normal n using Snell's law with index of refraction ratio nint. Returns a zero vector if total internal reflection occurs. + :Arguments: * **v** : float2 * **n** : float2 @@ -1738,6 +1801,7 @@ Computes the refraction direction of vector v through a surface with unit normal ---- + ++++++++++++++++++++++ float2, float3, float4 ++++++++++++++++++++++ @@ -1774,6 +1838,7 @@ dot Returns the dot product (scalar product) of two vectors as a float; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float3 * **y** : float3 @@ -1798,6 +1863,7 @@ fast_normalize Returns a unit-length vector in the same direction as x using a fast approximation; does not check for zero-length input; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float2 .. _function-math_fast_normalize_float4: @@ -1820,6 +1886,7 @@ inv_length Returns the reciprocal of the length of the vector (1 / length(x)) as a float; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float4 .. _function-math_inv_length_float3: @@ -1842,6 +1909,7 @@ inv_length_sq Returns the reciprocal of the squared length of the vector (1 / length_sq(x)) as a float; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float4 .. _function-math_inv_length_sq_float2: @@ -1864,6 +1932,7 @@ length Returns the Euclidean length (magnitude) of the vector as a float; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float3 .. _function-math_length_float2: @@ -1886,6 +1955,7 @@ length_sq Returns the squared Euclidean length of the vector as a float, equivalent to dot(x, x) and avoiding the square root for faster magnitude comparisons; works with float2, float3, and float4 vector types. + :Arguments: * **x** : float3 .. _function-math_length_sq_float2: @@ -1908,6 +1978,7 @@ normalize Returns a unit-length vector with the same direction as the input float2, float3, or float4 vector; behavior is undefined if the input vector has zero length. + :Arguments: * **x** : float2 .. _function-math_normalize_float3: @@ -1920,6 +1991,7 @@ Returns a unit-length vector with the same direction as the input float2, float3 ---- + +++++++++++++++ Noise functions +++++++++++++++ @@ -1935,6 +2007,7 @@ Noise functions Returns a well-distributed uint hash of the input uint seed using an improved integer hash function suitable for hash tables and procedural generation. + :Arguments: * **seed** : uint .. _function-math_uint_noise_1D_int_uint: @@ -1943,6 +2016,7 @@ Returns a well-distributed uint hash of the input uint seed using an improved in Generates a deterministic uint hash value from a 1D integer position and a uint seed, suitable for repeatable procedural noise. + :Arguments: * **position** : int * **seed** : uint @@ -1953,6 +2027,7 @@ Generates a deterministic uint hash value from a 1D integer position and a uint Generates a deterministic uint hash value from 2D integer coordinates (x, y) and a uint seed, suitable for repeatable procedural noise. + :Arguments: * **position** : int2 * **seed** : uint @@ -1963,10 +2038,12 @@ Generates a deterministic uint hash value from 2D integer coordinates (x, y) and Generates a deterministic uint hash value from 3D integer coordinates (x, y, z) and a uint seed, suitable for repeatable procedural noise. + :Arguments: * **position** : int3 * **seed** : uint + ++++++++++++++ lerp/mad/clamp ++++++++++++++ @@ -2027,6 +2104,7 @@ clamp Returns the value t clamped to the inclusive range [a, b], equivalent to min(max(t, a), b); works with float, double, float2, float3, float4, int, int64, uint, and uint64 types. + :Arguments: * **t** : float * **a** : float @@ -2101,6 +2179,7 @@ lerp Performs linear interpolation between a and b using the factor t, returning a + (b - a) * t; when t is 0 the result is a, when t is 1 the result is b; works component-wise with float, double, float2, float3, and float4 types. + :Arguments: * **a** : double * **b** : double @@ -2148,6 +2227,7 @@ mad Computes the fused multiply-add operation `a * b + c`. + :Arguments: * **a** : uint4 * **b** : uint4 @@ -2240,38 +2320,41 @@ Computes the fused multiply-add operation `a * b + c`. ---- + +++++++++++++++++++++ Matrix element access +++++++++++++++++++++ - * :ref:`float3x3 const implicit ==const.[] (m: float3x3 const implicit ==const; i: int) : float3 ` - * :ref:`float3x3 const implicit ==const.[] (m: float3x3 const implicit ==const; i: uint) : float3 ` - * :ref:`float3x3 implicit ==const.[] (m: float3x3 implicit ==const; i: int) : float3& ` - * :ref:`float3x3 implicit ==const.[] (m: float3x3 implicit ==const; i: uint) : float3& ` - * :ref:`float3x4 const implicit ==const.[] (m: float3x4 const implicit ==const; i: uint) : float3 ` - * :ref:`float3x4 const implicit ==const.[] (m: float3x4 const implicit ==const; i: int) : float3 ` - * :ref:`float3x4 implicit ==const.[] (m: float3x4 implicit ==const; i: uint) : float3& ` - * :ref:`float3x4 implicit ==const.[] (m: float3x4 implicit ==const; i: int) : float3& ` - * :ref:`float4x4 const implicit ==const.[] (m: float4x4 const implicit ==const; i: uint) : float4 ` - * :ref:`float4x4 const implicit ==const.[] (m: float4x4 const implicit ==const; i: int) : float4 ` - * :ref:`float4x4 implicit ==const.[] (m: float4x4 implicit ==const; i: int) : float4& ` - * :ref:`float4x4 implicit ==const.[] (m: float4x4 implicit ==const; i: uint) : float4& ` + * :ref:`float3x3 const implicit ==const.[] (m: float3x3 const implicit ==const; i: int) : float3 ` + * :ref:`float3x3 const implicit ==const.[] (m: float3x3 const implicit ==const; i: uint) : float3 ` + * :ref:`float3x3 implicit ==const.[] (m: float3x3 implicit ==const; i: int) : float3& ` + * :ref:`float3x3 implicit ==const.[] (m: float3x3 implicit ==const; i: uint) : float3& ` + * :ref:`float3x4 const implicit ==const.[] (m: float3x4 const implicit ==const; i: uint) : float3 ` + * :ref:`float3x4 const implicit ==const.[] (m: float3x4 const implicit ==const; i: int) : float3 ` + * :ref:`float3x4 implicit ==const.[] (m: float3x4 implicit ==const; i: uint) : float3& ` + * :ref:`float3x4 implicit ==const.[] (m: float3x4 implicit ==const; i: int) : float3& ` + * :ref:`float4x4 const implicit ==const.[] (m: float4x4 const implicit ==const; i: uint) : float4 ` + * :ref:`float4x4 const implicit ==const.[] (m: float4x4 const implicit ==const; i: int) : float4 ` + * :ref:`float4x4 implicit ==const.[] (m: float4x4 implicit ==const; i: int) : float4& ` + * :ref:`float4x4 implicit ==const.[] (m: float4x4 implicit ==const; i: uint) : float4& ` float3x3 const implicit ==const.[] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-math__dot__float3x3_const_implicit__eq__eq_const_int: +.. _function-math__dot__lb__rb__float3x3_const_implicit__eq__eq_const_int: .. das:function:: float3x3 const implicit ==const.[](m: float3x3 const implicit ==const; i: int) : float3 -Returns a reference to the row vector at the specified index of a float3x3, float3x4, or float4x4 matrix; the index can be int or uint and must be within the row count of the matrix. +// stub +def float3x3 const implicit ==const.[] (m: float3x3 const implicit ==const; i: int) : float3 + :Arguments: * **m** : :ref:`float3x3 ` implicit! * **i** : int -.. _function-math__dot__float3x3_const_implicit__eq__eq_const_uint: +.. _function-math__dot__lb__rb__float3x3_const_implicit__eq__eq_const_uint: .. das:function:: float3x3 const implicit ==const.[](m: float3x3 const implicit ==const; i: uint) : float3 @@ -2281,17 +2364,19 @@ Returns a reference to the row vector at the specified index of a float3x3, floa float3x3 implicit ==const.[] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-math__dot__float3x3_implicit__eq__eq_const_int: +.. _function-math__dot__lb__rb__float3x3_implicit__eq__eq_const_int: .. das:function:: float3x3 implicit ==const.[](m: float3x3 implicit ==const; i: int) : float3& -Returns a reference to the row vector at the specified index of a float3x3, float3x4, or float4x4 matrix; the index can be int or uint and must be within the row count of the matrix. +// stub +def float3x3 implicit ==const.[] (m: float3x3 implicit ==const; i: int) : float3& + :Arguments: * **m** : :ref:`float3x3 ` implicit! * **i** : int -.. _function-math__dot__float3x3_implicit__eq__eq_const_uint: +.. _function-math__dot__lb__rb__float3x3_implicit__eq__eq_const_uint: .. das:function:: float3x3 implicit ==const.[](m: float3x3 implicit ==const; i: uint) : float3& @@ -2301,17 +2386,19 @@ Returns a reference to the row vector at the specified index of a float3x3, floa float3x4 const implicit ==const.[] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-math__dot__float3x4_const_implicit__eq__eq_const_uint: +.. _function-math__dot__lb__rb__float3x4_const_implicit__eq__eq_const_uint: .. das:function:: float3x4 const implicit ==const.[](m: float3x4 const implicit ==const; i: uint) : float3 -Returns a reference to the row vector at the specified index of a float3x3, float3x4, or float4x4 matrix; the index can be int or uint and must be within the row count of the matrix. +// stub +def float3x4 const implicit ==const.[] (m: float3x4 const implicit ==const; i: uint) : float3 + :Arguments: * **m** : :ref:`float3x4 ` implicit! * **i** : uint -.. _function-math__dot__float3x4_const_implicit__eq__eq_const_int: +.. _function-math__dot__lb__rb__float3x4_const_implicit__eq__eq_const_int: .. das:function:: float3x4 const implicit ==const.[](m: float3x4 const implicit ==const; i: int) : float3 @@ -2321,17 +2408,19 @@ Returns a reference to the row vector at the specified index of a float3x3, floa float3x4 implicit ==const.[] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-math__dot__float3x4_implicit__eq__eq_const_uint: +.. _function-math__dot__lb__rb__float3x4_implicit__eq__eq_const_uint: .. das:function:: float3x4 implicit ==const.[](m: float3x4 implicit ==const; i: uint) : float3& -Returns a reference to the row vector at the specified index of a float3x3, float3x4, or float4x4 matrix; the index can be int or uint and must be within the row count of the matrix. +// stub +def float3x4 implicit ==const.[] (m: float3x4 implicit ==const; i: uint) : float3& + :Arguments: * **m** : :ref:`float3x4 ` implicit! * **i** : uint -.. _function-math__dot__float3x4_implicit__eq__eq_const_int: +.. _function-math__dot__lb__rb__float3x4_implicit__eq__eq_const_int: .. das:function:: float3x4 implicit ==const.[](m: float3x4 implicit ==const; i: int) : float3& @@ -2341,17 +2430,19 @@ Returns a reference to the row vector at the specified index of a float3x3, floa float4x4 const implicit ==const.[] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-math__dot__float4x4_const_implicit__eq__eq_const_uint: +.. _function-math__dot__lb__rb__float4x4_const_implicit__eq__eq_const_uint: .. das:function:: float4x4 const implicit ==const.[](m: float4x4 const implicit ==const; i: uint) : float4 -Returns a reference to the row vector at the specified index of a float3x3, float3x4, or float4x4 matrix; the index can be int or uint and must be within the row count of the matrix. +// stub +def float4x4 const implicit ==const.[] (m: float4x4 const implicit ==const; i: uint) : float4 + :Arguments: * **m** : :ref:`float4x4 ` implicit! * **i** : uint -.. _function-math__dot__float4x4_const_implicit__eq__eq_const_int: +.. _function-math__dot__lb__rb__float4x4_const_implicit__eq__eq_const_int: .. das:function:: float4x4 const implicit ==const.[](m: float4x4 const implicit ==const; i: int) : float4 @@ -2361,22 +2452,25 @@ Returns a reference to the row vector at the specified index of a float3x3, floa float4x4 implicit ==const.[] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _function-math__dot__float4x4_implicit__eq__eq_const_int: +.. _function-math__dot__lb__rb__float4x4_implicit__eq__eq_const_int: .. das:function:: float4x4 implicit ==const.[](m: float4x4 implicit ==const; i: int) : float4& -Returns a reference to the row vector at the specified index of a float3x3, float3x4, or float4x4 matrix; the index can be int or uint and must be within the row count of the matrix. +// stub +def float4x4 implicit ==const.[] (m: float4x4 implicit ==const; i: int) : float4& + :Arguments: * **m** : :ref:`float4x4 ` implicit! * **i** : int -.. _function-math__dot__float4x4_implicit__eq__eq_const_uint: +.. _function-math__dot__lb__rb__float4x4_implicit__eq__eq_const_uint: .. das:function:: float4x4 implicit ==const.[](m: float4x4 implicit ==const; i: uint) : float4& ---- + +++++++++++++++++ Matrix operations +++++++++++++++++ @@ -2400,6 +2494,7 @@ Matrix operations Returns true if two float3x3 matrices are not equal, comparing all elements component-wise. + :Arguments: * **x** : :ref:`float3x3 ` implicit * **y** : :ref:`float3x3 ` implicit @@ -2415,6 +2510,7 @@ float3x3 implicit* Multiplies two 3x3 matrices and returns the resulting 3x3 matrix. + :Arguments: * **x** : :ref:`float3x3 ` implicit * **y** : :ref:`float3x3 ` implicit @@ -2431,6 +2527,7 @@ Multiplies two 3x3 matrices and returns the resulting 3x3 matrix. Returns true if two float3x3 matrices are exactly equal, comparing all elements component-wise. + :Arguments: * **x** : :ref:`float3x3 ` implicit * **y** : :ref:`float3x3 ` implicit @@ -2441,6 +2538,7 @@ Returns true if two float3x3 matrices are exactly equal, comparing all elements Returns true if two float3x4 matrices are not equal, comparing all elements component-wise. + :Arguments: * **x** : :ref:`float3x4 ` implicit * **y** : :ref:`float3x4 ` implicit @@ -2456,6 +2554,7 @@ float3x4 implicit* Multiplies two 3x4 matrices and returns the resulting 3x4 matrix. + :Arguments: * **x** : :ref:`float3x4 ` implicit * **y** : :ref:`float3x4 ` implicit @@ -2472,6 +2571,7 @@ Multiplies two 3x4 matrices and returns the resulting 3x4 matrix. Returns true if two float3x4 matrices are exactly equal, comparing all elements component-wise. + :Arguments: * **x** : :ref:`float3x4 ` implicit * **y** : :ref:`float3x4 ` implicit @@ -2482,6 +2582,7 @@ Returns true if two float3x4 matrices are exactly equal, comparing all elements Returns true if two float4x4 matrices are not equal, comparing all elements component-wise. + :Arguments: * **x** : :ref:`float4x4 ` implicit * **y** : :ref:`float4x4 ` implicit @@ -2497,6 +2598,7 @@ float4x4 implicit* Transforms a float4 vector by a 4x4 matrix. + :Arguments: * **x** : :ref:`float4x4 ` implicit * **y** : float4 @@ -2513,10 +2615,12 @@ Transforms a float4 vector by a 4x4 matrix. Returns true if two float4x4 matrices are exactly equal, comparing all elements component-wise. + :Arguments: * **x** : :ref:`float4x4 ` implicit * **y** : :ref:`float4x4 ` implicit + +++++++++++++++++++ Matrix initializers +++++++++++++++++++ @@ -2542,6 +2646,7 @@ float3x3 Extracts the upper-left 3x3 rotation part from a float3x4 transformation matrix, returning it as a float3x3. + :Arguments: * **arg0** : :ref:`float3x4 ` implicit .. _function-math_float3x3: @@ -2564,6 +2669,7 @@ float3x4 Constructs a float3x4 transformation matrix from a float3x3 rotation matrix, with the translation component set to zero. + :Arguments: * **arg0** : :ref:`float4x4 ` implicit .. _function-math_float3x4: @@ -2582,6 +2688,7 @@ float4x4 Converts a float3x4 transformation matrix to a float4x4 matrix, filling the fourth row with [0, 0, 0, 1]. + :Arguments: * **arg0** : :ref:`float3x4 ` implicit .. _function-math_float4x4: @@ -2596,24 +2703,28 @@ Converts a float3x4 transformation matrix to a float4x4 matrix, filling the four Returns a float3x3 identity matrix with ones on the diagonal and zeros elsewhere. + .. _function-math_identity3x4: .. das:function:: identity3x4() : float3x4 Returns a float3x4 identity transformation matrix with the rotation part set to identity and the translation set to zero. + .. _function-math_identity4x4: .. das:function:: identity4x4() : float4x4 Returns a float4x4 identity matrix with ones on the diagonal and zeros elsewhere. + + +++++++++++++++++++ Matrix manipulation +++++++++++++++++++ * :ref:`compose (pos: float3; rot: float4; scale: float3) : float4x4 ` - * :ref:`decompose (mat: float4x4 implicit; pos: float3& implicit; rot: float4& implicit; scale: float3& implicit) ` + * :ref:`decompose (mat: float4x4 implicit; pos: float3& implicit; rot: float4& implicit; scale: float3& implicit) ` * :ref:`determinant (x: float3x4 implicit) : float ` * :ref:`determinant (x: float4x4 implicit) : float ` * :ref:`determinant (x: float3x3 implicit) : float ` @@ -2637,25 +2748,27 @@ Matrix manipulation Constructs a float4x4 transformation matrix from a float3 translation position, a float4 quaternion rotation, and a float3 scale. + :Arguments: * **pos** : float3 * **rot** : float4 * **scale** : float3 -.. _function-math_decompose_float4x4_implicit_float3_implicit_float4_implicit_float3_implicit: +.. _function-math_decompose_float4x4_implicit_float3_ref__implicit_float4_ref__implicit_float3_ref__implicit: .. das:function:: decompose(mat: float4x4 implicit; pos: float3& implicit; rot: float4& implicit; scale: float3& implicit) Decomposes a float4x4 transformation matrix into its float3 translation position, float4 quaternion rotation, and float3 scale components., writing the results into the output arguments rot and pos. + :Arguments: * **mat** : :ref:`float4x4 ` implicit - * **pos** : float3& implicit + * **pos** : float3\ & implicit - * **rot** : float4& implicit + * **rot** : float4\ & implicit - * **scale** : float3& implicit + * **scale** : float3\ & implicit determinant @@ -2667,6 +2780,7 @@ determinant Returns the determinant of a float3x4 matrix as a float scalar; a zero determinant indicates the matrix is singular and non-invertible. + :Arguments: * **x** : :ref:`float3x4 ` implicit .. _function-math_determinant_float4x4_implicit: @@ -2689,6 +2803,7 @@ identity Sets the given float3x4 matrix to the identity transformation (rotation part is the identity matrix, translation is zero) and returns it. + :Arguments: * **x** : :ref:`float3x4 ` implicit .. _function-math_identity_float4x4_implicit: @@ -2711,6 +2826,7 @@ inverse Returns the inverse of a matrix, such that multiplying the original by its inverse yields the identity; works with float3x4 and float4x4 matrix types. + :Arguments: * **x** : :ref:`float3x4 ` implicit .. _function-math_inverse_float4x4_implicit: @@ -2725,6 +2841,7 @@ Returns the inverse of a matrix, such that multiplying the original by its inver Constructs a float4x4 look-at view transformation matrix from eye position, target position, and up vector. from an eye position, a target point to look at, and an up direction vector. + :Arguments: * **eye** : float3 * **at** : float3 @@ -2741,6 +2858,7 @@ orthonormal_inverse Returns the inverse of a float3x3 orthonormal matrix (each axis is unit length and mutually perpendicular), computed more efficiently than a general matrix inverse. + :Arguments: * **m** : :ref:`float3x3 ` implicit .. _function-math_orthonormal_inverse_float3x4_implicit: @@ -2755,6 +2873,7 @@ Returns the inverse of a float3x3 orthonormal matrix (each axis is unit length a Returns a forward (standard) perspective projection float4x4 matrix constructed from horizontal scale wk, vertical scale hk, near plane zn, and far plane zf. + :Arguments: * **wk** : float * **hk** : float @@ -2769,6 +2888,7 @@ Returns a forward (standard) perspective projection float4x4 matrix constructed Returns a reverse-depth perspective projection float4x4 matrix constructed from horizontal scale wk, vertical scale hk, near plane zn, and far plane zf, mapping the far plane to 0 and the near plane to 1. + :Arguments: * **wk** : float * **hk** : float @@ -2783,6 +2903,7 @@ Returns a reverse-depth perspective projection float4x4 matrix constructed from Rotates a float3 vector v by the 3x3 rotation part of the float3x4 matrix m, ignoring the translation component. + :Arguments: * **x** : :ref:`float3x4 ` implicit * **y** : float3 @@ -2793,6 +2914,7 @@ Rotates a float3 vector v by the 3x3 rotation part of the float3x4 matrix m, ign Constructs a float4x4 matrix representing a pure translation by the given float3 offset. by the float3 offset xyz, with the rotation part set to identity. + :Arguments: * **xyz** : float3 .. _function-math_transpose_float4x4_implicit: @@ -2801,8 +2923,10 @@ Constructs a float4x4 matrix representing a pure translation by the given float3 Returns the transpose of a float3x3 or float4x4 matrix, swapping rows and columns. + :Arguments: * **x** : :ref:`float4x4 ` implicit + +++++++++++++++++++++ Quaternion operations +++++++++++++++++++++ @@ -2826,6 +2950,7 @@ Quaternion operations Converts a float4 quaternion to Euler angles, returning a float3 representing rotation around the x, y, and z axes in radians. + :Arguments: * **angles** : float4 @@ -2838,6 +2963,7 @@ quat Extracts the rotation part of a float3x4 matrix and returns it as a float4 quaternion in (x, y, z, w) format. + :Arguments: * **m** : :ref:`float4x4 ` implicit .. _function-math_quat_float3x3_implicit: @@ -2856,6 +2982,7 @@ Extracts the rotation part of a float3x4 matrix and returns it as a float4 quate Returns the conjugate of the float4 quaternion q by negating its xyz components, which for unit quaternions equals the inverse rotation. + :Arguments: * **q** : float4 @@ -2868,6 +2995,7 @@ quat_from_euler Creates a float4 quaternion from a float3 of Euler angles (pitch, yaw, roll) given in radians. + :Arguments: * **x** : float * **y** : float @@ -2886,6 +3014,7 @@ Creates a float4 quaternion from a float3 of Euler angles (pitch, yaw, roll) giv Creates a float4 quaternion representing the shortest rotation arc from unit-length float3 vector v0 to unit-length float3 vector v1; both input vectors must be normalized. + :Arguments: * **v0** : float3 * **v1** : float3 @@ -2896,6 +3025,7 @@ Creates a float4 quaternion representing the shortest rotation arc from unit-len Creates a float4 quaternion representing a rotation of ang radians around the unit-length float3 axis vector v. + :Arguments: * **v** : float3 * **ang** : float @@ -2906,6 +3036,7 @@ Creates a float4 quaternion representing a rotation of ang radians around the un Returns the float4 quaternion product of q1 and q2, representing the combined rotation of q2 followed by q1. + :Arguments: * **q1** : float4 * **q2** : float4 @@ -2916,6 +3047,7 @@ Returns the float4 quaternion product of q1 and q2, representing the combined ro Rotates a float3 vector v by the float4 quaternion q and returns the resulting float3 vector. + :Arguments: * **q** : float4 * **v** : float3 @@ -2926,12 +3058,14 @@ Rotates a float3 vector v by the float4 quaternion q and returns the resulting f Performs spherical linear interpolation between float4 quaternions a and b by factor t in the range [0,1], returning a smoothly interpolated float4 quaternion. + :Arguments: * **t** : float * **a** : float4 * **b** : float4 + +++++++++++++++++++++ Packing and unpacking +++++++++++++++++++++ @@ -2945,6 +3079,7 @@ Packing and unpacking Packs a float4 vector into a single uint by converting each component to an 8-bit byte value, mapping the XYZW components to the four bytes of the result. + :Arguments: * **x** : float4 .. _function-math_unpack_byte_to_float_uint: @@ -2953,6 +3088,7 @@ Packs a float4 vector into a single uint by converting each component to an 8-bi Unpacks the four bytes of a uint into a float4 vector, converting each 8-bit byte value to its corresponding floating-point component. + :Arguments: * **x** : uint diff --git a/doc/source/stdlib/math_bits.rst b/doc/source/stdlib/math_bits.rst index d90053a4ef..2b6895e586 100644 --- a/doc/source/stdlib/math_bits.rst +++ b/doc/source/stdlib/math_bits.rst @@ -5,6 +5,8 @@ Math bit helpers ================ +.. das:module:: math_bits + The MATH_BITS module provides bit manipulation functions for floating point numbers, including type punning between integer and float representations, and efficient integer math operations like ``int_bits_to_float`` and @@ -29,6 +31,8 @@ Example: :: // uint_bits_to_float(0x3F800000) = 1 // float_bits_to_uint(1.0) = 0x3f800000 + + +++++++++++++++++ float in int,uint +++++++++++++++++ @@ -52,6 +56,7 @@ int_bits_to_float bit representation of x is interpreted as a float + :Arguments: * **x** : int2 .. _function-math_bits_int_bits_to_float_int: @@ -78,6 +83,7 @@ uint_bits_to_float bit representation of x is interpreted as a float3 + :Arguments: * **x** : uint3 .. _function-math_bits_uint_bits_to_float_uint2: @@ -94,6 +100,7 @@ bit representation of x is interpreted as a float3 ---- + +++++++++++++++++ int,uint in float +++++++++++++++++ @@ -117,6 +124,7 @@ float_bits_to_int bit representation of x is interpreted as an int2 + :Arguments: * **x** : float2 .. _function-math_bits_float_bits_to_int_float: @@ -143,6 +151,7 @@ float_bits_to_uint bit representation of x is interpreted as a uint3 + :Arguments: * **x** : float3 .. _function-math_bits_float_bits_to_uint_float2: @@ -159,6 +168,7 @@ bit representation of x is interpreted as a uint3 ---- + ++++++++++++++++++++++ int64,uint64 in double ++++++++++++++++++++++ @@ -174,6 +184,7 @@ int64,uint64 in double bit representation of x is interpreted as a int64 + :Arguments: * **x** : double .. _function-math_bits_double_bits_to_uint64_double: @@ -182,6 +193,7 @@ bit representation of x is interpreted as a int64 bit representation of x is interpreted as a uint64 + :Arguments: * **x** : double .. _function-math_bits_int64_bits_to_double_int64: @@ -190,6 +202,7 @@ bit representation of x is interpreted as a uint64 bit representation of x is interpreted as a double + :Arguments: * **x** : int64 .. _function-math_bits_uint64_bits_to_double_uint64: @@ -198,8 +211,10 @@ bit representation of x is interpreted as a double bit representation of x is interpreted as a double + :Arguments: * **x** : uint64 + ++++++++++++++ bit-cast vec4f ++++++++++++++ @@ -219,6 +234,7 @@ bit-cast vec4f return an int16 which was bit-cast from x + :Arguments: * **data** : float4 .. _function-math_bits_cast_to_int32_float4: @@ -227,6 +243,7 @@ return an int16 which was bit-cast from x return an int32 which was bit-cast from x + :Arguments: * **data** : float4 .. _function-math_bits_cast_to_int64_float4: @@ -235,6 +252,7 @@ return an int32 which was bit-cast from x return an int64 which was bit-cast from x + :Arguments: * **data** : float4 .. _function-math_bits_cast_to_int8_float4: @@ -243,6 +261,7 @@ return an int64 which was bit-cast from x return an int8 which was bit-cast from x + :Arguments: * **data** : float4 .. _function-math_bits_cast_to_pointer_float4: @@ -251,6 +270,7 @@ return an int8 which was bit-cast from x return a pointer which was bit-cast from x + :Arguments: * **data** : float4 .. _function-math_bits_cast_to_string_float4: @@ -259,6 +279,7 @@ return a pointer which was bit-cast from x return a string which pointer was bit-cast from x + :Arguments: * **data** : float4 @@ -271,6 +292,7 @@ cast_to_vec4f return a float4 which stores bit-cast version of x + :Arguments: * **x** : int64 .. _function-math_bits_cast_to_vec4f_bool: diff --git a/doc/source/stdlib/math_boost.rst b/doc/source/stdlib/math_boost.rst index 1f7b4fb3ae..ff4775c896 100644 --- a/doc/source/stdlib/math_boost.rst +++ b/doc/source/stdlib/math_boost.rst @@ -5,6 +5,8 @@ Boost package for math ====================== +.. das:module:: math_boost + The MATH_BOOST module adds geometric types (``AABB``, ``AABR``, ``Ray``), angle conversion (``degrees``, ``radians``), intersection tests, color space conversion (``linear_to_SRGB``, ``RGBA_TO_UCOLOR``), and view/projection @@ -30,6 +32,8 @@ Example: :: // radians(180) = 3.1415927 // box = (0,0,0) - (10,10,10) + + ++++++++++ Structures ++++++++++ @@ -45,6 +49,7 @@ axis aligned bounding rectangle * **max** : float2 - max coordinates + .. _struct-math_boost-AABB: .. das:attribute:: AABB @@ -56,6 +61,7 @@ axis aligned bounding box * **max** : float3 - max coordinates + .. _struct-math_boost-Ray: .. das:attribute:: Ray @@ -67,6 +73,8 @@ ray (direction and origin) * **origin** : float3 - origin + + +++++++++++++++++ Angle conversions +++++++++++++++++ @@ -80,6 +88,7 @@ Angle conversions convert radians to degrees + :Arguments: * **f** : float .. _function-math_boost_radians_float: @@ -88,8 +97,10 @@ convert radians to degrees convert degrees to radians + :Arguments: * **f** : float + +++++++++++++ Intersections +++++++++++++ @@ -108,6 +119,7 @@ is_intersecting returns true if inputs intersect + :Arguments: * **a** : :ref:`AABB ` * **b** : :ref:`AABB ` @@ -122,6 +134,7 @@ returns true if inputs intersect ---- + ++++++++ Matrices ++++++++ @@ -140,6 +153,7 @@ Matrices left-handed (z forward) look at matrix with origin at `Eye` and target at `At`, and up vector `Up`. + :Arguments: * **Eye** : float3 * **At** : float3 @@ -152,6 +166,7 @@ left-handed (z forward) look at matrix with origin at `Eye` and target at `At`, right-handed (z towards viewer) look at matrix with origin at `Eye` and target at `At`, and up vector `Up`. + :Arguments: * **Eye** : float3 * **At** : float3 @@ -164,6 +179,7 @@ right-handed (z towards viewer) look at matrix with origin at `Eye` and target a right handed (z towards viewer) orthographic (parallel) projection matrix + :Arguments: * **left** : float * **right** : float @@ -182,6 +198,7 @@ right handed (z towards viewer) orthographic (parallel) projection matrix left-handed (z forward) perspective matrix + :Arguments: * **fovy** : float * **aspect** : float @@ -196,6 +213,7 @@ left-handed (z forward) perspective matrix right-handed (z toward viewer) perspective matrix + :Arguments: * **fovy** : float * **aspect** : float @@ -210,6 +228,7 @@ right-handed (z toward viewer) perspective matrix right-handed (z toward viewer) opengl (z in [-1..1]) perspective matrix + :Arguments: * **fovy** : float * **aspect** : float @@ -224,10 +243,12 @@ right-handed (z toward viewer) opengl (z in [-1..1]) perspective matrix planar shadow projection matrix, i.e. all light shadows to be projected on a plane + :Arguments: * **Light** : float4 * **Plane** : float4 + +++++ Plane +++++ @@ -242,6 +263,7 @@ Plane dot product of `Plane` and 'Vec' + :Arguments: * **Plane** : float4 * **Vec** : float4 @@ -252,6 +274,7 @@ dot product of `Plane` and 'Vec' construct plane from point `p` and normal `n` + :Arguments: * **p** : float3 * **n** : float3 @@ -260,10 +283,12 @@ construct plane from point `p` and normal `n` .. das:function:: plane_normalize(Plane: float4) : float4 -normalize `Plane', length xyz will be 1.0 (or 0.0 for no plane) +normalize ``Plane``, length xyz will be 1.0 (or 0.0 for no plane) + :Arguments: * **Plane** : float4 + +++++++++++++++++ Color conversions +++++++++++++++++ @@ -282,6 +307,7 @@ linear_to_SRGB convert value from linear space to sRGB curve space + :Arguments: * **c** : float3 .. _function-math_boost_linear_to_SRGB_float: @@ -294,6 +320,7 @@ convert value from linear space to sRGB curve space ---- + +++++++++++++++++++++++++++ Color packing and unpacking +++++++++++++++++++++++++++ @@ -313,6 +340,7 @@ RGBA_TO_UCOLOR conversion from RGBA to ucolor. xyzw components are in [0,1] range + :Arguments: * **xyzw** : float4 .. _function-math_boost_RGBA_TO_UCOLOR_float_float_float_float: @@ -327,6 +355,7 @@ conversion from RGBA to ucolor. xyzw components are in [0,1] range conversion from ucolor to RGB. x components are in [0,255] range. result is float3(x,y,z) + :Arguments: * **x** : uint .. _function-math_boost_UCOLOR_TO_RGBA_uint: @@ -335,6 +364,7 @@ conversion from ucolor to RGB. x components are in [0,255] range. result is floa conversion from ucolor to RGBA. x components are in [0,255] range + :Arguments: * **x** : uint diff --git a/doc/source/stdlib/network.rst b/doc/source/stdlib/network.rst index 11a07fb3f9..419105360f 100644 --- a/doc/source/stdlib/network.rst +++ b/doc/source/stdlib/network.rst @@ -5,6 +5,8 @@ Network socket library ====================== +.. das:module:: network + The NETWORK module implements networking facilities including HTTP client/server and low-level socket operations. It provides ``Server`` and ``Client`` classes with event-driven callbacks for handling connections, requests, and responses. @@ -13,6 +15,8 @@ All functions and symbols are in "network" module, use require to get access to require network + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -24,6 +28,8 @@ Handled structures Base implementation of the server. + + +++++++ Classes +++++++ @@ -35,37 +41,42 @@ Classes :Fields: * **_server** : smart_ptr< :ref:`NetworkServer `> - Single-socket listener that manages one client connection at a time. + .. _function-network_Server_rq_make_server_adapter_Server_0xe: .. das:function:: Server.make_server_adapter() Creates a low-level server adapter bound to this ``Server`` instance. + .. _function-network_Server_rq_init_Server_int_0x16: .. das:function:: Server.init(port: int) : bool Initializes the server on the specified port; returns ``true`` on success. + :Arguments: * **port** : int -.. _function-network_Server_rq_restore_Server_smart_ptr_ls_NetworkServer_gr__0x19: +.. _function-network_Server_rq_restore_Server_smart_ptr_ls_NetworkServer_gr__ref__0x19: .. das:function:: Server.restore(shared_orphan: smart_ptr&) Restores the server with the given shared orphan network server pointer. This is necessary to re-establish the server state after reload of a script. -:Arguments: * **shared_orphan** : smart_ptr< :ref:`NetworkServer `>& -.. _function-network_Server_rq_save_Server_smart_ptr_ls_NetworkServer_gr__0x20: +:Arguments: * **shared_orphan** : smart_ptr< :ref:`NetworkServer `>\ & + +.. _function-network_Server_rq_save_Server_smart_ptr_ls_NetworkServer_gr__ref__0x20: .. das:function:: Server.save(shared_orphan: smart_ptr&) Saves the server state to a shared orphan network server pointer. This is necessary to re-establish the server state after reload of a script. -:Arguments: * **shared_orphan** : smart_ptr< :ref:`NetworkServer `>& + +:Arguments: * **shared_orphan** : smart_ptr< :ref:`NetworkServer `>\ & .. _function-network_Server_rq_has_session_Server_0x23: @@ -73,30 +84,35 @@ This is necessary to re-establish the server state after reload of a script. Returns ``true`` if the server has an active client session. + .. _function-network_Server_rq_is_open_Server_0x26: .. das:function:: Server.is_open() : bool Returns ``true`` if the server is open and accepting connections. + .. _function-network_Server_rq_is_connected_Server_0x29: .. das:function:: Server.is_connected() : bool Returns ``true`` if the server is currently connected to a client. + .. _function-network_Server_rq_tick_Server_0x2c: .. das:function:: Server.tick() Processes pending connections and incoming data; must be called periodically. + .. _function-network_Server_rq_send_Server_uint8_q__int_0x31: .. das:function:: Server.send(data: uint8?; size: int) : bool Sends a data buffer to the connected client. + :Arguments: * **data** : uint8? * **size** : int @@ -107,6 +123,8 @@ Sends a data buffer to the connected client. Constructs a new ``Server`` instance with default settings. + + ++++++++++++++++++++++++++ Low level NetworkServer IO ++++++++++++++++++++++++++ @@ -125,6 +143,7 @@ Low level NetworkServer IO Creates a new ``Server`` instance. + :Arguments: * **class** : void? implicit * **info** : :ref:`StructInfo `? implicit @@ -135,6 +154,7 @@ Creates a new ``Server`` instance. Initializes the server to listen on the specified port. + :Arguments: * **server** : smart_ptr< :ref:`NetworkServer `> implicit * **port** : int @@ -145,6 +165,7 @@ Initializes the server to listen on the specified port. Returns ``true`` if the server has an active client connection. + :Arguments: * **server** : smart_ptr< :ref:`NetworkServer `> implicit .. _function-network_server_is_open_smart_ptr_ls_NetworkServer_gr__implicit: @@ -153,6 +174,7 @@ Returns ``true`` if the server has an active client connection. Returns ``true`` if the server is listening on its bound port. + :Arguments: * **server** : smart_ptr< :ref:`NetworkServer `> implicit .. _function-network_server_restore_smart_ptr_ls_NetworkServer_gr__implicit_void_q__implicit_StructInfo_const_q__implicit: @@ -161,6 +183,7 @@ Returns ``true`` if the server is listening on its bound port. Restores a server from an orphaned or interrupted state. + :Arguments: * **server** : smart_ptr< :ref:`NetworkServer `> implicit * **class** : void? implicit @@ -173,6 +196,7 @@ Restores a server from an orphaned or interrupted state. Sends data from the server to the connected client. + :Arguments: * **server** : smart_ptr< :ref:`NetworkServer `> implicit * **data** : uint8? implicit @@ -185,6 +209,7 @@ Sends data from the server to the connected client. Processes pending network I/O; must be called periodically for the server to function. + :Arguments: * **server** : smart_ptr< :ref:`NetworkServer `> implicit diff --git a/doc/source/stdlib/profiler.rst b/doc/source/stdlib/profiler.rst index 6ba59e8b61..023244351e 100644 --- a/doc/source/stdlib/profiler.rst +++ b/doc/source/stdlib/profiler.rst @@ -5,6 +5,8 @@ Instrumenting profiler ====================== +.. das:module:: profiler + The PROFILER module provides CPU profiling infrastructure for measuring function execution times. It includes instrumentation-based profiling with hierarchical call tracking and timing statistics. @@ -15,6 +17,8 @@ All functions and symbols are in "profiler" module, use require to get access to require daslib/profiler + + ++++++++++++++++ Profiler control ++++++++++++++++ @@ -27,6 +31,7 @@ Profiler control Enables or disables the profiler for the given context ID. + :Arguments: * **ctxId** : uint64 * **enabled** : bool diff --git a/doc/source/stdlib/profiler_boost.rst b/doc/source/stdlib/profiler_boost.rst index 6be4f1d66e..2123ecd374 100644 --- a/doc/source/stdlib/profiler_boost.rst +++ b/doc/source/stdlib/profiler_boost.rst @@ -5,6 +5,8 @@ Profiler cross-context helpers ============================== +.. das:module:: profiler_boost + The PROFILER_BOOST module extends profiling with high-level macros for scoped timing (``profile_block``), function-level profiling annotations, and formatted output of profiling results. @@ -15,6 +17,8 @@ All functions and symbols are in "profiler_boost" module, use require to get acc require daslib/profiler_boost + + ++++++++++++++++++++++++ Context profiler control ++++++++++++++++++++++++ @@ -28,6 +32,7 @@ Context profiler control Disables the profiler for the given context. + :Arguments: * **ctx** : :ref:`Context ` .. _function-profiler_boost_enable_profiler_Context: @@ -36,6 +41,7 @@ Disables the profiler for the given context. Enables the profiler for the given context. + :Arguments: * **ctx** : :ref:`Context ` diff --git a/doc/source/stdlib/quote.rst b/doc/source/stdlib/quote.rst index f64559212d..b503a564cc 100644 --- a/doc/source/stdlib/quote.rst +++ b/doc/source/stdlib/quote.rst @@ -5,6 +5,8 @@ AST quasiquoting infrastructure =============================== +.. das:module:: quote + The QUOTE module provides quasiquotation support for AST construction. It allows building AST nodes using daslang syntax with ``$``-prefixed splice points for inserting computed values, making macro writing more @@ -14,6 +16,43 @@ All functions and symbols are in "quote" module, use require to get access to it require daslib/quote + + +++++++++++ +Structures +++++++++++ + +.. _struct-quote-LineInfoInitData: + +.. das:attribute:: LineInfoInitData + +Initialization data for source line info reconstruction. + +:Fields: * **fileInfo** : :ref:`FileInfo `? - Pointer to the source file info. + + * **column** : uint - Column number (1-based). + + * **line** : uint - Line number (1-based). + + * **last_column** : uint - Last column number of the range. + + * **last_line** : uint - Last line number of the range. + + + +.. _struct-quote-FileInfoInitData: + +.. das:attribute:: FileInfoInitData + +Initialization data for reconstructing file info. + +:Fields: * **name** : string - File name string. + + * **tabSize** : int - Tab size for the file. + + + + ++++++++++++++++ Clone operations ++++++++++++++++ @@ -36,6 +75,7 @@ clone Clones an array of LineInfoInitData into a dasvector of LineInfo. + :Arguments: * **a** : vector * **b** : array< :ref:`LineInfoInitData `> @@ -64,6 +104,7 @@ Clones an array of LineInfoInitData into a dasvector of LineInfo. Creates a FileInfo from a FileInfoInitData struct. + :Arguments: * **b** : :ref:`FileInfoInitData ` .. _function-quote_clone_line_info_LineInfoInitData: @@ -72,8 +113,10 @@ Creates a FileInfo from a FileInfoInitData struct. Creates a LineInfo from a LineInfoInitData struct. + :Arguments: * **b** : :ref:`LineInfoInitData ` + ++++++++++ Conversion ++++++++++ @@ -86,6 +129,7 @@ Conversion Converts an array of arguments into a MakeStruct smart pointer. + :Arguments: * **args** : auto diff --git a/doc/source/stdlib/random.rst b/doc/source/stdlib/random.rst index 8b561f9bd0..8f77839ba8 100644 --- a/doc/source/stdlib/random.rst +++ b/doc/source/stdlib/random.rst @@ -5,6 +5,8 @@ Random generator library ======================== +.. das:module:: random + The RANDOM module implements pseudo-random number generation using a linear congruential generator with vectorized state (``int4``). It provides integer, float, and vector random values, as well as geometric sampling (unit vectors, @@ -30,6 +32,8 @@ Example: :: // float: 0.5848567 // float: 0.78722495 + + +++++++++ Constants +++++++++ @@ -40,64 +44,72 @@ Constants maximum possible output of random number generator + .. _global-random-LCG_RAND_MAX_BIG: .. das:attribute:: LCG_RAND_MAX_BIG = 1073741823 maximum possible output of random_big_int + + +++++++++++++++++++++++++ Seed and basic generators +++++++++++++++++++++++++ - * :ref:`random_big_int (var seed: int4&) : auto ` - * :ref:`random_float (var seed: int4&) : auto ` - * :ref:`random_float4 (var seed: int4&) : auto ` - * :ref:`random_int (var seed: int4&) : auto ` - * :ref:`random_int4 (var seed: int4&) : auto ` + * :ref:`random_big_int (var seed: int4&) : auto ` + * :ref:`random_float (var seed: int4&) : auto ` + * :ref:`random_float4 (var seed: int4&) : auto ` + * :ref:`random_int (var seed: int4&) : auto ` + * :ref:`random_int4 (var seed: int4&) : auto ` * :ref:`random_seed (seed: int) : auto ` - * :ref:`random_seed2D (var seed: int4&; co: int2; cf: int = 0) : auto ` - * :ref:`random_uint (var seed: int4&) : auto ` + * :ref:`random_seed2D (var seed: int4&; co: int2; cf: int = 0) : auto ` + * :ref:`random_uint (var seed: int4&) : auto ` -.. _function-random_random_big_int_int4: +.. _function-random_random_big_int_int4_ref_: .. das:function:: random_big_int(seed: int4&) : auto random integer 0..32768*32768-1 (LCG_RAND_MAX_BIG) -:Arguments: * **seed** : int4& -.. _function-random_random_float_int4: +:Arguments: * **seed** : int4\ & + +.. _function-random_random_float_int4_ref_: .. das:function:: random_float(seed: int4&) : auto random float 0..1 -:Arguments: * **seed** : int4& -.. _function-random_random_float4_int4: +:Arguments: * **seed** : int4\ & + +.. _function-random_random_float4_int4_ref_: .. das:function:: random_float4(seed: int4&) : auto random float4, each component is 0..1 -:Arguments: * **seed** : int4& -.. _function-random_random_int_int4: +:Arguments: * **seed** : int4\ & + +.. _function-random_random_int_int4_ref_: .. das:function:: random_int(seed: int4&) : auto random integer 0..32767 (LCG_RAND_MAX) -:Arguments: * **seed** : int4& -.. _function-random_random_int4_int4: +:Arguments: * **seed** : int4\ & + +.. _function-random_random_int4_int4_ref_: .. das:function:: random_int4(seed: int4&) : auto random int4, each component is 0..32767 (LCG_RAND_MAX) -:Arguments: * **seed** : int4& + +:Arguments: * **seed** : int4\ & .. _function-random_random_seed_int: @@ -105,27 +117,31 @@ random int4, each component is 0..32767 (LCG_RAND_MAX) constructs seed vector out of single integer seed + :Arguments: * **seed** : int -.. _function-random_random_seed2D_int4_int2_int: +.. _function-random_random_seed2D_int4_ref__int2_int: .. das:function:: random_seed2D(seed: int4&; co: int2; cf: int = 0) : auto constructs seed vector out of 2d screen coordinates and frame counter `cf` -:Arguments: * **seed** : int4& + +:Arguments: * **seed** : int4\ & * **co** : int2 * **cf** : int -.. _function-random_random_uint_int4: +.. _function-random_random_uint_int4_ref_: .. das:function:: random_uint(seed: int4&) : auto random unsigned integer using 3-component LCG, covering full uint range -:Arguments: * **seed** : int4& + +:Arguments: * **seed** : int4\ & + ++++++++++++++++ Random iterators @@ -139,38 +155,43 @@ Random iterators infinite generator of random uints initialized with `rnd_seed` + :Arguments: * **rnd_seed** : int + ++++++++++++++++++++++ Specific distributions ++++++++++++++++++++++ - * :ref:`random_in_unit_disk (var seed: int4&) : auto ` - * :ref:`random_in_unit_sphere (var seed: int4&) : auto ` - * :ref:`random_unit_vector (var seed: int4&) : auto ` + * :ref:`random_in_unit_disk (var seed: int4&) : auto ` + * :ref:`random_in_unit_sphere (var seed: int4&) : auto ` + * :ref:`random_unit_vector (var seed: int4&) : auto ` -.. _function-random_random_in_unit_disk_int4: +.. _function-random_random_in_unit_disk_int4_ref_: .. das:function:: random_in_unit_disk(seed: int4&) : auto Returns a random float3 point uniformly distributed inside the unit disk (length <= 1, z=0). -:Arguments: * **seed** : int4& -.. _function-random_random_in_unit_sphere_int4: +:Arguments: * **seed** : int4\ & + +.. _function-random_random_in_unit_sphere_int4_ref_: .. das:function:: random_in_unit_sphere(seed: int4&) : auto Returns a random float3 point uniformly distributed inside the unit sphere (length <= 1). -:Arguments: * **seed** : int4& -.. _function-random_random_unit_vector_int4: +:Arguments: * **seed** : int4\ & + +.. _function-random_random_unit_vector_int4_ref_: .. das:function:: random_unit_vector(seed: int4&) : auto random float3 unit vector (length=1.) -:Arguments: * **seed** : int4& + +:Arguments: * **seed** : int4\ & diff --git a/doc/source/stdlib/refactor.rst b/doc/source/stdlib/refactor.rst index e807aa9b67..ed3067120c 100644 --- a/doc/source/stdlib/refactor.rst +++ b/doc/source/stdlib/refactor.rst @@ -5,6 +5,8 @@ Automated refactoring tools =========================== +.. das:module:: refactor + The REFACTOR module implements automated code refactoring transformations. It provides tools for renaming symbols, extracting functions, and other structural code changes that preserve program semantics. @@ -13,6 +15,8 @@ All functions and symbols are in "refactor" module, use require to get access to require daslib/refactor + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -23,12 +27,15 @@ Function annotations Function annotation implementing extract-method refactoring. + .. _handle-refactor-ExtractVariableFunction: .. das:attribute:: ExtractVariableFunction Function annotation for extract-variable target functions. + + +++++++++++ Call macros +++++++++++ @@ -39,6 +46,8 @@ Call macros Call macro implementing extract-variable refactoring. + + ++++++++++++++++++++++ Refactoring operations ++++++++++++++++++++++ @@ -46,7 +55,7 @@ Refactoring operations * :ref:`extract_expression (method_name: string; expr: auto) : auto ` * :ref:`extract_method (method_name: string; blk: block\<():void\>) ` * :ref:`extract_variable_nonref (method_name: string; expr: auto) : auto ` - * :ref:`extract_variable_ref (method_name: string; var expr: auto(TT)& ==const) : TT& ` + * :ref:`extract_variable_ref (method_name: string; var expr: auto(TT)& ==const) : TT& ` .. _function-refactor_extract_expression_string_auto_0x1f: @@ -54,6 +63,7 @@ Refactoring operations Marks an expression for expression extraction refactoring. + :Arguments: * **method_name** : string * **expr** : auto @@ -64,6 +74,7 @@ Marks an expression for expression extraction refactoring. Marks a block of code for method extraction refactoring. + :Arguments: * **method_name** : string * **blk** : block @@ -74,18 +85,20 @@ Marks a block of code for method extraction refactoring. Marks an expression for variable extraction by value. + :Arguments: * **method_name** : string * **expr** : auto -.. _function-refactor_extract_variable_ref_string__autoTT__eq__eq_const_0x90: +.. _function-refactor_extract_variable_ref_string__autoTT_ref___eq__eq_const_0x90: .. das:function:: extract_variable_ref(method_name: string; expr: auto(TT)& ==const) : TT& Marks an expression for variable extraction by reference. + :Arguments: * **method_name** : string - * **expr** : auto(TT)&! + * **expr** : auto(TT)\ &! diff --git a/doc/source/stdlib/regex.rst b/doc/source/stdlib/regex.rst index a932db8385..8fa5a63cd3 100644 --- a/doc/source/stdlib/regex.rst +++ b/doc/source/stdlib/regex.rst @@ -5,6 +5,8 @@ Regular expression library ========================== +.. das:module:: regex + The REGEX module implements regular expression matching and searching. It provides ``regex_compile`` for building patterns, ``regex_match`` for full-string matching, ``regex_search`` for finding the first match anywhere, @@ -87,6 +89,8 @@ Example: :: // found: 25 // found: 180 + + ++++++++++++ Type aliases ++++++++++++ @@ -96,11 +100,13 @@ Type aliases .. das:attribute:: CharSet = uint[8] Bitfield character set used internally by the regex engine. + .. _alias-ReGenRandom: .. das:attribute:: ReGenRandom = iterator Random number generator callback used by ``re_gen`` for regex-based string generation. + .. _alias-MaybeReNode: .. das:attribute:: variant MaybeReNode @@ -112,6 +118,8 @@ Regex node or nothing. * **nothing** : void? - Nothing. + + ++++++++++++ Enumerations ++++++++++++ @@ -155,6 +163,8 @@ Type of regular expression operation. * **NegativeLookahead** = 15 - Negative lookahead assertion (?!...) + + ++++++++++ Structures ++++++++++ @@ -197,11 +207,12 @@ Regular expression node. * **max_rep** : int - Maximum repetition count for counted quantifiers (-1 means unlimited) - * **lazy** : bool - Whether this quantifier uses lazy matching (*?, +?, ??, {n,m}?) + * **lazy** : bool - Whether this quantifier uses lazy matching (``*?``, ``+?``, ``??``, ``{n,m}?``) * **tail** : uint8? - Tail of the string + .. _struct-regex-Regex: .. das:attribute:: Regex @@ -223,6 +234,8 @@ Regular expression structure. * **dotAll** : bool - When true, ``.`` matches newline characters as well. + + ++++++++++++++++++++++++++ Compilation and validation ++++++++++++++++++++++++++ @@ -241,6 +254,7 @@ Compilation and validation Prints all characters contained in a ``CharSet`` for debugging purposes. + :Arguments: * **cset** : :ref:`CharSet ` .. _function-regex_is_valid_Regex: @@ -249,6 +263,7 @@ Prints all characters contained in a ``CharSet`` for debugging purposes. Returns ``true`` if the compiled regex is valid and ready for matching. + :Arguments: * **re** : :ref:`Regex ` @@ -261,6 +276,7 @@ regex_compile Compiles a regular expression pattern string into a ``Regex`` object. Panics if the pattern is invalid. An overload taking a ``var re : Regex`` out-parameter returns ``bool`` instead of panicking. Optional flags: ``case_insensitive=true`` for ASCII case-insensitive matching, ``dot_all=true`` for ``.`` to also match newline characters. + :Arguments: * **expr** : string * **case_insensitive** : bool @@ -283,6 +299,7 @@ Compiles a regular expression pattern string into a ``Regex`` object. Panics if Prints the internal structure of a compiled regex for debugging purposes. + :Arguments: * **regex** : :ref:`Regex ` .. _function-regex_visit_top_down_ReNode_q__block_ls_var_n_c_ReNode_q__c_void_gr_: @@ -291,16 +308,18 @@ Prints the internal structure of a compiled regex for debugging purposes. Visits all nodes of a compiled regex tree in top-down order, invoking a callback for each node. + :Arguments: * **node** : :ref:`ReNode `? * **blk** : block<(n: :ref:`ReNode `?):void> + ++++++ Access ++++++ - * :ref:`Regex[] (regex: Regex; index: int) : range ` - * :ref:`Regex[] (regex: Regex; name: string) : range ` + * :ref:`Regex[] (regex: Regex; index: int) : range ` + * :ref:`Regex[] (regex: Regex; name: string) : range ` * :ref:`regex_foreach (var regex: Regex; str: string; blk: block\<(at:range):bool\>) ` * :ref:`regex_group (regex: Regex; index: int; match: string) : string ` * :ref:`regex_group_by_name (regex: Regex; name: string; str: string) : string ` @@ -309,17 +328,19 @@ Access Regex[] ^^^^^^^ -.. _function-regex__Regex_int: +.. _function-regex__lb__rb__Regex_int: .. das:function:: Regex[](regex: Regex; index: int) : range -Returns the match ``range`` for the capturing group at the given integer index (1-based). An overload accepting a string name for named capturing groups ``(?P...)`` is also available (returns ``range(0,0)`` if not found). Use with ``slice`` to extract the matched substring. +// stub +def Regex[] (regex: Regex; index: int) : range + :Arguments: * **regex** : :ref:`Regex ` * **index** : int -.. _function-regex__Regex_string: +.. _function-regex__lb__rb__Regex_string: .. das:function:: Regex[](regex: Regex; name: string) : range @@ -331,6 +352,7 @@ Returns the match ``range`` for the capturing group at the given integer index ( Iterates over all non-overlapping matches of a regex in a string, invoking a block for each match. + :Arguments: * **regex** : :ref:`Regex ` * **str** : string @@ -343,6 +365,7 @@ Iterates over all non-overlapping matches of a regex in a string, invoking a blo Returns the substring captured by the specified group index after a successful match. + :Arguments: * **regex** : :ref:`Regex ` * **index** : int @@ -355,12 +378,14 @@ Returns the substring captured by the specified group index after a successful m Returns the matched substring for the named capturing group ``(?P...)``. Returns empty string if the group name is not found. + :Arguments: * **regex** : :ref:`Regex ` * **name** : string * **str** : string + +++++++++++++++ Match & replace +++++++++++++++ @@ -378,6 +403,7 @@ Match & replace Matches a compiled regex against a string and returns the end position of the match, or ``-1`` on failure. + :Arguments: * **regex** : :ref:`Regex ` * **str** : string @@ -390,6 +416,7 @@ Matches a compiled regex against a string and returns the end position of the ma Returns an array of all non-overlapping match ranges for the regular expression in ``str``. + :Arguments: * **regex** : :ref:`Regex ` * **str** : string @@ -404,6 +431,7 @@ regex_replace Replaces each substring matched by the regex with the result returned by the provided block. An overload accepting a template string is also available, supporting ``$0``/``$&`` for the whole match, ``$1``–``$9`` for numbered groups, ``${name}`` for named groups, and ``$$`` for a literal ``$``. + :Arguments: * **regex** : :ref:`Regex ` * **str** : string @@ -422,6 +450,7 @@ Replaces each substring matched by the regex with the result returned by the pro Searches for the first occurrence of the regular expression anywhere in ``str``, starting from ``offset``. Returns ``int2(start, end)`` on success, or ``int2(-1, -1)`` if not found. Unlike ``regex_match``, this function scans the entire string. + :Arguments: * **regex** : :ref:`Regex ` * **str** : string @@ -434,10 +463,12 @@ Searches for the first occurrence of the regular expression anywhere in ``str``, Splits ``str`` by all non-overlapping matches of the regular expression. Returns an array of substrings between matches. + :Arguments: * **regex** : :ref:`Regex ` * **str** : string + ++++++++++ Generation ++++++++++ @@ -451,6 +482,7 @@ Generation Generates a random string that matches the given compiled regex. + :Arguments: * **re** : :ref:`Regex ` * **rnd** : :ref:`ReGenRandom ` @@ -462,3 +494,4 @@ Generates a random string that matches the given compiled regex. Returns the maximum repetition limit used by regex quantifiers during string generation. + diff --git a/doc/source/stdlib/regex_boost.rst b/doc/source/stdlib/regex_boost.rst index d4c26419bf..156b7aed76 100644 --- a/doc/source/stdlib/regex_boost.rst +++ b/doc/source/stdlib/regex_boost.rst @@ -5,6 +5,8 @@ Boost package for REGEX ======================= +.. das:module:: regex_boost + The REGEX_BOOST module extends regular expressions with the ``%regex~`` reader macro for compile-time regex construction. Inside the reader macro, backslashes are literal — no double-escaping is needed (e.g. ``%regex~\d{3}%%`` instead of @@ -44,6 +46,8 @@ Example: :: // found: 25 // found: 180 + + +++++++++++++ Reader macros +++++++++++++ @@ -54,3 +58,4 @@ Reader macros Reader macro that converts ``%regex~`` literals into precompiled ``regex::Regex`` objects at compilation time. Optional flags can follow a second ``~``: ``%regex~pattern~i%%`` for case-insensitive, ``%regex~pattern~s%%`` for dot-all, ``%regex~pattern~is%%`` for both. + diff --git a/doc/source/stdlib/remove_call_args.rst b/doc/source/stdlib/remove_call_args.rst index 0e7d3d7dac..38fe19cb36 100644 --- a/doc/source/stdlib/remove_call_args.rst +++ b/doc/source/stdlib/remove_call_args.rst @@ -5,6 +5,8 @@ Call argument removal annotation ================================ +.. das:module:: remove_call_args + The REMOVE_CALL_ARGS module provides AST transformation macros that remove specific arguments from function calls at compile time. Used for implementing optional parameter patterns and compile-time argument stripping. @@ -13,6 +15,8 @@ All functions and symbols are in "remove_call_args" module, use require to get a require daslib/remove_call_args + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -24,3 +28,4 @@ Function annotations This macro removes all arguments by given indices [remove_call_args(arg=(1,2,3))] + diff --git a/doc/source/stdlib/rst.rst b/doc/source/stdlib/rst.rst index 46e0a77f4b..24131db24d 100644 --- a/doc/source/stdlib/rst.rst +++ b/doc/source/stdlib/rst.rst @@ -5,6 +5,8 @@ Documentation generator ======================= +.. das:module:: rst + The RST module implements the documentation generation pipeline for daslang. It uses RTTI to introspect modules, types, and functions, then produces reStructuredText output suitable for Sphinx documentation builds. @@ -13,6 +15,8 @@ All functions and symbols are in "rst" module, use require to get access to it. require daslib/rst + + ++++++++++ Structures ++++++++++ @@ -32,6 +36,7 @@ Group of documentation items. * **_module** : :ref:`Module `? - Module, to which this group belongs. + .. _struct-rst-DocsHook: .. das:attribute:: DocsHook @@ -43,6 +48,8 @@ Hook for RST documentation generation. * **afterEnums** : lambda<(f: :ref:`FILE `?;was_enums:bool):void> - Additional generation hook after the enumerations. + + ++++++++++++++++ Document writers ++++++++++++++++ @@ -58,6 +65,7 @@ Document writers Generates RST documentation for a single module and writes it to a file. + :Arguments: * **name** : string * **mod** : :ref:`Module `? @@ -74,6 +82,7 @@ Generates RST documentation for a single module and writes it to a file. Generates RST documentation for a single enumeration type. + :Arguments: * **doc_file** : :ref:`file ` * **mod** : :ref:`Module `? @@ -86,6 +95,7 @@ Generates RST documentation for a single enumeration type. Generates RST documentation for all enumerations in the given modules. + :Arguments: * **doc_file** : :ref:`file ` * **mods** : array< :ref:`Module `?> @@ -96,6 +106,7 @@ Generates RST documentation for all enumerations in the given modules. Generates RST documentation for multiple modules and writes them to files. + :Arguments: * **name** : string * **mods** : array< :ref:`Module `?> @@ -106,6 +117,7 @@ Generates RST documentation for multiple modules and writes them to files. * **hook** : :ref:`DocsHook ` + ++++++++++++ Descriptions ++++++++++++ @@ -118,7 +130,9 @@ Descriptions Returns a concise one-line description of an expression or type. -:Arguments: * **expr** : option< :ref:`Expression `?|smart_ptr< :ref:`Expression `>&> + +:Arguments: * **expr** : option< :ref:`Expression `?\ | smart_ptr< :ref:`Expression `>\ &> + ++++++++++++ Label makers @@ -137,9 +151,10 @@ function_label_file Creates a unique, file-name-safe label string for a function. + :Arguments: * **name** : auto - * **value** : smart_ptr< :ref:`TypeDecl `>& + * **value** : smart_ptr< :ref:`TypeDecl `>\ & * **drop_args** : int @@ -149,6 +164,7 @@ Creates a unique, file-name-safe label string for a function. ---- + ++++++++++++++++++ RST section makers ++++++++++++++++++ @@ -161,10 +177,12 @@ RST section makers Creates a named documentation group with a decorative RST section header. + :Arguments: * **name** : string * **plus** : string + ++++++++++++++++ Group operations ++++++++++++++++ @@ -180,6 +198,7 @@ Group operations Appends functions whose names match a regex to an existing documentation group. + :Arguments: * **group** : :ref:`DocGroup ` * **mod** : :ref:`Module `? @@ -196,6 +215,7 @@ group_by_regex Groups module items whose names match the provided regular expression under a documentation section. + :Arguments: * **name** : string * **mod** : :ref:`Module `? @@ -214,8 +234,10 @@ Groups module items whose names match the provided regular expression under a do Marks the specified documentation group as hidden so it is excluded from output. + :Arguments: * **group** : :ref:`DocGroup ` + ++++++++++++++ Naming helpers ++++++++++++++ @@ -228,6 +250,7 @@ Naming helpers Escapes special characters in a function name to produce a safe identifier for RST output. + :Arguments: * **name** : string diff --git a/doc/source/stdlib/rtti.rst b/doc/source/stdlib/rtti.rst index 29efc016a9..6dd4c4cb5d 100644 --- a/doc/source/stdlib/rtti.rst +++ b/doc/source/stdlib/rtti.rst @@ -5,6 +5,8 @@ Runtime type information library ================================ +.. das:module:: rtti + The RTTI module exposes runtime type information and program introspection facilities. It allows querying module structure, type declarations, function signatures, annotations, and other compile-time metadata at runtime. Used primarily by macro libraries and @@ -14,6 +16,8 @@ All functions and symbols are in "rtti" module, use require to get access to it. require rtti + + ++++++++++++ Type aliases ++++++++++++ @@ -43,6 +47,7 @@ Flags which represent state of the `Program` object, both during and after compi * **macroException** (0x100) - indicates that a macro exception has occurred. + .. _alias-context_category_flags: .. das:attribute:: bitfield context_category_flags @@ -70,6 +75,7 @@ Flags which specify type of the `Context`. * **audio** (0x200) - indicates that the context is an audio context. + .. _alias-TypeInfoFlags: .. das:attribute:: bitfield TypeInfoFlags @@ -111,6 +117,7 @@ Flags which specify properties of the `TypeInfo` object (any rtti type). * **isPrivate** (0x10000) - indicates that the type is private. + .. _alias-StructInfoFlags: .. das:attribute:: bitfield StructInfoFlags @@ -128,6 +135,7 @@ Flags which represent properties of the `StructInfo` object (rtti object which r * **lockCheck** (0x10) - This structure needs lock checking. + .. _alias-ModuleFlags: .. das:attribute:: bitfield ModuleFlags @@ -157,6 +165,7 @@ Flags which represent the module's state. * **allowPodInscope** (0x400) - This module allows pod inscope. + .. _alias-AnnotationDeclarationFlags: .. das:attribute:: bitfield AnnotationDeclarationFlags @@ -166,6 +175,7 @@ Flags which represent properties of the `AnnotationDeclaration` object. :Fields: * **inherited** (0x1) - Indicates that the annotation is inherited. + .. _alias-RttiValue: .. das:attribute:: variant RttiValue @@ -191,11 +201,14 @@ Variant type which represents value of any annotation arguments and variable ann * **nothing** : any - no value + .. _alias-FileAccessPtr: .. das:attribute:: FileAccessPtr = smart_ptr Type alias for ``smart_ptr`` — a reference-counted pointer to a ``FileAccess`` object, used as the standard way to pass file access to the compiler. + + +++++++++ Constants +++++++++ @@ -205,26 +218,32 @@ Constants .. das:attribute:: FUNCINFO_INIT = 0x1 Bit flag constant on ``FuncInfo.flags`` indicating that the function runs during ``Context`` initialization (``[init]`` attribute). + .. _global-rtti-FUNCINFO_BUILTIN: .. das:attribute:: FUNCINFO_BUILTIN = 0x2 Bit flag constant on ``FuncInfo.flags`` indicating that the function is a built-in (C++-bound) function rather than a daslang-defined one. + .. _global-rtti-FUNCINFO_PRIVATE: .. das:attribute:: FUNCINFO_PRIVATE = 0x4 Bit flag constant on ``FuncInfo.flags`` indicating that the function has ``[private]`` visibility and cannot be called from other modules. + .. _global-rtti-FUNCINFO_SHUTDOWN: .. das:attribute:: FUNCINFO_SHUTDOWN = 0x8 Bit flag constant on ``FuncInfo.flags`` indicating that the function runs during ``Context`` shutdown (``[finalize]`` attribute). + .. _global-rtti-FUNCINFO_LATE_INIT: .. das:attribute:: FUNCINFO_LATE_INIT = 0x20 Bit flag constant on ``FuncInfo.flags`` indicating the function uses late initialization with a custom init order (``[init(order)]`` attribute). + + ++++++++++++ Enumerations ++++++++++++ @@ -448,6 +467,7 @@ Enumeration which represents error type for each of the errors which compiler re * **missing_node** = 50100 - Missing simulation node. + .. _enum-rtti-ConstMatters: .. das:attribute:: ConstMatters @@ -459,6 +479,7 @@ Yes or no flag which indicates if constant flag of the type matters (during comp * **yes** = 1 - const matters, when comparing types. + .. _enum-rtti-RefMatters: .. das:attribute:: RefMatters @@ -470,6 +491,7 @@ Yes or no flag which indicates if reference flag of the type matters (during com * **yes** = 1 - Ref matters, when comparing types. + .. _enum-rtti-TemporaryMatters: .. das:attribute:: TemporaryMatters @@ -481,6 +503,7 @@ Yes or no flag which indicates if temporary flag of the type matters (during com * **yes** = 1 - Temporary matters, when comparing types. + .. _enum-rtti-Type: .. das:attribute:: Type @@ -596,6 +619,8 @@ One of the fundamental (base) types of any type object. * **tVariant** = 53 - Variant type. + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -771,6 +796,7 @@ Handled structures * **jit_path_to_linker** : :ref:`das_string ` - Path to linker, which is used in JIT. + .. _handle-rtti-FileInfo: .. das:attribute:: FileInfo @@ -782,6 +808,7 @@ Information about a single file stored in the `FileAccess` object. * **tabSize** : int - Tab size for this file. + .. _handle-rtti-LineInfo: .. das:attribute:: LineInfo @@ -799,6 +826,7 @@ Information about a section of the file stored in the `FileAccess` object. * **last_line** : uint - Last line number (1-based). + .. _handle-rtti-Context: .. das:attribute:: Context @@ -809,24 +837,28 @@ Information about a section of the file stored in the `FileAccess` object. Property-like accessor that returns the ``uint64`` semantic hash of the initialization code for the given ``Context``, useful for detecting code changes. + .. _function-rtti__dot__rq_totalFunctions_Context_implicit: .. das:function:: Context implicit.totalFunctions() : int Property-like accessor that returns the total number of registered ``SimFunction`` entries in the given ``Context``. + .. _function-rtti__dot__rq_totalVariables_Context_implicit: .. das:function:: Context implicit.totalVariables() : int Property-like accessor that returns the total number of global variables registered in the given ``Context``. + .. _function-rtti__dot__rq_getCodeAllocatorId_Context_implicit: .. das:function:: Context implicit.getCodeAllocatorId() : uint64 Property-like accessor that returns a non-persistent unique integer ID of the code (node) allocator associated with the given ``Context``. + :Properties: * **getInitSemanticHash** : uint64 * **totalFunctions** : int @@ -856,6 +888,7 @@ Object which holds single Daslang Context. Context is the result of the simulati * **contextMutex** : :ref:`recursive_mutex `? - Context mutex. + .. _handle-rtti-Error: .. das:attribute:: Error @@ -873,6 +906,7 @@ Object which holds information about compilation error or exception. * **cerr** : :ref:`CompilationError ` - Compilation error. + .. _handle-rtti-FileAccess: .. das:attribute:: FileAccess @@ -880,6 +914,7 @@ Object which holds information about compilation error or exception. Object which holds collection of files as well as means to access them (Project). + .. _handle-rtti-Module: .. das:attribute:: Module @@ -893,6 +928,7 @@ Object which holds information about compilation error or exception. * **moduleFlags** : :ref:`ModuleFlags ` - Module flags. + .. _handle-rtti-ModuleGroup: .. das:attribute:: ModuleGroup @@ -900,6 +936,7 @@ Object which holds information about compilation error or exception. Collection of modules. + .. _handle-rtti-AnnotationArgument: .. das:attribute:: AnnotationArgument @@ -921,6 +958,7 @@ Single argument of the annotation, typically part of the `AnnotationArgumentList * **at** : :ref:`LineInfo ` - line info where the argument is defined + .. _handle-rtti-Program: .. das:attribute:: Program @@ -931,12 +969,14 @@ Single argument of the annotation, typically part of the `AnnotationArgumentList Property-like accessor that returns the ``Module`` pointer for the module currently being inferred in the given ``Program``. + .. _function-rtti__dot__rq_getDebugger_Program_implicit: .. das:function:: Program implicit.getDebugger() : bool Property-like accessor that returns ``true`` if the debugger is attached and enabled for the given ``Program``. + :Properties: * **getThisModule** : :ref:`Module `? * **getDebugger** : bool @@ -964,6 +1004,7 @@ Object representing full information about Daslang program during and after comp * **policies** : :ref:`CodeOfPolicies ` - code of policies + .. _handle-rtti-Annotation: .. das:attribute:: Annotation @@ -974,36 +1015,42 @@ Object representing full information about Daslang program during and after comp Property-like accessor that returns ``true`` if the given ``Annotation`` is a ``TypeAnnotation`` (defines a handled type). + .. _function-rtti__dot__rq_isBasicStructureAnnotation_Annotation_implicit: .. das:function:: Annotation implicit.isBasicStructureAnnotation() : bool Property-like accessor that returns ``true`` if the given ``Annotation`` is a ``BasicStructureAnnotation``, which exposes C++ struct fields to daslang. + .. _function-rtti__dot__rq_isStructureAnnotation_Annotation_implicit: .. das:function:: Annotation implicit.isStructureAnnotation() : bool Property-like accessor that returns ``true`` if the given ``Annotation`` is a structure annotation (applied to struct declarations). + .. _function-rtti__dot__rq_isStructureTypeAnnotation_Annotation_implicit: .. das:function:: Annotation implicit.isStructureTypeAnnotation() : bool Property-like accessor that returns ``true`` if the given ``Annotation`` is a ``StructureTypeAnnotation``, which binds a C++ class as a daslang handled struct. + .. _function-rtti__dot__rq_isFunctionAnnotation_Annotation_implicit: .. das:function:: Annotation implicit.isFunctionAnnotation() : bool Property-like accessor that returns ``true`` if the given ``Annotation`` is a ``FunctionAnnotation`` (applied to functions). + .. _function-rtti__dot__rq_isEnumerationAnnotation_Annotation_implicit: .. das:function:: Annotation implicit.isEnumerationAnnotation() : bool Property-like accessor that returns ``true`` if the given ``Annotation`` is an ``EnumerationAnnotation``. + :Properties: * **isTypeAnnotation** : bool * **isBasicStructureAnnotation** : bool @@ -1025,6 +1072,7 @@ Handled type or macro. * **_module** : :ref:`Module `? - module where the annotation is defined + .. _handle-rtti-AnnotationDeclaration: .. das:attribute:: AnnotationDeclaration @@ -1040,6 +1088,7 @@ Annotation declaration, its location, and arguments. * **flags** : :ref:`AnnotationDeclarationFlags ` - flags associated with the annotation. + .. _handle-rtti-TypeAnnotation: .. das:attribute:: TypeAnnotation @@ -1050,132 +1099,154 @@ Annotation declaration, its location, and arguments. Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` wraps any C++ vector-like container (e.g., ``std::vector``). + .. _function-rtti__dot__rq_canMove_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.canMove() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` supports move semantics. + .. _function-rtti__dot__rq_canCopy_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.canCopy() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` supports copy semantics. + .. _function-rtti__dot__rq_canClone_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.canClone() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` supports the clone operation. + .. _function-rtti__dot__rq_isPod_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.isPod() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` is a POD (plain old data) type — no constructor, destructor, or special semantics. + .. _function-rtti__dot__rq_isRawPod_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.isRawPod() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` is a raw POD type — a basic value type excluding pointers and strings. + .. _function-rtti__dot__rq_isRefType_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.isRefType() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` is always passed by reference, or is itself a reference type. + .. _function-rtti__dot__rq_hasNonTrivialCtor_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.hasNonTrivialCtor() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` has a non-trivial constructor (requires explicit initialization). + .. _function-rtti__dot__rq_hasNonTrivialDtor_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.hasNonTrivialDtor() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` has a non-trivial destructor (requires explicit finalization). + .. _function-rtti__dot__rq_hasNonTrivialCopy_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.hasNonTrivialCopy() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` has non-trivial copy semantics (i.e., a custom copy constructor). + .. _function-rtti__dot__rq_canBePlacedInContainer_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.canBePlacedInContainer() : bool Property-like accessor that returns ``true`` if values of the given ``TypeAnnotation`` can be stored inside arrays, tables, or other containers. + .. _function-rtti__dot__rq_isLocal_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.isLocal() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` can be used as a local variable type within a function. + .. _function-rtti__dot__rq_canNew_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.canNew() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` supports heap allocation via ``new``. + .. _function-rtti__dot__rq_canDelete_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.canDelete() : bool Property-like accessor that returns ``true`` if values of the given ``TypeAnnotation`` can be explicitly deleted. + .. _function-rtti__dot__rq_needDelete_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.needDelete() : bool Property-like accessor that returns ``true`` if values of the given ``TypeAnnotation`` require explicit ``delete`` to free resources. + .. _function-rtti__dot__rq_canDeletePtr_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.canDeletePtr() : bool Property-like accessor that returns ``true`` if a pointer to the given ``TypeAnnotation`` type can be explicitly deleted. + .. _function-rtti__dot__rq_isIterable_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.isIterable() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` supports iteration via ``for``. + .. _function-rtti__dot__rq_isShareable_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.isShareable() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` can be shared across multiple ``Context`` objects. + .. _function-rtti__dot__rq_isSmart_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.isSmart() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` represents a ``smart_ptr`` managed type. + .. _function-rtti__dot__rq_avoidNullPtr_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.avoidNullPtr() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` requires pointers to its type to be non-null (i.e., must be initialized on creation). + .. _function-rtti__dot__rq_sizeOf_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.sizeOf() : uint64 Property-like accessor that returns the size in bytes of the type described by the given ``TypeAnnotation``. + .. _function-rtti__dot__rq_alignOf_TypeAnnotation_implicit: .. das:function:: TypeAnnotation implicit.alignOf() : uint64 Property-like accessor that returns the memory alignment requirement (in bytes) of the type described by the given ``TypeAnnotation``. + :Properties: * **is_any_vector** : bool * **canMove** : bool @@ -1229,6 +1300,7 @@ Handled type. * **_module** : :ref:`Module `? - module where the annotation is defined + .. _handle-rtti-BasicStructureAnnotation: .. das:attribute:: BasicStructureAnnotation @@ -1239,6 +1311,7 @@ Handled type. Property-like accessor that returns the number of fields declared in the given ``BasicStructureAnnotation``. + :Properties: * **fieldCount** : int Handled type which represents a structure-like annotation for exposing C++ types to daslang. @@ -1248,6 +1321,7 @@ Handled type which represents a structure-like annotation for exposing C++ types * **cppName** : :ref:`das_string ` - C++ class name used in AOT code generation + .. _handle-rtti-EnumValueInfo: .. das:attribute:: EnumValueInfo @@ -1259,6 +1333,7 @@ Single element of enumeration, its name and value. * **value** : int64 - value of the enumeration value + .. _handle-rtti-EnumInfo: .. das:attribute:: EnumInfo @@ -1276,6 +1351,7 @@ Type object which represents enumeration. * **hash** : uint64 - hash of the enumeration + .. _handle-rtti-StructInfo: .. das:attribute:: StructInfo @@ -1301,6 +1377,7 @@ Type object which represents structure or class. * **firstGcField** : uint - index of the first GC field in the structure, i.e. field which requires garbage collection marking + .. _handle-rtti-TypeInfo: .. das:attribute:: TypeInfo @@ -1311,78 +1388,91 @@ Type object which represents structure or class. Property-like accessor that returns the ``EnumInfo`` pointer describing the underlying enumeration for the given enum ``TypeAnnotation``. + .. _function-rtti__dot__rq_isRef_TypeInfo_implicit: .. das:function:: TypeInfo implicit.isRef() : bool Property-like accessor that returns ``true`` if the given ``TypeInfo`` describes a reference (``&``) type. + .. _function-rtti__dot__rq_isRefType_TypeInfo_implicit: .. das:function:: TypeInfo implicit.isRefType() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` is always passed by reference, or is itself a reference type. + .. _function-rtti__dot__rq_isRefValue_TypeInfo_implicit: .. das:function:: TypeInfo implicit.isRefValue() : bool Property-like accessor that returns ``true`` if the given ``TypeInfo`` describes a ref-value type (boxed value accessed by reference). + .. _function-rtti__dot__rq_canCopy_TypeInfo_implicit: .. das:function:: TypeInfo implicit.canCopy() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` supports copy semantics. + .. _function-rtti__dot__rq_isPod_TypeInfo_implicit: .. das:function:: TypeInfo implicit.isPod() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` is a POD (plain old data) type — no constructor, destructor, or special semantics. + .. _function-rtti__dot__rq_isRawPod_TypeInfo_implicit: .. das:function:: TypeInfo implicit.isRawPod() : bool Property-like accessor that returns ``true`` if the given ``TypeAnnotation`` is a raw POD type — a basic value type excluding pointers and strings. + .. _function-rtti__dot__rq_isConst_TypeInfo_implicit: .. das:function:: TypeInfo implicit.isConst() : bool Property-like accessor that returns ``true`` if the given ``TypeInfo`` describes a ``const``-qualified type. + .. _function-rtti__dot__rq_isTemp_TypeInfo_implicit: .. das:function:: TypeInfo implicit.isTemp() : bool Property-like accessor that returns ``true`` if the given ``TypeInfo`` describes a temporary (``#``) type that cannot be captured or stored. + .. _function-rtti__dot__rq_isImplicit_TypeInfo_implicit: .. das:function:: TypeInfo implicit.isImplicit() : bool Property-like accessor that returns ``true`` if the given ``TypeInfo`` describes an implicit (compiler-inferred) type. + .. _function-rtti__dot__rq_annotation_TypeInfo_implicit: .. das:function:: TypeInfo implicit.annotation() : TypeAnnotation? Property-like accessor that returns the ``Annotation`` pointer associated with the given ``TypeInfo``. + .. _function-rtti__dot__rq_annotation_or_name_TypeInfo_implicit: .. das:function:: TypeInfo implicit.annotation_or_name() : TypeAnnotation? Property-like accessor that returns the annotation name if one exists, otherwise returns the raw type name from the given ``TypeInfo``. + .. _function-rtti__dot__rq_structType_TypeInfo_implicit: .. das:function:: TypeInfo implicit.structType() : StructInfo? Property-like accessor that returns the ``StructInfo`` pointer for the struct described by the given ``TypeInfo``, or null if not a struct type. + :Properties: * **enumType** : :ref:`EnumInfo `? * **isRef** : bool @@ -1436,6 +1526,7 @@ Object which represents any Daslang type. * **dimSize** : uint - number of dimensions in the type + .. _handle-rtti-VarInfo: .. das:attribute:: VarInfo @@ -1475,6 +1566,7 @@ Object which represents variable declaration. * **nextGcField** : uint - next garbage collection field in the structure, which requires garbage collection marking + .. _handle-rtti-LocalVariableInfo: .. das:attribute:: LocalVariableInfo @@ -1510,6 +1602,7 @@ Object which represents local variable declaration. * **localFlags** : :ref:`LocalVariableInfoFlags ` - local variable flags + .. _handle-rtti-FuncInfo: .. das:attribute:: FuncInfo @@ -1541,6 +1634,7 @@ Object which represents function declaration. * **globalCount** : uint - number of accessed global variables + .. _handle-rtti-SimFunction: .. das:attribute:: SimFunction @@ -1551,6 +1645,7 @@ Object which represents function declaration. Property-like accessor that returns the ``LineInfo`` (source location) associated with the given function's ``FuncInfo``. + :Properties: * **lineInfo** : :ref:`LineInfo `? Object which represents simulated function in the `Context`. @@ -1568,6 +1663,7 @@ Object which represents simulated function in the `Context`. * **flags** : :ref:`SimFunctionFlags ` - flags associated with the function + .. _handle-rtti-DebugInfoHelper: .. das:attribute:: DebugInfoHelper @@ -1577,6 +1673,8 @@ Object which represents simulated function in the `Context`. :Fields: * **rtti** : bool - The RTTI context pointer. + + +++++++++++++++ Typeinfo macros +++++++++++++++ @@ -1588,6 +1686,8 @@ Typeinfo macros Typeinfo macro that provides compile-time access to RTTI type information structures. Typeinfo macro rtti_typeinfo + + +++++++++++++ Handled types +++++++++++++ @@ -1597,21 +1697,26 @@ Handled types .. das:attribute:: recursive_mutex Handled type wrapping a system ``std::recursive_mutex``, used with ``lock_mutex`` for thread-safe access to shared data across contexts. + .. _handle-rtti-AnnotationArguments: .. das:attribute:: AnnotationArguments Handled type representing a collection of annotation arguments, typically the raw argument list parsed from an annotation declaration. + .. _handle-rtti-AnnotationArgumentList: .. das:attribute:: AnnotationArgumentList Handled type representing an ordered list of annotation arguments and properties, providing indexed and named access to argument entries. + .. _handle-rtti-AnnotationList: .. das:attribute:: AnnotationList Handled type representing all annotations attached to a single object (function, structure, or variable), iterable via ``each``. + + +++++++++++++++++++++++++++++++ Initialization and finalization +++++++++++++++++++++++++++++++ @@ -1631,6 +1736,7 @@ Initialization and finalization Constructs a default-initialized ``CodeOfPolicies`` structure, which controls compiler behavior and optimization settings. + LineInfo ^^^^^^^^ @@ -1640,6 +1746,7 @@ LineInfo Constructs a default-initialized ``LineInfo`` structure representing source file location (file, line, column). + .. _function-rtti_LineInfo_FileInfo_q__implicit_int_int_int_int: .. das:function:: LineInfo(arg0: FileInfo? implicit; arg1: int; arg2: int; arg3: int; arg4: int) : LineInfo @@ -1653,6 +1760,7 @@ Constructs a default-initialized ``LineInfo`` structure representing source file Constructs an ``RttiValue`` variant set to the ``nothing`` alternative, representing an absent or void value. + using ^^^^^ @@ -1662,6 +1770,7 @@ using Creates a temporary RTTI helper object (e.g., ``Program``, ``DebugInfoHelper``) scoped to the given block, automatically finalized on block exit. + :Arguments: * **arg0** : block<( :ref:`CodeOfPolicies `):void> implicit .. _function-rtti_using_block_ls_ModuleGroup_c_void_gr_: @@ -1674,6 +1783,7 @@ Creates a temporary RTTI helper object (e.g., ``Program``, ``DebugInfoHelper``) ---- + +++++++++++ Type access +++++++++++ @@ -1704,6 +1814,7 @@ arg_names Iterates through the argument names of an RTTI type, yielding each name as a ``string`` — used for inspecting function or call-site parameter names. + :Arguments: * **info** : :ref:`TypeInfo ` .. _function-rtti_arg_names_VarInfo: @@ -1722,6 +1833,7 @@ arg_types Iterates through the argument types of an RTTI type, yielding each element as a ``TypeInfo`` pointer — used for inspecting function or call-site parameter types. + :Arguments: * **info** : :ref:`VarInfo ` .. _function-rtti_arg_types_TypeInfo: @@ -1736,6 +1848,7 @@ Iterates through the argument types of an RTTI type, yielding each element as a Returns ``true`` if two ``TypeInfo`` pointers describe the same type, with flags controlling whether ref, const, temp, and other qualifiers are included in the comparison. + :Arguments: * **a** : :ref:`TypeInfo `? implicit * **b** : :ref:`TypeInfo `? implicit @@ -1758,6 +1871,7 @@ each_dim Iterates through the dimension sizes of a fixed-size array ``TypeInfo``, yielding each ``int`` dimension value (e.g., ``int[3][4]`` yields 3 then 4). + :Arguments: * **info** : :ref:`TypeInfo ` .. _function-rtti_each_dim_VarInfo: @@ -1772,6 +1886,7 @@ Iterates through the dimension sizes of a fixed-size array ``TypeInfo``, yieldin Returns the canonical ``string`` name of the given ``Type`` enumeration value (e.g., ``tInt`` → ``"int"``). + :Arguments: * **type** : :ref:`Type ` @@ -1784,6 +1899,7 @@ get_dim Returns the dimension size (``int``) at the specified index for a fixed-size array type described by ``TypeInfo``. + :Arguments: * **typeinfo** : :ref:`VarInfo ` implicit * **index** : int @@ -1800,6 +1916,7 @@ Returns the dimension size (``int``) at the specified index for a fixed-size arr Returns the memory alignment (``int``, in bytes) of the type described by the given ``TypeInfo``. + :Arguments: * **type** : :ref:`TypeInfo `? implicit .. _function-rtti_get_type_size_TypeInfo_q__implicit: @@ -1808,6 +1925,7 @@ Returns the memory alignment (``int``, in bytes) of the type described by the gi Returns the size (``int``, in bytes) of the type described by the given ``TypeInfo``. + :Arguments: * **type** : :ref:`TypeInfo `? implicit @@ -1820,6 +1938,7 @@ is_compatible_cast Returns ``true`` if an object of type ``from`` (``StructInfo``) can be safely cast to type ``to`` (``StructInfo``), following the class hierarchy. + :Arguments: * **from** : :ref:`StructInfo `? implicit * **to** : :ref:`StructInfo `? implicit @@ -1836,6 +1955,7 @@ Returns ``true`` if an object of type ``from`` (``StructInfo``) can be safely ca Returns ``true`` if two ``TypeInfo`` objects describe the same type, with flags controlling comparison of qualifiers (ref, const, temp, etc.). + :Arguments: * **a** : :ref:`TypeInfo ` * **b** : :ref:`TypeInfo ` @@ -1848,6 +1968,7 @@ Returns ``true`` if two ``TypeInfo`` objects describe the same type, with flags * **topLevel** : bool + +++++++++++++++++++ Rtti context access +++++++++++++++++++ @@ -1875,6 +1996,7 @@ Rtti context access Returns a ``StructInfo`` pointer for the given class instance, enabling runtime introspection of its fields and annotations via RTTI. + :Arguments: * **cl** : auto .. _function-rtti_context_for_each_function_block_ls_info_c_FuncInfo_c_void_gr_: @@ -1883,6 +2005,7 @@ Returns a ``StructInfo`` pointer for the given class instance, enabling runtime Iterates through all functions in the given ``Context``, yielding a ``FuncInfo`` pointer for each registered function. + :Arguments: * **blk** : block<(info: :ref:`FuncInfo `):void> .. _function-rtti_context_for_each_variable_block_ls_info_c_VarInfo_c_void_gr_: @@ -1891,6 +2014,7 @@ Iterates through all functions in the given ``Context``, yielding a ``FuncInfo`` Iterates through all global variables in the given ``Context``, yielding a ``VarInfo`` pointer for each registered variable. + :Arguments: * **blk** : block<(info: :ref:`VarInfo `):void> .. _function-rtti_get_function_by_mnh_Context_implicit_uint64: @@ -1899,6 +2023,7 @@ Iterates through all global variables in the given ``Context``, yielding a ``Var Returns a ``SimFunction`` pointer looked up by mangled name hash — an alternative form of ``get_function_address``. + :Arguments: * **context** : :ref:`Context ` implicit * **MNH** : uint64 @@ -1913,6 +2038,7 @@ get_function_info Returns the ``FuncInfo`` pointer for a function at the given index in the ``Context``, providing access to its name, arguments, and return type. + :Arguments: * **context** : any * **index** : int @@ -1933,6 +2059,7 @@ get_line_info Returns a ``LineInfo`` structure representing the source location (file, line, column) of the call site where ``get_line_info`` is invoked. + .. _function-rtti_get_line_info_int: .. das:function:: get_line_info(depth: int) : LineInfo @@ -1945,6 +2072,7 @@ Returns a ``LineInfo`` structure representing the source location (file, line, c Returns the total number of registered functions (``int``) in the given ``Context``. + :Arguments: * **context** : :ref:`Context ` implicit .. _function-rtti_get_total_variables_Context_implicit: @@ -1953,6 +2081,7 @@ Returns the total number of registered functions (``int``) in the given ``Contex Returns the total number of global variables (``int``) in the given ``Context``. + :Arguments: * **context** : :ref:`Context ` implicit .. _function-rtti_get_variable_info_any_int: @@ -1961,6 +2090,7 @@ Returns the total number of global variables (``int``) in the given ``Context``. Returns the ``VarInfo`` pointer for a global variable at the given index in the ``Context``, providing access to its name, type, and offset. + :Arguments: * **context** : any * **index** : int @@ -1971,6 +2101,7 @@ Returns the ``VarInfo`` pointer for a global variable at the given index in the Returns an ``RttiValue`` variant representing the current value of a global variable, looked up by ``VarInfo`` in the given ``Context``. + :Arguments: * **varInfo** : :ref:`VarInfo ` implicit .. _function-rtti_this_context: @@ -1980,6 +2111,7 @@ Returns an ``RttiValue`` variant representing the current value of a global vari Returns a pointer to the current ``Context`` in which the calling code is executing. + type_info ^^^^^^^^^ @@ -1989,6 +2121,7 @@ type_info Returns the ``TypeInfo`` object for the specified local variable or expression, resolved at compile time via the ``[typeinfo(...)]`` macro. + :Arguments: * **cl** : auto .. _function-rtti_type_info_VarInfo: @@ -2001,6 +2134,7 @@ Returns the ``TypeInfo`` object for the specified local variable or expression, ---- + ++++++++++++++ Program access ++++++++++++++ @@ -2016,6 +2150,7 @@ Program access Returns a ``Module`` pointer looked up by module name ``string``, or null if no such module is registered. + :Arguments: * **name** : string implicit .. _function-rtti_get_this_module_smart_ptr_ls_Program_gr__implicit: @@ -2024,6 +2159,7 @@ Returns a ``Module`` pointer looked up by module name ``string``, or null if no Returns the ``Module`` pointer for the module currently being compiled or inferred, retrieved from the ``Program``. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit .. _function-rtti_program_for_each_module_smart_ptr_ls_Program_gr__implicit_block_ls_Module_q__c_void_gr_: @@ -2032,6 +2168,7 @@ Returns the ``Module`` pointer for the module currently being compiled or inferr Iterates through all modules referenced by the given ``Program`` (including transitive dependencies), yielding a ``Module`` pointer for each. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **block** : block<( :ref:`Module `?):void> implicit @@ -2042,8 +2179,10 @@ Iterates through all modules referenced by the given ``Program`` (including tran Iterates through all modules registered in the daslang runtime (globally, not per-program), yielding a ``Module`` pointer for each. + :Arguments: * **block** : block<( :ref:`Module `?):void> implicit + +++++++++++++ Module access +++++++++++++ @@ -2062,6 +2201,7 @@ Module access Iterates through each annotation (handled type) in the given ``Module``, yielding an ``Annotation`` pointer for each registered annotation. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<( :ref:`Annotation `):void> implicit @@ -2072,6 +2212,7 @@ Iterates through each annotation (handled type) in the given ``Module``, yieldin Iterates through each module dependency of the given ``Module``, yielding the dependent ``Module`` pointer for each required module. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<( :ref:`Module `?;bool):void> implicit @@ -2082,6 +2223,7 @@ Iterates through each module dependency of the given ``Module``, yielding the de Iterates through each enumeration declared in the given ``Module``, yielding an ``EnumInfo`` pointer for each enum. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<( :ref:`EnumInfo `):void> implicit @@ -2092,6 +2234,7 @@ Iterates through each enumeration declared in the given ``Module``, yielding an Iterates through each function declared in the given ``Module``, yielding a ``FuncInfo`` pointer for each function. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<( :ref:`FuncInfo `):void> implicit @@ -2102,6 +2245,7 @@ Iterates through each function declared in the given ``Module``, yielding a ``Fu Iterates through each generic (template) function declared in the given ``Module``, yielding a ``FuncInfo`` pointer for each generic. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<( :ref:`FuncInfo `):void> implicit @@ -2112,6 +2256,7 @@ Iterates through each generic (template) function declared in the given ``Module Iterates through each global variable declared in the given ``Module``, yielding a ``VarInfo`` pointer for each variable. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<( :ref:`VarInfo `):void> implicit @@ -2122,10 +2267,12 @@ Iterates through each global variable declared in the given ``Module``, yielding Iterates through each structure declaration in the given ``Module``, yielding a ``StructInfo`` pointer for each struct. + :Arguments: * **module** : :ref:`Module `? implicit * **block** : block<( :ref:`StructInfo `):void> implicit + +++++++++++++++++ Annotation access +++++++++++++++++ @@ -2139,6 +2286,7 @@ Annotation access Appends an annotation argument (name-value pair) to the given ``AnnotationArgumentList``, used when constructing annotations programmatically. + :Arguments: * **annotation** : :ref:`AnnotationArgumentList ` implicit * **name** : string implicit @@ -2149,8 +2297,10 @@ Appends an annotation argument (name-value pair) to the given ``AnnotationArgume Returns an ``RttiValue`` variant representing the value of a specific named argument from an ``AnnotationArgumentList``. + :Arguments: * **info** : :ref:`AnnotationArgument ` implicit + ++++++++++++++++++++++++++ Compilation and simulation ++++++++++++++++++++++++++ @@ -2160,7 +2310,7 @@ Compilation and simulation * :ref:`compile_file (module_name: string implicit; fileAccess: smart_ptr\ implicit; moduleGroup: ModuleGroup? implicit; codeOfPolicies: CodeOfPolicies implicit; block: block\<(bool;smart_ptr\;das_string):void\>) ` * :ref:`for_each_expected_error (program: smart_ptr\ implicit; block: block\<(CompilationError;int):void\>) ` * :ref:`for_each_require_declaration (program: smart_ptr\ implicit; block: block\<(Module?;string#;string#;bool;LineInfo):void\>) ` - * :ref:`simulate (program: smart_ptr\ const& implicit; block: block\<(bool;smart_ptr\;das_string):void\>) ` + * :ref:`simulate (program: smart_ptr\ const& implicit; block: block\<(bool;smart_ptr\;das_string):void\>) ` compile @@ -2172,6 +2322,7 @@ compile Compiles a daslang program from a source code string using the provided ``FileAccess`` and ``ModuleGroup``, returning a ``ProgramPtr`` (null on failure). + :Arguments: * **module_name** : string implicit * **codeText** : string implicit @@ -2194,6 +2345,7 @@ Compiles a daslang program from a source code string using the provided ``FileAc Compiles a daslang program from a file registered in the given ``FileAccess`` object, returning a ``ProgramPtr`` (null on failure). + :Arguments: * **module_name** : string implicit * **fileAccess** : smart_ptr< :ref:`FileAccess `> implicit @@ -2210,6 +2362,7 @@ Compiles a daslang program from a file registered in the given ``FileAccess`` ob Iterates through each expected compilation error declared in the ``Program`` (via ``expect``), yielding the error code for each. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit * **block** : block<( :ref:`CompilationError `;int):void> implicit @@ -2220,20 +2373,23 @@ Iterates through each expected compilation error declared in the ``Program`` (vi Iterates through each ``require`` declaration of the compiled ``Program``, yielding the module name, public/private flag, and source ``LineInfo``. + :Arguments: * **program** : smart_ptr< :ref:`Program `> implicit - * **block** : block<( :ref:`Module `?;string#;string#;bool; :ref:`LineInfo `&):void> implicit + * **block** : block<( :ref:`Module `?;string\ #;string\ #;bool; :ref:`LineInfo `\ &):void> implicit -.. _function-rtti_simulate_smart_ptr_ls_Program_gr__const_implicit_block_ls_bool;smart_ptr_ls_Context_gr_;das_string_c_void_gr_: +.. _function-rtti_simulate_smart_ptr_ls_Program_gr__const_ref__implicit_block_ls_bool;smart_ptr_ls_Context_gr_;das_string_c_void_gr_: .. das:function:: simulate(program: smart_ptr const& implicit; block: block<(bool;smart_ptr;das_string):void>) Simulates (links and initializes) a compiled ``Program``, returning a ``Context`` pointer ready for function execution, or null on failure. -:Arguments: * **program** : smart_ptr< :ref:`Program `>& implicit + +:Arguments: * **program** : smart_ptr< :ref:`Program `>\ & implicit * **block** : block<(bool;smart_ptr< :ref:`Context `>; :ref:`das_string `):void> implicit + +++++++++++ File access +++++++++++ @@ -2248,6 +2404,7 @@ File access Adds an extra root directory (search path) to the given ``FileAccess`` object, expanding where ``require`` resolves files from. + :Arguments: * **access** : smart_ptr< :ref:`FileAccess `> implicit * **mod** : string implicit @@ -2260,6 +2417,7 @@ Adds an extra root directory (search path) to the given ``FileAccess`` object, e Creates and returns a new ``FileAccessPtr`` (``smart_ptr``) initialized as a default file-system-backed project. + :Arguments: * **project** : string implicit .. _function-rtti_set_file_source_smart_ptr_ls_FileAccess_gr__implicit_string_implicit_string_implicit: @@ -2268,12 +2426,14 @@ Creates and returns a new ``FileAccessPtr`` (``smart_ptr``) initiali Registers a source code ``string`` for the given file name inside the ``FileAccess`` object, allowing in-memory compilation without disk files. + :Arguments: * **access** : smart_ptr< :ref:`FileAccess `> implicit * **fileName** : string implicit * **text** : string implicit + ++++++++++++++++ Structure access ++++++++++++++++ @@ -2289,6 +2449,7 @@ Structure access Iterates through each field of a ``BasicStructureAnnotation``, yielding the field name, C++ name, ``TypeInfo``, and byte offset for each field. + :Arguments: * **annotation** : :ref:`BasicStructureAnnotation ` implicit * **block** : block<(string;string; :ref:`TypeInfo `;uint):void> implicit @@ -2299,6 +2460,7 @@ Iterates through each field of a ``BasicStructureAnnotation``, yielding the fiel Iterates through each parent (base class) of a ``BasicStructureAnnotation``, yielding the parent ``TypeInfo`` for each ancestor. + :Arguments: * **annotation** : :ref:`BasicStructureAnnotation ` implicit * **block** : block<( :ref:`Annotation `?):void> implicit @@ -2309,6 +2471,7 @@ Iterates through each parent (base class) of a ``BasicStructureAnnotation``, yie Iterates through each annotation attached to a ``StructInfo``, yielding the annotation name and its ``AnnotationArgumentList`` for each. + :Arguments: * **struct** : :ref:`StructInfo ` implicit * **block** : block implicit @@ -2319,10 +2482,12 @@ Iterates through each annotation attached to a ``StructInfo``, yielding the anno Iterates through each annotation attached to a ``StructInfo``, yielding the annotation name and ``AnnotationArgumentList`` — an alias of ``rtti_builtin_structure_for_each_annotation``. + :Arguments: * **st** : :ref:`StructInfo ` * **subexpr** : block<(ann: :ref:`Annotation `;args: :ref:`AnnotationArguments `):void> + +++++++++++++++++++++++++ Data walking and printing +++++++++++++++++++++++++ @@ -2343,6 +2508,7 @@ describe Returns a human-readable ``string`` description of an RTTI object (``TypeInfo``, ``VarInfo``, ``FuncInfo``, etc.), useful for logging and debug output. + :Arguments: * **lineinfo** : :ref:`LineInfo ` implicit * **fully** : bool @@ -2359,6 +2525,7 @@ Returns a human-readable ``string`` description of an RTTI object (``TypeInfo``, Returns the full mangled name ``string`` for the given ``FuncInfo``, encoding its module, name, and argument types. + :Arguments: * **type** : :ref:`TypeInfo `? implicit @@ -2371,6 +2538,7 @@ sprint_data Returns a ``string`` representation of a value given its data pointer and ``TypeInfo``, similar to ``debug`` or ``print`` but capturing output as a string. + :Arguments: * **data** : float4 * **type** : :ref:`TypeInfo `? implicit @@ -2383,6 +2551,7 @@ Returns a ``string`` representation of a value given its data pointer and ``Type ---- + ++++++++++++++++++++++++++++++ Function and mangled name hash ++++++++++++++++++++++++++++++ @@ -2398,6 +2567,7 @@ Function and mangled name hash Returns a ``SimFunction`` pointer looked up by mangled name hash in the given ``Context``, or null if not found. + :Arguments: * **MNH** : uint64 * **at** : :ref:`Context ` implicit @@ -2412,6 +2582,7 @@ get_function_by_mangled_name_hash Returns a ``function<>`` lambda value looked up by its mangled name hash in the given ``Context``. + :Arguments: * **src** : uint64 * **context** : :ref:`Context ` implicit @@ -2428,8 +2599,10 @@ Returns a ``function<>`` lambda value looked up by its mangled name hash in the Returns the ``uint64`` mangled name hash for the given ``function<>`` value, which uniquely identifies the function in its ``Context``. + :Arguments: * **src** : function + +++++++++++++++++++++++++ Context and mutex locking +++++++++++++++++++++++++ @@ -2444,6 +2617,7 @@ Context and mutex locking Acquires a recursive lock on the given ``Context`` and executes a block, ensuring thread-safe access to context data within the scope. + :Arguments: * **lock_context** : :ref:`Context ` implicit * **block** : block implicit @@ -2454,6 +2628,7 @@ Acquires a recursive lock on the given ``Context`` and executes a block, ensurin Acquires a recursive lock on the given ``recursive_mutex`` and executes a block, releasing the lock when the block exits. + :Arguments: * **mutex** : :ref:`recursive_mutex ` implicit * **block** : block implicit @@ -2464,8 +2639,10 @@ Acquires a recursive lock on the given ``recursive_mutex`` and executes a block, Acquires a recursive lock on the current ``Context`` and executes a block, ensuring thread-safe access within the scope. + :Arguments: * **block** : block implicit + +++++++++++++++++++ Runtime data access +++++++++++++++++++ @@ -2478,6 +2655,7 @@ Runtime data access Returns the internal slot index (``int``) for the given key within a ``table`` value, or ``-1`` if the key is not present. + :Arguments: * **table** : void? implicit * **key** : any @@ -2486,6 +2664,7 @@ Returns the internal slot index (``int``) for the given key within a ``table`` v * **valueTypeSize** : int + ++++++++++++++++++++++++ Tuple and variant access ++++++++++++++++++++++++ @@ -2499,6 +2678,7 @@ Tuple and variant access Returns the byte offset (``int``) of a field at the given index within a tuple type described by ``TypeInfo``. + :Arguments: * **type** : :ref:`TypeInfo `? implicit * **index** : int @@ -2509,10 +2689,12 @@ Returns the byte offset (``int``) of a field at the given index within a tuple t Returns the byte offset (``int``) of a field at the given index within a variant type described by ``TypeInfo``. + :Arguments: * **type** : :ref:`TypeInfo `? implicit * **index** : int + +++++++++ Iteration +++++++++ @@ -2534,6 +2716,7 @@ each Iterates through each element of an RTTI container (e.g., ``AnnotationArguments``, ``AnnotationArgumentList``, ``AnnotationList``), yielding individual entries. + :Arguments: * **info** : :ref:`FuncInfo ` implicit! .. _function-rtti_each_FuncInfo_implicit__eq__eq_const: diff --git a/doc/source/stdlib/safe_addr.rst b/doc/source/stdlib/safe_addr.rst index ce845d06cf..965c90e0cf 100644 --- a/doc/source/stdlib/safe_addr.rst +++ b/doc/source/stdlib/safe_addr.rst @@ -5,6 +5,8 @@ safe_addr macro =============== +.. das:module:: safe_addr + The SAFE_ADDR module provides compile-time checked pointer operations. ``safe_addr`` returns a temporary pointer to a variable only if the compiler can verify the pointer will not outlive its target. This prevents dangling @@ -14,6 +16,8 @@ All functions and symbols are in "safe_addr" module, use require to get access t require daslib/safe_addr + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -25,6 +29,7 @@ Function annotations This macro reports an error if safe_addr is attempted on the object, which is not local to the scope. I.e. if the object can `expire` while in scope, with delete, garbage collection, or on the C++ side. + .. _handle-safe_addr-SharedAddrMacro: .. das:attribute:: SharedAddrMacro @@ -32,18 +37,21 @@ I.e. if the object can `expire` while in scope, with delete, garbage collection, This macro reports an error if shared_addr is attempted on anything other that shared global variables. I.e. only global variables are safe to use with shared_addr. + .. _handle-safe_addr-TempValueMacro: .. das:attribute:: TempValueMacro This macro reports an error if temp_value is attempted outside of function arguments. + + ++++++++++++++++++++++ Safe temporary address ++++++++++++++++++++++ - * :ref:`safe_addr (x: auto(T) const& ==const) : T?# ` - * :ref:`safe_addr (var x: auto(T)& ==const) : T?# ` + * :ref:`safe_addr (x: auto(T) const& ==const) : T?# ` + * :ref:`safe_addr (var x: auto(T)& ==const) : T?# ` * :ref:`shared_addr (val: auto(VALUE)) : auto ` * :ref:`shared_addr (tab: table\; k: KEY) : auto ` @@ -51,15 +59,16 @@ Safe temporary address safe_addr ^^^^^^^^^ -.. _function-safe_addr_safe_addr_autoT_const__eq__eq_const_0x1e: +.. _function-safe_addr_safe_addr_autoT_const_ref___eq__eq_const_0x1e: .. das:function:: safe_addr(x: auto(T) const& ==const) : T?# returns temporary pointer to the given expression -:Arguments: * **x** : auto(T)&! -.. _function-safe_addr_safe_addr__autoT__eq__eq_const_0x16: +:Arguments: * **x** : auto(T)\ &! + +.. _function-safe_addr_safe_addr__autoT_ref___eq__eq_const_0x16: .. das:function:: safe_addr(x: auto(T)& ==const) : T?# @@ -75,7 +84,8 @@ shared_addr returns address of the given shared variable. it's safe because shared variables never go out of scope -:Arguments: * **val** : auto(VALUE)& + +:Arguments: * **val** : auto(VALUE)\ & .. _function-safe_addr_shared_addr_table_ls_autoKEY,_autoVAL_gr__KEY: @@ -83,6 +93,7 @@ returns address of the given shared variable. it's safe because shared variables ---- + ++++++++++++++++++ Temporary pointers ++++++++++++++++++ @@ -100,6 +111,7 @@ temp_ptr returns temporary pointer from a given pointer + :Arguments: * **x** : auto(T)? implicit! .. _function-safe_addr_temp_ptr_autoT_q__const_implicit__eq__eq_const: @@ -108,26 +120,28 @@ returns temporary pointer from a given pointer ---- + ++++++++++++++++ Temporary values ++++++++++++++++ - * :ref:`temp_value (var x: auto(T)& ==const) : T&# ` - * :ref:`temp_value (x: auto(T) const& ==const) : T const&# ` + * :ref:`temp_value (var x: auto(T)& ==const) : T&# ` + * :ref:`temp_value (x: auto(T) const& ==const) : T const&# ` temp_value ^^^^^^^^^^ -.. _function-safe_addr_temp_value__autoT__eq__eq_const_0x63: +.. _function-safe_addr_temp_value__autoT_ref___eq__eq_const_0x63: .. das:function:: temp_value(x: auto(T)& ==const) : T&# returns temporary reference to the given expression -:Arguments: * **x** : auto(T)&! -.. _function-safe_addr_temp_value_autoT_const__eq__eq_const_0x5b: +:Arguments: * **x** : auto(T)\ &! + +.. _function-safe_addr_temp_value_autoT_const_ref___eq__eq_const_0x5b: .. das:function:: temp_value(x: auto(T) const& ==const) : T const&# diff --git a/doc/source/stdlib/soa.rst b/doc/source/stdlib/soa.rst index cdadcb0c96..94e36c4a13 100644 --- a/doc/source/stdlib/soa.rst +++ b/doc/source/stdlib/soa.rst @@ -5,6 +5,8 @@ SOA (Structure of Arrays) transformation ======================================== +.. das:module:: soa + The SOA (Structure of Arrays) module transforms array-of-structures data layouts into structure-of-arrays layouts for better cache performance. It provides macros that generate parallel arrays for each field of a structure, enabling SIMD-friendly @@ -14,6 +16,8 @@ All functions and symbols are in "soa" module, use require to get access to it. require daslib/soa + + ++++++++++ Structures ++++++++++ @@ -26,6 +30,8 @@ Proxy type returned by the ``[]`` operator on an SOA structure. Field access on this proxy is rewritten by `SoaCallMacro` to index into the correct column array. + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -38,6 +44,8 @@ Rewrites ``soa[index].field`` into ``soa.field[index]`` at compile time. This is the core of the SOA access pattern — it transforms AOS-style element access into column-wise array indexing for better cache locality. + + ++++++++++++++++ Structure macros ++++++++++++++++ @@ -52,6 +60,8 @@ For a struct ``Foo`` with fields ``x : float`` and ``y : float``, generates: * ``operator []`` returning ``SOA_INDEX`` proxy * ``length``, ``push``, ``emplace``, ``push_clone``, ``erase`` functions + + ++++++++++++++++ SOA field access ++++++++++++++++ @@ -64,6 +74,7 @@ SOA field access Field access operator for SOA_INDEX; rewritten by SoaCallMacro to convert soa[index].field into soa.field[index]. + :Arguments: * **src** : :ref:`SOA_INDEX ` * **field** : string diff --git a/doc/source/stdlib/sort_boost.rst b/doc/source/stdlib/sort_boost.rst index 45272df15f..eb861b1555 100644 --- a/doc/source/stdlib/sort_boost.rst +++ b/doc/source/stdlib/sort_boost.rst @@ -5,6 +5,8 @@ Boost package for the builtin sort ================================== +.. das:module:: sort_boost + The SORT_BOOST module provides the ``qsort`` macro that uniformly sorts built-in arrays, dynamic arrays, and C++ handled vectors using the same syntax. It automatically wraps handled types in ``temp_array`` as needed. @@ -13,6 +15,8 @@ All functions and symbols are in "sort_boost" module, use require to get access require daslib/sort_boost + + +++++++++++ Call macros +++++++++++ @@ -26,3 +30,4 @@ For the regular array<> or dim it's replaced with `sort(value,block)`. For the handled types like das`vector its replaced with `sort(temp_array(value),block)`. + diff --git a/doc/source/stdlib/static_let.rst b/doc/source/stdlib/static_let.rst index 2d2c0d6325..0d3fc9829f 100644 --- a/doc/source/stdlib/static_let.rst +++ b/doc/source/stdlib/static_let.rst @@ -5,6 +5,8 @@ static_let macro ================ +.. das:module:: static_let + The STATIC_LET module implements the ``static_let`` pattern — local variables that persist across function calls, similar to C ``static`` variables. The variable is initialized once on first call and retains its value in subsequent @@ -37,6 +39,8 @@ Example: :: // 2 // 3 + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -47,6 +51,8 @@ Function annotations This macro implements the `static_let` and `static_let_finalize` functions. + + ++++++++++++++++++++++++++++ Static variable declarations ++++++++++++++++++++++++++++ @@ -66,6 +72,7 @@ static_let Given a scope with the variable declarations, this function will make those variables global. Variable will be renamed under the hood, and all local access to it will be renamed as well. + :Arguments: * **name** : string * **blk** : block @@ -82,6 +89,7 @@ Variable will be renamed under the hood, and all local access to it will be rena This is very similar to regular static_let, but additionally the variable will be deleted on the context shutdown. + :Arguments: * **blk** : block diff --git a/doc/source/stdlib/stringify.rst b/doc/source/stdlib/stringify.rst index e146da2113..9255152755 100644 --- a/doc/source/stdlib/stringify.rst +++ b/doc/source/stdlib/stringify.rst @@ -5,6 +5,8 @@ Long string embedding macro =========================== +.. das:module:: stringify + The STRINGIFY module provides the ``%stringify~`` reader macro for embedding multi-line string literals verbatim. Text between ``%stringify~`` and ``%%`` is captured as-is without requiring escape sequences for quotes, braces, @@ -14,6 +16,8 @@ All functions and symbols are in "stringify" module, use require to get access t require daslib/stringify + + +++++++++++++ Reader macros +++++++++++++ @@ -22,11 +26,13 @@ Reader macros .. das:attribute:: stringify -This macro implements embedding of the long string into the source code. - var st = %stringify~ - This is a long string - with multiple lines - and special charactes like { this } and "that" - %% +This macro implements embedding of the long string into the source code. :: + + var st = %stringify~ + This is a long string + with multiple lines + and special charactes like { this } and "that" + %% + diff --git a/doc/source/stdlib/strings.rst b/doc/source/stdlib/strings.rst index a7ae4d9d16..b2619f658f 100644 --- a/doc/source/stdlib/strings.rst +++ b/doc/source/stdlib/strings.rst @@ -5,6 +5,8 @@ String manipulation library =========================== +.. das:module:: strings + The STRINGS module implements string formatting, conversion, searching, and modification routines. It provides functions for building strings (``build_string``), parsing (``to_int``, ``to_float``), character classification (``is_alpha``, ``is_number``), @@ -14,6 +16,8 @@ All functions and symbols are in "strings" module, use require to get access to require strings + + ++++++++++++ Enumerations ++++++++++++ @@ -31,6 +35,8 @@ Result of conversion from string to number. * **out_of_range** = 34 - Argument is out of range for the target type + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -42,42 +48,48 @@ Handled structures Object representing a string builder. Its significantly faster to write data to the string builder and than convert it to a string, as oppose to using sequences of string concatenations. + + +++++++++++++ Character set +++++++++++++ - * :ref:`is_char_in_set (Character: int; Charset: uint const[8] implicit) : bool ` - * :ref:`set_element (Character: int; Charset: uint const[8] implicit) : int ` - * :ref:`set_total (Charset: uint const[8] implicit) : uint ` + * :ref:`is_char_in_set (Character: int; Charset: uint const[8] implicit) : bool ` + * :ref:`set_element (Character: int; Charset: uint const[8] implicit) : int ` + * :ref:`set_total (Charset: uint const[8] implicit) : uint ` -.. _function-strings_is_char_in_set_int_uint_const8_implicit: +.. _function-strings_is_char_in_set_int_uint_const_lb_8_rb__implicit: .. das:function:: is_char_in_set(Character: int; Charset: uint const[8] implicit) : bool Returns true if the character given by its integer code is present in the 256-bit character set represented as a uint[8] array. + :Arguments: * **Character** : int * **Charset** : uint[8] implicit -.. _function-strings_set_element_int_uint_const8_implicit: +.. _function-strings_set_element_int_uint_const_lb_8_rb__implicit: .. das:function:: set_element(Character: int; Charset: uint const[8] implicit) : int Returns the character code at the given element index within the 256-bit character set represented as a uint[8] array. + :Arguments: * **Character** : int * **Charset** : uint[8] implicit -.. _function-strings_set_total_uint_const8_implicit: +.. _function-strings_set_total_uint_const_lb_8_rb__implicit: .. das:function:: set_total(Charset: uint const[8] implicit) : uint Returns the total number of characters present (bits set) in the 256-bit character set represented as a uint[8] array. + :Arguments: * **Charset** : uint[8] implicit + ++++++++++++++++ Character groups ++++++++++++++++ @@ -96,6 +108,7 @@ Character groups Returns true if the integer character code represents an alphanumeric ASCII character [A-Za-z0-9]. + :Arguments: * **Character** : int .. _function-strings_is_alpha_int: @@ -104,6 +117,7 @@ Returns true if the integer character code represents an alphanumeric ASCII char Returns true if the integer character code represents an alphabetic ASCII character [A-Za-z]. + :Arguments: * **Character** : int .. _function-strings_is_hex_int: @@ -112,6 +126,7 @@ Returns true if the integer character code represents an alphabetic ASCII charac Returns true if the integer character code represents a hexadecimal digit [0-9A-Fa-f]. + :Arguments: * **Character** : int .. _function-strings_is_new_line_int: @@ -120,6 +135,7 @@ Returns true if the integer character code represents a hexadecimal digit [0-9A- Returns true if the integer character code is a newline character (\\n or \\r). + :Arguments: * **Character** : int .. _function-strings_is_number_int: @@ -128,6 +144,7 @@ Returns true if the integer character code is a newline character (\\n or \\r). Returns true if the integer character code represents a decimal digit [0-9]. + :Arguments: * **Character** : int .. _function-strings_is_tab_or_space_int: @@ -136,6 +153,7 @@ Returns true if the integer character code represents a decimal digit [0-9]. Returns true if the integer character code is a tab or space character. + :Arguments: * **Character** : int .. _function-strings_is_white_space_int: @@ -144,8 +162,10 @@ Returns true if the integer character code is a tab or space character. Returns true if the integer character code is a whitespace character (space, tab, newline, carriage return, etc.). + :Arguments: * **Character** : int + ++++++++++++++++++ Character by index ++++++++++++++++++ @@ -159,6 +179,7 @@ Character by index Returns the integer character code of string `str` at the given index `idx`, with bounds checking. + :Arguments: * **str** : string implicit * **idx** : int @@ -172,10 +193,12 @@ Returns the integer character code of string `str` at the given index `idx`, wit Returns the integer character code of string `str` at the given index `idx` without performing bounds checking (unsafe). + :Arguments: * **str** : string implicit * **idx** : int + +++++++++++++++++ String properties +++++++++++++++++ @@ -199,6 +222,7 @@ ends_with Returns true if the string `str` ends with the substring `cmp`, false otherwise. + :Arguments: * **str** : :ref:`das_string ` implicit * **cmp** : string implicit @@ -219,6 +243,7 @@ length Returns the length of the string or das_string in characters as an int. + :Arguments: * **str** : string implicit .. _function-strings_length_das_string_implicit: @@ -237,6 +262,7 @@ starts_with Returns true if the beginning of string `str` matches the string `cmp`, with optional `offset` and `cmpLen` parameters to control the comparison start position and length. + :Arguments: * **str** : string implicit * **cmp** : string implicit @@ -257,6 +283,7 @@ Returns true if the beginning of string `str` matches the string `cmp`, with opt ---- + ++++++++++++++ String builder ++++++++++++++ @@ -286,6 +313,7 @@ String builder Computes a uint64 hash by streaming writes through a StringBuilderWriter passed to `block`, without allocating the full concatenated string. + :Arguments: * **block** : block<( :ref:`StringBuilderWriter `):void> implicit .. _function-strings_build_string_block_ls_StringBuilderWriter_c_void_gr_: @@ -294,6 +322,7 @@ Computes a uint64 hash by streaming writes through a StringBuilderWriter passed Creates a StringBuilderWriter, passes it to `block` for writing, and returns the accumulated output as a string. + :Arguments: * **block** : block<( :ref:`StringBuilderWriter `):void> implicit @@ -309,6 +338,7 @@ format Formats a numeric value of type T using a C printf-style format string, either appending to a StringBuilderWriter and returning a reference to it, or returning the formatted result as a new string. + :Arguments: * **format** : string implicit * **value** : int64 @@ -365,6 +395,7 @@ Formats a numeric value of type T using a C printf-style format string, either a Writes the textual representation of any value into the StringBuilderWriter and returns a reference to the writer for chaining. + :Arguments: * **writer** : :ref:`StringBuilderWriter ` * **anything** : any @@ -375,6 +406,7 @@ Writes the textual representation of any value into the StringBuilderWriter and Writes a single character specified by its integer code `ch` into the StringBuilderWriter and returns a reference to the writer. + :Arguments: * **writer** : :ref:`StringBuilderWriter ` implicit * **ch** : int @@ -385,6 +417,7 @@ Writes a single character specified by its integer code `ch` into the StringBuil Writes the character specified by integer code `ch` repeated `count` times into the StringBuilderWriter and returns a reference to the writer. + :Arguments: * **writer** : :ref:`StringBuilderWriter ` implicit * **ch** : int @@ -397,10 +430,12 @@ Writes the character specified by integer code `ch` repeated `count` times into Writes the escaped form of string `str` (with special characters converted to escape sequences) into the StringBuilderWriter and returns a reference to the writer. + :Arguments: * **writer** : :ref:`StringBuilderWriter ` implicit * **str** : string implicit + ++++++++++++++++++++++++ das::string manipulation ++++++++++++++++++++++++ @@ -414,6 +449,7 @@ das::string manipulation Appends a single character specified by its integer code `ch` to the mutable das_string `str`. + :Arguments: * **str** : :ref:`das_string ` implicit * **ch** : int @@ -424,10 +460,12 @@ Appends a single character specified by its integer code `ch` to the mutable das Resizes the mutable das_string `str` in place to `new_length` characters. + :Arguments: * **str** : :ref:`das_string ` implicit * **new_length** : int + ++++++++++++++++++++ String modifications ++++++++++++++++++++ @@ -459,6 +497,7 @@ String modifications Returns a substring of `str` beginning at index `start` with the specified `length`. + :Arguments: * **str** : string implicit * **start** : int @@ -471,6 +510,7 @@ Returns a substring of `str` beginning at index `start` with the specified `leng Returns a new string with special characters replaced by their printable escape sequences (e.g. newline becomes \\n). + :Arguments: * **str** : string implicit .. _function-strings_ltrim_string_implicit: @@ -479,6 +519,7 @@ Returns a new string with special characters replaced by their printable escape Returns a new string with leading whitespace characters removed from `str`. + :Arguments: * **str** : string implicit .. _function-strings_repeat_string_implicit_int: @@ -487,6 +528,7 @@ Returns a new string with leading whitespace characters removed from `str`. Returns a new string formed by concatenating `str` repeated `count` times. + :Arguments: * **str** : string implicit * **count** : int @@ -497,6 +539,7 @@ Returns a new string formed by concatenating `str` repeated `count` times. Returns a new string with all occurrences of substring `toSearch` in `str` replaced by the substring `replace`. + :Arguments: * **str** : string implicit * **toSearch** : string implicit @@ -509,6 +552,7 @@ Returns a new string with all occurrences of substring `toSearch` in `str` repla Returns a new string with the characters of `str` in reverse order. + :Arguments: * **str** : string implicit @@ -521,6 +565,7 @@ rtrim Returns a new string with trailing whitespace removed from `str`, or with trailing characters from the specified `chars` set removed. + :Arguments: * **str** : string implicit * **chars** : string implicit @@ -537,6 +582,7 @@ Returns a new string with trailing whitespace removed from `str`, or with traili Unescapes a string by converting printable escape sequences back to their original characters (e.g. \\n becomes a newline), skipping invalid sequences instead of failing. + :Arguments: * **str** : string implicit @@ -549,6 +595,7 @@ slice Returns a substring of `str` from index `start` to optional `end` (exclusive), where negative indices count from the end of the string. + :Arguments: * **str** : string implicit * **start** : int @@ -565,6 +612,7 @@ Returns a substring of `str` from index `start` to optional `end` (exclusive), w Returns a new string with all leading and trailing whitespace characters removed from `str`. + :Arguments: * **str** : string implicit .. _function-strings_strip_left_string_implicit: @@ -573,6 +621,7 @@ Returns a new string with all leading and trailing whitespace characters removed Returns a new string with all leading whitespace characters removed from `str`. + :Arguments: * **str** : string implicit .. _function-strings_strip_right_string_implicit: @@ -581,6 +630,7 @@ Returns a new string with all leading whitespace characters removed from `str`. Returns a new string with all trailing whitespace characters removed from `str`. + :Arguments: * **str** : string implicit .. _function-strings_to_lower_string_implicit: @@ -589,6 +639,7 @@ Returns a new string with all trailing whitespace characters removed from `str`. Returns a new string with all characters of `str` converted to lower case. + :Arguments: * **str** : string implicit .. _function-strings_to_lower_in_place_string_implicit: @@ -600,6 +651,7 @@ Returns a new string with all characters of `str` converted to lower case. Converts all characters of `str` to lower case in place and returns the modified string. + :Arguments: * **str** : string implicit .. _function-strings_to_upper_string_implicit: @@ -608,6 +660,7 @@ Converts all characters of `str` to lower case in place and returns the modified Returns a new string with all characters of `str` converted to upper case. + :Arguments: * **str** : string implicit .. _function-strings_to_upper_in_place_string_implicit: @@ -619,6 +672,7 @@ Returns a new string with all characters of `str` converted to upper case. Converts all characters of `str` to upper case in place and returns the modified string. + :Arguments: * **str** : string implicit .. _function-strings_trim_string_implicit: @@ -627,6 +681,7 @@ Converts all characters of `str` to upper case in place and returns the modified Returns a new string with both leading and trailing whitespace characters removed from `str`. + :Arguments: * **str** : string implicit .. _function-strings_unescape_string_implicit: @@ -635,8 +690,10 @@ Returns a new string with both leading and trailing whitespace characters remove Returns a new string with printable escape sequences converted back to their original characters (e.g. \\n becomes a newline). + :Arguments: * **str** : string implicit + +++++++++++++++++ Search substrings +++++++++++++++++ @@ -656,6 +713,7 @@ find Returns the first index at which `substr` (string or character code) occurs in `str`, optionally searching from `start`, or -1 if not found. + :Arguments: * **str** : string implicit * **substr** : string implicit @@ -674,6 +732,7 @@ Returns the first index at which `substr` (string or character code) occurs in ` ---- + +++++++++++++++++ String comparison +++++++++++++++++ @@ -687,18 +746,20 @@ String comparison // stub def compare_ignore_case (a: string implicit; b: string implicit) : int + :Arguments: * **a** : string implicit * **b** : string implicit + ++++++++++++++++++++++++++ String conversion routines ++++++++++++++++++++++++++ - * :ref:`double (str: string implicit; result: ConversionResult& implicit; offset: int& implicit) : double ` + * :ref:`double (str: string implicit; result: ConversionResult& implicit; offset: int& implicit) : double ` * :ref:`double (str: string implicit) : double ` * :ref:`float (str: string implicit) : float ` - * :ref:`float (str: string implicit; result: ConversionResult& implicit; offset: int& implicit) : float ` + * :ref:`float (str: string implicit; result: ConversionResult& implicit; offset: int& implicit) : float ` * :ref:`fmt (writer: StringBuilderWriter implicit; format: string implicit; value: int64) : StringBuilderWriter& ` * :ref:`fmt (writer: StringBuilderWriter implicit; format: string implicit; value: uint) : StringBuilderWriter& ` * :ref:`fmt (writer: StringBuilderWriter implicit; format: string implicit; value: uint64) : StringBuilderWriter& ` @@ -710,13 +771,13 @@ String conversion routines * :ref:`fmt (writer: StringBuilderWriter implicit; format: string implicit; value: double) : StringBuilderWriter& ` * :ref:`fmt (writer: StringBuilderWriter implicit; format: string implicit; value: float) : StringBuilderWriter& ` * :ref:`int (str: string implicit) : int ` - * :ref:`int (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int ` - * :ref:`int16 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int16 ` + * :ref:`int (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int ` + * :ref:`int16 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int16 ` * :ref:`int16 (str: string implicit) : int16 ` * :ref:`int64 (str: string implicit) : int64 ` - * :ref:`int64 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int64 ` + * :ref:`int64 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int64 ` * :ref:`int8 (str: string implicit) : int8 ` - * :ref:`int8 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int8 ` + * :ref:`int8 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int8 ` * :ref:`string (bytes: array\) : string ` * :ref:`to_char (char: int) : string ` * :ref:`to_cpp_float (value: float) : string ` @@ -731,29 +792,30 @@ String conversion routines * :ref:`to_uint64 (value: string implicit; hex: bool = false) : uint64 ` * :ref:`to_uint8 (value: string implicit; hex: bool = false) : uint8 ` * :ref:`uint (str: string implicit) : uint ` - * :ref:`uint (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint ` + * :ref:`uint (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint ` * :ref:`uint16 (str: string implicit) : uint16 ` - * :ref:`uint16 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint16 ` + * :ref:`uint16 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint16 ` * :ref:`uint64 (str: string implicit) : uint64 ` - * :ref:`uint64 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint64 ` - * :ref:`uint8 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint8 ` + * :ref:`uint64 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint64 ` + * :ref:`uint8 (str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint8 ` * :ref:`uint8 (str: string implicit) : uint8 ` double ^^^^^^ -.. _function-strings_double_string_implicit_ConversionResult_implicit_int_implicit: +.. _function-strings_double_string_implicit_ConversionResult_ref__implicit_int_ref__implicit: .. das:function:: double(str: string implicit; result: ConversionResult& implicit; offset: int& implicit) : double Converts a string to a double value, panicking on failure; an overload accepts `result` and `offset` output parameters to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit - * **result** : :ref:`ConversionResult `& implicit + * **result** : :ref:`ConversionResult `\ & implicit - * **offset** : int& implicit + * **offset** : int\ & implicit .. _function-strings_double_string_implicit: @@ -771,9 +833,10 @@ float Converts a string to a float value, panicking on failure; an overload accepts `result` and `offset` output parameters to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit -.. _function-strings_float_string_implicit_ConversionResult_implicit_int_implicit: +.. _function-strings_float_string_implicit_ConversionResult_ref__implicit_int_ref__implicit: .. das:function:: float(str: string implicit; result: ConversionResult& implicit; offset: int& implicit) : float @@ -789,6 +852,7 @@ fmt Formats a numeric value of type T into the StringBuilderWriter using a libfmt/C++20 std::format format string and returns a reference to the writer. + :Arguments: * **writer** : :ref:`StringBuilderWriter ` implicit * **format** : string implicit @@ -843,9 +907,10 @@ int Converts a string to an int, panicking on failure; an overload accepts `result`, `offset`, and optional `hex` flag to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit -.. _function-strings_int_string_implicit_ConversionResult_implicit_int_implicit_bool: +.. _function-strings_int_string_implicit_ConversionResult_ref__implicit_int_ref__implicit_bool: .. das:function:: int(str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int @@ -855,17 +920,18 @@ Converts a string to an int, panicking on failure; an overload accepts `result`, int16 ^^^^^ -.. _function-strings_int16_string_implicit_ConversionResult_implicit_int_implicit_bool: +.. _function-strings_int16_string_implicit_ConversionResult_ref__implicit_int_ref__implicit_bool: .. das:function:: int16(str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int16 Converts a string to an int16, panicking on failure; an overload accepts `result`, `offset`, and optional `hex` flag to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit - * **result** : :ref:`ConversionResult `& implicit + * **result** : :ref:`ConversionResult `\ & implicit - * **offset** : int& implicit + * **offset** : int\ & implicit * **hex** : bool @@ -885,9 +951,10 @@ int64 Converts a string to an int64, panicking on failure; an overload accepts `result`, `offset`, and optional `hex` flag to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit -.. _function-strings_int64_string_implicit_ConversionResult_implicit_int_implicit_bool: +.. _function-strings_int64_string_implicit_ConversionResult_ref__implicit_int_ref__implicit_bool: .. das:function:: int64(str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int64 @@ -903,9 +970,10 @@ int8 Converts a string to an int8, panicking on failure; an overload accepts `result`, `offset`, and optional `hex` flag to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit -.. _function-strings_int8_string_implicit_ConversionResult_implicit_int_implicit_bool: +.. _function-strings_int8_string_implicit_ConversionResult_ref__implicit_int_ref__implicit_bool: .. das:function:: int8(str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : int8 @@ -917,6 +985,7 @@ Converts a string to an int8, panicking on failure; an overload accepts `result` Constructs and returns a new string from the contents of a uint8 byte array. + :Arguments: * **bytes** : array implicit .. _function-strings_to_char_int: @@ -925,6 +994,7 @@ Constructs and returns a new string from the contents of a uint8 byte array. Converts an integer character code to a single-character string. + :Arguments: * **char** : int .. _function-strings_to_cpp_float_float: @@ -933,6 +1003,7 @@ Converts an integer character code to a single-character string. Converts a float value to its string representation using C++ fmt::format_to, correctly handling special constants like FLT_MIN and FLT_MAX. + :Arguments: * **value** : float .. _function-strings_to_double_string_implicit: @@ -941,6 +1012,7 @@ Converts a float value to its string representation using C++ fmt::format_to, co Converts a string to a double value, returning 0.0lf if the conversion fails. + :Arguments: * **value** : string implicit .. _function-strings_to_float_string_implicit: @@ -949,6 +1021,7 @@ Converts a string to a double value, returning 0.0lf if the conversion fails. Converts a string to a float value, returning 0.0 if the conversion fails. + :Arguments: * **value** : string implicit .. _function-strings_to_int_string_implicit_bool: @@ -957,6 +1030,7 @@ Converts a string to a float value, returning 0.0 if the conversion fails. Converts a string to an int value with optional hexadecimal parsing when `hex` is true, returning 0 if the conversion fails. + :Arguments: * **value** : string implicit * **hex** : bool @@ -967,6 +1041,7 @@ Converts a string to an int value with optional hexadecimal parsing when `hex` i Converts a string to an int16 value with optional hexadecimal parsing when `hex` is true, returning 0 if the conversion fails. + :Arguments: * **value** : string implicit * **hex** : bool @@ -977,6 +1052,7 @@ Converts a string to an int16 value with optional hexadecimal parsing when `hex` Converts a string to an int64 value with optional hexadecimal parsing when `hex` is true, returning 0l if the conversion fails. + :Arguments: * **value** : string implicit * **hex** : bool @@ -987,6 +1063,7 @@ Converts a string to an int64 value with optional hexadecimal parsing when `hex` Converts a string to an int8 value with optional hexadecimal parsing when `hex` is true, returning 0 if the conversion fails. + :Arguments: * **value** : string implicit * **hex** : bool @@ -997,6 +1074,7 @@ Converts a string to an int8 value with optional hexadecimal parsing when `hex` Converts a string to a uint value with optional hexadecimal parsing when `hex` is true, returning 0u if the conversion fails. + :Arguments: * **value** : string implicit * **hex** : bool @@ -1008,6 +1086,7 @@ Converts a string to a uint value with optional hexadecimal parsing when `hex` i // stub def to_uint16 (value: string implicit; hex: bool = false) : uint16 + :Arguments: * **value** : string implicit * **hex** : bool @@ -1018,6 +1097,7 @@ def to_uint16 (value: string implicit; hex: bool = false) : uint16 Converts a string to a uint64 value with optional hexadecimal parsing when `hex` is true, returning 0ul if the conversion fails. + :Arguments: * **value** : string implicit * **hex** : bool @@ -1028,6 +1108,7 @@ Converts a string to a uint64 value with optional hexadecimal parsing when `hex` Converts a string to a uint8 value with optional hexadecimal parsing when `hex` is true, returning 0u if the conversion fails. + :Arguments: * **value** : string implicit * **hex** : bool @@ -1042,9 +1123,10 @@ uint Converts a string to a uint, panicking on failure; an overload accepts `result`, `offset`, and optional `hex` flag to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit -.. _function-strings_uint_string_implicit_ConversionResult_implicit_int_implicit_bool: +.. _function-strings_uint_string_implicit_ConversionResult_ref__implicit_int_ref__implicit_bool: .. das:function:: uint(str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint @@ -1060,9 +1142,10 @@ uint16 Converts a string to a uint16, panicking on failure; an overload accepts `result`, `offset`, and optional `hex` flag to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit -.. _function-strings_uint16_string_implicit_ConversionResult_implicit_int_implicit_bool: +.. _function-strings_uint16_string_implicit_ConversionResult_ref__implicit_int_ref__implicit_bool: .. das:function:: uint16(str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint16 @@ -1078,9 +1161,10 @@ uint64 Converts a string to a uint64, panicking on failure; an overload accepts `result`, `offset`, and optional `hex` flag to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit -.. _function-strings_uint64_string_implicit_ConversionResult_implicit_int_implicit_bool: +.. _function-strings_uint64_string_implicit_ConversionResult_ref__implicit_int_ref__implicit_bool: .. das:function:: uint64(str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint64 @@ -1090,17 +1174,18 @@ Converts a string to a uint64, panicking on failure; an overload accepts `result uint8 ^^^^^ -.. _function-strings_uint8_string_implicit_ConversionResult_implicit_int_implicit_bool: +.. _function-strings_uint8_string_implicit_ConversionResult_ref__implicit_int_ref__implicit_bool: .. das:function:: uint8(str: string implicit; result: ConversionResult& implicit; offset: int& implicit; hex: bool = false) : uint8 Converts a string to a uint8, panicking on failure; an overload accepts `result`, `offset`, and optional `hex` flag to report the ConversionResult status and parsed position instead of panicking. + :Arguments: * **str** : string implicit - * **result** : :ref:`ConversionResult `& implicit + * **result** : :ref:`ConversionResult `\ & implicit - * **offset** : int& implicit + * **offset** : int\ & implicit * **hex** : bool @@ -1110,6 +1195,7 @@ Converts a string to a uint8, panicking on failure; an overload accepts `result` ---- + +++++++++++++++ String as array +++++++++++++++ @@ -1123,9 +1209,10 @@ String as array Maps the raw bytes of string `str` into a temporary uint8 array, passes it to `block` for in-place reading and writing, and returns the modified string. + :Arguments: * **str** : string implicit - * **block** : block<(array#):void> implicit + * **block** : block<(array\ #):void> implicit .. _function-strings_peek_data_string_implicit_block_ls_array_ls_uint8_gr__hh__c_void_gr_: @@ -1133,18 +1220,20 @@ Maps the raw bytes of string `str` into a temporary uint8 array, passes it to `b Maps the raw bytes of string `str` into a temporary read-only uint8 array and passes it to `block` for inspection. + :Arguments: * **str** : string implicit - * **block** : block<(array#):void> implicit + * **block** : block<(array\ #):void> implicit + +++++++++++++++++++++++++++ Low level memory allocation +++++++++++++++++++++++++++ - * :ref:`delete_string (str: string& implicit) : bool ` + * :ref:`delete_string (str: string& implicit) : bool ` * :ref:`reserve_string_buffer (str: string implicit; length: int) : string ` -.. _function-strings_delete_string_string_implicit: +.. _function-strings_delete_string_string_ref__implicit: .. das:function:: delete_string(str: string& implicit) : bool @@ -1153,7 +1242,8 @@ Low level memory allocation Frees the string `str` from the heap and clears the reference, returning true on success; unsafe because existing aliases become dangling pointers. -:Arguments: * **str** : string& implicit + +:Arguments: * **str** : string\ & implicit .. _function-strings_reserve_string_buffer_string_implicit_int: @@ -1161,6 +1251,7 @@ Frees the string `str` from the heap and clears the reference, returning true on Allocates a copy of the string data on the heap with at least `length` bytes reserved and returns the new string. + :Arguments: * **str** : string implicit * **length** : int diff --git a/doc/source/stdlib/strings_boost.rst b/doc/source/stdlib/strings_boost.rst index 283ab3164c..c5ac51a7b6 100644 --- a/doc/source/stdlib/strings_boost.rst +++ b/doc/source/stdlib/strings_boost.rst @@ -5,6 +5,8 @@ Boost package for string manipulation library ============================================= +.. das:module:: strings_boost + The STRINGS_BOOST module extends string handling with splitting, joining, padding, character replacement, and edit distance computation. @@ -30,6 +32,8 @@ Example: :: // [hello ] // distance: 3 + + ++++++++++++++ Split and join ++++++++++++++ @@ -38,7 +42,7 @@ Split and join * :ref:`join (iterable: array\; separator: string; blk: block\<(var writer:StringBuilderWriter;elem:TT):void\>) : string ` * :ref:`join (var it: iterator\; separator: string implicit) : auto ` * :ref:`join (var iterable: iterator\; separator: string; blk: block\<(var writer:StringBuilderWriter;elem:TT):void\>) : string ` - * :ref:`join (iterable: auto(TT)[]; separator: string; blk: block\<(var writer:StringBuilderWriter;elem:TT):void\>) : string ` + * :ref:`join (iterable: auto(TT)[]; separator: string; blk: block\<(var writer:StringBuilderWriter;elem:TT):void\>) : string ` * :ref:`split (text: string implicit; delim: string implicit) : array\ ` * :ref:`split (text: string implicit; delim: string implicit; blk: block\<(arg:array\#):auto\>) : auto ` * :ref:`split_by_chars (text: string implicit; delim: string implicit) : array\ ` @@ -54,6 +58,7 @@ join Joins the elements of an iterable into a single string using the specified separator. + :Arguments: * **it** : auto * **separator** : string implicit @@ -70,7 +75,7 @@ Joins the elements of an iterable into a single string using the specified separ .. das:function:: join(iterable: iterator; separator: string; blk: block<(var writer:StringBuilderWriter;elem:TT):void>) : string -.. _function-strings_boost_join_autoTT_string_block_ls_var_writer_c_StringBuilderWriter;elem_c_TT_c_void_gr__0x64: +.. _function-strings_boost_join_autoTT_lb__rb__string_block_ls_var_writer_c_StringBuilderWriter;elem_c_TT_c_void_gr__0x64: .. das:function:: join(iterable: auto(TT)[]; separator: string; blk: block<(var writer:StringBuilderWriter;elem:TT):void>) : string @@ -86,6 +91,7 @@ split Splits a string by the specified delimiter characters, invoking a block for each resulting substring. + :Arguments: * **text** : string implicit * **delim** : string implicit @@ -106,6 +112,7 @@ split_by_chars Splits a string by the specified delimiter characters and returns an array of substrings. + :Arguments: * **text** : string implicit * **delim** : string implicit @@ -116,6 +123,7 @@ Splits a string by the specified delimiter characters and returns an array of su ---- + ++++++++++ Formatting ++++++++++ @@ -132,6 +140,7 @@ Formatting // stub def capitalize (str: string) : string + :Arguments: * **str** : string .. _function-strings_boost_pad_left_string_int_int: @@ -141,6 +150,7 @@ def capitalize (str: string) : string // stub def pad_left (str: string; width: int; ch: int = 32) : string + :Arguments: * **str** : string * **width** : int @@ -154,6 +164,7 @@ def pad_left (str: string; width: int; ch: int = 32) : string // stub def pad_right (str: string; width: int; ch: int = 32) : string + :Arguments: * **str** : string * **width** : int @@ -166,10 +177,12 @@ def pad_right (str: string; width: int; ch: int = 32) : string Pads the string with trailing spaces to reach the specified minimum width. + :Arguments: * **text** : string implicit * **width** : int + +++++++++++++++++++++++ Queries and comparisons +++++++++++++++++++++++ @@ -188,6 +201,7 @@ Queries and comparisons // stub def contains (str: string; sub: string) : bool + :Arguments: * **str** : string * **sub** : string @@ -199,6 +213,7 @@ def contains (str: string; sub: string) : bool // stub def count (str: string; sub: string) : int + :Arguments: * **str** : string * **sub** : string @@ -213,6 +228,7 @@ eq Compares a ``string`` with a ``das_string`` for equality, returning ``true`` if they match. + :Arguments: * **b** : :ref:`das_string ` * **a** : string implicit @@ -229,6 +245,7 @@ Compares a ``string`` with a ``das_string`` for equality, returning ``true`` if Returns ``true`` if the byte at the specified index in the array equals the given character code. + :Arguments: * **foo** : array implicit * **idx** : int @@ -242,8 +259,10 @@ Returns ``true`` if the byte at the specified index in the array equals the give // stub def is_null_or_whitespace (str: string) : bool + :Arguments: * **str** : string + ++++++ Search ++++++ @@ -262,6 +281,7 @@ last_index_of // stub def last_index_of (str: string; sub: string; start: int) : int + :Arguments: * **str** : string * **sub** : string @@ -274,6 +294,7 @@ def last_index_of (str: string; sub: string; start: int) : int ---- + +++++++ Replace +++++++ @@ -286,10 +307,12 @@ Replace Applies multiple find-and-replace substitutions to a string in a single pass. + :Arguments: * **source** : string * **replaces** : array> + +++++++++++++++++ Prefix and suffix +++++++++++++++++ @@ -304,6 +327,7 @@ Prefix and suffix // stub def trim_prefix (str: string; prefix: string) : string + :Arguments: * **str** : string * **prefix** : string @@ -315,10 +339,12 @@ def trim_prefix (str: string; prefix: string) : string // stub def trim_suffix (str: string; suffix: string) : string + :Arguments: * **str** : string * **suffix** : string + ++++++++++++++++++++ Levenshtein distance ++++++++++++++++++++ @@ -332,6 +358,7 @@ Levenshtein distance Computes the Levenshtein edit distance between two strings. + :Arguments: * **s** : string implicit * **t** : string implicit @@ -342,6 +369,7 @@ Computes the Levenshtein edit distance between two strings. Computes the Levenshtein edit distance between two strings using an optimized algorithm. + :Arguments: * **s** : string implicit * **t** : string implicit diff --git a/doc/source/stdlib/temp_strings.rst b/doc/source/stdlib/temp_strings.rst index b8b32374f1..90639e1517 100644 --- a/doc/source/stdlib/temp_strings.rst +++ b/doc/source/stdlib/temp_strings.rst @@ -5,6 +5,8 @@ Temporary string utilities ========================== +.. das:module:: temp_strings + The TEMP_STRINGS module provides temporary string construction that avoids heap allocations. Temporary strings are allocated on the stack or in scratch memory and are valid only within the current scope, offering fast string building @@ -14,6 +16,8 @@ All functions and symbols are in "temp_strings" module, use require to get acces require daslib/temp_strings + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -24,6 +28,8 @@ Function annotations Function annotation that enables temporary string optimization. + + +++++++++++++++++++++++++ Temporary string builders +++++++++++++++++++++++++ @@ -37,9 +43,11 @@ Temporary string builders Same as build_string, but delete the string after the callback is called. Intern strings are not deleted. + :Arguments: * **bldr** : block<(writer: :ref:`StringBuilderWriter `):void> - * **cb** : block<(res:string#):void> + * **cb** : block<(res:string\ #):void> + +++++++++++++++++++++++++++ Temporary string conversion @@ -59,9 +67,10 @@ temp_string Construct string from array of bytes and pass it to the callback. Delete the string after the callback is called. Intern strings are not deleted. + :Arguments: * **arr** : array - * **cb** : block<(res:string#):void> + * **cb** : block<(res:string\ #):void> .. _function-temp_strings_temp_string_string_block_ls_res_c_string_hh__c_void_gr_: diff --git a/doc/source/stdlib/templates.rst b/doc/source/stdlib/templates.rst index f98ccaafba..f7d1856bd4 100644 --- a/doc/source/stdlib/templates.rst +++ b/doc/source/stdlib/templates.rst @@ -5,6 +5,8 @@ decltype macro and template function annotation =============================================== +.. das:module:: templates + The TEMPLATES module implements template instantiation utilities for daslang code generation. It supports stamping out parameterized code patterns with type and value substitution. @@ -15,6 +17,8 @@ All functions and symbols are in "templates" module, use require to get access t require daslib/templates + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -35,6 +39,8 @@ For example:: boo(1,type) // will be replaced with boo(1). instace will print "1_int" + + +++++++++++ Call macros +++++++++++ @@ -49,6 +55,7 @@ This macro returns ast::TypeDecl for the corresponding expression. For example:: let y <- decltype(x) // [[TypeDecl() baseType==Type tInt, flags=TypeDeclFlags constant | TypeDeclFlags ref]] + .. _call-macro-templates-decltype_noref: .. das:attribute:: decltype_noref @@ -56,3 +63,4 @@ This macro returns ast::TypeDecl for the corresponding expression. For example:: This macro returns TypeDecl for the corresponding expression, minus the ref (&) portion. + diff --git a/doc/source/stdlib/templates_boost.rst b/doc/source/stdlib/templates_boost.rst index 52156f89f7..e4f27a76d8 100644 --- a/doc/source/stdlib/templates_boost.rst +++ b/doc/source/stdlib/templates_boost.rst @@ -5,6 +5,8 @@ Template application helpers ============================ +.. das:module:: templates_boost + The TEMPLATES_BOOST module extends template utilities with high-level macros for common code generation patterns, including template function generation, type-parameterized struct creation, and compile-time code expansion. @@ -15,6 +17,8 @@ All functions and symbols are in "templates_boost" module, use require to get ac require daslib/templates_boost + + ++++++++++ Structures ++++++++++ @@ -52,6 +56,8 @@ This structure contains collection of substitution rules for a template. * **tag2expr** : table`>> - tag expression replacement rules + + +++++++++++ Call macros +++++++++++ @@ -62,24 +68,28 @@ Call macros This macro implements expression reification for variables. + .. _call-macro-templates_boost-qmacro_expr: .. das:attribute:: qmacro_expr This macro implements first line of the expression block reification 'qmacro_expr' + .. _call-macro-templates_boost-qmacro_function: .. das:attribute:: qmacro_function This macro implements expression reification for functions. + .. _call-macro-templates_boost-qmacro_block_to_array: .. das:attribute:: qmacro_block_to_array This macro implements expression block to array reification 'qmacro_block_to_array' + .. _call-macro-templates_boost-qmacro_template_class: .. das:attribute:: qmacro_template_class @@ -87,12 +97,14 @@ This macro implements expression block to array reification 'qmacro_block_to_arr Call macro for quoting named template class methods. This macro implements expression reification for the named expressions (function, variable, etc.) + .. _call-macro-templates_boost-qmacro_method: .. das:attribute:: qmacro_method This macro implements expression reification for class methods. + .. _call-macro-templates_boost-qmacro_template_function: .. das:attribute:: qmacro_template_function @@ -100,24 +112,29 @@ This macro implements expression reification for class methods. Call macro for quoting named template functions. This macro implements expression reification for the named expressions (function, variable, etc.) + .. _call-macro-templates_boost-qmacro: .. das:attribute:: qmacro This macro implements expression reification 'qmacro' + .. _call-macro-templates_boost-qmacro_block: .. das:attribute:: qmacro_block This macro implements expression block reification 'qmacro_block' + .. _call-macro-templates_boost-qmacro_type: .. das:attribute:: qmacro_type This macro implements type declaration reification 'qmacro_type' + + ++++++++++++++ Template rules ++++++++++++++ @@ -147,6 +164,7 @@ Template rules Adds a rule to to the template to replace a variable field access with a prefix and suffix. I.e. foo.bar into prefix + bar + suffix + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -165,6 +183,7 @@ renameCall Adds a rule to the template to rename a call. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -187,6 +206,7 @@ renameField Adds a rule to the template to rename any field lookup (., ?., as, is, etc) + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -209,6 +229,7 @@ renameVariable Adds a rule to the template to rename a variable. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -227,6 +248,7 @@ Adds a rule to the template to rename a variable. Adds a rule to the template to replace an annotation argument with the result of a callback. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -239,6 +261,7 @@ Adds a rule to the template to replace an annotation argument with the result of Adds a rule to the template to replace a block argument with a list of variables. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -251,6 +274,7 @@ Adds a rule to the template to replace a block argument with a list of variables Adds a rule to the template to rename a block argument. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -263,6 +287,7 @@ Adds a rule to the template to rename a block argument. Adds a rule to the template to replace a type alias with another type alias, specified by type declaration. + :Arguments: * **self** : :ref:`Template ` * **pstruct** : :ref:`Structure `? @@ -275,6 +300,7 @@ Adds a rule to the template to replace a type alias with another type alias, spe Adds a rule to the template to replace a type alias with another type alias, specified by name. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -287,6 +313,7 @@ Adds a rule to the template to replace a type alias with another type alias, spe Adds a rule to the template to replace a type alias with another type alias, specified by type declaration. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -299,6 +326,7 @@ Adds a rule to the template to replace a type alias with another type alias, spe Adds a rule to the template to replace a variable tag with an expression. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -311,6 +339,7 @@ Adds a rule to the template to replace a variable tag with an expression. Adds a rule to the template to replace a variable with an expression. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -327,6 +356,7 @@ replaceVariableWithList Adds a rule to the template to replace a variable with an expression list. + :Arguments: * **self** : :ref:`Template ` * **name** : string @@ -339,15 +369,16 @@ Adds a rule to the template to replace a variable with an expression list. ---- + ++++++++++++++++++++ Template application ++++++++++++++++++++ * :ref:`apply_template (var rules: Template; at: LineInfo; var typ: smart_ptr\; forceAt: bool = true) : TypeDeclPtr ` * :ref:`apply_template (var rules: Template; at: LineInfo; var expr: smart_ptr\; forceAt: bool = true) : ExpressionPtr ` - * :ref:`apply_template (at: LineInfo; var expr: smart_ptr\&; blk: block\<(var rules:Template):void\>) : ExpressionPtr ` - * :ref:`apply_template (at: LineInfo; var typ: smart_ptr\&; blk: block\<(var rules:Template):void\>) : TypeDeclPtr ` - * :ref:`apply_template (var expr: smart_ptr\&; blk: block\<(var rules:Template):void\>) : ExpressionPtr ` + * :ref:`apply_template (at: LineInfo; var expr: smart_ptr\&; blk: block\<(var rules:Template):void\>) : ExpressionPtr ` + * :ref:`apply_template (at: LineInfo; var typ: smart_ptr\&; blk: block\<(var rules:Template):void\>) : TypeDeclPtr ` + * :ref:`apply_template (var expr: smart_ptr\&; blk: block\<(var rules:Template):void\>) : ExpressionPtr ` apply_template @@ -359,6 +390,7 @@ apply_template Applies the template to the given expression. If `forceAt` is set, the resulting expression will have the same line info as 'at'. + :Arguments: * **rules** : :ref:`Template ` * **at** : :ref:`LineInfo ` @@ -371,20 +403,21 @@ Applies the template to the given expression. If `forceAt` is set, the resulting .. das:function:: apply_template(rules: Template; at: LineInfo; expr: smart_ptr; forceAt: bool = true) : ExpressionPtr -.. _function-templates_boost_apply_template_LineInfo_smart_ptr_ls_Expression_gr__block_ls_var_rules_c_Template_c_void_gr_: +.. _function-templates_boost_apply_template_LineInfo_smart_ptr_ls_Expression_gr__ref__block_ls_var_rules_c_Template_c_void_gr_: .. das:function:: apply_template(at: LineInfo; expr: smart_ptr&; blk: block<(var rules:Template):void>) : ExpressionPtr -.. _function-templates_boost_apply_template_LineInfo_smart_ptr_ls_TypeDecl_gr__block_ls_var_rules_c_Template_c_void_gr_: +.. _function-templates_boost_apply_template_LineInfo_smart_ptr_ls_TypeDecl_gr__ref__block_ls_var_rules_c_Template_c_void_gr_: .. das:function:: apply_template(at: LineInfo; typ: smart_ptr&; blk: block<(var rules:Template):void>) : TypeDeclPtr -.. _function-templates_boost_apply_template_smart_ptr_ls_Expression_gr__block_ls_var_rules_c_Template_c_void_gr_: +.. _function-templates_boost_apply_template_smart_ptr_ls_Expression_gr__ref__block_ls_var_rules_c_Template_c_void_gr_: .. das:function:: apply_template(expr: smart_ptr&; blk: block<(var rules:Template):void>) : ExpressionPtr ---- + ++++++++++++++++++ Expression helpers ++++++++++++++++++ @@ -399,6 +432,7 @@ Expression helpers Force expression location, then return it. + :Arguments: * **expr** : :ref:`ExpressionPtr ` * **at** : :ref:`LineInfo ` @@ -410,6 +444,7 @@ Force expression location, then return it. Removes dereferences of the variable `varname` from the expression. This is typically used when replacing 'workhorse' variable with constant. + :Arguments: * **varname** : string * **expr** : smart_ptr< :ref:`Expression `> @@ -420,10 +455,12 @@ This is typically used when replacing 'workhorse' variable with constant. Visits the expression with the given visitor adapter. + :Arguments: * **expr** : :ref:`ExpressionPtr ` * **adapter** : smart_ptr< :ref:`VisitorAdapter `> + +++++++++++++++++++++ Expression generation +++++++++++++++++++++ @@ -441,6 +478,7 @@ make_expression_block Create ExprBlock and move all expressions from expr to the list of the block. + :Arguments: * **exprs** : vector> .. _function-templates_boost_make_expression_block_array_ls_ExpressionPtr_gr_: @@ -449,6 +487,7 @@ Create ExprBlock and move all expressions from expr to the list of the block. ---- + +++++++++++++ Block helpers +++++++++++++ @@ -462,6 +501,7 @@ Block helpers Moves the corresponding block subexpression expression from the ExprMakeBlock. + :Arguments: * **expr** : :ref:`ExpressionPtr ` .. _function-templates_boost_unquote_block_ExpressionPtr: @@ -470,8 +510,10 @@ Moves the corresponding block subexpression expression from the ExprMakeBlock. Returns the corresponding block subexpression expression from the ExprMakeBlock. + :Arguments: * **expr** : :ref:`ExpressionPtr ` + +++++++++++++++++++++++ Global variable helpers +++++++++++++++++++++++ @@ -490,6 +532,7 @@ Global variable helpers Add global variable to the module, given name and initial value. Variable type will be constant. + :Arguments: * **mod** : :ref:`Module `? * **vname** : string @@ -505,6 +548,7 @@ Variable type will be constant. Add global variable to the module, given name and initial value. It will be private, and type will be constant. + :Arguments: * **mod** : :ref:`Module `? * **vname** : string @@ -520,6 +564,7 @@ It will be private, and type will be constant. Add global variable to the module, given name and initial value. It will be private. + :Arguments: * **mod** : :ref:`Module `? * **vname** : string @@ -539,6 +584,7 @@ add_global_var Add global variable to the module, given name and type. `priv` specifies if the variable is private to the block. + :Arguments: * **mod** : :ref:`Module `? * **vname** : string @@ -561,6 +607,7 @@ Add global variable to the module, given name and type. ---- + ++++++++++++++ Hygienic names ++++++++++++++ @@ -574,13 +621,16 @@ Hygienic names Generates unique private name for the variable, given prefix and line info. .. warning:: -The assumption is that line info is unique for the context of the unique name generation. -If it is not, additional measures must be taken to ensure uniqueness of prefix. + + The assumption is that line info is unique for the context of the unique name generation. + If it is not, additional measures must be taken to ensure uniqueness of prefix. + :Arguments: * **prefix** : string * **vat** : :ref:`LineInfo ` + ++++++++++++++ Quoting macros ++++++++++++++ @@ -602,6 +652,7 @@ Quoting macros Implementation details for the expression reification. This is a block reification. + :Arguments: * **expr** : smart_ptr< :ref:`Expression `> * **blk** : block<(rules: :ref:`Template `):void> @@ -612,6 +663,7 @@ Implementation details for the expression reification. This is a block reificati Implementation details for the expression reification. This is a first line of the block as expression reification. + :Arguments: * **expr** : smart_ptr< :ref:`Expression `> * **blk** : block<(rules: :ref:`Template `):void> @@ -622,6 +674,7 @@ Implementation details for the expression reification. This is a first line of t Implementation details for the expression reification. This is a block reification. + :Arguments: * **expr** : smart_ptr< :ref:`Expression `> * **blk** : block<(rules: :ref:`Template `):void> @@ -632,6 +685,7 @@ Implementation details for the expression reification. This is a block reificati Implementation details for the expression reification. + :Arguments: * **expr** : smart_ptr< :ref:`Expression `> * **blk** : block<(rules: :ref:`Template `):void> @@ -642,6 +696,7 @@ Implementation details for the expression reification. Implementation details for reification. This is a function generation reification. + :Arguments: * **fname** : string * **expr** : smart_ptr< :ref:`Expression `> @@ -654,6 +709,7 @@ Implementation details for reification. This is a function generation reificatio Implementation details for reification. This is a class method function generation reification. + :Arguments: * **fname** : string * **parent** : :ref:`StructurePtr ` @@ -668,6 +724,7 @@ Implementation details for reification. This is a class method function generati Implementation details for the expression reification. This is a template class instantiation reification. + :Arguments: * **instance_name** : string * **template_type** : smart_ptr< :ref:`TypeDecl `> @@ -680,6 +737,7 @@ Implementation details for the expression reification. This is a template class Applies template rules to a function, cloning it with substituted types. + :Arguments: * **func** : :ref:`FunctionPtr ` * **blk** : block<(rules: :ref:`Template `):void> @@ -690,6 +748,7 @@ Applies template rules to a function, cloning it with substituted types. Implementation details for reification. This is a variable generation reification. + :Arguments: * **vname** : string * **expr** : smart_ptr< :ref:`Expression `> @@ -702,10 +761,12 @@ Implementation details for reification. This is a variable generation reificatio Implementation details for the expression reification. This is a type declaration reification. + :Arguments: * **expr** : smart_ptr< :ref:`Expression `> * **blk** : block<(rules: :ref:`Template `):void> + ++++++++++++++++++++ Type pointer helpers ++++++++++++++++++++ @@ -714,7 +775,7 @@ Type pointer helpers * :ref:`add_type_ptr_ref (var st: StructurePtr; flags: TypeDeclFlags) : TypeDeclPtr ` * :ref:`add_type_ptr_ref (var st: EnumerationPtr; flags: TypeDeclFlags) : TypeDeclPtr ` * :ref:`add_type_ptr_ref (a: TypeDeclPtr; flags: TypeDeclFlags) : TypeDeclPtr ` - * :ref:`add_type_ptr_ref (anything: auto(TT); flags: TypeDeclFlags) : TypeDeclPtr ` + * :ref:`add_type_ptr_ref (anything: auto(TT); flags: TypeDeclFlags) : TypeDeclPtr ` * :ref:`add_type_ptr_ref (var st: Structure?; flags: TypeDeclFlags) : TypeDeclPtr ` * :ref:`add_type_ptr_ref (var st: Enumeration?; flags: TypeDeclFlags) : TypeDeclPtr ` @@ -724,6 +785,7 @@ Type pointer helpers Implementation details for the reification. This adds any array to the rules. + :Arguments: * **a** : array> @@ -736,6 +798,7 @@ add_type_ptr_ref Implementation details for the reification. Creates a type declaration from a structure smart pointer. + :Arguments: * **st** : :ref:`StructurePtr ` * **flags** : :ref:`TypeDeclFlags ` @@ -748,7 +811,7 @@ Implementation details for the reification. Creates a type declaration from a st .. das:function:: add_type_ptr_ref(a: TypeDeclPtr; flags: TypeDeclFlags) : TypeDeclPtr -.. _function-templates_boost_add_type_ptr_ref_autoTT_TypeDeclFlags_0x298: +.. _function-templates_boost_add_type_ptr_ref_autoTT_TypeDeclFlags_0x299: .. das:function:: add_type_ptr_ref(anything: auto(TT); flags: TypeDeclFlags) : TypeDeclPtr @@ -762,6 +825,7 @@ Implementation details for the reification. Creates a type declaration from a st ---- + +++++++++++++++++ Structure helpers +++++++++++++++++ @@ -774,6 +838,7 @@ Structure helpers Adds a field to the structure. + :Arguments: * **cls** : :ref:`StructurePtr ` * **name** : string @@ -782,23 +847,25 @@ Adds a field to the structure. * **init** : :ref:`ExpressionPtr ` + ++++++++++++++++ Class generation ++++++++++++++++ - * :ref:`enum_class_type (st: auto) : auto ` + * :ref:`enum_class_type (st: auto) : auto ` * :ref:`make_class (name: string; var baseClass: StructurePtr; mod: Module?) : smart_ptr\ ` * :ref:`make_class (name: string; mod: Module?) : smart_ptr\ ` * :ref:`make_class (name: string; var baseClass: Structure?; mod: Module?) : smart_ptr\ ` * :ref:`make_class_constructor (cls: StructurePtr; ctor: FunctionPtr) : smart_ptr\ ` * :ref:`modify_to_class_member (cls: StructurePtr; fun: FunctionPtr; isExplicit: bool; Constant: bool) ` -.. _function-templates_boost_enum_class_type_auto_0x276: +.. _function-templates_boost_enum_class_type_auto_0x277: .. das:function:: enum_class_type(st: auto) : auto return underlying type for the enumeration + :Arguments: * **st** : auto @@ -811,6 +878,7 @@ make_class Creates a class structure derived from baseClass. Adds __rtti, __finalize fields. + :Arguments: * **name** : string * **baseClass** : :ref:`StructurePtr ` @@ -833,6 +901,7 @@ Creates a class structure derived from baseClass. Adds __rtti, __finalize fields Adds a class constructor from a constructor function. + :Arguments: * **cls** : :ref:`StructurePtr ` * **ctor** : :ref:`FunctionPtr ` @@ -843,6 +912,7 @@ Adds a class constructor from a constructor function. Modifies function to be a member of a particular class. + :Arguments: * **cls** : :ref:`StructurePtr ` * **fun** : :ref:`FunctionPtr ` diff --git a/doc/source/stdlib/type_traits.rst b/doc/source/stdlib/type_traits.rst index d9517cb822..1d902d744a 100644 --- a/doc/source/stdlib/type_traits.rst +++ b/doc/source/stdlib/type_traits.rst @@ -5,6 +5,8 @@ Type trait macros ================= +.. das:module:: type_traits + The TYPE_TRAITS module provides compile-time type introspection and manipulation. It includes type queries (``is_numeric``, ``is_string``, ``is_pointer``), type transformations, and generic programming utilities for writing @@ -14,6 +16,8 @@ All functions and symbols are in "type_traits" module, use require to get access require daslib/type_traits + + +++++++++++ Call macros +++++++++++ @@ -24,6 +28,8 @@ Call macros Converts to 'true' if the first type is a subclass of the second type. + + +++++++++++++++ Typeinfo macros +++++++++++++++ @@ -34,6 +40,7 @@ Typeinfo macros this macro implements "has_property" type trait, which returns true when structure has a property + .. _call-macro-type_traits-fields_count: .. das:attribute:: fields_count @@ -41,3 +48,4 @@ this macro implements "has_property" type trait, which returns true when structu this macro implements "fields_count" type trait, which returns total number of fields in the structure + diff --git a/doc/source/stdlib/typemacro_boost.rst b/doc/source/stdlib/typemacro_boost.rst index 0b2a7d1296..91f61046aa 100644 --- a/doc/source/stdlib/typemacro_boost.rst +++ b/doc/source/stdlib/typemacro_boost.rst @@ -5,6 +5,8 @@ Type macro and template structure support ========================================= +.. das:module:: typemacro_boost + The TYPEMACRO_BOOST module provides infrastructure for defining type macros — custom compile-time type transformations. Type macros allow introducing new type syntax that expands into standard daslang types during compilation. @@ -13,6 +15,8 @@ All functions and symbols are in "typemacro_boost" module, use require to get ac require daslib/typemacro_boost + + ++++++++++ Structures ++++++++++ @@ -30,6 +34,8 @@ Holds a type macro template argument with its name and inferred type. * **inferred_type** : :ref:`TypeDeclPtr ` - Inferred concrete type after template instantiation. + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -40,6 +46,7 @@ Function annotations This macro converts function into a type macro. + .. _handle-typemacro_boost-typemacro_template_function: .. das:attribute:: typemacro_template_function @@ -48,6 +55,8 @@ This one converts function into a type macro that uses template arguments. For example [typemacro_template(TFlatHashTable)] def makeFlatHashTable ( macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr; hashFunctionName : string) : TypeDeclPtr { ... } We generate the body that handles template argument inference and instantiation. + + ++++++++++++++++ Structure macros ++++++++++++++++ @@ -58,27 +67,32 @@ Structure macros Structure annotation that stores type macro documentation metadata. + .. _handle-typemacro_boost-typemacro_template: .. das:attribute:: typemacro_template Structure annotation that marks a struct as a type macro template instance. + .. _handle-typemacro_boost-template_structure: .. das:attribute:: template_structure This macro creates typemacro function and associates it with the structure. It also creates the typemacro_template_function to associate with it. -For example: -[template_structure(KeyType,ValueType)] struct template TFlatHashTable { ... } -creates: -1) [typemacro_function] def TFlatHashTable (macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr) : TypeDeclPtr { - return <- make`template`TFlatHashTable(macroArgument, passArgument, KeyType, ValueType) - } -2) [typemacro_template_function(TFlatHashTable)] def make`template`TFlatHashTable (macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr) : TypeDeclPtr { - return <- default - } +For example:: + + [template_structure(KeyType,ValueType)] struct template TFlatHashTable { ... } + creates: + 1) [typemacro_function] def TFlatHashTable (macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr) : TypeDeclPtr { + return <- make`template`TFlatHashTable(macroArgument, passArgument, KeyType, ValueType) + } + 2) [typemacro_template_function(TFlatHashTable)] def make`template`TFlatHashTable (macroArgument, passArgument : TypeDeclPtr; KeyType, ValueType : TypeDeclPtr) : TypeDeclPtr { + return <- default + } + + ++++++++++++ Enum helpers @@ -92,10 +106,12 @@ Enum helpers Converts an int64 value to the specified enum type via reinterpret cast. + :Arguments: * **_enu** : auto(ET) * **value** : int64 + ++++++++++++++++++++++++++++++++ Template structure instantiation ++++++++++++++++++++++++++++++++ @@ -110,6 +126,7 @@ Template structure instantiation template instance is determined by having parent == template.parent + :Arguments: * **passArgument** : :ref:`TypeDeclPtr ` * **templateType** : :ref:`TypeDeclPtr ` @@ -122,6 +139,7 @@ template instance is determined by having parent == template.parent Annotates a structure as a typemacro template instance of the given template type. + :Arguments: * **instance_type** : :ref:`Structure `? * **template_type** : :ref:`Structure `? @@ -134,12 +152,14 @@ Annotates a structure as a typemacro template instance of the given template typ Builds a mangled template structure name from its base name and argument types. + :Arguments: * **base** : :ref:`Structure `? * **arguments** : array< :ref:`TypeMacroTemplateArgument `> * **extra** : array> + ++++++++++++++++++++++ Type inference helpers ++++++++++++++++++++++ @@ -155,6 +175,7 @@ Type inference helpers Adds all template argument type aliases to a structure. + :Arguments: * **structType** : :ref:`Structure `? * **args** : array< :ref:`TypeMacroTemplateArgument `> @@ -165,6 +186,7 @@ Adds all template argument type aliases to a structure. Infers structure alias types for all template arguments from a structure definition. + :Arguments: * **structType** : :ref:`Structure `? * **args** : array< :ref:`TypeMacroTemplateArgument `> @@ -175,6 +197,7 @@ Infers structure alias types for all template arguments from a structure definit Infers and validates template argument types against a pass argument, returning the resolved type. + :Arguments: * **passArgument** : :ref:`TypeDeclPtr ` * **args** : array< :ref:`TypeMacroTemplateArgument `> @@ -185,8 +208,10 @@ Infers and validates template argument types against a pass argument, returning Verifies that all template arguments have been fully inferred (no remaining auto or alias types). + :Arguments: * **args** : array< :ref:`TypeMacroTemplateArgument `> + ++++++++++++++++++++++ String constant access ++++++++++++++++++++++ @@ -199,8 +224,10 @@ String constant access Extracts a string constant value or function address name from an expression. + :Arguments: * **expr** : :ref:`ExpressionPtr ` + +++++++++++++ Work tracking +++++++++++++ @@ -214,6 +241,7 @@ Work tracking Returns true if custom work has already been performed on the template structure. + :Arguments: * **structType** : :ref:`Structure `? .. _function-typemacro_boost_mark_custom_work_done_Structure_q_: @@ -222,8 +250,10 @@ Returns true if custom work has already been performed on the template structure Marks the template structure's custom work as complete in its annotation. + :Arguments: * **structType** : :ref:`Structure `? + ++++++++++++++++++++ Type macro arguments ++++++++++++++++++++ @@ -241,6 +271,7 @@ typemacro_argument Extracts a string constant or function address argument at the given index from a type macro's dimension expressions. + :Arguments: * **dimExpr** : auto * **index** : int diff --git a/doc/source/stdlib/unroll.rst b/doc/source/stdlib/unroll.rst index 7f9e372932..06eb60034d 100644 --- a/doc/source/stdlib/unroll.rst +++ b/doc/source/stdlib/unroll.rst @@ -5,6 +5,8 @@ Loop unrolling ============== +.. das:module:: unroll + The UNROLL module implements compile-time loop unrolling. The ``unroll`` macro replaces a ``for`` loop with a constant ``range`` bound by stamping out each iteration as separate inlined code, eliminating loop overhead. @@ -31,6 +33,8 @@ Example: :: // step 2 // step 3 + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -49,6 +53,8 @@ For example::: for i in range(9) n[i] = imageLoad(c_bloom_htex, xy + int2(0,i-4)) + + +++++++++ Unrolling +++++++++ @@ -61,6 +67,7 @@ Unrolling Unrolls the for loop (with fixed range) + :Arguments: * **blk** : block diff --git a/doc/source/stdlib/uriparser.rst b/doc/source/stdlib/uriparser.rst index 53613e57c0..6782ba8502 100644 --- a/doc/source/stdlib/uriparser.rst +++ b/doc/source/stdlib/uriparser.rst @@ -5,6 +5,8 @@ URI manipulation library based on UriParser =========================================== +.. das:module:: uriparser + The URIPARSER module provides URI parsing and manipulation based on the uriparser library. It supports parsing URI strings into components (scheme, host, path, query, fragment), normalization, resolution of relative URIs, and GUID generation. @@ -13,6 +15,8 @@ All functions and symbols are in "uriparser" module, use require to get access t require uriparser + + ++++++++++++++++++ Handled structures ++++++++++++++++++ @@ -24,6 +28,7 @@ Handled structures Range of text in the URI. + .. _handle-uriparser-UriIp4Struct: .. das:attribute:: UriIp4Struct @@ -33,6 +38,7 @@ Handled structures :Fields: * **data** : uint8[4] - IPv4 address data. + .. _handle-uriparser-UriIp6Struct: .. das:attribute:: UriIp6Struct @@ -42,6 +48,7 @@ Handled structures :Fields: * **data** : uint8[16] - IPv6 address data. + .. _handle-uriparser-UriHostDataA: .. das:attribute:: UriHostDataA @@ -55,6 +62,7 @@ Host data portion of the URI (IPv4 or IPv6, or some future data). * **ipFuture** : :ref:`UriTextRangeA ` - Future host address data. + .. _handle-uriparser-UriPathSegmentStructA: .. das:attribute:: UriPathSegmentStructA @@ -66,6 +74,7 @@ Part of the path portion of the URI. * **next** : :ref:`UriPathSegmentStructA `? - Next path segment, or null if this is the last segment. + .. _handle-uriparser-UriUriA: .. das:attribute:: UriUriA @@ -95,6 +104,7 @@ URI base class, contains all URI data. * **owner** : int - Whether the URI is owned by the parser. + .. _handle-uriparser-Uri: .. das:attribute:: Uri @@ -105,18 +115,21 @@ URI base class, contains all URI data. Returns ``true`` if the ``Uri`` object contains no URI data. + .. _function-uriparser__dot__rq_size_Uri_implicit: .. das:function:: Uri implicit.size() : int Returns the string length of the URI. + .. _function-uriparser__dot__rq_status_Uri_implicit: .. das:function:: Uri implicit.status() : int Returns the parse status code of the ``Uri`` object. + :Properties: * **empty** : bool * **size** : int @@ -126,6 +139,8 @@ Returns the parse status code of the ``Uri`` object. :Fields: * **uri** : :ref:`UriUriA ` - URI implementation. + + +++++++++++++++++++++++++++++++ Initialization and finalization +++++++++++++++++++++++++++++++ @@ -147,6 +162,7 @@ Uri Constructs a new empty ``Uri`` object. + :Arguments: * **arg0** : string implicit .. _function-uriparser_Uri: @@ -161,6 +177,7 @@ Constructs a new empty ``Uri`` object. Creates a deep copy of the given ``Uri`` object. + :Arguments: * **dest** : :ref:`Uri ` implicit * **src** : :ref:`Uri ` implicit @@ -171,6 +188,7 @@ Creates a deep copy of the given ``Uri`` object. Releases all resources held by the ``Uri`` object. + :Arguments: * **uri** : :ref:`Uri ` implicit @@ -183,9 +201,10 @@ using Creates a scoped ``Uri`` variable that is automatically finalized at end of block. + :Arguments: * **arg0** : string implicit - * **arg1** : block<( :ref:`Uri `#):void> implicit + * **arg1** : block<( :ref:`Uri `\ #):void> implicit .. _function-uriparser_using_block_ls_Uri_hh__c_void_gr_: @@ -193,6 +212,7 @@ Creates a scoped ``Uri`` variable that is automatically finalized at end of bloc ---- + +++++++++++++++++++ Escape and unescape +++++++++++++++++++ @@ -206,6 +226,7 @@ Escape and unescape Percent-encodes reserved and special characters in the URI string. + :Arguments: * **uriStr** : string implicit * **spaceToPlus** : bool @@ -218,8 +239,10 @@ Percent-encodes reserved and special characters in the URI string. Decodes percent-encoded characters in the URI string. + :Arguments: * **uriStr** : string implicit + +++++++++++++++++ Uri manipulations +++++++++++++++++ @@ -239,6 +262,7 @@ Uri manipulations Resolves a relative URI against a base URI, producing an absolute URI. + :Arguments: * **base** : :ref:`Uri ` implicit * **relative** : :ref:`Uri ` implicit @@ -249,6 +273,7 @@ Resolves a relative URI against a base URI, producing an absolute URI. Normalizes a ``Uri`` in place, removing redundant ``/``, ``.``, and ``..`` path segments. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_normalize_uri_string_implicit: @@ -257,6 +282,7 @@ Normalizes a ``Uri`` in place, removing redundant ``/``, ``.``, and ``..`` path Returns a normalized copy of the URI string with redundant ``/``, ``.``, and ``..`` segments removed. + :Arguments: * **uriStr** : string implicit .. _function-uriparser_remove_base_uri_Uri_implicit_Uri_implicit: @@ -265,6 +291,7 @@ Returns a normalized copy of the URI string with redundant ``/``, ``.``, and ``. Computes a relative URI by removing the base URI prefix from an absolute URI. + :Arguments: * **base** : :ref:`Uri ` implicit * **relative** : :ref:`Uri ` implicit @@ -279,6 +306,7 @@ string Converts a ``Uri`` object to its string representation. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_string_UriTextRangeA_implicit: @@ -293,6 +321,7 @@ Converts a ``Uri`` object to its string representation. Removes the query string and fragment from the URI. + :Arguments: * **uri** : :ref:`Uri ` implicit * **query** : bool @@ -305,9 +334,11 @@ Removes the query string and fragment from the URI. Iterates over each key-value pair in the URI's query string, invoking a block for each. + :Arguments: * **uri** : :ref:`Uri ` implicit - * **block** : block<(string#;string#):void> implicit + * **block** : block<(string\ #;string\ #):void> implicit + +++++++++++++++++++++ File name conversions @@ -332,6 +363,7 @@ File name conversions Converts a platform-native file path to a ``file://`` URI string. + :Arguments: * **uriStr** : string implicit .. _function-uriparser_to_file_name_Uri_implicit: @@ -340,6 +372,7 @@ Converts a platform-native file path to a ``file://`` URI string. Converts a ``Uri`` to a platform-native file path. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_to_unix_file_name_Uri_implicit: @@ -348,6 +381,7 @@ Converts a ``Uri`` to a platform-native file path. Converts a ``Uri`` to a Unix-style file path. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_to_windows_file_name_Uri_implicit: @@ -356,6 +390,7 @@ Converts a ``Uri`` to a Unix-style file path. Converts a ``Uri`` to a Windows-style file path. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_unix_file_name_to_uri_string_implicit: @@ -364,6 +399,7 @@ Converts a ``Uri`` to a Windows-style file path. Converts a Unix-style file path to a ``file://`` URI string. + :Arguments: * **uriStr** : string implicit .. _function-uriparser_uri_from_file_name_string_implicit: @@ -372,6 +408,7 @@ Converts a Unix-style file path to a ``file://`` URI string. Converts a platform-native file path to a ``file://`` URI string. + :Arguments: * **filename** : string implicit .. _function-uriparser_uri_from_unix_file_name_string_implicit: @@ -380,6 +417,7 @@ Converts a platform-native file path to a ``file://`` URI string. Converts a Unix-style file path to a ``file://`` URI string. + :Arguments: * **filename** : string implicit .. _function-uriparser_uri_from_windows_file_name_string_implicit: @@ -388,6 +426,7 @@ Converts a Unix-style file path to a ``file://`` URI string. Converts a Windows-style file path to a ``file://`` URI string. + :Arguments: * **filename** : string implicit .. _function-uriparser_uri_to_file_name_string_implicit: @@ -396,6 +435,7 @@ Converts a Windows-style file path to a ``file://`` URI string. Converts a URI string to a platform-native file path. + :Arguments: * **uriStr** : string implicit .. _function-uriparser_uri_to_unix_file_name_string_implicit: @@ -404,6 +444,7 @@ Converts a URI string to a platform-native file path. Converts a URI string to a Unix-style file path. + :Arguments: * **uriStr** : string implicit .. _function-uriparser_uri_to_windows_file_name_string_implicit: @@ -412,6 +453,7 @@ Converts a URI string to a Unix-style file path. Converts a URI string to a Windows-style file path. + :Arguments: * **uriStr** : string implicit .. _function-uriparser_windows_file_name_to_uri_string_implicit: @@ -420,8 +462,10 @@ Converts a URI string to a Windows-style file path. Converts a Windows-style file path to a ``file://`` URI string. + :Arguments: * **uriStr** : string implicit + ++++ GUID ++++ @@ -435,3 +479,4 @@ GUID Generates a new random GUID/UUID string. + diff --git a/doc/source/stdlib/uriparser_boost.rst b/doc/source/stdlib/uriparser_boost.rst index 57ab67e2a6..a1d630d5ff 100644 --- a/doc/source/stdlib/uriparser_boost.rst +++ b/doc/source/stdlib/uriparser_boost.rst @@ -5,6 +5,8 @@ Boost package for the URI parser ================================ +.. das:module:: uriparser_boost + The URIPARSER_BOOST module extends URI handling with convenience functions for common operations like building URIs from components, extracting query parameters, and resolving relative paths. @@ -13,6 +15,8 @@ All functions and symbols are in "uriparser_boost" module, use require to get ac require daslib/uriparser_boost + + +++++++++++++++++ Split and compose +++++++++++++++++ @@ -28,6 +32,7 @@ Split and compose Compose a URI from its components. + :Arguments: * **scheme** : string * **userInfo** : string @@ -48,6 +53,7 @@ Compose a URI from its components. Compose a query string from a table of key-value pairs. + :Arguments: * **query** : table .. _function-uriparser_boost_uri_compose_query_in_order_table_ls_string,_string_gr_: @@ -56,6 +62,7 @@ Compose a query string from a table of key-value pairs. Compose a query string from a table of key-value pairs, in the sorted order. + :Arguments: * **query** : table .. _function-uriparser_boost_uri_split_full_path_Uri_implicit: @@ -64,8 +71,10 @@ Compose a query string from a table of key-value pairs, in the sorted order. Split the full path of a URI into its components. + :Arguments: * **uri** : :ref:`Uri ` implicit + +++++++++++++++++++ Component accessors +++++++++++++++++++ @@ -84,6 +93,7 @@ Component accessors Return the fragment of a URI. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_boost_host_Uri_implicit: @@ -92,6 +102,7 @@ Return the fragment of a URI. Return the host of a URI. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_boost_path_Uri_implicit: @@ -100,6 +111,7 @@ Return the host of a URI. Return the path of a URI. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_boost_port_Uri_implicit: @@ -108,6 +120,7 @@ Return the path of a URI. Return the port of a URI. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_boost_query_Uri_implicit: @@ -116,6 +129,7 @@ Return the port of a URI. Return the query of a URI. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_boost_scheme_Uri_implicit: @@ -124,6 +138,7 @@ Return the query of a URI. Returns the scheme of a URI. + :Arguments: * **uri** : :ref:`Uri ` implicit .. _function-uriparser_boost_user_info_Uri_implicit: @@ -132,6 +147,7 @@ Returns the scheme of a URI. Return the user info of a URI. + :Arguments: * **uri** : :ref:`Uri ` implicit diff --git a/doc/source/stdlib/utf8_utils.rst b/doc/source/stdlib/utf8_utils.rst index 20835ac10a..c2cd8dc714 100644 --- a/doc/source/stdlib/utf8_utils.rst +++ b/doc/source/stdlib/utf8_utils.rst @@ -5,6 +5,8 @@ UTF-8 utilities =============== +.. das:module:: utf8_utils + The UTF8_UTILS module provides Unicode UTF-8 string utilities including character iteration, codepoint extraction, byte length calculation, and validation of UTF-8 encoded text. @@ -13,6 +15,8 @@ All functions and symbols are in "utf8_utils" module, use require to get access require daslib/utf8_utils + + +++++++++ Constants +++++++++ @@ -23,12 +27,15 @@ Constants Byte-class and state-transition table for the UTF-8 DFA decoder. + .. _global-utf8_utils-UTF8_ACCEPT: .. das:attribute:: UTF8_ACCEPT = 0x0 DFA accept state indicating a valid UTF-8 sequence. + + +++++++++++++++++++++ Encoding and decoding +++++++++++++++++++++ @@ -50,6 +57,7 @@ Encoding and decoding Decodes Unicode escape sequences (backslash followed by hex digits) in a string to UTF-8. + :Arguments: * **str** : string .. _function-utf8_utils_utf16_to_utf32_uint_uint: @@ -58,6 +66,7 @@ Decodes Unicode escape sequences (backslash followed by hex digits) in a string Converts a UTF-16 surrogate pair to a single UTF-32 codepoint. + :Arguments: * **high** : uint * **low** : uint @@ -72,6 +81,7 @@ utf8_decode Converts UTF-8 string to UTF-32 and returns it as an array of codepoints (UTF-32 string) + :Arguments: * **source_utf8_string** : string .. _function-utf8_utils_utf8_decode_array_ls_uint_gr__string: @@ -98,6 +108,7 @@ utf8_encode Converts UTF-32 string to UTF-8 and appends it to the UTF-8 byte array + :Arguments: * **dest_array** : array * **source_utf32_string** : array implicit @@ -116,6 +127,7 @@ Converts UTF-32 string to UTF-8 and appends it to the UTF-8 byte array ---- + ++++++++++++++++++++++ Length and measurement ++++++++++++++++++++++ @@ -133,6 +145,7 @@ utf8_length Returns the number of characters in the UTF-8 string + :Arguments: * **utf8_string** : string .. _function-utf8_utils_utf8_length_array_ls_uint8_gr_: @@ -141,6 +154,7 @@ Returns the number of characters in the UTF-8 string ---- + ++++++++++ Validation ++++++++++ @@ -161,6 +175,7 @@ contains_utf8_bom Returns true if the byte array starts with a UTF-8 BOM (byte order mark). + :Arguments: * **utf8_string** : array implicit .. _function-utf8_utils_contains_utf8_bom_string: @@ -175,6 +190,7 @@ Returns true if the byte array starts with a UTF-8 BOM (byte order mark). Returns true if the given byte is the first byte of a UTF-8 character. + :Arguments: * **ch** : uint8 @@ -187,6 +203,7 @@ is_utf8_string_valid Returns true if the byte array contains a valid UTF-8 encoded string. + :Arguments: * **utf8_string** : array implicit .. _function-utf8_utils_is_utf8_string_valid_string: diff --git a/doc/source/stdlib/validate_code.rst b/doc/source/stdlib/validate_code.rst index 0bb27947e5..cd852a8252 100644 --- a/doc/source/stdlib/validate_code.rst +++ b/doc/source/stdlib/validate_code.rst @@ -5,6 +5,8 @@ Code validation annotations =========================== +.. das:module:: validate_code + The VALIDATE_CODE module implements AST validation passes that check for common code quality issues, unreachable code, missing return statements, and other semantic errors beyond what the type checker verifies. @@ -13,6 +15,8 @@ All functions and symbols are in "validate_code" module, use require to get acce require daslib/validate_code + + ++++++++++++++++++++ Function annotations ++++++++++++++++++++ @@ -27,3 +31,4 @@ within the annotated function. If any are detected, a compile-time error is generated, preventing the code from compiling. + From 23bb0242f541d288d0aa3bfb05e36f4992d933e5 Mon Sep 17 00:00:00 2001 From: Boris Batkin Date: Tue, 17 Feb 2026 13:18:34 -0800 Subject: [PATCH 2/6] fixing some misleading documentation --- .../reference/tutorials/05_functions.rst | 8 +++--- doc/source/reference/tutorials/14_lambdas.rst | 16 ++++++++++-- .../tutorials/15_iterators_and_generators.rst | 2 +- .../tutorials/24_pattern_matching.rst | 3 +-- .../reference/tutorials/33_algorithm.rst | 2 +- doc/source/stdlib/match.rst | 1 - tutorials/language/05_functions.das | 4 +-- tutorials/language/13_blocks.das | 1 + tutorials/language/14_lambdas.das | 25 +++++++++++++++++-- .../language/15_iterators_and_generators.das | 2 +- tutorials/language/24_pattern_matching.das | 16 +----------- .../language/25_annotations_and_options.das | 2 +- tutorials/language/30_json.das | 1 - tutorials/language/33_algorithm.das | 2 +- 14 files changed, 51 insertions(+), 34 deletions(-) diff --git a/doc/source/reference/tutorials/05_functions.rst b/doc/source/reference/tutorials/05_functions.rst index 51e56b327c..b90fc97c67 100644 --- a/doc/source/reference/tutorials/05_functions.rst +++ b/doc/source/reference/tutorials/05_functions.rst @@ -46,15 +46,15 @@ Default arguments Parameters can have default values. Callers may omit them:: - def formatNumber(value : int; width : int = 6; prefix : string = "#") : string { + def formatNumber(value : int; prefix : string = "#") : string { return "{prefix}{value}" } - formatNumber(42) // uses defaults: "#42" + formatNumber(42) // uses default: "#42" formatNumber(42, [prefix = ">"]) // named argument: ">42" -To skip over defaults and specify a later parameter, use named argument -syntax: ``[name = value]``. +To specify a parameter by name, use named argument syntax: +``[name = value]``. Function overloading ==================== diff --git a/doc/source/reference/tutorials/14_lambdas.rst b/doc/source/reference/tutorials/14_lambdas.rst index 14717a5cba..52e0fda3c6 100644 --- a/doc/source/reference/tutorials/14_lambdas.rst +++ b/doc/source/reference/tutorials/14_lambdas.rst @@ -73,8 +73,20 @@ Lambdas must be **moved** with ``<-``, not copied:: var b <- a // a is now empty b() -Lambdas **cannot** be stored in arrays or copied — each must live in its -own variable and be moved individually. +Lambdas cannot be copied, but they **can** be stored in arrays using +``emplace``, which moves the lambda into the container:: + + var callbacks : array> + var greet <- @() { print("hello from callback\n") } + callbacks |> emplace(greet) // greet is now empty + var farewell <- @() { print("goodbye from callback\n") } + callbacks |> emplace(farewell) + for (cb in callbacks) { + invoke(cb) + } + +Blocks **cannot** be stored in arrays or variables — they live on the +stack and are only valid as function arguments. Stateful lambda factory ======================== diff --git a/doc/source/reference/tutorials/15_iterators_and_generators.rst b/doc/source/reference/tutorials/15_iterators_and_generators.rst index 946505c955..64b067b452 100644 --- a/doc/source/reference/tutorials/15_iterators_and_generators.rst +++ b/doc/source/reference/tutorials/15_iterators_and_generators.rst @@ -26,7 +26,7 @@ Generators ========== A generator lazily produces values one at a time using ``yield``. -Generators use ``$`` with no parentheses:: +Generators use ``$`` (either ``$ { }`` or ``$() { }``):: var counter <- generator() <| $ { for (i in range(5)) { diff --git a/doc/source/reference/tutorials/24_pattern_matching.rst b/doc/source/reference/tutorials/24_pattern_matching.rst index e441634ef6..a00e235f2a 100644 --- a/doc/source/reference/tutorials/24_pattern_matching.rst +++ b/doc/source/reference/tutorials/24_pattern_matching.rst @@ -19,7 +19,6 @@ Basic match require daslib/match - [sideeffects] def describe(n : int) : string { match (n) { if (0) { return "zero" } @@ -31,7 +30,7 @@ Basic match .. note:: - Functions using ``match`` need the ``[sideeffects]`` annotation. + ``match`` works on functions that return values. Wildcards and binding ===================== diff --git a/doc/source/reference/tutorials/33_algorithm.rst b/doc/source/reference/tutorials/33_algorithm.rst index 4e71ed1d30..bfe15eed55 100644 --- a/doc/source/reference/tutorials/33_algorithm.rst +++ b/doc/source/reference/tutorials/33_algorithm.rst @@ -153,7 +153,7 @@ Most functions (``reverse``, ``fill``, ``lower_bound``, ``binary_search``, .. code-block:: das - var a = [5, 3, 1, 4, 2] + var a = fixed_array(5, 3, 1, 4, 2) print("min: {min_element(a)}\n") // 2 (value 1) reverse(a) // [2, 4, 1, 3, 5] diff --git a/doc/source/stdlib/match.rst b/doc/source/stdlib/match.rst index 58b162bd8b..b6cb748ad1 100644 --- a/doc/source/stdlib/match.rst +++ b/doc/source/stdlib/match.rst @@ -28,7 +28,6 @@ Example: :: blue } - [sideeffects] def describe(c : Color) : string { match (c) { if (Color.red) { return "red"; } diff --git a/tutorials/language/05_functions.das b/tutorials/language/05_functions.das index 65b2071a9c..03442f56e7 100644 --- a/tutorials/language/05_functions.das +++ b/tutorials/language/05_functions.das @@ -49,7 +49,7 @@ def increment(var x : int&) { // === Default arguments === -def formatNumber(value : int; width : int = 6; prefix : string = "#") : string { +def formatNumber(value : int; prefix : string = "#") : string { return "{prefix}{value}" } @@ -111,7 +111,7 @@ def main { // Default arguments — omit the ones with defaults print("formatNumber(42) = {formatNumber(42)}\n") - // To specify a non-adjacent default, use named arguments: [name = value] + // To specify a specific default, use named arguments: [name = value] let formatted = formatNumber(42, [prefix = ">"]) print("formatNumber(42, prefix=\">\") = {formatted}\n") diff --git a/tutorials/language/13_blocks.das b/tutorials/language/13_blocks.das index 6b4cb3cf44..f20ee4ad21 100644 --- a/tutorials/language/13_blocks.das +++ b/tutorials/language/13_blocks.das @@ -91,6 +91,7 @@ def main { // === Blocks cannot be stored or returned === // Blocks live on the stack — they can only be passed DOWN as arguments. + // They cannot be stored in arrays, tables, or other containers. // This makes them very fast (no heap allocation). // If you need to store or return a callable, use a lambda (tutorial 14). diff --git a/tutorials/language/14_lambdas.das b/tutorials/language/14_lambdas.das index 85ee1473aa..37a8274267 100644 --- a/tutorials/language/14_lambdas.das +++ b/tutorials/language/14_lambdas.das @@ -48,6 +48,24 @@ def main { // var copy = doubler // ERROR: lambdas can't be copied // var moved <- doubler // OK but doubler becomes null + // === Storing lambdas in arrays === + // Lambdas can be stored in arrays using emplace (which moves them in). + // Blocks CANNOT be stored in arrays — they are stack-bound. + var callbacks : array> + var greet <- @() { + print("hello from callback\n") + } + callbacks |> emplace(greet) + var farewell <- @() { + print("goodbye from callback\n") + } + callbacks |> emplace(farewell) + for (cb in callbacks) { + invoke(cb) + } + print("stored {length(callbacks)} lambdas in array\n") + delete callbacks + // === Passing lambdas to functions === // Functions that take lambda<> accept only @ lambdas (not @@ functions). print("apply(doubler, 21) = {apply_lambda(doubler, 21)}\n") @@ -99,12 +117,12 @@ def main { // BLOCK ($): // - Stack-allocated, very fast // - Captures by reference automatically - // - Cannot be stored or returned — only passed as argument + // - Cannot be stored, returned, or put in arrays — only passed as argument // - Type: block<> // // LAMBDA (@): // - Heap-allocated, captures by copy (default), move, clone, or ref - // - Can be stored in variables (moved), passed around + // - Can be stored in variables (moved), passed around, stored in arrays // - Type: lambda<> // // Each type has its own parameter type: @@ -131,6 +149,9 @@ def apply_lambda(fn : lambda<(x : int) : int>; value : int) : int { // doubler(7) = 14 // call syntax: 6 // invoke: 6 +// hello from callback +// goodbye from callback +// stored 2 lambdas in array // apply(doubler, 21) = 42 // inc() = 1 // inc() = 2 diff --git a/tutorials/language/15_iterators_and_generators.das b/tutorials/language/15_iterators_and_generators.das index fc51317a54..0d6a2d7397 100644 --- a/tutorials/language/15_iterators_and_generators.das +++ b/tutorials/language/15_iterators_and_generators.das @@ -60,7 +60,7 @@ def main { // A generator creates an iterator using yield. // generator() <| $ { ... yield value ... return false } - // Note: generators use $ { } (no parentheses), not $ () { }. + // Note: generators use either $ { } or $() { } (both are valid). // --- Simple generator: count up --- var counter <- generator() <| $ { diff --git a/tutorials/language/24_pattern_matching.das b/tutorials/language/24_pattern_matching.das index 2fb0c22e69..dfe59bbe3e 100644 --- a/tutorials/language/24_pattern_matching.das +++ b/tutorials/language/24_pattern_matching.das @@ -47,7 +47,6 @@ variant Value { // === Basic integer matching === -[sideeffects] def describe_number(n : int) : string { match (n) { if (0) { @@ -68,7 +67,6 @@ def describe_number(n : int) : string { // === Enum matching === -[sideeffects] def color_code(c : Color) : int { match (c) { if (Color.red) { // gen2 dot syntax for enum values @@ -89,7 +87,6 @@ def color_code(c : Color) : int { // === Struct matching + variable binding === -[sideeffects] def describe_point(p : Point) : string { match (p) { if (Point(x = 0, y = 0)) { // exact values @@ -110,7 +107,6 @@ def describe_point(p : Point) : string { // === Guards === -[sideeffects] def classify_shape(s : Shape) : string { match (s) { if (Shape(kind = "circle", size = $v(sz)) && sz > 100) { @@ -128,7 +124,6 @@ def classify_shape(s : Shape) : string { // === OR patterns === -[sideeffects] def is_primary(c : Color) : bool { match (c) { if (Color.red || Color.green || Color.blue) { @@ -143,7 +138,6 @@ def is_primary(c : Color) : bool { // === Tuple matching === -[sideeffects] def classify_pair(t : tuple) : string { match (t) { if ((0, "zero")) { // exact match @@ -164,7 +158,6 @@ def classify_pair(t : tuple) : string { // === Variant matching === -[sideeffects] def describe_value(v : Value) : string { match (v) { if ($v(i) as i) { // match variant alternative by name @@ -182,7 +175,6 @@ def describe_value(v : Value) : string { // === Null / pointer matching === -[sideeffects] def describe_point_ptr(p : Point?) : string { match (p) { if (null) { // null check @@ -200,7 +192,6 @@ def describe_point_ptr(p : Point?) : string { // === multi_match — all matching arms execute === -[sideeffects] def tag_number(n : int) : string { var tags = "{n}:" multi_match(n) { @@ -227,7 +218,6 @@ def tag_number(n : int) : string { // Arms with type mismatches are silently dropped, // so this function works regardless of argument type. -[sideeffects] def static_type_name(what) : string { static_match(what) { if (match_type(type, $v(v))) { @@ -250,7 +240,6 @@ def static_type_name(what) : string { // Static arrays match element-by-element. // Dynamic arrays match head elements; tail is ignored. -[sideeffects] def classify_static_arr(a : int[3]) : string { match (a) { if (fixed_array(0, 0, 0)) { // all zeros @@ -266,7 +255,6 @@ def classify_static_arr(a : int[3]) : string { return "unreachable" } -[sideeffects] def classify_dynamic_arr(a : array) : string { match (a) { if (array(0, 0, ...)) { // starts with 0, 0 @@ -286,7 +274,6 @@ def classify_dynamic_arr(a : array) : string { // match_expr(expression) evaluates at runtime instead of matching literally. // Useful when the expected value depends on captured variables. -[sideeffects] def is_consecutive_triple(t : tuple) : bool { match (t) { if (($v(a), match_expr(a + 1), match_expr(a + 2))) { @@ -301,7 +288,6 @@ def is_consecutive_triple(t : tuple) : bool { // === Bool matching === -[sideeffects] def describe_bool(b : bool) : string { match (b) { if (true) { @@ -423,7 +409,7 @@ def main { // === Summary === // - require daslib/match // - match(expr) { if (pattern) { body } } - // - [sideeffects] annotation required on functions using match + // - match works on functions that return values // - $v(name) — bind matched value to a variable // - _ — wildcard, matches anything // - Guards: if (pattern && condition) { ... } diff --git a/tutorials/language/25_annotations_and_options.das b/tutorials/language/25_annotations_and_options.das index c2ecb4b797..f8bb06e42b 100644 --- a/tutorials/language/25_annotations_and_options.das +++ b/tutorials/language/25_annotations_and_options.das @@ -42,7 +42,7 @@ def private helper() : string { // === [sideeffects] === // Tells the compiler this function has side effects. // Without it, calls whose return values are unused may be eliminated. -// Required for functions using match, or that only do I/O. +// Required for functions that only do I/O (e.g. print). [sideeffects] def log_message(msg : string) { diff --git a/tutorials/language/30_json.das b/tutorials/language/30_json.das index 5f91ead30c..d0bd791b9d 100644 --- a/tutorials/language/30_json.das +++ b/tutorials/language/30_json.das @@ -371,5 +371,4 @@ def main() { broken_json_demo() tuples_and_variants() vectors_demo() - return true } diff --git a/tutorials/language/33_algorithm.das b/tutorials/language/33_algorithm.das index c061110130..ce8bc4df47 100644 --- a/tutorials/language/33_algorithm.das +++ b/tutorials/language/33_algorithm.das @@ -213,7 +213,7 @@ def fixed_array_demo() { // Most algorithm functions also work on fixed-size arrays // via [expect_any_array] overloads. - var a = [5, 3, 1, 4, 2] + var a = fixed_array(5, 3, 1, 4, 2) print("min_element: {min_element(a)}\n") // index of 1 print("max_element: {max_element(a)}\n") // index of 5 print("is_sorted: {is_sorted(a)}\n") // false From 95f5df647ac0630f86d550fb4442be34f49712a8 Mon Sep 17 00:00:00 2001 From: Churkin Aleksey Date: Wed, 18 Feb 2026 00:59:28 +0300 Subject: [PATCH 3/6] jit: remove profile tests Profile tests in JIT was subset of `examples/profile` since JIT was already added to `examples/profile` there is no need anymore in JIT-specific profile tests. --- modules/dasLLVM/profile/dict.das | 33 -- modules/dasLLVM/profile/exp.das | 58 --- modules/dasLLVM/profile/fib.das | 35 -- modules/dasLLVM/profile/mandelbrot.das | 213 -------- modules/dasLLVM/profile/max_from_1s.das | 109 ----- modules/dasLLVM/profile/nbodies.das | 116 ----- .../dasLLVM/profile/nbodies_scalar_double.das | 106 ---- modules/dasLLVM/profile/particles.das | 38 -- modules/dasLLVM/profile/pathtracer.das | 453 ------------------ modules/dasLLVM/profile/primes.das | 53 -- modules/dasLLVM/profile/sha256.das | 124 ----- modules/dasLLVM/profile/table-sort.das | 36 -- modules/dasLLVM/profile/tree.das | 154 ------ 13 files changed, 1528 deletions(-) delete mode 100644 modules/dasLLVM/profile/dict.das delete mode 100644 modules/dasLLVM/profile/exp.das delete mode 100644 modules/dasLLVM/profile/fib.das delete mode 100644 modules/dasLLVM/profile/mandelbrot.das delete mode 100644 modules/dasLLVM/profile/max_from_1s.das delete mode 100644 modules/dasLLVM/profile/nbodies.das delete mode 100644 modules/dasLLVM/profile/nbodies_scalar_double.das delete mode 100644 modules/dasLLVM/profile/particles.das delete mode 100644 modules/dasLLVM/profile/pathtracer.das delete mode 100644 modules/dasLLVM/profile/primes.das delete mode 100644 modules/dasLLVM/profile/sha256.das delete mode 100644 modules/dasLLVM/profile/table-sort.das delete mode 100644 modules/dasLLVM/profile/tree.das diff --git a/modules/dasLLVM/profile/dict.das b/modules/dasLLVM/profile/dict.das deleted file mode 100644 index ad294c266e..0000000000 --- a/modules/dasLLVM/profile/dict.das +++ /dev/null @@ -1,33 +0,0 @@ -options gen2 -require math - -def makeRandomSequence(var src : array) { - let n = 500000 - let mod = uint(n) - resize(src, n) - for (i in range(n)) { - let num = (271828183u ^ uint(i * 119)) % mod - src[i] = "{num}" - } -} - -[jit, hint(hot)] -def dict(var tab : table; src : array) { - clear(tab) - var maxOcc = 0 - for (s in src) { - maxOcc = max(++tab[s], maxOcc) - } - return maxOcc -} - -[export] -def main { - var tab : table - var src : array - makeRandomSequence(src) - profile(20, "dictionary") <| $() { - dict(tab, src) - } -} - diff --git a/modules/dasLLVM/profile/exp.das b/modules/dasLLVM/profile/exp.das deleted file mode 100644 index fc503ca0a3..0000000000 --- a/modules/dasLLVM/profile/exp.das +++ /dev/null @@ -1,58 +0,0 @@ -options gen2 -// options log=true, log_nodes=true, print_var_access=true, print_ref=true - -require math - -[jit, sideeffects] -def expLoop(n) { - var sum = 0. - for (i in range(n)) { - sum += exp(rcp_est(float(i + 1))) - } - return sum -} - -[jit, sideeffects] -def expLoopU(n) { - var sum = 0. - for (i in range(n / 4)) { - let k = float(i * 4) - sum += exp(rcp_est(1. + k)) + exp(rcp_est(2. + k)) + exp(rcp_est(3. + k)) + exp(rcp_est(4. + k)) - } - return sum -} - -[jit, sideeffects] -def expLoopUV(n) { - var sumV = float4(0.) - for (i in range(n / 4)) { - sumV += exp(rcp_est(float4(i * 16) + float4(1, 2, 3, 4))) - } - return sumV.x + sumV.y + sumV.z + sumV.w -} - -def verifyExp(f) { - let t = 1e+06 - let eps = 10. - let q = abs(f - t) - assert(q < eps) -} - -[export] -def main { - var f1 = 0. - profile(20, "exp loop - jit") <| $() { - f1 = expLoop(1000000) - } - verifyExp(f1) - var f2 = 0. - profile(20, "exp loop, unrolled - jit") <| $() { - f2 = expLoopU(1000000) - } - verifyExp(f2) - var f3 = 0. - profile(20, "exp loop, unrolled and vectorized - jit") <| $() { - f3 = expLoopUV(1000000) - } - verifyExp(f3) -} diff --git a/modules/dasLLVM/profile/fib.das b/modules/dasLLVM/profile/fib.das deleted file mode 100644 index 933df72153..0000000000 --- a/modules/dasLLVM/profile/fib.das +++ /dev/null @@ -1,35 +0,0 @@ -options gen2 -[jit, sideeffects] -def fibR_jit(n) { - if (n < 2) { - return n - } - return fibR_jit(n - 1) + fibR_jit(n - 2) -} - -[jit, sideeffects] -def fibI_jit(n : int) { - var last = 0 - var cur = 1 - for (i in range(n - 1)) { - let tmp = cur - cur += last - last = tmp - } - return cur -} - -[export] -def main() { - var f1_j = 0 - profile(20, "fibonacci loop - jit") <| $() { - f1_j = fibI_jit(6511134) - } - assert(f1_j == 1781508648) - var f3_j = 0 - profile(20, "fibonacci recursive - jit") <| $() { - f3_j = fibR_jit(31) - } - assert(f3_j == 1346269) -} - diff --git a/modules/dasLLVM/profile/mandelbrot.das b/modules/dasLLVM/profile/mandelbrot.das deleted file mode 100644 index 6007fa8f5f..0000000000 --- a/modules/dasLLVM/profile/mandelbrot.das +++ /dev/null @@ -1,213 +0,0 @@ -options gen2 -require strings -require fio -//require brainfuck_mandelbrot - -[jit, unsafe_deref, hint(hot, unsafe_alias, noalias=code, nocapture=code, noalias=tape, nocapture=tape)] -def run(code : uint8?; lengthOfCode : int; var tape : uint8?; var codePos, tapePos : int&; skip : bool) : bool { - unsafe { - if (skip) { - while (tapePos >= 0 && codePos < lengthOfCode) { - let sym = code[codePos] - if (sym == uint8('[')) { - ++codePos; - let oldPos = codePos; - while (run(code, lengthOfCode, tape, codePos, tapePos, tape[tapePos] == uint8(0))) { - codePos = oldPos; - } - } elif (sym == uint8(']')) { - return tape[tapePos] != uint8(0) - } - ++codePos - } - } else { - while (tapePos >= 0 && codePos < lengthOfCode) { - let sym = code[codePos] - if (sym == uint8('[')) { - ++codePos; - let oldPos = codePos; - while (run(code, lengthOfCode, tape, codePos, tapePos, tape[tapePos] == uint8(0))) { - codePos = oldPos; - } - ++codePos; - } elif (sym == uint8(']')) { - return tape[tapePos] != uint8(0) - } elif (sym == uint8('.')) { - print(int(tape[tapePos]) |> to_char) - ++codePos - } else { - var rep = 1 - while (code[codePos + rep] == sym) { - ++rep - } - if (sym == uint8('+')) { tape[tapePos] = uint8(int(tape[tapePos]) + rep); } elif (sym == uint8('-')) { tape[tapePos] = uint8(int(tape[tapePos]) - rep); } elif (sym == uint8('>')) { tapePos += rep; } else { tapePos -= rep; } - // elif sym == '<' { tapePos -= rep; } - codePos += rep - } - } - } - return false - } -} - -def interpret(code : string) { - let totalTime = ref_time_ticks() - var tape : array - var codePos, tapePos : int - tape |> resize(1000000) - var filteredCode <- [for (Ch in code); uint8(Ch); where Ch == '[' || Ch == ']' || Ch == '<' || Ch == '>' || Ch == '+' || Ch == '-' || Ch == '.' ] - unsafe { - run(reinterpret addr(filteredCode[0]), length(filteredCode), addr(tape[0]), codePos, tapePos, false) - } - delete filteredCode - let totalDt = double(get_time_usec(totalTime)) / 1000000.0lf - to_log(LOG_INFO, "total {totalDt} sec\n") -} - -[export] -def main { - interpret("+++++++++++++[->++>>>+++++>++>+<<<<<<]>>>>>++++++>--->>>>>>>>>>+++++++++++++++[[ ->>>>>>>>>]+[<<<<<<<<<]>>>>>>>>>-]+[>>>>>>>>[-]>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>[-]+ -<<<<<<<+++++[-[->>>>>>>>>+<<<<<<<<<]>>>>>>>>>]>>>>>>>+>>>>>>>>>>>>>>>>>>>>>>>>>> ->+<<<<<<<<<<<<<<<<<[<<<<<<<<<]>>>[-]+[>>>>>>[>>>>>>>[-]>>]<<<<<<<<<[<<<<<<<<<]>> ->>>>>[-]+<<<<<<++++[-[->>>>>>>>>+<<<<<<<<<]>>>>>>>>>]>>>>>>+<<<<<<+++++++[-[->>> ->>>>>>+<<<<<<<<<]>>>>>>>>>]>>>>>>+<<<<<<<<<<<<<<<<[<<<<<<<<<]>>>[[-]>>>>>>[>>>>> ->>[-<<<<<<+>>>>>>]<<<<<<[->>>>>>+<<+<<<+<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>> -[>>>>>>>>[-<<<<<<<+>>>>>>>]<<<<<<<[->>>>>>>+<<+<<<+<<]>>>>>>>>]<<<<<<<<<[<<<<<<< -<<]>>>>>>>[-<<<<<<<+>>>>>>>]<<<<<<<[->>>>>>>+<<+<<<<<]>>>>>>>>>+++++++++++++++[[ ->>>>>>>>>]+>[-]>[-]>[-]>[-]>[-]>[-]>[-]>[-]>[-]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>-]+[ ->+>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>->>>>[-<<<<+>>>>]<<<<[->>>>+<<<<<[->>[ --<<+>>]<<[->>+>>+<<<<]+>>>>>>>>>]<<<<<<<<[<<<<<<<<<]]>>>>>>>>>[>>>>>>>>>]<<<<<<< -<<[>[->>>>>>>>>+<<<<<<<<<]<<<<<<<<<<]>[->>>>>>>>>+<<<<<<<<<]<+>>>>>>>>]<<<<<<<<< -[>[-]<->>>>[-<<<<+>[<->-<<<<<<+>>>>>>]<[->+<]>>>>]<<<[->>>+<<<]<+<<<<<<<<<]>>>>> ->>>>[>+>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>->>>>>[-<<<<<+>>>>>]<<<<<[->>>>>+ -<<<<<<[->>>[-<<<+>>>]<<<[->>>+>+<<<<]+>>>>>>>>>]<<<<<<<<[<<<<<<<<<]]>>>>>>>>>[>> ->>>>>>>]<<<<<<<<<[>>[->>>>>>>>>+<<<<<<<<<]<<<<<<<<<<<]>>[->>>>>>>>>+<<<<<<<<<]<< -+>>>>>>>>]<<<<<<<<<[>[-]<->>>>[-<<<<+>[<->-<<<<<<+>>>>>>]<[->+<]>>>>]<<<[->>>+<< -<]<+<<<<<<<<<]>>>>>>>>>[>>>>[-<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<+>>>>>>>>>>>>> ->>>>>>>>>>>>>>>>>>>>>>>]>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>+++++++++++++++[[>>>> ->>>>>]<<<<<<<<<-<<<<<<<<<[<<<<<<<<<]>>>>>>>>>-]+>>>>>>>>>>>>>>>>>>>>>+<<<[<<<<<< -<<<]>>>>>>>>>[>>>[-<<<->>>]+<<<[->>>->[-<<<<+>>>>]<<<<[->>>>+<<<<<<<<<<<<<[<<<<< -<<<<]>>>>[-]+>>>>>[>>>>>>>>>]>+<]]+>>>>[-<<<<->>>>]+<<<<[->>>>-<[-<<<+>>>]<<<[-> ->>+<<<<<<<<<<<<[<<<<<<<<<]>>>[-]+>>>>>>[>>>>>>>>>]>[-]+<]]+>[-<[>>>>>>>>>]<<<<<< -<<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]<<<<<<<[->+>>>-<<<<]>>>>>>>>>+++++++++++++++++++ -+++++++>>[-<<<<+>>>>]<<<<[->>>>+<<[-]<<]>>[<<<<<<<+<[-<+>>>>+<<[-]]>[-<<[->+>>>- -<<<<]>>>]>>>>>>>>>>>>>[>>[-]>[-]>[-]>>>>>]<<<<<<<<<[<<<<<<<<<]>>>[-]>>>>>>[>>>>> -[-<<<<+>>>>]<<<<[->>>>+<<<+<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>>[-<<<<<<<< -<+>>>>>>>>>]>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>+++++++++++++++[[>>>>>>>>>]+>[- -]>[-]>[-]>[-]>[-]>[-]>[-]>[-]>[-]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>-]+[>+>>>>>>>>]<<< -<<<<<<[<<<<<<<<<]>>>>>>>>>[>->>>>>[-<<<<<+>>>>>]<<<<<[->>>>>+<<<<<<[->>[-<<+>>]< -<[->>+>+<<<]+>>>>>>>>>]<<<<<<<<[<<<<<<<<<]]>>>>>>>>>[>>>>>>>>>]<<<<<<<<<[>[->>>> ->>>>>+<<<<<<<<<]<<<<<<<<<<]>[->>>>>>>>>+<<<<<<<<<]<+>>>>>>>>]<<<<<<<<<[>[-]<->>> -[-<<<+>[<->-<<<<<<<+>>>>>>>]<[->+<]>>>]<<[->>+<<]<+<<<<<<<<<]>>>>>>>>>[>>>>>>[-< -<<<<+>>>>>]<<<<<[->>>>>+<<<<+<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>+>>>>>>>> -]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>->>>>>[-<<<<<+>>>>>]<<<<<[->>>>>+<<<<<<[->>[-<<+ ->>]<<[->>+>>+<<<<]+>>>>>>>>>]<<<<<<<<[<<<<<<<<<]]>>>>>>>>>[>>>>>>>>>]<<<<<<<<<[> -[->>>>>>>>>+<<<<<<<<<]<<<<<<<<<<]>[->>>>>>>>>+<<<<<<<<<]<+>>>>>>>>]<<<<<<<<<[>[- -]<->>>>[-<<<<+>[<->-<<<<<<+>>>>>>]<[->+<]>>>>]<<<[->>>+<<<]<+<<<<<<<<<]>>>>>>>>> -[>>>>[-<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> -]>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>>>[-<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<+> ->>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>++++++++ -+++++++[[>>>>>>>>>]<<<<<<<<<-<<<<<<<<<[<<<<<<<<<]>>>>>>>>>-]+[>>>>>>>>[-<<<<<<<+ ->>>>>>>]<<<<<<<[->>>>>>>+<<<<<<+<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>>>>>>[ --]>>>]<<<<<<<<<[<<<<<<<<<]>>>>+>[-<-<<<<+>>>>>]>[-<<<<<<[->>>>>+<++<<<<]>>>>>[-< -<<<<+>>>>>]<->+>]<[->+<]<<<<<[->>>>>+<<<<<]>>>>>>[-]<<<<<<+>>>>[-<<<<->>>>]+<<<< -[->>>>->>>>>[>>[-<<->>]+<<[->>->[-<<<+>>>]<<<[->>>+<<<<<<<<<<<<[<<<<<<<<<]>>>[-] -+>>>>>>[>>>>>>>>>]>+<]]+>>>[-<<<->>>]+<<<[->>>-<[-<<+>>]<<[->>+<<<<<<<<<<<[<<<<< -<<<<]>>>>[-]+>>>>>[>>>>>>>>>]>[-]+<]]+>[-<[>>>>>>>>>]<<<<<<<<]>>>>>>>>]<<<<<<<<< -[<<<<<<<<<]>>>>[-<<<<+>>>>]<<<<[->>>>+>>>>>[>+>>[-<<->>]<<[->>+<<]>>>>>>>>]<<<<< -<<<+<[>[->>>>>+<<<<[->>>>-<<<<<<<<<<<<<<+>>>>>>>>>>>[->>>+<<<]<]>[->>>-<<<<<<<<< -<<<<<+>>>>>>>>>>>]<<]>[->>>>+<<<[->>>-<<<<<<<<<<<<<<+>>>>>>>>>>>]<]>[->>>+<<<]<< -<<<<<<<<<<]>>>>[-]<<<<]>>>[-<<<+>>>]<<<[->>>+>>>>>>[>+>[-<->]<[->+<]>>>>>>>>]<<< -<<<<<+<[>[->>>>>+<<<[->>>-<<<<<<<<<<<<<<+>>>>>>>>>>[->>>>+<<<<]>]<[->>>>-<<<<<<< -<<<<<<<+>>>>>>>>>>]<]>>[->>>+<<<<[->>>>-<<<<<<<<<<<<<<+>>>>>>>>>>]>]<[->>>>+<<<< -]<<<<<<<<<<<]>>>>>>+<<<<<<]]>>>>[-<<<<+>>>>]<<<<[->>>>+>>>>>[>>>>>>>>>]<<<<<<<<< -[>[->>>>>+<<<<[->>>>-<<<<<<<<<<<<<<+>>>>>>>>>>>[->>>+<<<]<]>[->>>-<<<<<<<<<<<<<< -+>>>>>>>>>>>]<<]>[->>>>+<<<[->>>-<<<<<<<<<<<<<<+>>>>>>>>>>>]<]>[->>>+<<<]<<<<<<< -<<<<<]]>[-]>>[-]>[-]>>>>>[>>[-]>[-]>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>>>>>[-< -<<<+>>>>]<<<<[->>>>+<<<+<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>+++++++++++++++[ -[>>>>>>>>>]+>[-]>[-]>[-]>[-]>[-]>[-]>[-]>[-]>[-]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>-]+ -[>+>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>->>>>[-<<<<+>>>>]<<<<[->>>>+<<<<<[->> -[-<<+>>]<<[->>+>+<<<]+>>>>>>>>>]<<<<<<<<[<<<<<<<<<]]>>>>>>>>>[>>>>>>>>>]<<<<<<<< -<[>[->>>>>>>>>+<<<<<<<<<]<<<<<<<<<<]>[->>>>>>>>>+<<<<<<<<<]<+>>>>>>>>]<<<<<<<<<[ ->[-]<->>>[-<<<+>[<->-<<<<<<<+>>>>>>>]<[->+<]>>>]<<[->>+<<]<+<<<<<<<<<]>>>>>>>>>[ ->>>[-<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]> ->>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>[-]>>>>+++++++++++++++[[>>>>>>>>>]<<<<<<<<<-<<<<< -<<<<[<<<<<<<<<]>>>>>>>>>-]+[>>>[-<<<->>>]+<<<[->>>->[-<<<<+>>>>]<<<<[->>>>+<<<<< -<<<<<<<<[<<<<<<<<<]>>>>[-]+>>>>>[>>>>>>>>>]>+<]]+>>>>[-<<<<->>>>]+<<<<[->>>>-<[- -<<<+>>>]<<<[->>>+<<<<<<<<<<<<[<<<<<<<<<]>>>[-]+>>>>>>[>>>>>>>>>]>[-]+<]]+>[-<[>> ->>>>>>>]<<<<<<<<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>[-<<<+>>>]<<<[->>>+>>>>>>[>+>>> -[-<<<->>>]<<<[->>>+<<<]>>>>>>>>]<<<<<<<<+<[>[->+>[-<-<<<<<<<<<<+>>>>>>>>>>>>[-<< -+>>]<]>[-<<-<<<<<<<<<<+>>>>>>>>>>>>]<<<]>>[-<+>>[-<<-<<<<<<<<<<+>>>>>>>>>>>>]<]> -[-<<+>>]<<<<<<<<<<<<<]]>>>>[-<<<<+>>>>]<<<<[->>>>+>>>>>[>+>>[-<<->>]<<[->>+<<]>> ->>>>>>]<<<<<<<<+<[>[->+>>[-<<-<<<<<<<<<<+>>>>>>>>>>>[-<+>]>]<[-<-<<<<<<<<<<+>>>> ->>>>>>>]<<]>>>[-<<+>[-<-<<<<<<<<<<+>>>>>>>>>>>]>]<[-<+>]<<<<<<<<<<<<]>>>>>+<<<<< -]>>>>>>>>>[>>>[-]>[-]>[-]>>>>]<<<<<<<<<[<<<<<<<<<]>>>[-]>[-]>>>>>[>>>>>>>[-<<<<< -<+>>>>>>]<<<<<<[->>>>>>+<<<<+<<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>+>[-<-<<<<+>>>> ->]>>[-<<<<<<<[->>>>>+<++<<<<]>>>>>[-<<<<<+>>>>>]<->+>>]<<[->>+<<]<<<<<[->>>>>+<< -<<<]+>>>>[-<<<<->>>>]+<<<<[->>>>->>>>>[>>>[-<<<->>>]+<<<[->>>-<[-<<+>>]<<[->>+<< -<<<<<<<<<[<<<<<<<<<]>>>>[-]+>>>>>[>>>>>>>>>]>+<]]+>>[-<<->>]+<<[->>->[-<<<+>>>]< -<<[->>>+<<<<<<<<<<<<[<<<<<<<<<]>>>[-]+>>>>>>[>>>>>>>>>]>[-]+<]]+>[-<[>>>>>>>>>]< -<<<<<<<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>[-<<<+>>>]<<<[->>>+>>>>>>[>+>[-<->]<[->+ -<]>>>>>>>>]<<<<<<<<+<[>[->>>>+<<[->>-<<<<<<<<<<<<<+>>>>>>>>>>[->>>+<<<]>]<[->>>- -<<<<<<<<<<<<<+>>>>>>>>>>]<]>>[->>+<<<[->>>-<<<<<<<<<<<<<+>>>>>>>>>>]>]<[->>>+<<< -]<<<<<<<<<<<]>>>>>[-]>>[-<<<<<<<+>>>>>>>]<<<<<<<[->>>>>>>+<<+<<<<<]]>>>>[-<<<<+> ->>>]<<<<[->>>>+>>>>>[>+>>[-<<->>]<<[->>+<<]>>>>>>>>]<<<<<<<<+<[>[->>>>+<<<[->>>- -<<<<<<<<<<<<<+>>>>>>>>>>>[->>+<<]<]>[->>-<<<<<<<<<<<<<+>>>>>>>>>>>]<<]>[->>>+<<[ -->>-<<<<<<<<<<<<<+>>>>>>>>>>>]<]>[->>+<<]<<<<<<<<<<<<]]>>>>[-]<<<<]>>>>[-<<<<+>> ->>]<<<<[->>>>+>[-]>>[-<<<<<<<+>>>>>>>]<<<<<<<[->>>>>>>+<<+<<<<<]>>>>>>>>>[>>>>>> ->>>]<<<<<<<<<[>[->>>>+<<<[->>>-<<<<<<<<<<<<<+>>>>>>>>>>>[->>+<<]<]>[->>-<<<<<<<< -<<<<<+>>>>>>>>>>>]<<]>[->>>+<<[->>-<<<<<<<<<<<<<+>>>>>>>>>>>]<]>[->>+<<]<<<<<<<< -<<<<]]>>>>>>>>>[>>[-]>[-]>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>[-]>[-]>>>>>[>>>>>[-<<<<+ ->>>>]<<<<[->>>>+<<<+<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>>>>>>[-<<<<<+>>>>> -]<<<<<[->>>>>+<<<+<<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>+++++++++++++++[[>>>> ->>>>>]+>[-]>[-]>[-]>[-]>[-]>[-]>[-]>[-]>[-]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>-]+[>+>> ->>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>->>>>[-<<<<+>>>>]<<<<[->>>>+<<<<<[->>[-<<+ ->>]<<[->>+>>+<<<<]+>>>>>>>>>]<<<<<<<<[<<<<<<<<<]]>>>>>>>>>[>>>>>>>>>]<<<<<<<<<[> -[->>>>>>>>>+<<<<<<<<<]<<<<<<<<<<]>[->>>>>>>>>+<<<<<<<<<]<+>>>>>>>>]<<<<<<<<<[>[- -]<->>>>[-<<<<+>[<->-<<<<<<+>>>>>>]<[->+<]>>>>]<<<[->>>+<<<]<+<<<<<<<<<]>>>>>>>>> -[>+>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>->>>>>[-<<<<<+>>>>>]<<<<<[->>>>>+<<<< -<<[->>>[-<<<+>>>]<<<[->>>+>+<<<<]+>>>>>>>>>]<<<<<<<<[<<<<<<<<<]]>>>>>>>>>[>>>>>> ->>>]<<<<<<<<<[>>[->>>>>>>>>+<<<<<<<<<]<<<<<<<<<<<]>>[->>>>>>>>>+<<<<<<<<<]<<+>>> ->>>>>]<<<<<<<<<[>[-]<->>>>[-<<<<+>[<->-<<<<<<+>>>>>>]<[->+<]>>>>]<<<[->>>+<<<]<+ -<<<<<<<<<]>>>>>>>>>[>>>>[-<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<+>>>>>>>>>>>>>>>>> ->>>>>>>>>>>>>>>>>>>]>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>+++++++++++++++[[>>>>>>>> ->]<<<<<<<<<-<<<<<<<<<[<<<<<<<<<]>>>>>>>>>-]+>>>>>>>>>>>>>>>>>>>>>+<<<[<<<<<<<<<] ->>>>>>>>>[>>>[-<<<->>>]+<<<[->>>->[-<<<<+>>>>]<<<<[->>>>+<<<<<<<<<<<<<[<<<<<<<<< -]>>>>[-]+>>>>>[>>>>>>>>>]>+<]]+>>>>[-<<<<->>>>]+<<<<[->>>>-<[-<<<+>>>]<<<[->>>+< -<<<<<<<<<<<[<<<<<<<<<]>>>[-]+>>>>>>[>>>>>>>>>]>[-]+<]]+>[-<[>>>>>>>>>]<<<<<<<<]> ->>>>>>>]<<<<<<<<<[<<<<<<<<<]>>->>[-<<<<+>>>>]<<<<[->>>>+<<[-]<<]>>]<<+>>>>[-<<<< -->>>>]+<<<<[->>>>-<<<<<<.>>]>>>>[-<<<<<<<.>>>>>>>]<<<[-]>[-]>[-]>[-]>[-]>[-]>>>[ ->[-]>[-]>[-]>[-]>[-]>[-]>>>]<<<<<<<<<[<<<<<<<<<]>>>>>>>>>[>>>>>[-]>>>>]<<<<<<<<< -[<<<<<<<<<]>+++++++++++[-[->>>>>>>>>+<<<<<<<<<]>>>>>>>>>]>>>>+>>>>>>>>>+<<<<<<<< -<<<<<<[<<<<<<<<<]>>>>>>>[-<<<<<<<+>>>>>>>]<<<<<<<[->>>>>>>+[-]>>[>>>>>>>>>]<<<<< -<<<<[>>>>>>>[-<<<<<<+>>>>>>]<<<<<<[->>>>>>+<<<<<<<[<<<<<<<<<]>>>>>>>[-]+>>>]<<<< -<<<<<<]]>>>>>>>[-<<<<<<<+>>>>>>>]<<<<<<<[->>>>>>>+>>[>+>>>>[-<<<<->>>>]<<<<[->>> ->+<<<<]>>>>>>>>]<<+<<<<<<<[>>>>>[->>+<<]<<<<<<<<<<<<<<]>>>>>>>>>[>>>>>>>>>]<<<<< -<<<<[>[-]<->>>>>>>[-<<<<<<<+>[<->-<<<+>>>]<[->+<]>>>>>>>]<<<<<<[->>>>>>+<<<<<<]< -+<<<<<<<<<]>>>>>>>-<<<<[-]+<<<]+>>>>>>>[-<<<<<<<->>>>>>>]+<<<<<<<[->>>>>>>->>[>> ->>>[->>+<<]>>>>]<<<<<<<<<[>[-]<->>>>>>>[-<<<<<<<+>[<->-<<<+>>>]<[->+<]>>>>>>>]<< -<<<<[->>>>>>+<<<<<<]<+<<<<<<<<<]>+++++[-[->>>>>>>>>+<<<<<<<<<]>>>>>>>>>]>>>>+<<< -<<[<<<<<<<<<]>>>>>>>>>[>>>>>[-<<<<<->>>>>]+<<<<<[->>>>>->>[-<<<<<<<+>>>>>>>]<<<< -<<<[->>>>>>>+<<<<<<<<<<<<<<<<[<<<<<<<<<]>>>>[-]+>>>>>[>>>>>>>>>]>+<]]+>>>>>>>[-< -<<<<<<->>>>>>>]+<<<<<<<[->>>>>>>-<<[-<<<<<+>>>>>]<<<<<[->>>>>+<<<<<<<<<<<<<<[<<< -<<<<<<]>>>[-]+>>>>>>[>>>>>>>>>]>[-]+<]]+>[-<[>>>>>>>>>]<<<<<<<<]>>>>>>>>]<<<<<<< -<<[<<<<<<<<<]>>>>[-]<<<+++++[-[->>>>>>>>>+<<<<<<<<<]>>>>>>>>>]>>>>-<<<<<[<<<<<<< -<<]]>>>]<<<<.>>>>>>>>>>[>>>>>>[-]>>>]<<<<<<<<<[<<<<<<<<<]>++++++++++[-[->>>>>>>> ->+<<<<<<<<<]>>>>>>>>>]>>>>>+>>>>>>>>>+<<<<<<<<<<<<<<<[<<<<<<<<<]>>>>>>>>[-<<<<<< -<<+>>>>>>>>]<<<<<<<<[->>>>>>>>+[-]>[>>>>>>>>>]<<<<<<<<<[>>>>>>>>[-<<<<<<<+>>>>>> ->]<<<<<<<[->>>>>>>+<<<<<<<<[<<<<<<<<<]>>>>>>>>[-]+>>]<<<<<<<<<<]]>>>>>>>>[-<<<<< -<<<+>>>>>>>>]<<<<<<<<[->>>>>>>>+>[>+>>>>>[-<<<<<->>>>>]<<<<<[->>>>>+<<<<<]>>>>>> ->>]<+<<<<<<<<[>>>>>>[->>+<<]<<<<<<<<<<<<<<<]>>>>>>>>>[>>>>>>>>>]<<<<<<<<<[>[-]<- ->>>>>>>>[-<<<<<<<<+>[<->-<<+>>]<[->+<]>>>>>>>>]<<<<<<<[->>>>>>>+<<<<<<<]<+<<<<<< -<<<]>>>>>>>>-<<<<<[-]+<<<]+>>>>>>>>[-<<<<<<<<->>>>>>>>]+<<<<<<<<[->>>>>>>>->[>>> ->>>[->>+<<]>>>]<<<<<<<<<[>[-]<->>>>>>>>[-<<<<<<<<+>[<->-<<+>>]<[->+<]>>>>>>>>]<< -<<<<<[->>>>>>>+<<<<<<<]<+<<<<<<<<<]>+++++[-[->>>>>>>>>+<<<<<<<<<]>>>>>>>>>]>>>>> -+>>>>>>>>>>>>>>>>>>>>>>>>>>>+<<<<<<[<<<<<<<<<]>>>>>>>>>[>>>>>>[-<<<<<<->>>>>>]+< -<<<<<[->>>>>>->>[-<<<<<<<<+>>>>>>>>]<<<<<<<<[->>>>>>>>+<<<<<<<<<<<<<<<<<[<<<<<<< -<<]>>>>[-]+>>>>>[>>>>>>>>>]>+<]]+>>>>>>>>[-<<<<<<<<->>>>>>>>]+<<<<<<<<[->>>>>>>> --<<[-<<<<<<+>>>>>>]<<<<<<[->>>>>>+<<<<<<<<<<<<<<<[<<<<<<<<<]>>>[-]+>>>>>>[>>>>>> ->>>]>[-]+<]]+>[-<[>>>>>>>>>]<<<<<<<<]>>>>>>>>]<<<<<<<<<[<<<<<<<<<]>>>>[-]<<<++++ -+[-[->>>>>>>>>+<<<<<<<<<]>>>>>>>>>]>>>>>->>>>>>>>>>>>>>>>>>>>>>>>>>>-<<<<<<[<<<< -<<<<<]]>>>]") -} diff --git a/modules/dasLLVM/profile/max_from_1s.das b/modules/dasLLVM/profile/max_from_1s.das deleted file mode 100644 index 384148f22e..0000000000 --- a/modules/dasLLVM/profile/max_from_1s.das +++ /dev/null @@ -1,109 +0,0 @@ -options gen2 -// from https://spiiin.github.io/blog/2385889062/ - -[sideeffects] -def popcount(x) { - var temp = x - var count = 0u - while (temp != 0u) { - temp &= temp - 1u - count++ - } - return count -} - -[sideeffects] -def maxFrom1s(x) { - let count1s = popcount(x) - var res = 0u - for (i in range(count1s)) { - res++ - res <<= 1u - } - for (i in urange(31u - count1s)) {//assume 32 bits - res <<= 1u - } - return res -} - -[sideeffects] -def maxFrom1s_popcnt(x) { - let count1s = popcnt(x) - var res = 0u - for (i in range(count1s)) { - res++ - res <<= 1u - } - for (i in urange(31u - count1s)) {//assume 32 bits - res <<= 1u - } - return res -} - -[jit, sideeffects] -def popcount_jit(x) { - var temp = x - var count = 0u - while (temp != 0u) { - temp &= temp - 1u - count++ - } - return count -} - -[jit, sideeffects] -def maxFrom1s_jit(x) { - let count1s = popcount_jit(x) - var res = 0u - for (i in range(count1s)) { - res++ - res <<= 1u - } - for (i in urange(31u - count1s)) {//assume 32 bits - res <<= 1u - } - return res -} - -[jit, sideeffects] -def maxFrom1s_popcnt_jit(x) { - let count1s = popcnt(x) - var res = 0u - for (i in range(count1s)) { - res++ - res <<= 1u - } - for (i in urange(31u - count1s)) {//assume 32 bits - res <<= 1u - } - return res -} - -[export, no_jit] -def main { - verify(maxFrom1s(256u - 1u) == 0xff000000) - verify(maxFrom1s_popcnt(256u - 1u) == 0xff000000) - verify(maxFrom1s_jit(256u - 1u) == 0xff000000) - verify(maxFrom1s_popcnt_jit(256u - 1u) == 0xff000000) - profile(10, "max from 1s") <| $() { - for (i in range(100000)) { - maxFrom1s(256u - 1u)//'0xff000000' - } - } - profile(10, "max from 1s, popcnt") <| $() { - for (i in range(100000)) { - maxFrom1s_popcnt(256u - 1u)//'0xff000000' - } - } - profile(10, "max from 1s, jit") <| $() { - for (i in range(100000)) { - maxFrom1s_jit(256u - 1u)//'0xff000000' - } - } - profile(10, "max from 1s, popcnt, jit") <| $() { - for (i in range(100000)) { - maxFrom1s_popcnt_jit(256u - 1u)//'0xff000000' - } - } -} - diff --git a/modules/dasLLVM/profile/nbodies.das b/modules/dasLLVM/profile/nbodies.das deleted file mode 100644 index 013a62274e..0000000000 --- a/modules/dasLLVM/profile/nbodies.das +++ /dev/null @@ -1,116 +0,0 @@ -options gen2 -options solid_context - -require math -require daslib/unroll -//ported from https://benchmarksgame-team.pages.debian.net/benchmarksgame/program/nbody-gcc-2.html - -let { - SOLAR_MASS = 4. * PI * PI -} - -let { - DAYS_PER_YEAR = 365.24 -} - -struct body { - x : float3 - pad : float - v : float3 - mass : float -} - -var { - g_bodies = fixed_array(body( - /*sun*/ - x = float3(0, 0, 0), v = float3(0, 0, 0), mass = SOLAR_MASS), body( - /*jupiter*/ - x = float3(4.84143144246472090, -1.16032004402742839, -1.03622044471123109e-01), - v = float3(1.66007664274403694e-03 * DAYS_PER_YEAR, 7.69901118419740425e-03 * DAYS_PER_YEAR, -6.90460016972063023e-05 * DAYS_PER_YEAR), - mass = 9.54791938424326609e-04 * SOLAR_MASS), body( - /*saturn*/ - x = float3(8.34336671824457987e+00, 4.12479856412430479e+00, -4.03523417114321381e-01), - v = float3(-2.76742510726862411e-03 * DAYS_PER_YEAR, 4.99852801234917238e-03 * DAYS_PER_YEAR, 2.30417297573763929e-05 * DAYS_PER_YEAR), - mass = 2.85885980666130812e-04 * SOLAR_MASS), body( - /*uranus*/ - x = float3(1.28943695621391310e+01, -1.51111514016986312e+01, -2.23307578892655734e-01), - v = float3(2.96460137564761618e-03 * DAYS_PER_YEAR, 2.37847173959480950e-03 * DAYS_PER_YEAR, -2.96589568540237556e-05 * DAYS_PER_YEAR), - mass = 4.36624404335156298e-05 * SOLAR_MASS), body( - /*neptune*/ - x = float3(1.53796971148509165e+01, -2.59193146099879641e+01, 1.79258772950371181e-01), - v = float3(2.68067772490389322e-03 * DAYS_PER_YEAR, 1.62824170038242295e-03 * DAYS_PER_YEAR, -9.51592254519715870e-05 * DAYS_PER_YEAR), - mass = 5.15138902046611451e-05 * SOLAR_MASS - )) -} -let { - nbodies = 5 -} - -def offset_momentum(var bodies : body[5]) { - var px : float3 - for (b in bodies) { - px -= b.v * b.mass - } - bodies[0].v = px / SOLAR_MASS -} - -[hint(vec3_ldu)] -def advance(var bodies : body[5]) { - unroll <| $() { - for (i in range(nbodies)) { - var b = bodies[i] - for (j in range(i + 1, nbodies)) { - var b2 : body& = unsafe(bodies[j]) - let dx = b.x - b2.x - let inv_distance = inv_length(dx) - let mag = inv_distance * inv_distance * inv_distance - b.v -= dx * (b2.mass * mag) - b2.v += dx * (b.mass * mag) - } - b.x += b.v - bodies[i] = b - } - } -} - -def energy(var bodies : body[5]) { - var e = 0.0 - var i = 0 - for (b in bodies) { - e += 0.5 * b.mass * length_sq(b.v) - ++i - for (j in range(i, nbodies)) { - let b2 = bodies[j] - e -= (b.mass * b2.mass) / distance(b.x, b2.x) - } - } - return e -} - -def scale_bodies(scale; var bodies : body[5]) { - for (b in bodies) { - b.mass *= scale * scale - b.v *= scale - } -} - -def nbodies(n : int) { - scale_bodies(0.01, g_bodies) - for (i in range(n)) { - advance(g_bodies) - } - scale_bodies(1. / 0.01, g_bodies) -} - -[export] -def main { - offset_momentum(g_bodies) - // print("\ninitial energy {energy(g_bodies)}\n") - energy(g_bodies) - profile(10, "n-bodies jit") <| $() { - nbodies(500000) - } - // print("\nresult energy {energy(g_bodies)}\n") - energy(g_bodies) -} - diff --git a/modules/dasLLVM/profile/nbodies_scalar_double.das b/modules/dasLLVM/profile/nbodies_scalar_double.das deleted file mode 100644 index 516c9641d9..0000000000 --- a/modules/dasLLVM/profile/nbodies_scalar_double.das +++ /dev/null @@ -1,106 +0,0 @@ -options gen2 -require math - -options solid_context - -struct body { - x, y, z : double - vx, vy, vz : double - mass : double -} - -let PId = 3.141592653589793lf -let SOLAR_MASS = 4.lf * PId * PId -let DAYS_PER_YEAR = 365.24lf - -[jit] -def offset_momentum(var bodies : body[5]) { - var px, py, pz : double - for (b in bodies) { - px -= b.vx * b.mass - py -= b.vy * b.mass - pz -= b.vz * b.mass - } - bodies[0].vx = px / SOLAR_MASS - bodies[0].vy = py / SOLAR_MASS - bodies[0].vz = pz / SOLAR_MASS -} - -[jit] -def advance(dt; var bodies : body[5]) { - var i = 0 - for (b in bodies) { - ++i - for (j in range(i, length(bodies))) { - var b2 : body& = unsafe(bodies[j]) - let dx = b.x - b2.x - let dy = b.y - b2.y - let dz = b.z - b2.z - let dsq = dx * dx + dy * dy + dz * dz - let mag = dt / (dsq * sqrt(dsq)) - b.vx -= dx * (b2.mass * mag) - b.vy -= dy * (b2.mass * mag) - b.vz -= dz * (b2.mass * mag) - b2.vx += dx * (b.mass * mag) - b2.vy += dy * (b.mass * mag) - b2.vz += dz * (b.mass * mag) - } - b.x += dt * b.vx - b.y += dt * b.vy - b.z += dt * b.vz - } -} - -[jit] -def energy(var bodies : body[5]) { - var e = 0.0lf - var i = 0 - for (b in bodies) { - e += 0.5lf * b.mass * (b.vx * b.vx + b.vy * b.vy + b.vz * b.vz) - ++i - for (j in range(i, length(bodies))) { - let b2 = bodies[j] - e -= (b.mass * b2.mass) / sqrt((b.x - b2.x) * (b.x - b2.x) + (b.y - b2.y) * (b.y - b2.y) + (b.z - b2.z) * (b.z - b2.z)) - } - } - return e -} - -[jit] -def nbodies(n : int) { - for (i in range(n)) { - advance(0.01lf, g_bodies) - } -} - -var g_bodies = fixed_array(body( - /*sun*/ - mass = SOLAR_MASS), body( - /*jupiter*/ - x = 4.84143144246472090lf, y = -1.16032004402742839lf, z = -1.03622044471123109e-01lf, - vx = 1.66007664274403694e-03lf * DAYS_PER_YEAR, vy = 7.69901118419740425e-03lf * DAYS_PER_YEAR, vz = -6.90460016972063023e-05lf * DAYS_PER_YEAR, - mass = 9.54791938424326609e-04lf * SOLAR_MASS), body( - /*saturn*/ - x = 8.34336671824457987e+00lf, y = 4.12479856412430479e+00lf, z = -4.03523417114321381e-01lf, - vx = -2.76742510726862411e-03lf * DAYS_PER_YEAR, vy = 4.99852801234917238e-03lf * DAYS_PER_YEAR, vz = 2.30417297573763929e-05lf * DAYS_PER_YEAR, - mass = 2.85885980666130812e-04lf * SOLAR_MASS), body( - /*uranus*/ - x = 1.28943695621391310e+01lf, y = -1.51111514016986312e+01lf, z = -2.23307578892655734e-01lf, - vx = 2.96460137564761618e-03lf * DAYS_PER_YEAR, vy = 2.37847173959480950e-03lf * DAYS_PER_YEAR, vz = -2.96589568540237556e-05lf * DAYS_PER_YEAR, - mass = 4.36624404335156298e-05lf * SOLAR_MASS), body( - /*neptune*/ - x = 1.53796971148509165e+01lf, y = -2.59193146099879641e+01lf, z = 1.79258772950371181e-01lf, - vx = 2.68067772490389322e-03lf * DAYS_PER_YEAR, vy = 1.62824170038242295e-03lf * DAYS_PER_YEAR, vz = -9.51592254519715870e-05lf * DAYS_PER_YEAR, - mass = 5.15138902046611451e-05lf * SOLAR_MASS - )) - -[export] -def main() { - offset_momentum(g_bodies) - print("\ninitial energy {energy(g_bodies)}\n") - profile(10, "n-bodies (scalar, double) - jit") <| $() { - nbodies(500000) - } - print("\nresult energy {energy(g_bodies)}\n") - return true -} \ No newline at end of file diff --git a/modules/dasLLVM/profile/particles.das b/modules/dasLLVM/profile/particles.das deleted file mode 100644 index 3c1200fe4a..0000000000 --- a/modules/dasLLVM/profile/particles.das +++ /dev/null @@ -1,38 +0,0 @@ -options gen2 -// options log = true, log_nodes =true, print_ref = true, print_var_access = true // , log_optimization_passes = true -// options logCpp = true -// options log_nodes=true -struct NObject { - position : float3 - velocity : float3 -} - -[jit] -def testSim2I(var objects : array; count : int) { - for (i in range(count)) { - for (obj in objects) { - obj.position += obj.velocity - } - } -} - -def init(var objects : array) { - resize(objects, 50000) - var i = 0 - for (obj in objects) { - obj.position = float3(i++, i + 1, i + 2) - obj.velocity = float3(1.0, 2.0, 3.0) - } - assert(i == length(objects)) -} - -[export] -def main { - var objects : array - init(objects) - let total = 20 - profile(total, "particles kinematics") <| $() { - testSim2I(objects, 100) - } -} - diff --git a/modules/dasLLVM/profile/pathtracer.das b/modules/dasLLVM/profile/pathtracer.das deleted file mode 100644 index 908175eed3..0000000000 --- a/modules/dasLLVM/profile/pathtracer.das +++ /dev/null @@ -1,453 +0,0 @@ -options gen2 -// options log -// options logCpp -// options log_nodes - -options solid_context - -require math -require strings -require stbimage - -/* -[jit] -def reflect_jit(i,n:float3) - return i - 2.0 * n * dot(n,i) - -[jit] -def refract_jit( i,n:float3; eta:float ) - let cosi = dot(-i, n) - let cost2 = 1.0f - eta * eta * (1.0f - cosi*cosi) - let t = eta*i + ((eta*cosi - sqrt(abs(cost2))) * n) - return cost2>0. ? t : float3(0.) -*/ - -// random - -let LCG_RAND_MAX = 32767 -let LCG_IRAND_MAX_FLT = 1.0f / float(LCG_RAND_MAX) - -[jit] -def random_int4(var seed : int4&) { - //! random int4, each component is 0..32767 (LCG_RAND_MAX) - seed = int4(214013) * seed + int4(2531011) - return (seed >> 16) & int4(LCG_RAND_MAX) -} - -[jit] -def random_float4(var seed : int4&) { - //! random float4, each component is 0..1 - return float4(random_int4(seed)) * float4(LCG_IRAND_MAX_FLT) -} - -[jit] -def random_in_unit_disk(var seed : int4&) { - //! random float3 unit vector (length=1) which happens to be inside a disk R=1, Z=0 - while (true) { - let R = random_float4(seed).xy - let r = float3(R.x, R.y, 0.) - let p = float3(2.) * r - float3(1., 1., 0.) - if (length_sq(p) <= 1.0) { - return p - } - } - return float3(0.) -} - -[jit] -def random_unit_vector(var seed : int4&) { - //! random float3 unit vector (length=1.) - let zz = random_float4(seed) - let z = zz.x * 2. - 1. - let a = zz.y * (2. * PI) - let r = sqrt(1. - z * z) - var x, y : float - sincos(a, x, y) - return float3(r * x, r * y, z) -} - -[jit] -def random_in_unit_sphere(var seed : int4&) { - //! random float3 unit vector (length=1) which happens to be inside a sphere R=1 - while (true) { - let r = random_float4(seed).xyz - let p = float3(2.) * r - float3(1.) - if (length_sq(p) <= 1.0) { - return p - } - } - return float3(0.) -} - -[jit] -def random_float(var seed : int4&) { - //! random float 0..1 - return float(random_int(seed)) * LCG_IRAND_MAX_FLT -} - -[jit] -def random_seed(seed : int) { - //! constructs seed vector out of single integer seed - return int4(seed, seed + 1, seed + 2, seed + 3) -} - -[jit] -def random_int(var seed : int4&) { - //! random integer 0..32767 (LCG_RAND_MAX) - seed.x = 214013 * seed.x + 2531011 - return (seed.x >> 16) & LCG_RAND_MAX -} - -// pathtracer - -let { - DO_SAMPLES_PER_PIXEL = 32 - LIGHT_SPHERE_ID = 8 -} - -let { - kMinT = 0.001 - kMaxT = 1.0e7f - kMaxDepth = 10 -} - -var RAND_SEED : int4 - -[jit] -def schlick(cosine, ri : float) { - var r0 = (1. - ri) / (1. + ri) - var t = 1. - cosine - var t2 = t * t - return lerp(r0 * r0, 1., t2 * t2 * t) -} - -struct Sphere { - center : float3 - radius : float - radius2 : float - iRadius : float - pad1, pad2 : float -} - -struct Ray { - orig : float3 - pad1 : float - dir : float3 - pad2 : float -} - -[jit, hint(alwaysinline)] -def pointAt(ray : Ray const; t : float) { - return ray.orig + ray.dir * t -} - -struct Hit { - pos : float3 - pad : float - normal : float3 - t : float -} - -struct Camera { - origin : float3 - lowerLeftCorner : float3 - horizontal : float3 - vertical : float3 - u, v, w : float3 - lensRadius : float -} - -[jit, hint(alwaysinline)] -def Camera(lookFrom, lookAt, vup : float3; vfov, aspect, aperture, focusDist : float) { - var that : Camera - let theta = vfov * PI / 180. - let halfHeight = tan(theta / 2.) - let halfWidth = aspect * halfHeight - with (that) { - lensRadius = aperture / 2. - origin = lookFrom - w = normalize(lookFrom - lookAt) - u = normalize(cross(vup, w)) - v = cross(w, u) - lowerLeftCorner = origin - halfWidth * focusDist * u - halfHeight * focusDist * v - focusDist * w - horizontal = 2. * halfWidth * focusDist * u - vertical = 2. * halfHeight * focusDist * v - } - return that -} - -[jit, hint(alwaysinline)] -def getRay(that : Camera; s, t : float) { - with (that) { - let rd = lensRadius * random_in_unit_disk(RAND_SEED) - let offset = mad(u, rd.x, v * rd.y) - return Ray(orig = origin + offset, - dir = normalize(mad(vertical, t, mad(horizontal, s, lowerLeftCorner)) - origin - offset)) - } -} - -enum Type { - Lambert - Metal - Dielectric -} - -struct Material { - mtype : Type - albedo : float3 - emissive : float3 - roughness : float - ri : float -} - -let TOTAL_SPHERES = 9 - -var @groupshared s_Spheres : Sphere[TOTAL_SPHERES] -var @groupshared s_SphereMats : Material[TOTAL_SPHERES] - -def init_path_tracer { - s_Spheres[0] = Sphere(center = float3(0., -100.5, -1.), radius = 100., radius2 = 100.0 * 100., iRadius = 1. / 100.) - s_Spheres[1] = Sphere(center = float3(2., 0., -1.), radius = 0.5, radius2 = 0.5 * 0.5, iRadius = 1. / .5) - s_Spheres[2] = Sphere(center = float3(0., 0., -1.), radius = 0.5, radius2 = 0.5 * 0.5, iRadius = 1. / .5) - s_Spheres[3] = Sphere(center = float3(-2., 0., -1.), radius = 0.5, radius2 = 0.5 * 0.5, iRadius = 1. / .5) - s_Spheres[4] = Sphere(center = float3(2., 0., 1.), radius = 0.5, radius2 = 0.5 * 0.5, iRadius = 1. / .5) - s_Spheres[5] = Sphere(center = float3(0., 0., 1.), radius = 0.5, radius2 = 0.5 * 0.5, iRadius = 1. / .5) - s_Spheres[6] = Sphere(center = float3(-2., 0., 1.), radius = 0.5, radius2 = 0.5 * 0.5, iRadius = 1. / .5) - s_Spheres[7] = Sphere(center = float3(0.5, 1., 0.5), radius = 0.5, radius2 = 0.5 * 0.5, iRadius = 1. / .5) - s_Spheres[8] = Sphere(center = float3(-1.5, 1.5, 0.), radius = 0.3, radius2 = 0.3 * 0.3, iRadius = 1. / .3) - s_SphereMats[0] = Material(mtype = Type.Lambert, albedo = float3(0.8, 0.8, 0.8), emissive = float3(0, 0, 0), roughness = 0., ri = 0.) - s_SphereMats[1] = Material(mtype = Type.Lambert, albedo = float3(0.8, 0.4, 0.4), emissive = float3(0, 0, 0), roughness = 0., ri = 0.) - s_SphereMats[2] = Material(mtype = Type.Lambert, albedo = float3(0.4, 0.8, 0.4), emissive = float3(0, 0, 0), roughness = 0., ri = 0.) - s_SphereMats[3] = Material(mtype = Type.Metal, albedo = float3(0.4, 0.4, 0.8), emissive = float3(0, 0, 0), roughness = 0., ri = 0.) - s_SphereMats[4] = Material(mtype = Type.Metal, albedo = float3(0.4, 0.8, 0.4), emissive = float3(0, 0, 0), roughness = 0., ri = 0.) - s_SphereMats[5] = Material(mtype = Type.Metal, albedo = float3(0.4, 0.8, 0.4), emissive = float3(0, 0, 0), roughness = 0.2, ri = 0.) - s_SphereMats[6] = Material(mtype = Type.Metal, albedo = float3(0.4, 0.8, 0.4), emissive = float3(0, 0, 0), roughness = 0.6, ri = 0.) - s_SphereMats[7] = Material(mtype = Type.Dielectric, albedo = float3(0.4, 0.4, 0.4), emissive = float3(0, 0, 0), roughness = 0., ri = 1.5) - s_SphereMats[8] = Material(mtype = Type.Lambert, albedo = float3(0.8, 0.6, 0.2), emissive = float3(30, 25, 15), roughness = 0., ri = 0.) -} - -[jit, hint(unsafe_range_check)] -def hitSpheres(r : Ray const; tMin, tMax : float; var outHit : Hit) { - var hitT = tMax - var id = -1 - var i = 0 - for (sph in s_Spheres) { - let co = sph.center - r.orig - let nb = dot(co, r.dir) - let discr = mad(nb, nb, sph.radius2 - length_sq(co)) - if (discr > 0.) { - let discrSq = sqrt(discr) - var t = nb - discrSq - if (t <= tMin) { - t = nb + discrSq - } - if (t > tMin && t < hitT) { - id = i - hitT = t - } - } - ++ i - } - if (id != -1) { - let atPos = pointAt(r, hitT) - outHit = Hit(pos = atPos, - normal = (atPos - s_Spheres[id].center) * s_Spheres[id].iRadius, - t = hitT) - } - return id -} - -[jit, hint(alwaysinline)] -def hitWorld(r : Ray const; tMin, tMax : float; var outHit : Hit; var outID : int&) { - outID = r |> hitSpheres(tMin, tMax, outHit) - return outID != -1 -} - -[jit, hint(unsafe_range_check)] -def scatter(mat : Material const; r_in : Ray const; rec : Hit; var attenuation : float3&; var scattered : Ray; var outLightE : float3&; var inoutRayCount : int&) { - outLightE = float3(0) - if (mat.mtype == Type.Lambert) { - let target = rec.pos + rec.normal + random_unit_vector(RAND_SEED) - scattered = Ray(orig = rec.pos, dir = normalize(target - rec.pos)) - attenuation = mat.albedo - let sc = s_Spheres[LIGHT_SPHERE_ID].center - let sw = normalize(sc - rec.pos) - let su = normalize(cross(abs(sw.x) > 0.01 ? float3(0, 1, 0) : float3(1, 0, 0), sw)) - let sv = cross(sw, su) - let sr = s_Spheres[LIGHT_SPHERE_ID].radius - let cosAMax = sqrt(saturate(1. - sr * sr * inv_distance_sq(rec.pos, sc))) - let eps = random_float4(RAND_SEED) - let cosA = mad(eps.x, cosAMax, 1.) - eps.x - let sinA = sqrt(1. - cosA * cosA) - var sinPhi, cosPhi : float - sincos(2. * PI * eps.y, sinPhi, cosPhi) - let l = su * (cosPhi * sinA) + sv * (sinPhi * sinA) + sw * cosA - var lightHit : Hit - var hitID = 0 - ++inoutRayCount - let ray = Ray(orig = rec.pos, dir = l) - if (ray |> hitWorld(kMinT, kMaxT, lightHit, hitID) && hitID == LIGHT_SPHERE_ID) { - let nl = dot(rec.normal, r_in.dir) < 0. ? rec.normal : -rec.normal - outLightE += (mat.albedo * s_SphereMats[LIGHT_SPHERE_ID].emissive) * (saturate(dot(l, nl)) * mad(-2., cosAMax, 2.)) - } - return true - } elif (mat.mtype == Type.Metal) { - let refl = reflect(r_in.dir, rec.normal) - scattered = Ray(orig = rec.pos, dir = normalize(mad(random_in_unit_sphere(RAND_SEED), mat.roughness, refl))) - attenuation = mat.albedo - return dot(scattered.dir, rec.normal) > 0. - } elif (mat.mtype == Type.Dielectric) { - attenuation = float3(1) - var refr : float3 - var reflProb : float - let dott = dot(r_in.dir, rec.normal) - if (dot(r_in.dir, rec.normal) > 0.) {// here - refr = refract(r_in.dir, -rec.normal, mat.ri) - if (length_sq(refr) > 0.) { - reflProb = schlick(mat.ri * dot(r_in.dir, rec.normal), mat.ri) - } else { - reflProb = 1. - } - } else { - refr = refract(r_in.dir, rec.normal, 1.0 / mat.ri) - if (length_sq(refr) > 0.) { - reflProb = schlick(-dot(r_in.dir, rec.normal), mat.ri) - } else { - reflProb = 1. - } - } - if (random_float(RAND_SEED) < reflProb) { - scattered = Ray(orig = rec.pos, dir = normalize(reflect(r_in.dir, rec.normal))) - } else { - scattered = Ray(orig = rec.pos, dir = normalize(refr)) - } - } else { - attenuation = float3(1, 0, 1) - scattered = Ray(orig = float3(0.), dir = float3(0.)) - return false - } - return true -} - -[jit, hint(unsafe_range_check)] -def trace(r : Ray; var inoutRayCount : int&) { - var ray = r - var col = float3(0.) - var curAtten = float3(1.) - var doMaterialE = true - for (depth in range(kMaxDepth)) { - var rec : Hit - var id = 0 - ++inoutRayCount - if (ray |> hitWorld(kMinT, kMaxT, rec, id)) { - var scattered : Ray - var attenuation : float3 - var lightE : float3 - var matE = s_SphereMats[id].emissive - if (s_SphereMats[id] |> scatter(ray, rec, attenuation, scattered, lightE, inoutRayCount)) { - if (!doMaterialE) { - matE = float3(0) - } - doMaterialE = s_SphereMats[id].mtype != Type.Lambert - col += curAtten * (matE + lightE) - curAtten *= attenuation - ray = scattered - } else { - col += curAtten * matE - break - } - } else { - let t = mad(ray.dir, 0.5, float3(1.)) - let skyCol = lerp(0.3 * float3(1.), 0.3 * float3(0.5, 0.7, 1.0), t) - col += curAtten * skyCol - break - } - } - return col -} - -[jit, hint(unsafe_range_check)] -def trace(screenWidth, screenHeight, frameCount, ymin, ymax : int; var backbuffer : array; cam : Camera) { - let invWH = float(1) / float2(screenWidth, screenHeight) - let lerpFac = float3(float(frameCount) / float(frameCount + 1)) - var rayCount = 0 - var backbufferIdx = ymin * screenWidth - for (y in range(ymin, ymax)) { - RAND_SEED = random_seed(y * 117 + frameCount * 13) - for (x in range(screenWidth)) { - var col = float3(0) - for (s in range(DO_SAMPLES_PER_PIXEL)) { - let uv = (float2(x, y) + random_float4(RAND_SEED).xy) * invWH - col += cam |> getRay(uv.x, uv.y) |> trace(rayCount) - } - col *= 1. / float(DO_SAMPLES_PER_PIXEL) - backbuffer[backbufferIdx] = lerp(col, backbuffer[backbufferIdx], lerpFac) - backbufferIdx ++ - } - } - return rayCount -} - -[jit] -def draw(frameCount, screenWidth, screenHeight, ymin, ymax : int; var backbuffer : array; var outRayCount : int&) { - var rayCount = 0 - let lookfrom = float3(0, 2, 3) - let lookat = float3(0) - let distToFocus = 3. - let aperture = 0.1 - let cam = Camera(lookfrom, lookat, float3(0, 1, 0), 60., float(screenWidth) / float(screenHeight), aperture, distToFocus) - rayCount += trace(screenWidth, screenHeight, frameCount, ymin, ymax, backbuffer, cam) - outRayCount = rayCount -} - -def linear_to_SRGB(x : float) { - if (x <= 0.00031308) { - return 12.92 * x - } else { - return 1.055 * pow(x, (1.0 / 2.4)) - 0.055 - } -} - -def linear_to_SRGB(c : float4) { - return float4(linear_to_SRGB(c.x), linear_to_SRGB(c.y), linear_to_SRGB(c.z), c.w) -} - -def RGBA_TO_UCOLOR(xyzw : float4) { - return pack_float_to_byte(xyzw * 255.) -} - -[export] -def main { - let width = 256 - let height = 256 - let kFrameCount = 1 - var backbuffer : array - resize(backbuffer, width * height) - print("\ntracing...\n") - var i = 0 - - init_path_tracer() - // trace_ray(width, height, 132, 0) - - var t0 = ref_time_ticks() - var totalRays = 0 - draw(i, width, height, 0, height, backbuffer, totalRays) - var dt = get_time_usec(t0) - var sec = double(dt) / 1000000.0lf - print("JIT: {totalRays} in {sec} sec, {fmt(":.3f",double(totalRays)/double(dt))} mrays/sec\n") - - var pixels : array - pixels |> reserve(width * height) - for (y in range(height)) { - for (x in range(width)) { - let srgb = linear_to_SRGB(float4(backbuffer[x + (height - 1 - y) * width].xyz, 1.0f)) - pixels |> push <| RGBA_TO_UCOLOR(srgb) - } - } - let path = "{get_das_root()}/modules/dasLLVM/profile/path_tracer.png" - unsafe { - stbi_write_png(path, width, height, 4, addr(pixels[0]), width * 4) - print("image saved to {path}\n") - } -} - diff --git a/modules/dasLLVM/profile/primes.das b/modules/dasLLVM/profile/primes.das deleted file mode 100644 index 9d0d97f5ad..0000000000 --- a/modules/dasLLVM/profile/primes.das +++ /dev/null @@ -1,53 +0,0 @@ -options gen2 -[jit, sideeffects] -def isprime_jit(n : int) { - for (i in range(2, n)) { - if (n % i == 0) { - return false - } - } - return true -} - -[jit, sideeffects] -def primes_jit(n : int) { - var count = 0 - for (i in range(2, n + 1)) { - if (isprime_jit(i)) { - ++count - } - } - return count -} - -[jit, sideeffects] -def primesI_jit(n : int) { - var count = 0 - for (i in range(2, n + 1)) { - count ++ - for (j in range(2, i)) { - if (i % j == 0) { - count -- - break - } - } - } - return count -} - -[export] -def main() { - if (true) { - var f1j = 0 - profile(20, "primes loop - jit") <| $() { - f1j = primes_jit(14000) - } - assert(f1j == 1652) - var f2j = 0 - profile(20, "primes loop, inline - jit") <| $() { - f2j = primesI_jit(14000) - } - assert(f2j == 1652) - } -} - diff --git a/modules/dasLLVM/profile/sha256.das b/modules/dasLLVM/profile/sha256.das deleted file mode 100644 index e3b78e13a2..0000000000 --- a/modules/dasLLVM/profile/sha256.das +++ /dev/null @@ -1,124 +0,0 @@ -options gen2 -// options log_nodes=true -require daslib/unroll - -// options log_nodes=true - -options solid_context - -require math -require strings - -let { - primes = fixed_array( - 0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, - 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, - 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, - 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, - 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, - 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, - 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, - 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, - 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, - 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, - 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, - 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, - 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, - 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, - 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, - 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2 - ) -} - -def toHex(hash : uint[8]) { - let st = build_string() <| $(var writer) { - for (i in hash) { - format(writer, "%08x", i) - } - } - return st -} - -[jit, unsafe_deref, hint(alwaysinline, unsafe_range_check, noalias=data, noalias=hash)] -def digestBlock(data : uint?; var hash : uint[8]) { - var digest : uint[64] - for (j in range(16)) { - unsafe { - digest[j] = data[j] - } - } - unroll <| $() { - for (j in range(16, 64)) { - let v0 = digest[j - 15] - let s0 = (v0 >>> 7u) ^ (v0 >>> 18u) ^ (v0 >> 3u) - let v1 = digest[j - 2] - let s1 = (v1 >>> 17u) ^ (v1 >>> 19u) ^ (v1 >> 10u) - digest[j] = digest[j - 16] + s0 + digest[j - 7] + s1 - } - } - var a = hash[0] - var b = hash[1] - var c = hash[2] - var d = hash[3] - var e = hash[4] - var f = hash[5] - var g = hash[6] - var h = hash[7] - for (i in range(64)) { - let s0 = (a >>> 2u) ^ (a >>> 13u) ^ (a >>> 22u) - let maj = (a & b) ^ (a & c) ^ (b & c) - let t2 = s0 + maj - let s1 = (e >>> 6u) ^ (e >>> 11u) ^ (e >>> 25u) - let ch = (e & f) ^ ((~e) & g) - let t1 = h + s1 + ch + primes[i] + digest[i] - h = g - g = f - f = e - e = d + t1 - d = c - c = b - b = a - a = t1 + t2 - } - hash[0] += a - hash[1] += b - hash[2] += c - hash[3] += d - hash[4] += e - hash[5] += f - hash[6] += g - hash[7] += h -} - -[jit, unsafe_deref] -def sha256(msg : array) { - var hash = fixed_array( - 0x6a09e667, - 0xbb67ae85, - 0x3c6ef372, - 0xa54ff53a, - 0x510e527f, - 0x9b05688c, - 0x1f83d9ab, - 0x5be0cd19 - ) - let len = length(msg) / 64 - for (i in range(len)) { - unsafe { - digestBlock(reinterpret(addr(msg[i * 64])), hash) - } - } - return toHex(hash) -} - -[export] -def main { - let input <- [for (i in range(1024)); uint8('.')] - let dt = profile(20, "sha256 jit") <| $() { - for (i in range(1024)) { - sha256(input) - } - } - verify(sha256(input) == "8adcaee60bb05a9964a1df12d2f007adcb8f3fa20ff7d1ecfde0a2ac301ff412") - print("{1.0/dt} mb/sec\n") -} diff --git a/modules/dasLLVM/profile/table-sort.das b/modules/dasLLVM/profile/table-sort.das deleted file mode 100644 index 10a03f19d7..0000000000 --- a/modules/dasLLVM/profile/table-sort.das +++ /dev/null @@ -1,36 +0,0 @@ -options gen2 -// options log=true, print_var_access=true, print_ref=true - -require math - -def makeRandomSequence(var src : array) { - let n = 2000000 - let seed = 1u - resize(src, n) - for (i in range(n)) { - src[i] = int(uint_noise_1D(i, seed)) - } -} - -[jit] -def jit_sort(var tab : array) { - sort(tab, $(a, b) => !(a < b)) -} - -[export] -def main { - var tab : array - makeRandomSequence(tab) - profile(1, "table-sort") <| $() { - sort(tab) - } - makeRandomSequence(tab) - profile(1, "table-sort-cmp") <| $() { - sort(tab, $(a, b) => !(a < b)) - } - makeRandomSequence(tab) - profile(1, "table-sort-cmp JIT") <| $() { - jit_sort(tab) - } -} - diff --git a/modules/dasLLVM/profile/tree.das b/modules/dasLLVM/profile/tree.das deleted file mode 100644 index 8ac261f17f..0000000000 --- a/modules/dasLLVM/profile/tree.das +++ /dev/null @@ -1,154 +0,0 @@ -options gen2 -// this is port from https://github.com/frol/completely-unscientific-benchmarks -// naive is almost direct kotlin implementation -// regular is almost direct C++-raw implementation - -// options log_infer_passes = true -// options log = true -// options log_nodes = true - -options persistent_heap = true -options solid_context - -require daslib/random - -require jit - -struct Node { - x, y : int - left, right : Node? -} - -var { - seed : int4 = int4(1, 1, 1, 1) -} - -[jit] -def private finalize(var that : Node?& explicit -const) { - unsafe { - if (that != null) { - finalize(*that) - delete explicit that - that = null - } - } -} - -[jit] -def private finalize(var that : Node explicit) { - unsafe { - finalize(that.left) - finalize(that.right) - memzero(that) - } -} - -[jit, unsafe_deref, hint(hot)] -def merge(var lower, greater : Node?) : Node? { - if (lower == null) { - return greater - } - if (greater == null) { - return lower - } - if (lower.y < greater.y) { - lower.right = merge(lower.right, greater) - return lower - } else { - greater.left = merge(lower, greater.left) - return greater - } -} - -[jit, hint(alwaysinline, hot)] -def merge(var lower, equal, greater : Node?) : Node? { - return merge(merge(lower, equal), greater) -} - -[jit, unsafe_deref, hint(hot)] -def split(var orig : Node?; var lower : Node?&; var greaterOrEqual : Node?&; value : int) { - if (orig == null) { - lower = null - greaterOrEqual = null - } elif (orig.x < value) { - lower = orig - split(lower.right, lower.right, greaterOrEqual, value) - } else { - greaterOrEqual = orig - split(greaterOrEqual.left, lower, greaterOrEqual.left, value) - } -} - -[jit, hint(alwaysinline, hot)] -def split(var orig : Node?; var lower : Node?&; var equal : Node?&; var greater : Node?&; value : int) { - var equalOrGreater : Node? - split(orig, lower, equalOrGreater, value) - split(equalOrGreater, equal, greater, value + 1) -} - -[jit, hint(alwaysinline, hot)] -def hasValue(var mRoot : Node?&; x : int) : bool { - var lower, equal, greater : Node? - split(mRoot, lower, equal, greater, x) - let res = equal != null - mRoot = merge(lower, equal, greater) - return res -} - -[jit, hint(alwaysinline, hot)] -def random_int_jit(var seed : int4&) { - //! random integer 0..32767 (LCG_RAND_MAX) - seed.x = 214013 * seed.x + 2531011 - return (seed.x >> 16) & LCG_RAND_MAX -} - -[jit, hint(alwaysinline, hot)] -def insert(var mRoot : Node?&; x : int) { - var lower, equal, greater : Node? - split(mRoot, lower, equal, greater, x) - if (equal == null) { - equal = new Node(x = x, y = random_int_jit(seed)) - } - mRoot = merge(lower, equal, greater) -} - -[jit, hint(alwaysinline, hot)] -def erase_raw(var mRoot : Node?&; x : int) { - var lower, equal, greater : Node? - split(mRoot, lower, equal, greater, x) - mRoot = merge(lower, greater) - unsafe { - delete equal - } -} - -[jit] -def testTreeJit { - var tree : Node? - var cur = 5 - var res = 0 - for (i in range(1, 1000000)) { - let a = i % 3 - cur = (cur * 57 + 43) % 10007 - if (a == 0) { - tree |> insert(cur) - } elif (a == 1) { - tree |> erase_raw(cur) - } elif (a == 2) { - res += (tree |> hasValue(cur)) ? 1 : 0 - } - } - unsafe { - delete tree - } - return res -} - -[export] -def main { - verify(is_jit_function(@@testTreeJit)) - profile(10, "tree jit") <| $() { - testTreeJit() - } -} - From 22eb719c84f47c445b82f913608cfef15c14c32f Mon Sep 17 00:00:00 2001 From: Churkin Aleksey Date: Wed, 18 Feb 2026 01:12:42 +0300 Subject: [PATCH 4/6] build: disable dasTelegram and dasOpenAI by default `dasTelegram` and `dasOpenAI` is not tested enough and should not be enabled in default `daslang` build. Disable them by default. --- CMakeLists.txt | 2 ++ modules/dasOpenAI/CMakeLists.txt | 2 +- modules/dasTelegram/CMakeLists.txt | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 25cc895273..1c2b74ec03 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -20,12 +20,14 @@ option(DAS_BGFX_DISABLED "Disable dasBGFX (BGFX graphics API)" ON) option(DAS_XBYAK_DISABLED "Disable dasXbyak (XBYAK and ZYDIS, x86 assembly, jit)" ON) option(DAS_MINFFT_DISABLED "Disable dasMinfft (Minimal FFT library)" ON) option(DAS_AUDIO_DISABLED "Disable dasAudio (Miniaudio sound library)" ON) +option(DAS_OPENAI_DISABLED "Disable dasOpenAI (OpenAI site API)" ON) option(DAS_STDDLG_DISABLED "Disable dasStdDlg (File new,open,save etc dialogs)" OFF) option(DAS_STBIMAGE_DISABLED "Disable dasStbImage (StbImage bindings, image loading and saving)" OFF) option(DAS_STBTRUETYPE_DISABLED "Disable dasStbTrueType (StbTrueType bindings, ttf rasterization)" OFF) option(DAS_SFML_DISABLED "Disable dasSFML (SFML multimedia library)" ON) option(DAS_PUGIXML_DISABLED "Disable dasPUGIXML (xml parsing library)" ON) option(DAS_SQLITE_DISABLED "Disable dasSQLITE (sqlite3 library)" ON) +option(DAS_TELEGRAM_DISABLED "Disable dasTelegram (Telegram API bindings)" ON) option(DAS_TOOLS_DISABLED "Disable dasTools" OFF) option(DAS_AOT_EXAMPLES_DISABLED "Disable dasAOT examples" OFF) option(DAS_PROFILE_DISABLED "Disable dasProfile" OFF) diff --git a/modules/dasOpenAI/CMakeLists.txt b/modules/dasOpenAI/CMakeLists.txt index c8aeb42484..56022a1a01 100644 --- a/modules/dasOpenAI/CMakeLists.txt +++ b/modules/dasOpenAI/CMakeLists.txt @@ -1,4 +1,4 @@ -IF(NOT DAS_OPENAI_INCLUDED) +IF(NOT DAS_OPENAI_INCLUDED AND ((NOT ${DAS_LLVM_DISABLED}) OR (NOT DEFINED DAS_LLVM_DISABLED))) SET(DAS_OPENAI_INCLUDED TRUE) MESSAGE(STATUS "dasOpenAI module included.") ADD_MODULE_DAS(openai openai openai) diff --git a/modules/dasTelegram/CMakeLists.txt b/modules/dasTelegram/CMakeLists.txt index 4dd1258baf..9d8d580d3d 100644 --- a/modules/dasTelegram/CMakeLists.txt +++ b/modules/dasTelegram/CMakeLists.txt @@ -1,4 +1,4 @@ -IF(NOT DAS_TELEGRAM_INCLUDED) +IF(NOT DAS_TELEGRAM_INCLUDED AND ((NOT ${DAS_TELEGRAM_DISABLED}) OR (NOT DEFINED DAS_TELEGRAM_DISABLED))) SET(DAS_TELEGRAM_INCLUDED TRUE) MESSAGE(STATUS "dasTELEGRAM module included.") ADD_MODULE_DAS(telegram telegram tbotapi) From 49315c406590b1604fc3e2413f846658803a50b3 Mon Sep 17 00:00:00 2001 From: Boris Batkin Date: Tue, 17 Feb 2026 15:28:13 -0800 Subject: [PATCH 5/6] tables, warnings, errors - even better documentation --- .github/copilot-instructions.md | 47 +- CLAUDE.md | 47 +- daslib/array_boost.das | 4 + daslib/decs_boost.das | 2 +- daslib/linq_boost.das | 31 +- daslib/rst.das | 8 +- daslib/soa.das | 1 + doc/reflections/gen_module_examples.py | 1411 +++++++++++++++++ doc/source/reference/index.rst | 2 +- .../reference/language/lexical_structure.rst | 4 +- .../reference/language/type_mangling.rst | 134 +- doc/source/reference/tutorials/31_regex.rst | 18 +- .../integration_c_02_calling_functions.rst | 2 +- .../tutorials/integration_c_06_sandbox.rst | 18 +- .../integration_c_07_context_variables.rst | 18 +- .../tutorials/integration_c_09_aot.rst | 18 +- .../integration_cpp_02_calling_functions.rst | 22 +- .../integration_cpp_12_smart_pointers.rst | 4 +- .../tutorials/integration_cpp_16_sandbox.rst | 4 +- doc/source/stdlib/algorithm.rst | 2 - doc/source/stdlib/array_boost.rst | 21 +- doc/source/stdlib/ast.rst | 2 - doc/source/stdlib/ast_boost.rst | 4 - doc/source/stdlib/base64.rst | 4 - doc/source/stdlib/builtin.rst | 10 - doc/source/stdlib/dap.rst | 2 - doc/source/stdlib/decs.rst | 4 - doc/source/stdlib/decs_boost.rst | 2 +- doc/source/stdlib/enum_trait.rst | 2 - doc/source/stdlib/faker.rst | 2 - doc/source/stdlib/fio.rst | 2 - doc/source/stdlib/functional.rst | 6 - doc/source/stdlib/handmade/module-match.rst | 1 - doc/source/stdlib/index.rst | 2 +- doc/source/stdlib/jobque_boost.rst | 2 - doc/source/stdlib/json.rst | 2 - doc/source/stdlib/json_boost.rst | 6 - doc/source/stdlib/linked_list.rst | 6 +- doc/source/stdlib/linq.rst | 12 - doc/source/stdlib/linq_boost.rst | 28 + doc/source/stdlib/math.rst | 14 - doc/source/stdlib/math_bits.rst | 6 - doc/source/stdlib/math_boost.rst | 4 - doc/source/stdlib/rst.rst | 6 +- doc/source/stdlib/rtti.rst | 8 - doc/source/stdlib/safe_addr.rst | 6 - doc/source/stdlib/soa.rst | 1 + doc/source/stdlib/strings.rst | 6 - doc/source/stdlib/strings_boost.rst | 4 - doc/source/stdlib/temp_strings.rst | 2 - doc/source/stdlib/templates_boost.rst | 10 - doc/source/stdlib/typemacro_boost.rst | 2 - doc/source/stdlib/uriparser.rst | 2 - doc/source/stdlib/utf8_utils.rst | 6 - 54 files changed, 1710 insertions(+), 284 deletions(-) create mode 100644 doc/reflections/gen_module_examples.py diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1695298fdd..ef092a603c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -48,13 +48,15 @@ All code examples and documentation MUST use gen2 syntax (add `options gen2` at - **Braces** on all blocks — no indentation-based blocks: `def foo() { ... }`, `if (x) { ... }` - **Construction:** `new Type(field=val)` — NOT `new [[Type() field=val]]` - **Enum access:** `EnumName.EnumValue` with dot — NOT `EnumName EnumValue` without -- **Array literals:** `[1, 2, 3]` (commas, square brackets) — NOT `[[int 1; 2; 3]]` +- **Array literals:** `[1, 2, 3]` (commas, square brackets) — NOT `[[int 1; 2; 3]]`. Note: this creates a **dynamic** `array` — use `fixed_array(1, 2, 3)` for fixed-size arrays - **Struct init:** `Foo(a=1, b=2)` — NOT `[[Foo() a=1, b=2]]` - **No `[[ ]]` for `new`** — `new` always uses parentheses: `new Foo(x=1)` - **Table literals:** `{ "k" => v, "k2" => v2 }` (single braces, commas) — NOT `{{ "k" => v; "k2" => v2 }}` - **Named arguments:** `foo([name = value])` with square brackets — NOT `foo(name=value)` - **Block arguments with `<|`:** use `$()` or `@()` prefix: `defer() <| $() { ... }` — NOT `defer <| { ... }` (bare `{ }` creates a table literal) - **Lambda:** `@(args) { body }` or `@@(args) { body }` (no-capture) +- **Generator:** `$() { yield value; }` or `$ { yield value; }` — both are valid gen2 syntax +- **Tuple `=>` operator:** `a => b` creates a `tuple` — useful in LINQ, table construction, and ad-hoc pairs - **Bitfield variables** need explicit type for `.field` access and printing: `var f : MyBitfield` - **Bitfield dot access:** read with `f.flag` (returns bool), write with `f.flag = true/false` - **`typeinfo`** special syntax: `typeinfo enum_length(type)` — NOT `typeinfo(enum_length type)` @@ -110,6 +112,10 @@ All code examples and documentation MUST use gen2 syntax (add `options gen2` at - When calling `apply_template`, always capture the return value: `unsafe { expr <- apply_template(expr) <| ... }` — discarding the return loses the expression data - Iterator comprehension: `[iterator for(x in src); expression]` — semicolon separates generator from body - `to_array` (from `daslib/builtin`) converts any iterator to an array +- Lambdas CAN be stored in arrays: `var fns : array>` + `fns |> emplace() <| @(x : int) : int { return x * 2; }` — move semantics, not copy +- Blocks CANNOT be stored in containers, returned from functions, or captured — use lambdas or function pointers for those use cases +- `match`, `multi_match`, `static_match` macros (from `daslib/match.das`) handle side effects automatically — do NOT add `[sideeffects]` annotations to functions that only use match +- `[export] def main()` returns `void` — do NOT `return true` or return other values from main ## Key Directories @@ -175,6 +181,45 @@ When editing RST files in `doc/source/reference/language/`: - Use `:ref:` cross-references to link between pages (labels: `_structs`, `_classes`, `_functions`, `_statements`, `_expressions`, `_arrays`, `_tables`, `_iterators`, `_generators`, `_lambdas`, `_blocks`, `_tuples`, `_variants`, `_bitfields`, `_aliases`, `_modules`, `_options`, `_unsafe`, `_enumerations`, `_generic_programming`, `_pattern-matching`, `_comprehensions`, `_string_builder`, `_macros`, `_reification`, `_finalizers`, `_clone`, `_temporary`, `_move_copy_clone`, `_annotations`, `_program_structure`, `_type_conversions`, `_contexts`, `_locks`, `_datatypes_and_values`) - Verify examples compile: `bin/Release/daslang.exe example.das` +### RST table rules + +RST uses two table formats — **grid tables** and **simple tables**. Both are fragile: + +- **Grid tables** (`+---+---+`): Every row line must be exactly the same width as every separator line. Off-by-one spaces cause Sphinx errors. +- **Simple tables** (`=== ===`): The `=` separator defines column widths. Content in non-last columns must NOT extend past its column's `=` boundary. Headers must start at or after the column's start position (not in the gap). The gap between columns must be at least 2 spaces. +- After creating or editing any RST table, verify the file with a Sphinx build (see below). + +### Documentation workflow (REQUIRED) + +After creating or modifying any RST files, stdlib documentation, or `daslib/*.das` module doc-comments: + +1. **Regenerate stdlib docs** (if `daslib/*.das` files or `doc/reflections/das2rst.das` were changed): + ``` + bin/Release/daslang.exe doc/reflections/das2rst.das + ``` + +2. **Clean Sphinx build** — MUST delete cache; cached builds hide errors: + ``` + cd doc + Remove-Item -Recurse -Force sphinx-build # delete doctree cache + Remove-Item -Recurse -Force ../site/doc # delete HTML output + sphinx-build -b html -d sphinx-build source ../site/doc + ``` + On Linux/Mac: + ``` + cd doc + rm -rf sphinx-build ../site/doc + sphinx-build -b html -d sphinx-build source ../site/doc + ``` + +3. **Verify no new errors or warnings**: Check the build output for `ERROR` and `WARNING`. The build must introduce **no new** Sphinx errors or warnings compared to the baseline. + +**When to run the workflow:** +- New or modified RST files (language docs, tutorials, stdlib docs) +- New or modified `//!` doc-comments in `daslib/*.das` files +- Changes to `doc/reflections/das2rst.das` or `doc/reflections/rst.das` +- New public functions added to any `daslib/*.das` module (also update `group_by_regex` in `das2rst.das`) + ### Tutorial RST conventions Tutorial RST files live in `doc/source/reference/tutorials/` with companion `.das` files in `tutorials/language/`. diff --git a/CLAUDE.md b/CLAUDE.md index e31901128a..4a870005b6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,13 +48,15 @@ All code examples and documentation MUST use gen2 syntax (add `options gen2` at - **Braces** on all blocks — no indentation-based blocks: `def foo() { ... }`, `if (x) { ... }` - **Construction:** `new Type(field=val)` — NOT `new [[Type() field=val]]` - **Enum access:** `EnumName.EnumValue` with dot — NOT `EnumName EnumValue` without -- **Array literals:** `[1, 2, 3]` (commas, square brackets) — NOT `[[int 1; 2; 3]]` +- **Array literals:** `[1, 2, 3]` (commas, square brackets) — NOT `[[int 1; 2; 3]]`. Note: this creates a **dynamic** `array` — use `fixed_array(1, 2, 3)` for fixed-size arrays - **Struct init:** `Foo(a=1, b=2)` — NOT `[[Foo() a=1, b=2]]` - **No `[[ ]]` for `new`** — `new` always uses parentheses: `new Foo(x=1)` - **Table literals:** `{ "k" => v, "k2" => v2 }` (single braces, commas) — NOT `{{ "k" => v; "k2" => v2 }}` - **Named arguments:** `foo([name = value])` with square brackets — NOT `foo(name=value)` - **Block arguments with `<|`:** use `$()` or `@()` prefix: `defer() <| $() { ... }` — NOT `defer <| { ... }` (bare `{ }` creates a table literal) - **Lambda:** `@(args) { body }` or `@@(args) { body }` (no-capture) +- **Generator:** `$() { yield value; }` or `$ { yield value; }` — both are valid gen2 syntax +- **Tuple `=>` operator:** `a => b` creates a `tuple` — useful in LINQ, table construction, and ad-hoc pairs - **Bitfield variables** need explicit type for `.field` access and printing: `var f : MyBitfield` - **Bitfield dot access:** read with `f.flag` (returns bool), write with `f.flag = true/false` - **`typeinfo`** special syntax: `typeinfo enum_length(type)` — NOT `typeinfo(enum_length type)` @@ -110,6 +112,10 @@ All code examples and documentation MUST use gen2 syntax (add `options gen2` at - When calling `apply_template`, always capture the return value: `unsafe { expr <- apply_template(expr) <| ... }` — discarding the return loses the expression data - Iterator comprehension: `[iterator for(x in src); expression]` — semicolon separates generator from body - `to_array` (from `daslib/builtin`) converts any iterator to an array +- Lambdas CAN be stored in arrays: `var fns : array>` + `fns |> emplace() <| @(x : int) : int { return x * 2; }` — move semantics, not copy +- Blocks CANNOT be stored in containers, returned from functions, or captured — use lambdas or function pointers for those use cases +- `match`, `multi_match`, `static_match` macros (from `daslib/match.das`) handle side effects automatically — do NOT add `[sideeffects]` annotations to functions that only use match +- `[export] def main()` returns `void` — do NOT `return true` or return other values from main ## Key Directories @@ -175,6 +181,45 @@ When editing RST files in `doc/source/reference/language/`: - Use `:ref:` cross-references to link between pages (labels: `_structs`, `_classes`, `_functions`, `_statements`, `_expressions`, `_arrays`, `_tables`, `_iterators`, `_generators`, `_lambdas`, `_blocks`, `_tuples`, `_variants`, `_bitfields`, `_aliases`, `_modules`, `_options`, `_unsafe`, `_enumerations`, `_generic_programming`, `_pattern-matching`, `_comprehensions`, `_string_builder`, `_macros`, `_reification`, `_finalizers`, `_clone`, `_temporary`, `_move_copy_clone`, `_annotations`, `_program_structure`, `_type_conversions`, `_contexts`, `_locks`, `_datatypes_and_values`) - Verify examples compile: `bin/Release/daslang.exe example.das` +### RST table rules + +RST uses two table formats — **grid tables** and **simple tables**. Both are fragile: + +- **Grid tables** (`+---+---+`): Every row line must be exactly the same width as every separator line. Off-by-one spaces cause Sphinx errors. +- **Simple tables** (`=== ===`): The `=` separator defines column widths. Content in non-last columns must NOT extend past its column's `=` boundary. Headers must start at or after the column's start position (not in the gap). The gap between columns must be at least 2 spaces. +- After creating or editing any RST table, verify the file with a Sphinx build (see below). + +### Documentation workflow (REQUIRED) + +After creating or modifying any RST files, stdlib documentation, or `daslib/*.das` module doc-comments: + +1. **Regenerate stdlib docs** (if `daslib/*.das` files or `doc/reflections/das2rst.das` were changed): + ``` + bin/Release/daslang.exe doc/reflections/das2rst.das + ``` + +2. **Clean Sphinx build** — MUST delete cache; cached builds hide errors: + ``` + cd doc + Remove-Item -Recurse -Force sphinx-build # delete doctree cache + Remove-Item -Recurse -Force ../site/doc # delete HTML output + sphinx-build -b html -d sphinx-build source ../site/doc + ``` + On Linux/Mac: + ``` + cd doc + rm -rf sphinx-build ../site/doc + sphinx-build -b html -d sphinx-build source ../site/doc + ``` + +3. **Verify no new errors or warnings**: Check the build output for `ERROR` and `WARNING`. The build must introduce **no new** Sphinx errors or warnings compared to the baseline. + +**When to run the workflow:** +- New or modified RST files (language docs, tutorials, stdlib docs) +- New or modified `//!` doc-comments in `daslib/*.das` files +- Changes to `doc/reflections/das2rst.das` or `doc/reflections/rst.das` +- New public functions added to any `daslib/*.das` module (also update `group_by_regex` in `das2rst.das`) + ### Tutorial RST conventions Tutorial RST files live in `doc/source/reference/tutorials/` with companion `.das` files in `tutorials/language/`. diff --git a/daslib/array_boost.das b/daslib/array_boost.das index f33cc31594..0fcc0f7a0d 100644 --- a/daslib/array_boost.das +++ b/daslib/array_boost.das @@ -46,6 +46,7 @@ def private array_helper(arr : auto implicit ==const; a : auto(TT)) : array { //! creates a temporary array from the given data pointer and length //! Important requirements are: + //! //! * data pointer is valid and points to a memory block of at least lenA elements //! * each element follows the next one directly, with the stride equal to size of the element //! * data memory does not change within the lifetime of the returned array @@ -92,6 +95,7 @@ def public temp_array(var data : auto? ==const; lenA : int; a : auto(TT)) : arra def public temp_array(data : auto? ==const; lenA : int; a : auto(TT)) : array const { //! creates a temporary array from the given data pointer and length //! Important requirements are: + //! //! * data pointer is valid and points to a memory block of at least lenA elements //! * each element follows the next one directly, with the stride equal to size of the element //! * data memory does not change within the lifetime of the returned array diff --git a/daslib/decs_boost.das b/daslib/decs_boost.das index 4a138e7b6d..4aaf715e40 100644 --- a/daslib/decs_boost.das +++ b/daslib/decs_boost.das @@ -305,7 +305,7 @@ class DecsQueryMacro : AstCallMacro { //! //! In the example above structure q : Particle does not exist as a variable. Instead it is expanded into accessing individual components of the entity. //! REQURE section of the query is automatically filled with all components of the template. - //! If template prefix is not specified, prefix is taken from the name of the template (would be "Particle_"). + //! If template prefix is not specified, prefix is taken from the name of the template (would be ``Particle_``). //! Specifying empty prefix `[decs_template(prefix)]` will result in no prefix being added. //! //! Note: apart from tagging structure as a template, the macro also generates `apply_decs_template` and `remove_decs_template` functions. diff --git a/daslib/linq_boost.das b/daslib/linq_boost.das index fb6f07f4e3..7e994a635f 100644 --- a/daslib/linq_boost.das +++ b/daslib/linq_boost.das @@ -1,4 +1,4 @@ -options gen2 +options gen2 options indenting = 4 options no_unused_block_arguments = false options no_unused_function_arguments = false @@ -53,6 +53,7 @@ class private LinqWhere : AstCallMacro_LinqPred2 { //! implements _where(iterator, expression) shorthand notation //! that expands into where_(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._where(_ < 5) override predName = "where_" } @@ -62,6 +63,7 @@ class private LinqWhereToArray : AstCallMacro_LinqPred2 { //! implements _where_to_array(iterator, expression) shorthand notation //! that expands into where_to_array(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._where_to_array(_ < 5) override predName = "where_to_array" } @@ -71,6 +73,7 @@ class private LinqSelect : AstCallMacro_LinqPred2 { //! implements _select(iterator, expression) shorthand notation //! that expands into select(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._select(_ * 2) override predName = "select" } @@ -80,6 +83,7 @@ class private LinqSelectToArray : AstCallMacro_LinqPred2 { //! implements _select_to_array(iterator, expression) shorthand notation //! that expands into select_to_array(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._select_to_array(_ * 2) override predName = "select_to_array" } @@ -89,6 +93,7 @@ class private LinqMinBy : AstCallMacro_LinqPred2 { //! implements _min_by(iterator, expression) shorthand notation //! that expands into min_by(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._min_by(_.value) override predName = "min_by" } @@ -98,6 +103,7 @@ class private LinqMaxBy : AstCallMacro_LinqPred2 { //! implements _max_by(iterator, expression) shorthand notation //! that expands into max_by(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._max_by(_.value) override predName = "max_by" } @@ -107,6 +113,7 @@ class private LinqMinMaxBy : AstCallMacro_LinqPred2 { //! implements _min_max_by(iterator, expression) shorthand notation //! that expands into min_max_by(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._min_max_by(_.value) override predName = "min_max_by" } @@ -116,6 +123,7 @@ class private LinqMinMaxAverageBy : AstCallMacro_LinqPred2 { //! implements _min_max_average_by(iterator, expression) shorthand notation //! that expands into min_max_average_by(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._min_max_average_by(_.value) override predName = "min_max_average_by" } @@ -125,6 +133,7 @@ class private LinqSkipWhile : AstCallMacro_LinqPred2 { //! implements _skip_while(iterator, expression) shorthand notation //! that expands into skip_while(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._skip_while(_ < 5) override predName = "skip_while" } @@ -134,6 +143,7 @@ class private LinqTakeWhile : AstCallMacro_LinqPred2 { //! implements _take_while(iterator, expression) shorthand notation //! that expands into take_while(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._take_while(_ < 5) override predName = "take_while" } @@ -143,6 +153,7 @@ class private LinqAll : AstCallMacro_LinqPred2 { //! implements _all(iterator, expression) shorthand notation //! that expands into all(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._all(_ < 5) override predName = "all" } @@ -152,6 +163,7 @@ class private LinqAny : AstCallMacro_LinqPred2 { //! implements _any(iterator, expression) shorthand notation //! that expands into any(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._any(_ < 5) override predName = "any" } @@ -161,6 +173,7 @@ class private LinqCount : AstCallMacro_LinqPred2 { //! implements _count(iterator, expression) shorthand notation //! that expands into count(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._count(_ > 3) override predName = "count" } @@ -170,6 +183,7 @@ class private LinqUnique : AstCallMacro_LinqPred2 { //! implements _unique_by(iterator, expression) shorthand notation //! that expands into unique_by(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._unique_by(_.id) override predName = "unique_by" } @@ -179,6 +193,7 @@ class private LinqUniqueToArray : AstCallMacro_LinqPred2 { //! implements _unique_by_to_array(iterator, expression) shorthand notation //! that expands into unique_by_to_array(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._unique_by_to_array(_.id) override predName = "unique_by_to_array" } @@ -188,6 +203,7 @@ class private LinqDistinctBy : AstCallMacro_LinqPred2 { //! implements _distinct_by(iterator, expression) shorthand notation //! that expands into distinct_by(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._distinct_by(_.id) override predName = "distinct_by" } @@ -197,6 +213,7 @@ class private LinqDistinctByToArray : AstCallMacro_LinqPred2 { //! implements _distinct_by_to_array(iterator, expression) shorthand notation //! that expands into distinct_by_to_array(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._distinct_by_to_array(_.id) override predName = "distinct_by_to_array" } @@ -206,6 +223,7 @@ class private LinqOrderBy : AstCallMacro_LinqPred2 { //! implements _order_by(iterator, expression) shorthand notation //! that expands into order_by(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._order_by(_.id) override predName = "order_by" } @@ -215,6 +233,7 @@ class private LinqOrderByToArray : AstCallMacro_LinqPred2 { //! implements _order_by_to_array(iterator, expression) shorthand notation //! that expands into order_by_to_array(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._order_by_to_array(_.id) override predName = "order_by_to_array" } @@ -224,6 +243,7 @@ class private LinqOrderByDescending : AstCallMacro_LinqPred2 { //! implements _order_by_descending(iterator, expression) shorthand notation //! that expands into order_by_descending(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._order_by_descending(_.id) override predName = "order_by_descending" } @@ -233,6 +253,7 @@ class private LinqOrderByDescendingToArray : AstCallMacro_LinqPred2 { //! implements _order_by_descending_to_array(iterator, expression) shorthand notation //! that expands into order_by_descending_to_array(iterator, $(_) => expression) //! for example:: + //! //! each(foo)._order_by_descending_to_array(_.id) override predName = "order_by_descending_to_array" } @@ -243,6 +264,7 @@ class private AstCallMacro_LinqPredII2 : AstCallMacro { //! implements sequence_equal_by(i1, i2, expresion) shorthand notation //! that expands into sequence_equal_by(i1, i2, $(_) => expression) //! for example:: + //! //! each(foo1)._sequence_equal_by(each(foo2), _.id) def override visit(prog : ProgramPtr; mod : Module?; var call : smart_ptr) : ExpressionPtr { //! Visits the LINQ two-iterator predicate macro call and rewrites it with a lambda argument. @@ -266,6 +288,7 @@ class private LinqPred3 : AstCallMacro_LinqPredII2 { //! implements _sequence_equal_by(iterator1, iterator2, expression) shorthand notation //! that expands into sequence_equal_by(iterator1, iterator2, $(_) => expression) //! for example:: + //! //! each(foo1)._sequence_equal_by(each(foo2), _.id) override predName = "sequence_equal_by" } @@ -275,6 +298,7 @@ class private LinqExceptBy : AstCallMacro_LinqPredII2 { //! implements _except_by(iterator1, iterator2, expression) shorthand notation //! that expands into except_by(iterator1, iterator2, $(_) => expression) //! for example:: + //! //! each(foo1)._except_by(each(foo2), _.id) override predName = "except_by" } @@ -284,6 +308,7 @@ class private LinqExceptByToArray : AstCallMacro_LinqPredII2 { //! implements _except_by_to_array(iterator1, iterator2, expression) shorthand notation //! that expands into except_by_to_array(iterator1, iterator2, $(_) => expression) //! for example:: + //! //! each(foo1)._except_by_to_array(each(foo2), _.id) override predName = "except_by_to_array" } @@ -293,6 +318,7 @@ class private LinqIntersectBy : AstCallMacro_LinqPredII2 { //! implements _intersect_by(iterator1, iterator2, expression) shorthand notation //! that expands into intersect_by(iterator1, iterator2, $(_) => expression) //! for example:: + //! //! each(foo1)._intersect_by(each(foo2), _.id) override predName = "intersect_by" } @@ -302,6 +328,7 @@ class private LinqIntersectByToArray : AstCallMacro_LinqPredII2 { //! implements _intersect_by_to_array(iterator1, iterator2, expression) shorthand notation //! that expands into intersect_by_to_array(iterator1, iterator2, $(_) => expression) //! for example:: + //! //! each(foo1)._intersect_by_to_array(each(foo2), _.id) override predName = "intersect_by_to_array" } @@ -311,6 +338,7 @@ class private LinqUnionBy : AstCallMacro_LinqPredII2 { //! implements _union_by(iterator1, iterator2, expression) shorthand notation //! that expands into union_by(iterator1, iterator2, $(_) => expression) //! for example:: + //! //! each(foo1)._union_by(each(foo2), _.id) override predName = "union_by" } @@ -320,6 +348,7 @@ class private LinqUnionByToArray : AstCallMacro_LinqPredII2 { //! implements _union_by_to_array(iterator1, iterator2, expression) shorthand notation //! that expands into union_by_to_array(iterator1, iterator2, $(_) => expression) //! for example:: + //! //! each(foo1)._union_by_to_array(each(foo2), _.id) override predName = "union_by_to_array" } diff --git a/daslib/rst.das b/daslib/rst.das index 25ca09cc0a..e5b07392a2 100644 --- a/daslib/rst.das +++ b/daslib/rst.das @@ -902,7 +902,10 @@ def document_topic(doc_file : file; topic, content : string implicit; cb : block } } } elif (add_empty_topic) { - fwrite(doc_file, "{topic}\n\n") + // write content directly when topic file is missing, instead of raw substitution reference + if (content != "") { + fwrite(doc_file, "{content}\n\n") + } } } @@ -2062,9 +2065,6 @@ def document_functions(doc_file : file; mods : array; var groups : arra document_function(doc_file, func.mod, func.fn, 0, "", "das:function", is_overload) prev_func_name = cur_name } - if (prev_was_overload_group) { - fwrite(doc_file, "----\n\n") - } } } } diff --git a/daslib/soa.das b/daslib/soa.das index 573ef0816d..6c7921ba50 100644 --- a/daslib/soa.das +++ b/daslib/soa.das @@ -76,6 +76,7 @@ class SoaCallMacro : AstFunctionAnnotation { class SoaStructMacro : AstStructureAnnotation { //! Generates a Structure-of-Arrays layout from a regular struct. //! For a struct ``Foo`` with fields ``x : float`` and ``y : float``, generates: + //! //! * ``Foo`SOA`` — struct where every field is ``array`` //! * ``operator []`` returning ``SOA_INDEX`` proxy //! * ``length``, ``push``, ``emplace``, ``push_clone``, ``erase`` functions diff --git a/doc/reflections/gen_module_examples.py b/doc/reflections/gen_module_examples.py new file mode 100644 index 0000000000..f3d0d82144 --- /dev/null +++ b/doc/reflections/gen_module_examples.py @@ -0,0 +1,1411 @@ +"""Generate improved module documentation with compilable examples. + +Writes updated module-*.rst files in handmade/ with: +- Improved descriptions +- Compilable code examples +- Expected output comments +""" +import os + +HANDMADE = r"d:\Work\daslang\doc\source\stdlib\handmade" +EXAMPLES_DIR = r"d:\Work\daslang\doc\reflections\examples" + +# Module documentation with examples +# Format: module_name -> (description_text, require_line, example_code_or_None) +# description_text replaces everything before the require block +# example_code is appended after the require block + +MODULES = {} + +def reg(name, desc, require, example=None, after_require=""): + """Register a module doc.""" + MODULES[name] = (desc, require, example, after_require) + + +# ============ CORE LANGUAGE MODULES ============ + +reg("builtin", + """The BUILTIN module contains core runtime functions available in all daslang programs +without explicit ``require``. It includes: + +- Heap and memory management (``heap_bytes_allocated``, ``heap_report``, ``memory_report``) +- Debug output (``print``, ``debug``, ``stackwalk``) +- Panic and error handling (``panic``, ``terminate``, ``assert``) +- Pointer and memory operations (``intptr``, ``malloc``, ``free``) +- Profiling (``profile``) +- Type conversion (``string``)""", + "require builtin", + example="""\ + [export] + def main() { + print("hello, world!\\n") + assert(1 + 1 == 2) + let s = string(42) + print("string(42) = {s}\\n") + let name = "daslang" + print("welcome to {name}\\n") + var arr : array + arr |> push(10) + arr |> push(20) + print("length = {length(arr)}\\n") + print("arr[0] = {arr[0]}\\n") + } + // output: + // hello, world! + // string(42) = 42 + // welcome to daslang + // length = 2 + // arr[0] = 10 +""") + + +reg("math", + """The MATH module contains floating point math functions and constants +(trigonometry, exponentials, clamping, interpolation, noise, and vector/matrix operations). +Floating point math in general is not bit-precise: the compiler may optimize +permutations, replace divisions with multiplications, and some functions are +not bit-exact. Use ``double`` precision types when exact results are required.""", + "require math", + example="""\ + require math + + [export] + def main() { + print("sin(PI/2) = {sin(PI / 2.0)}\\n") + print("cos(0) = {cos(0.0)}\\n") + print("sqrt(16) = {sqrt(16.0)}\\n") + print("abs(-5) = {abs(-5)}\\n") + print("clamp(15, 0, 10) = {clamp(15, 0, 10)}\\n") + print("min(3, 7) = {min(3, 7)}\\n") + print("max(3, 7) = {max(3, 7)}\\n") + let v = float3(1, 0, 0) + print("length = {length(v)}\\n") + } + // output: + // sin(PI/2) = 1 + // cos(0) = 1 + // sqrt(16) = 4 + // abs(-5) = 5 + // clamp(15, 0, 10) = 10 + // min(3, 7) = 3 + // max(3, 7) = 7 + // length = 1 +""") + + +reg("strings", + """The STRINGS module implements string formatting, conversion, searching, and modification +routines. It provides functions for building strings (``build_string``), parsing +(``to_int``, ``to_float``), character classification (``is_alpha``, ``is_number``), +and low-level string manipulation.""", + "require strings", +) + +reg("rtti", + """The RTTI module exposes runtime type information and program introspection facilities. +It allows querying module structure, type declarations, function signatures, annotations, +and other compile-time metadata at runtime. Used primarily by macro libraries and +code generation tools.""", + "require rtti", +) + +reg("ast", + """The AST module provides access to the abstract syntax tree representation of daslang programs. +It defines node types for all language constructs (expressions, statements, types, functions, +structures, enumerations, etc.), visitors for tree traversal, and utilities for AST +construction and manipulation. This module is the foundation for writing macros, code +generators, and source-level program transformations.""", + "require ast", +) + +reg("fio", + """The FIO module implements file input/output and filesystem operations. +It provides functions for reading and writing files (``fopen``, ``fread``, ``fwrite``), +directory management (``mkdir``, ``dir``), path manipulation (``join_path``, +``basename``, ``dirname``), and file metadata queries (``stat``, ``file_time``).""", + "require fio", + example="""\ + require fio + + [export] + def main() { + let fname = "_test_fio_tmp.txt" + fopen(fname, "wb") <| $(f) { + fwrite(f, "hello, daslang!") + } + fopen(fname, "rb") <| $(f) { + let content = fread(f) + print("{content}\\n") + } + remove(fname) + } + // output: + // hello, daslang! +""") + + +reg("jobque", + """The JOBQUE module provides low-level job queue and threading primitives. +It includes thread-safe channels for inter-thread communication, lock boxes +for shared data access, job status tracking, and fine-grained thread +management. For higher-level job abstractions, see ``jobque_boost``.""", + "require jobque", + example="""\ + require jobque + + [export] + def main() { + with_atomic32 <| $(counter) { + counter |> set(10) + print("value = {counter |> get}\\n") + let after_inc = counter |> inc + print("after inc = {after_inc}\\n") + let after_dec = counter |> dec + print("after dec = {after_dec}\\n") + } + } + // output: + // value = 10 + // after inc = 11 + // after dec = 10 +""") + + +reg("network", + """The NETWORK module implements networking facilities including HTTP client/server +and low-level socket operations. It provides ``Server`` and ``Client`` classes +with event-driven callbacks for handling connections, requests, and responses.""", + "require network", +) + +reg("uriparser", + """The URIPARSER module provides URI parsing and manipulation based on the uriparser library. +It supports parsing URI strings into components (scheme, host, path, query, fragment), +normalization, resolution of relative URIs, and GUID generation.""", + "require uriparser", +) + +# ============ DASLIB MODULES ============ + +reg("algorithm", + """The ALGORITHM module provides array and collection manipulation algorithms including +sorting, searching, set operations, and element removal.""", + "require daslib/algorithm", + example="""\ + require daslib/algorithm + + [export] + def main() { + var arr <- [3, 1, 4, 1, 5, 9, 2, 6, 5] + sort_unique(arr) + print("sort_unique: {arr}\\n") + print("has 4: {binary_search(arr, 4)}\\n") + print("has 7: {binary_search(arr, 7)}\\n") + print("lower_bound(4): {lower_bound(arr, 4)}\\n") + reverse(arr) + print("reversed: {arr}\\n") + } + // output: + // sort_unique: [[ 1; 2; 3; 4; 5; 6; 9]] + // has 4: true + // has 7: false + // lower_bound(4): 3 + // reversed: [[ 9; 6; 5; 4; 3; 2; 1]] +""") + +reg("strings_boost", + """The STRINGS_BOOST module extends string handling with splitting, joining, +padding, character replacement, and edit distance computation.""", + "require daslib/strings_boost", + example="""\ + require daslib/strings_boost + + [export] + def main() { + let parts = split("one,two,three", ",") + print("split: {parts}\\n") + print("join: {join(parts, " | ")}\\n") + print("[{wide("hello", 10)}]\\n") + print("distance: {levenshtein_distance("kitten", "sitting")}\\n") + } + // output: + // split: [[ one; two; three]] + // join: one | two | three + // [hello ] + // distance: 3 +""") + +reg("functional", + """The FUNCTIONAL module implements lazy iterator adapters and higher-order +function utilities including ``filter``, ``map``, ``reduce``, ``fold``, +``scan``, ``flatten``, ``flat_map``, ``enumerate``, ``chain``, ``pairwise``, +``iterate``, ``islice``, ``cycle``, ``repeat``, ``sorted``, ``sum``, +``any``, ``all``, ``tap``, ``for_each``, ``find``, ``find_index``, and +``partition``.""", + "require daslib/functional", + example="""\ + require daslib/functional + + [export] + def main() { + var src <- [iterator for (x in range(6)); x] + var evens <- filter(src, @(x : int) : bool { return x % 2 == 0; }) + for (v in evens) { + print("{v} ") + } + print("\\n") + } + // output: + // 0 2 4 +""") + +reg("json", + """The JSON module implements JSON parsing and serialization. +It provides ``read_json`` for parsing JSON text into a ``JsonValue`` tree, +``write_json`` for serializing back to text, and ``JV`` helpers for constructing +JSON values from daslang types. + +See also :doc:`json_boost` for automatic struct-to-JSON conversion and the ``%json~`` reader macro.""", + "require daslib/json", + example="""\ + require daslib/json + + [export] + def main() { + let data = "[1, 2, 3]" + var error = "" + var js <- read_json(data, error) + print("json: {write_json(js)}\\n") + unsafe { + delete js + } + } + // output: + // json: [1,2,3] +""") + +reg("json_boost", + """The JSON_BOOST module extends JSON support with operator overloads for convenient +field access (``?[]``), null-coalescing (``??``), and automatic struct-to-JSON +conversion macros (``from_JsValue``, ``to_JsValue``). + +See also :doc:`json` for core JSON parsing and writing.""", + "require daslib/json_boost", + example="""\ + require daslib/json_boost + + [export] + def main() { + let data = "\\{ \\"name\\": \\"Alice\\", \\"age\\": 30 \\}" + var error = "" + var js <- read_json(data, error) + if (error == "") { + let name = js?.name ?? "?" + print("name = {name}\\n") + let age = js?.age ?? -1 + print("age = {age}\\n") + } + unsafe { + delete js + } + } + // output: + // name = Alice + // age = 30 +""") + +reg("random", + """The RANDOM module implements pseudo-random number generation using a linear +congruential generator with vectorized state (``int4``). It provides integer, +float, and vector random values, as well as geometric sampling (unit vectors, +points in spheres and disks).""", + "require daslib/random", + example="""\ + require daslib/random + + [export] + def main() { + var seed = random_seed(12345) + print("int: {random_int(seed)}\\n") + print("float: {random_float(seed)}\\n") + print("float: {random_float(seed)}\\n") + } + // output: + // int: 7584 + // float: 0.5848567 + // float: 0.78722495 +""") + +reg("base64", + """The BASE64 module implements Base64 encoding and decoding. +It provides ``base64_encode`` and ``base64_decode`` for converting between binary data +(strings or ``array``) and Base64 text representation.""", + "require daslib/base64", + example="""\ + require daslib/base64 + + [export] + def main() { + let encoded = base64_encode("Hello, daslang!") + print("encoded: {encoded}\\n") + let decoded = base64_decode(encoded) + print("decoded: {decoded.text}\\n") + } + // output: + // encoded: SGVsbG8sIGRhU2NyaXB0IQ== + // decoded: Hello, daslang! +""") + +reg("defer", + """The DEFER module implements the ``defer`` pattern — the ability to schedule cleanup +code to run at scope exit, similar to Go's ``defer``. The deferred block is moved +to the ``finally`` section of the enclosing scope at compile time.""", + "require daslib/defer", + example="""\ + require daslib/defer + + [export] + def main() { + print("start\\n") + defer() <| $() { + print("cleanup runs last\\n") + } + print("middle\\n") + } + // output: + // start + // middle + // cleanup runs last +""") + +reg("enum_trait", + """The ENUM_TRAIT module provides reflection utilities for enumerations: iterating +over all values, converting between enum values and strings, and building +lookup tables. The ``[string_to_enum]`` annotation generates a string constructor +for the annotated enum type.""", + "require daslib/enum_trait", + example="""\ + require daslib/enum_trait + + enum Color { + red + green + blue + } + + [export] + def main() { + print("{Color.green}\\n") + let c = to_enum(type, "blue") + print("{c}\\n") + let bad = to_enum(type, "purple", Color.red) + print("fallback = {bad}\\n") + } + // output: + // green + // blue + // fallback = red +""") + +reg("safe_addr", + """The SAFE_ADDR module provides compile-time checked pointer operations. +``safe_addr`` returns a temporary pointer to a variable only if the compiler +can verify the pointer will not outlive its target. This prevents dangling +pointer bugs without runtime overhead.""", + "require daslib/safe_addr", +) + +reg("array_boost", + """The ARRAY_BOOST module extends array operations with temporary array views +over fixed-size arrays and C++ handled vectors, emptiness checks, sub-array +views, and arithmetic operators on fixed-size arrays.""", + "require daslib/array_boost", +) + +reg("match", + """The MATCH module implements pattern matching on variants, structs, tuples, +arrays, and scalar values. Supports variable capture, wildcards, guard +expressions, and alternation. ``static_match`` enforces exhaustive matching +at compile time.""", + "require daslib/match", + example="""\ + require daslib/match + + enum Color { + red + green + blue + } + + def describe(c : Color) : string { + match (c) { + if (Color.red) { return "red"; } + if (Color.green) { return "green"; } + if (_) { return "other"; } + } + return "?" + } + + [export] + def main() { + print("{describe(Color.red)}\\n") + print("{describe(Color.green)}\\n") + print("{describe(Color.blue)}\\n") + } + // output: + // red + // green + // other +""") + +reg("linq", + """The LINQ module provides query-style operations on sequences: filtering +(``where_``), projection (``select``), sorting (``order``, ``order_by``), +deduplication (``distinct``), pagination (``skip``, ``take``), aggregation +(``sum``, ``average``, ``aggregate``), and element access (``first``, ``last``). + +See also :doc:`linq_boost` for pipe-syntax macros with underscore shorthand.""", + "require daslib/linq", + example="""\ + require daslib/linq + + [export] + def main() { + var src <- [iterator for (x in range(10)); x] + var evens <- where_(src, $(x : int) : bool { return x % 2 == 0; }) + for (v in evens) { + print("{v} ") + } + print("\\n") + } + // output: + // 0 2 4 6 8 +""") + +reg("linq_boost", + """The LINQ_BOOST module extends LINQ with pipe-friendly macros using underscore +syntax for inline predicates and selectors. Expressions like +``arr |> _where(_ > 3) |> _select(_ * 2)`` provide concise functional pipelines. + +See also :doc:`linq` for the full set of query operations.""", + "require daslib/linq_boost", + example="""\ + require daslib/linq + require daslib/linq_boost + + [export] + def main() { + var src <- [iterator for (x in range(10)); x] + var evens <- _where(src, _ % 2 == 0) + for (v in evens) { + print("{v} ") + } + print("\\n") + } + // output: + // 0 2 4 6 8 +""") + +reg("math_boost", + """The MATH_BOOST module adds geometric types (``AABB``, ``AABR``, ``Ray``), +angle conversion (``degrees``, ``radians``), intersection tests, color space +conversion (``linear_to_SRGB``, ``RGBA_TO_UCOLOR``), and view/projection +matrix construction (``look_at_lh``, ``perspective_rh``).""", + "require daslib/math_boost", + example="""\ + require daslib/math_boost + + [export] + def main() { + print("degrees(PI) = {degrees(PI)}\\n") + print("radians(180) = {radians(180.0)}\\n") + var box = AABB(min = float3(0), max = float3(10)) + print("box = ({box.min}) - ({box.max})\\n") + } + // output: + // degrees(PI) = 180 + // radians(180) = 3.1415927 + // box = (0,0,0) - (10,10,10) +""") + +reg("contracts", + """The CONTRACTS module provides compile-time type constraints for generic function +arguments. Annotations like ``[expect_any_array]``, ``[expect_any_enum]``, +``[expect_any_numeric]``, and ``[expect_any_struct]`` restrict which types +can instantiate a generic parameter, producing clear error messages on mismatch.""", + "require daslib/contracts", + example="""\ + require daslib/contracts + + [!expect_dim(a)] + def process(a) { + return "scalar" + } + + [expect_dim(a)] + def process(a) { + return "array" + } + + [export] + def main() { + var arr : int[3] + print("{process(42)}\\n") + print("{process(arr)}\\n") + } + // output: + // scalar + // array +""") + +reg("static_let", + """The STATIC_LET module implements the ``static_let`` pattern — local variables +that persist across function calls, similar to C ``static`` variables. The +variable is initialized once on first call and retains its value in subsequent +invocations.""", + "require daslib/static_let", + example="""\ + require daslib/static_let + + def counter() : int { + static_let <| $() { + var count = 0 + } + count ++ + return count + } + + [export] + def main() { + print("{counter()}\\n") + print("{counter()}\\n") + print("{counter()}\\n") + } + // output: + // 1 + // 2 + // 3 +""") + +reg("sort_boost", + """The SORT_BOOST module provides the ``qsort`` macro that uniformly sorts +built-in arrays, dynamic arrays, and C++ handled vectors using the same +syntax. It automatically wraps handled types in ``temp_array`` as needed.""", + "require daslib/sort_boost", +) + +reg("unroll", + """The UNROLL module implements compile-time loop unrolling. The ``unroll`` +macro replaces a ``for`` loop with a constant ``range`` bound by stamping +out each iteration as separate inlined code, eliminating loop overhead.""", + "require daslib/unroll", + example="""\ + require daslib/unroll + + [export] + def main() { + unroll <| $() { + for (i in range(4)) { + print("step {i}\\n") + } + } + } + // output: + // step 0 + // step 1 + // step 2 + // step 3 +""") + +reg("lpipe", + """The LPIPE module provides the ``lpipe`` macro for passing multiple block +arguments to a single function call. While ``<|`` handles the first block +argument, ``lpipe`` adds subsequent blocks on following lines.""", + "require daslib/lpipe", + example="""\ + require daslib/lpipe + + def take2(a, b : block) { + invoke(a) + invoke(b) + } + + [export] + def main() { + take2() <| $() { + print("first\\n") + } + lpipe <| $() { + print("second\\n") + } + } + // output: + // first + // second +""") + +reg("if_not_null", + """The IF_NOT_NULL module provides a null-safe call macro. The expression +``ptr |> if_not_null <| call(args)`` expands to a null check followed by +a dereferenced call: ``if (ptr != null) { call(*ptr, args) }``.""", + "require daslib/if_not_null", +) + +reg("stringify", + """The STRINGIFY module provides the ``%stringify~`` reader macro for embedding +multi-line string literals verbatim. Text between ``%stringify~`` and ``%%`` +is captured as-is without requiring escape sequences for quotes, braces, +or other special characters.""", + "require daslib/stringify", +) + +reg("coroutines", + """The COROUTINES module provides coroutine infrastructure including the +``[coroutine]`` function annotation, ``yield_from`` for delegating to +sub-coroutines, and ``co_await`` for composing asynchronous generators. +Coroutines produce values lazily via ``yield`` and can be iterated with +``for``.""", + "require daslib/coroutines", + example="""\ + require daslib/coroutines + + [coroutine] + def fibonacci() : int { + var a = 0 + var b = 1 + while (true) { + yield a + let next = a + b + a = b + b = next + } + } + + [export] + def main() { + var count = 0 + for (n in fibonacci()) { + print("{n} ") + count ++ + if (count >= 10) { + break + } + } + print("\\n") + } + // output: + // 0 1 1 2 3 5 8 13 21 34 +""") + +reg("archive", + """The ARCHIVE module implements general-purpose serialization infrastructure. +It provides the ``Archive`` type and ``serialize`` functions for reading and +writing binary data. Custom types are supported by implementing ``serialize`` +for each type.""", + "require daslib/archive", + example="""\ + require daslib/archive + + struct Foo { + a : float + b : string + } + + [export] + def main() { + var original = Foo(a = 3.14, b = "hello") + var data <- mem_archive_save(original) + var loaded : Foo + data |> mem_archive_load(loaded) + delete data + print("a = {loaded.a}, b = {loaded.b}\\n") + } + // output: + // a = 3.14, b = hello +""", + after_require="""\ +To correctly support serialization of the specific type, you need to define and +implement ``serialize`` method for it. +For example this is how DECS implements component serialization: :: + + def public serialize ( var arch:Archive; var src:Component ) + arch |> serialize(src.name) + arch |> serialize(src.hash) + arch |> serialize(src.stride) + arch |> serialize(src.info) + invoke(src.info.serializer, arch, src.data) +""") + +reg("apply", + """The APPLY module provides the ``apply`` macro for iterating over struct, tuple, +and variant fields at compile time. Each field is visited with its name and +a reference to its value, enabling generic per-field operations like +serialization, printing, and validation.""", + "require daslib/apply", + example="""\ + require daslib/apply + + struct Foo { + a : int + b : float + c : string + } + + [export] + def main() { + var foo = Foo(a = 42, b = 3.14, c = "hello") + apply(foo) <| $(name, field) { + print("{name} = {field}\\n") + } + } + // output: + // a = 42 + // b = 3.14 + // c = hello +""") + +reg("apply_in_context", + """The APPLY_IN_CONTEXT module extends apply operations to work across +different execution contexts, enabling cross-context function invocation +with packed arguments.""", + "require daslib/apply_in_context", +) + +reg("ast_block_to_loop", + """The AST_BLOCK_TO_LOOP module provides an AST transformation macro that +converts block-based iteration patterns into explicit loop constructs. +Used internally by other macro libraries for optimization.""", + "require daslib/ast_block_to_loop", +) + +reg("ast_boost", + """The AST_BOOST module provides high-level utilities for working with the AST. +It includes helpers for creating expressions, types, and declarations, +quote-based AST construction, and common AST query and transformation +patterns used by macro authors.""", + "require daslib/ast_boost", +) + +reg("ast_used", + """The AST_USED module implements analysis passes that determine which AST nodes +are actually used in the program. This information is used for dead code +elimination, tree shaking, and optimizing generated output.""", + "require daslib/ast_used", +) + +reg("async_boost", + """The ASYNC_BOOST module implements an async/await pattern for daslang using +channels and coroutines. It provides ``async`` for launching concurrent tasks +and ``await`` for waiting on their results, built on top of the job queue +infrastructure.""", + "require daslib/async_boost", +) + +reg("bitfield_boost", + """The BITFIELD_BOOST module provides utility macros for working with bitfield types +including conversion between bitfield values and strings, and iteration over +set bits.""", + "require daslib/bitfield_boost", +) + +reg("bitfield_trait", + """The BITFIELD_TRAIT module implements reflection utilities for bitfield types: +converting bitfield values to and from human-readable strings, iterating +over individual set bits, and constructing bitfield values from string names.""", + "require daslib/bitfield_trait", +) + +reg("bool_array", + """The BOOL_ARRAY module provides a compact boolean array implementation using +bit-packing. Each boolean value uses a single bit instead of a byte, +providing an 8x memory reduction compared to ``array``.""", + "require daslib/bool_array", +) + +reg("class_boost", + """The CLASS_BOOST module provides macros for extending class functionality, +including the ``[serialize_as_class]`` annotation for automatic serialization +and common class patterns like abstract method enforcement.""", + "require daslib/class_boost", +) + +reg("constant_expression", + """The CONSTANT_EXPRESSION module provides the ``[constant_expression]`` function +annotation. Functions marked with this annotation are evaluated at compile +time when all arguments are constants, replacing the call with the computed +result.""", + "require daslib/constant_expression", +) + +reg("consume", + """The CONSUME module implements the ``consume`` pattern, which moves ownership +of containers and other moveable values while leaving the source in a +default-constructed state. This enables efficient ownership transfer.""", + "require daslib/consume", +) + +reg("cpp_bind", + """The CPP_BIND module provides utilities for generating daslang bindings +to C++ code. It helps generate module registration code, type annotations, +and function wrappers for exposing C++ APIs to daslang programs.""", + "require daslib/cpp_bind", +) + +reg("cuckoo_hash_table", + """The CUCKOO_HASH_TABLE module implements a cuckoo hash table data structure. +Cuckoo hashing provides worst-case O(1) lookup time by using multiple hash +functions and displacing existing entries on collision.""", + "require daslib/cuckoo_hash_table", +) + +reg("dap", + """The DAP module implements the Debug Adapter Protocol (DAP) for integrating +daslang with external debuggers. It provides the message types, serialization, +and communication infrastructure needed for IDE debugging support.""", + "require daslib/dap", +) + +reg("das_source_formatter", + """The DAS_SOURCE_FORMATTER module implements source code formatting for daslang. +It can parse and re-emit daslang source code with consistent indentation, +spacing, and line breaking rules. Used by editor integrations and code +quality tools.""", + "require daslib/das_source_formatter", +) + +reg("das_source_formatter_fio", + """The DAS_SOURCE_FORMATTER_FIO module extends the source formatter with file I/O +capabilities, enabling formatting of daslang source files on disk. +It reads, formats, and writes back source files in place or to new locations.""", + "require daslib/das_source_formatter_fio", +) + +reg("debug_eval", + """The DEBUG_EVAL module provides runtime expression evaluation for debugging +purposes. It can evaluate daslang expressions in the context of a running +program, supporting variable inspection and interactive debugging.""", + "require daslib/debug_eval", +) + +reg("decs", + """The DECS module implements a Data-oriented Entity Component System. +Entities are identified by integer IDs and store components as typed data. +Systems query and process entities by their component signatures, +enabling cache-friendly batch processing of game objects.""", + "require daslib/decs", +) + +reg("decs_boost", + """The DECS_BOOST module provides convenience macros and syntactic sugar for +the DECS entity component system, including simplified component registration, +entity creation, and system definition patterns. + +See also :doc:`decs` for the core ECS runtime and :doc:`decs_state` for entity state machines.""", + "require daslib/decs_boost", + example="""\ + options persistent_heap = true + require daslib/decs_boost + + [export] + def main() { + restart() + create_entity <| @(eid, cmp) { + cmp |> set("pos", float3(1, 2, 3)) + cmp |> set("name", "hero") + } + commit() + query <| $(pos : float3; name : string) { + print("{name} at {pos}\\n") + } + } + // output: + // hero at 1,2,3 +""") + +reg("decs_state", + """The DECS_STATE module extends DECS with state machine support for entities. +It provides state transition management, allowing entities to change behavior +based on their current state. + +See also :doc:`decs` for the core ECS runtime and :doc:`decs_boost` for query macros.""", + "require daslib/decs_state", +) + +reg("dynamic_cast_rtti", + """The DYNAMIC_CAST_RTTI module implements runtime dynamic casting between class +types using RTTI information. It provides safe downcasting with null results +on type mismatch, similar to C++ ``dynamic_cast``.""", + "require daslib/dynamic_cast_rtti", +) + +reg("export_constructor", + """The EXPORT_CONSTRUCTOR module provides the ``[export_constructor]`` annotation +for struct types. Annotated structs automatically generate an exported +constructor function that can be called from other modules or from C++ code.""", + "require daslib/export_constructor", +) + +reg("faker", + """Random test-data generator. + +The ``Faker`` struct produces random values for every built-in type +(integers, floats, vectors, strings, dates, booleans) using +configurable ranges. Used by ``fuzzer`` for fuzz testing.""", + "require daslib/faker", +) + +reg("flat_hash_table", + """The FLAT_HASH_TABLE module implements a flat (open addressing) hash table. +It stores all entries in a single contiguous array, providing cache-friendly +access patterns and good performance for small to medium-sized tables.""", + "require daslib/flat_hash_table", + example="""\ + require daslib/flat_hash_table public + + typedef IntMap = TFlatHashTable + + [export] + def main() { + var m <- IntMap() + m[1] = "one" + m[2] = "two" + m[3] = "three" + print("length = {m.data_length}\\n") + print("m[2] = {m[2]}\\n") + m.clear() + print("after clear: {m.data_length}\\n") + } + // output: + // length = 3 + // m[2] = two + // after clear: 0 +""") + +reg("fuzzer", + """The FUZZER module implements fuzz testing infrastructure for daslang programs. +It generates random inputs for functions and verifies they do not crash or +produce unexpected errors, helping discover edge cases and robustness issues.""", + "require daslib/fuzzer", +) + +reg("generic_return", + """The GENERIC_RETURN module provides the ``[generic_return]`` annotation that +allows generic functions to automatically deduce their return type from +the body. This simplifies writing generic utility functions by eliminating +explicit return type specifications.""", + "require daslib/generic_return", +) + +reg("instance_function", + """The INSTANCE_FUNCTION module provides the ``[instance_function]`` annotation +for creating bound method-like functions. It captures the ``self`` reference +at call time, enabling object-oriented dispatch patterns in daslang.""", + "require daslib/instance_function", +) + +reg("interfaces", + """The INTERFACES module implements interface-based polymorphism for daslang. +It provides the ``[interface]`` annotation for defining abstract interfaces +with virtual method tables, supporting multiple implementations and dynamic +dispatch without class inheritance.""", + "require daslib/interfaces", + example="""\ + require daslib/interfaces + + [interface] + class IGreeter { + def abstract greet(name : string) : string + } + + class MyGreeter { + def greet(name : string) : string { + return "Hello, {name}!" + } + } + + [export] + def main() { + var obj = new MyGreeter() + print("{obj->greet("world")}\\n") + unsafe { + delete obj + } + } + // output: + // Hello, world! +""") + +reg("is_local", + """The IS_LOCAL module provides compile-time checks for whether a variable +is locally allocated (on the stack) versus heap-allocated. This enables +writing generic code that optimizes differently based on allocation strategy.""", + "require daslib/is_local", +) + +reg("jobque_boost", + """The JOBQUE_BOOST module provides high-level job queue abstractions built on +the low-level ``jobque`` primitives. It includes ``with_job``, ``with_job_status``, +and channel-based patterns for simplified concurrent programming. + +See also :doc:`jobque` for the low-level job queue primitives.""", + "require daslib/jobque_boost", + example="""\ + require daslib/jobque_boost + + [export] + def main() { + with_job_status(1) <| $(status) { + new_thread <| @() { + print("from thread\\n") + status |> notify_and_release() + } + status |> join() + print("thread done\\n") + } + } + // output: + // from thread + // thread done +""") + +reg("linked_list", + """The LINKED_LIST module implements intrusive linked list data structures. +Elements contain embedded next/prev pointers, avoiding separate node +allocations. Useful for implementing queues, work lists, and other +dynamic collections with O(1) insertion and removal.""", + "require daslib/linked_list", +) + +reg("lint", + """The LINT module implements static analysis checks for daslang code. +It provides customizable lint rules that detect common mistakes, style +violations, and potential bugs at compile time. + +See also :doc:`lint_everything` for applying lint diagnostics to all modules.""", + "require daslib/lint", +) + +reg("macro_boost", + """The MACRO_BOOST module provides utility macros for macro authors, including +pattern matching on AST nodes, code generation helpers, and common +transformation patterns used when writing compile-time code.""", + "require daslib/macro_boost", +) + +reg("math_bits", + """The MATH_BITS module provides bit manipulation functions for floating point +numbers, including type punning between integer and float representations, +and efficient integer math operations like ``int_bits_to_float`` and +``float_bits_to_int``.""", + "require daslib/math_bits", + example="""\ + require daslib/math_bits + + [export] + def main() { + let f = uint_bits_to_float(0x3F800000u) + print("uint_bits_to_float(0x3F800000) = {f}\\n") + let back = float_bits_to_uint(1.0) + print("float_bits_to_uint(1.0) = {back}\\n") + } + // output: + // uint_bits_to_float(0x3F800000) = 1 + // float_bits_to_uint(1.0) = 0x3f800000 +""") + +reg("profiler", + """The PROFILER module provides CPU profiling infrastructure for measuring +function execution times. It includes instrumentation-based profiling with +hierarchical call tracking and timing statistics. + +See also :doc:`profiler_boost` for cross-context profiler control and scoped timing macros.""", + "require daslib/profiler", +) + +reg("profiler_boost", + """The PROFILER_BOOST module extends profiling with high-level macros for +scoped timing (``profile_block``), function-level profiling annotations, +and formatted output of profiling results. + +See also :doc:`profiler` for the core profiling infrastructure.""", + "require daslib/profiler_boost", +) + +reg("quote", + """The QUOTE module provides quasiquotation support for AST construction. +It allows building AST nodes using daslang syntax with ``$``-prefixed +splice points for inserting computed values, making macro writing more +readable and less error-prone than manual AST construction.""", + "require daslib/quote", +) + +reg("refactor", + """The REFACTOR module implements automated code refactoring transformations. +It provides tools for renaming symbols, extracting functions, and other +structural code changes that preserve program semantics.""", + "require daslib/refactor", +) + +reg("regex", + """The REGEX module implements regular expression matching and searching. +It provides ``regex_compile`` for building patterns, ``regex_match`` for +full-string matching, ``regex_search`` for finding the first match anywhere, +``regex_foreach`` for iterating all matches, ``regex_replace`` for substitution, +``regex_split`` for splitting strings, ``regex_match_all`` for collecting all +match ranges, ``regex_group`` for capturing groups by index, and +``regex_group_by_name`` for named group lookup. + +Supported syntax: + +- ``.`` — any character +- ``^`` — beginning of string (or offset position) +- ``$`` — end of string +- ``+`` — one or more (greedy) +- ``*`` — zero or more (greedy) +- ``?`` — zero or one (greedy) +- ``+?`` — one or more (lazy) +- ``*?`` — zero or more (lazy) +- ``??`` — zero or one (lazy) +- ``{n}`` — exactly *n* repetitions +- ``{n,}`` — *n* or more (greedy) +- ``{n,m}`` — between *n* and *m* (greedy) +- ``{n}?`` ``{n,}?`` ``{n,m}?`` — counted repetitions (lazy) +- ``(...)`` — capturing group +- ``(?:...)`` — non-capturing group +- ``(?P...)`` — named capturing group +- ``|`` — alternation +- ``[abc]``, ``[a-z]``, ``[^abc]`` — character sets (negated with ``^``) +- ``\\w`` ``\\W`` — word / non-word characters +- ``\\d`` ``\\D`` — digit / non-digit characters +- ``\\s`` ``\\S`` — whitespace / non-whitespace characters +- ``\\b`` ``\\B`` — word boundary / non-boundary assertions +- ``\\t`` ``\\n`` ``\\r`` ``\\f`` ``\\v`` — whitespace escapes +- ``\\xHH`` — hexadecimal character escape +- ``\\.`` ``\\+`` ``\\*`` ``\\(`` ``\\)`` ``\\[`` ``\\]`` ``\\|`` ``\\\\`` ``\\^`` ``\\{`` ``\\}`` — escaped metacharacters + +The engine is ASCII-only (256-bit ``CharSet``). Matching is anchored — ``regex_match`` tests from +position 0 (or the given offset) and does NOT search; use ``regex_search`` to find the first +occurrence, or ``regex_foreach`` / ``regex_match_all`` to find all occurrences. + +See also :doc:`regex_boost` for compile-time regex construction via the ``%regex~`` reader macro.""", + "require daslib/regex", + example="""\ + require daslib/regex + require strings + + [export] + def main() { + var re <- regex_compile("[0-9]+") + let m = regex_match(re, "123abc") + print("match length = {m}\\n") + let text = "age 25, height 180" + regex_foreach(re, text) <| $(r) { + print("found: {slice(text, r.x, r.y)}\\n") + return true + } + } + // output: + // match length = 3 + // found: 25 + // found: 180 +""") + +reg("regex_boost", + """The REGEX_BOOST module extends regular expressions with the ``%regex~`` reader +macro for compile-time regex construction. Inside the reader macro, backslashes are +literal — no double-escaping is needed (e.g. ``%regex~\\d{3}%%`` instead of +``"\\\\d\\{3}"``). + +See :doc:`regex` for the full list of supported syntax.""", + "require daslib/regex_boost", + example="""\ + require daslib/regex_boost + require strings + + [export] + def main() { + var inscope re <- %regex~\\d+%% + let m = regex_match(re, "123abc") + print("match length = {m}\\n") + let text = "age 25, height 180" + regex_foreach(re, text) <| $(r) { + print("found: {slice(text, r.x, r.y)}\\n") + return true + } + } + // output: + // match length = 3 + // found: 25 + // found: 180 +""") + +reg("remove_call_args", + """The REMOVE_CALL_ARGS module provides AST transformation macros that remove +specific arguments from function calls at compile time. Used for implementing +optional parameter patterns and compile-time argument stripping.""", + "require daslib/remove_call_args", +) + +reg("rst", + """The RST module implements the documentation generation pipeline for daslang. +It uses RTTI to introspect modules, types, and functions, then produces +reStructuredText output suitable for Sphinx documentation builds.""", + "require daslib/rst", +) + +reg("soa", + """The SOA (Structure of Arrays) module transforms array-of-structures data layouts +into structure-of-arrays layouts for better cache performance. It provides macros +that generate parallel arrays for each field of a structure, enabling SIMD-friendly +data access patterns.""", + "require daslib/soa", +) + +reg("temp_strings", + """The TEMP_STRINGS module provides temporary string construction that avoids heap +allocations. Temporary strings are allocated on the stack or in scratch memory +and are valid only within the current scope, offering fast string building +for formatting and output.""", + "require daslib/temp_strings", +) + +reg("templates", + """The TEMPLATES module implements template instantiation utilities for daslang +code generation. It supports stamping out parameterized code patterns with +type and value substitution. + +See also :doc:`templates_boost` for template substitution and code generation.""", + "require daslib/templates", +) + +reg("templates_boost", + """The TEMPLATES_BOOST module extends template utilities with high-level macros +for common code generation patterns, including template function generation, +type-parameterized struct creation, and compile-time code expansion. + +See also :doc:`templates` for ``decltype`` and ``[template]`` annotations.""", + "require daslib/templates_boost", +) + +reg("type_traits", + """The TYPE_TRAITS module provides compile-time type introspection and manipulation. +It includes type queries (``is_numeric``, ``is_string``, ``is_pointer``), +type transformations, and generic programming utilities for writing +type-aware macros and functions.""", + "require daslib/type_traits", +) + +reg("typemacro_boost", + """The TYPEMACRO_BOOST module provides infrastructure for defining type macros — +custom compile-time type transformations. Type macros allow introducing new +type syntax that expands into standard daslang types during compilation.""", + "require daslib/typemacro_boost", +) + +reg("uriparser_boost", + """The URIPARSER_BOOST module extends URI handling with convenience functions +for common operations like building URIs from components, extracting query +parameters, and resolving relative paths.""", + "require daslib/uriparser_boost", +) + +reg("utf8_utils", + """The UTF8_UTILS module provides Unicode UTF-8 string utilities including +character iteration, codepoint extraction, byte length calculation, and +validation of UTF-8 encoded text.""", + "require daslib/utf8_utils", +) + +reg("validate_code", + """The VALIDATE_CODE module implements AST validation passes that check for +common code quality issues, unreachable code, missing return statements, +and other semantic errors beyond what the type checker verifies.""", + "require daslib/validate_code", +) + +reg("assert_once", + """The ASSERT_ONCE module provides the ``assert_once`` macro — an assertion that +triggers only on its first failure. Subsequent failures at the same location +are silently ignored, preventing assertion storms in loops or frequently +called code.""", + "require daslib/assert_once", +) + + +def format_module_doc(name, desc, require_line, example=None, after_require=""): + """Format a module documentation file.""" + lines = [] + lines.append(desc.strip()) + lines.append("") + lines.append(f'All functions and symbols are in "{name}" module, use require to get access to it. ::') + lines.append("") + lines.append(f" {require_line}") + lines.append("") + + if after_require: + lines.append(after_require.strip()) + lines.append("") + + if example: + lines.append("Example: ::") + lines.append("") + # Dedent: remove common leading whitespace from example lines + example_lines = example.strip().split("\n") + # Find minimum indent + min_indent = float('inf') + for line in example_lines: + if line.strip(): + indent = len(line) - len(line.lstrip()) + min_indent = min(min_indent, indent) + if min_indent == float('inf'): + min_indent = 0 + for line in example_lines: + if line.strip(): + dedented = line[min_indent:] + lines.append(f" {dedented}") + else: + lines.append("") + lines.append("") + + return "\n".join(lines) + + +def main(): + written = 0 + skipped = 0 + missing = 0 + + # Get list of existing module files + existing = set() + for f in os.listdir(HANDMADE): + if f.startswith("module-") and f.endswith(".rst"): + existing.add(f[len("module-"):-4]) + + for name, (desc, require_line, example, after_require) in sorted(MODULES.items()): + fname = f"module-{name}.rst" + path = os.path.join(HANDMADE, fname) + if not os.path.exists(path): + print(f"MISSING: {fname}") + missing += 1 + continue + + content = format_module_doc(name, desc, require_line, example, after_require) + with open(path, "w", encoding="utf-8", newline="") as f: + f.write(content) + written += 1 + has_ex = "+ example" if example else "" + print(f"Updated: {fname} {has_ex}") + + # Report modules we don't have entries for + covered = set(MODULES.keys()) + uncovered = existing - covered + if uncovered: + print(f"\nNot covered ({len(uncovered)}):") + for name in sorted(uncovered): + print(f" module-{name}.rst") + + print(f"\nWritten: {written}, Missing: {missing}, Uncovered: {len(uncovered)}") + + +if __name__ == "__main__": + main() diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 74db2d7cea..c907e7ccf2 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -4,7 +4,7 @@ Daslang 0.6 Reference Manual ################################# -Copyright (c) 2018-2024 Gaijin Entertainment +Copyright (c) 2018-2026 Gaijin Entertainment The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. diff --git a/doc/source/reference/language/lexical_structure.rst b/doc/source/reference/language/lexical_structure.rst index bb181aa0f6..182c3b0a0d 100644 --- a/doc/source/reference/language/lexical_structure.rst +++ b/doc/source/reference/language/lexical_structure.rst @@ -40,7 +40,7 @@ The following words are reserved as keywords and cannot be used as identifiers: +----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+ | ``new`` | :ref:`typeinfo ` | ``type`` | ``in`` | :ref:`is ` | :ref:`as ` | +----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+ -| ``elif`` | ``static_elif`` | :ref:`array ` | :ref:`return ` | ``null`` | :ref:`break ` | +| ``elif`` | ``static_elif`` | :ref:`array ` | :ref:`return ` | ``null`` | :ref:`break ` | +----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+ | ``try`` | :ref:`options ` | :ref:`table ` | ``expect`` | ``const`` | :ref:`require ` | +----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+ @@ -56,7 +56,7 @@ The following words are reserved as keywords and cannot be used as identifiers: +----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+ | :ref:`assume ` | ``explicit`` | ``sealed`` | ``static`` | :ref:`inscope ` | ``fixed_array`` | +----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+ -| ``typedecl`` | ``capture`` | ``default`` | ``uninitialized`` | ``template`` | +| ``typedecl`` | ``capture`` | ``default`` | ``uninitialized`` | | ``template`` | +----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+ The following words are reserved as built-in type names and cannot be used as identifiers: diff --git a/doc/source/reference/language/type_mangling.rst b/doc/source/reference/language/type_mangling.rst index 5c48688378..f5e3aacb9d 100644 --- a/doc/source/reference/language/type_mangling.rst +++ b/doc/source/reference/language/type_mangling.rst @@ -24,36 +24,36 @@ Primitive types Each primitive type has a short mnemonic: -=========== ======== ============================ -daslang Mangled Notes -=========== ======== ============================ -``void`` ``v`` -``bool`` ``b`` -``int`` ``i`` -``int2`` ``i2`` SIMD 2-component vector -``int3`` ``i3`` -``int4`` ``i4`` -``int8`` ``i8`` 8-bit signed integer -``int16`` ``i16`` 16-bit signed integer -``int64`` ``i64`` 64-bit signed integer -``uint`` ``u`` -``uint2`` ``u2`` -``uint3`` ``u3`` -``uint4`` ``u4`` -``uint8`` ``u8`` -``uint16`` ``u16`` -``uint64`` ``u64`` -``float`` ``f`` -``float2`` ``f2`` -``float3`` ``f3`` -``float4`` ``f4`` -``double`` ``d`` -``string`` ``s`` -``range`` ``r`` -``urange`` ``z`` -``range64`` ``r64`` -``urange64`` ``z64`` -=========== ======== ============================ +============ ======== ============================ +daslang Mangled Notes +============ ======== ============================ +``void`` ``v`` +``bool`` ``b`` +``int`` ``i`` +``int2`` ``i2`` SIMD 2-component vector +``int3`` ``i3`` +``int4`` ``i4`` +``int8`` ``i8`` 8-bit signed integer +``int16`` ``i16`` 16-bit signed integer +``int64`` ``i64`` 64-bit signed integer +``uint`` ``u`` +``uint2`` ``u2`` +``uint3`` ``u3`` +``uint4`` ``u4`` +``uint8`` ``u8`` +``uint16`` ``u16`` +``uint64`` ``u64`` +``float`` ``f`` +``float2`` ``f2`` +``float3`` ``f3`` +``float4`` ``f4`` +``double`` ``d`` +``string`` ``s`` +``range`` ``r`` +``urange`` ``z`` +``range64`` ``r64`` +``urange64`` ``z64`` +============ ======== ============================ Qualifiers and modifiers @@ -62,15 +62,15 @@ Qualifiers and modifiers Qualifiers are **prepended** before the base type they modify. For example, ``const int`` is ``Ci`` and ``const string&`` is ``C&s``. -========= ======== ============================ -Qualifier Mangled Meaning -========= ======== ============================ -const ``C`` Constant -ref (``&``) ``&`` Reference -temporary ``#`` Temporary value -implicit ``I`` Implicit type -explicit ``X`` Explicit type match -========= ======== ============================ +============ ======== ============================ +Qualifier Mangled Meaning +============ ======== ============================ +const ``C`` Constant +ref (``&``) ``&`` Reference +temporary ``#`` Temporary value +implicit ``I`` Implicit type +explicit ``X`` Explicit type match +============ ======== ============================ Pointers @@ -79,7 +79,7 @@ Pointers A raw pointer is ``?``, followed by an optional smart-pointer marker: ==================== ======== -daslang Mangled +daslang Mangled ==================== ======== ``Foo?`` ``?`` ``smart_ptr`` ``?M`` @@ -95,19 +95,19 @@ Composite prefixes Some types carry sub-types. These use numbered prefix wrappers: -======== ====================================== ================================== -Prefix Meaning Example -======== ====================================== ================================== -``1`` First sub-type (element type) ``array`` → ``1A`` -``2`` Second sub-type (value type for tables) ``table`` → ``12T`` -======== ====================================== ================================== +======== ======================================= ================================== +Prefix Meaning Example +======== ======================================= ================================== +``1`` First sub-type (element type) ``array`` → ``1A`` +``2`` Second sub-type (value type for tables) ``table`` → ``12T`` +======== ======================================= ================================== Container types =============== ============= ======== =============================== -daslang Mangled Encoding pattern +daslang Mangled Encoding pattern ============= ======== =============================== ``array`` ``A`` ``1A`` ``table`` ``T`` ``12T`` @@ -139,11 +139,11 @@ Callable types daslang has three callable types, each with its own suffix: ================ ======== ============================ -daslang Mangled Characteristics +daslang Mangled Characteristics ================ ======== ============================ -function pointer ``@@`` No capture, cheapest call -lambda ``@`` Heap-allocated, captures variables -block ``$`` Stack-allocated, cannot outlive scope +function pointer ``@@`` No capture, cheapest call +lambda ``@`` Heap-allocated, captures variables +block ``$`` Stack-allocated, cannot outlive scope ================ ======== ============================ The argument list uses the ``0`` prefix with arguments separated @@ -200,14 +200,14 @@ Named arguments in callable types use the ``N`` prefix: Bitfields ========= -========= ======== -daslang Mangled -========= ======== -bitfield ``t`` -bitfield8 ``t8`` -bitfield16 ``t16`` -bitfield64 ``t64`` -========= ======== +========== ======== +daslang Mangled +========== ======== +bitfield ``t`` +bitfield8 ``t8`` +bitfield16 ``t16`` +bitfield64 ``t64`` +========== ======== Special / internal types @@ -235,14 +235,14 @@ Remove-qualifiers (generics) In generic function signatures, qualifiers can be explicitly removed: -========= ======== ============================ -Trait Mangled Meaning -========= ======== ============================ -remove ref ``-&`` Strip reference -remove const ``-C`` Strip const -remove temp ``-#`` Strip temporary -remove dim ``-[]`` Strip fixed dimensions -========= ======== ============================ +============ ======== ============================ +Trait Mangled Meaning +============ ======== ============================ +remove ref ``-&`` Strip reference +remove const ``-C`` Strip const +remove temp ``-#`` Strip temporary +remove dim ``-[]`` Strip fixed dimensions +============ ======== ============================ Interop function signatures diff --git a/doc/source/reference/tutorials/31_regex.rst b/doc/source/reference/tutorials/31_regex.rst index b58a64b804..e244dba5ea 100644 --- a/doc/source/reference/tutorials/31_regex.rst +++ b/doc/source/reference/tutorials/31_regex.rst @@ -396,15 +396,15 @@ Template-string replace ``regex_replace`` also accepts a replacement template string instead of a block. The template supports group references: -============ ==================================== -Reference Meaning -============ ==================================== -``$0`` Whole match -``$&`` Whole match (alternative syntax) -``$1``–``$9`` Numbered capturing groups -``${name}`` Named capturing group -``$$`` Literal ``$`` character -============ ==================================== +============= ==================================== +Reference Meaning +============= ==================================== +``$0`` Whole match +``$&`` Whole match (alternative syntax) +``$1``–``$9`` Numbered capturing groups +``${name}`` Named capturing group +``$$`` Literal ``$`` character +============= ==================================== :: diff --git a/doc/source/reference/tutorials/integration_c_02_calling_functions.rst b/doc/source/reference/tutorials/integration_c_02_calling_functions.rst index 4efc233d68..9ec4592dae 100644 --- a/doc/source/reference/tutorials/integration_c_02_calling_functions.rst +++ b/doc/source/reference/tutorials/integration_c_02_calling_functions.rst @@ -20,7 +20,7 @@ Every value crossing the C ↔ daslang boundary is carried in a ``vec4f`` — a 128-bit SSE register. The API provides symmetric helper pairs: ============================= ============================== -Packing (C → daslang) Unpacking (daslang → C) +Packing (C → daslang) Unpacking (daslang → C) ============================= ============================== ``das_result_int(value)`` ``das_argument_int(vec4f)`` ``das_result_float(value)`` ``das_argument_float(vec4f)`` diff --git a/doc/source/reference/tutorials/integration_c_06_sandbox.rst b/doc/source/reference/tutorials/integration_c_06_sandbox.rst index cb365ad318..2ce9cc9dd0 100644 --- a/doc/source/reference/tutorials/integration_c_06_sandbox.rst +++ b/doc/source/reference/tutorials/integration_c_06_sandbox.rst @@ -56,15 +56,15 @@ owned and freed by the file access. Available ``introduce`` functions: -================================ ============================================= -Function Purpose -================================ ============================================= -``das_fileaccess_introduce_file`` Register a virtual file from a string -``das_fileaccess_introduce_file_from_disk`` Read a disk file into cache -``das_fileaccess_introduce_daslib`` Cache all ``daslib/*.das`` files -``das_fileaccess_introduce_native_modules`` Cache all native plugin modules -``das_fileaccess_introduce_native_module`` Cache a single native module -================================ ============================================= +============================================ ================================= +Function Purpose +============================================ ================================= +``das_fileaccess_introduce_file`` Register a virtual file from a string +``das_fileaccess_introduce_file_from_disk`` Read a disk file into cache +``das_fileaccess_introduce_daslib`` Cache all ``daslib/*.das`` files +``das_fileaccess_introduce_native_modules`` Cache all native plugin modules +``das_fileaccess_introduce_native_module`` Cache a single native module +============================================ ================================= The .das_project file diff --git a/doc/source/reference/tutorials/integration_c_07_context_variables.rst b/doc/source/reference/tutorials/integration_c_07_context_variables.rst index 81cf9e7956..b68c860285 100644 --- a/doc/source/reference/tutorials/integration_c_07_context_variables.rst +++ b/doc/source/reference/tutorials/integration_c_07_context_variables.rst @@ -15,15 +15,15 @@ global variables from a C host using the ``daScriptC.h`` API. After a program is compiled and simulated, its global variables live in the context. The C API provides five functions to access them: -======================================== ========================================== -Function Purpose -======================================== ========================================== -``das_context_find_variable(ctx, name)`` Look up a global by name; returns an index -``das_context_get_variable(ctx, idx)`` Get a raw ``void*`` to the variable storage -``das_context_get_total_variables(ctx)`` Total number of globals -``das_context_get_variable_name(ctx, i)`` Name of the i-th global -``das_context_get_variable_size(ctx, i)`` Size (in bytes) of the i-th global -======================================== ========================================== +========================================= ========================================= +Function Purpose +========================================= ========================================= +``das_context_find_variable(ctx, name)`` Look up a global by name; returns an index +``das_context_get_variable(ctx, idx)`` Get a raw ``void*`` to the variable storage +``das_context_get_total_variables(ctx)`` Total number of globals +``das_context_get_variable_name(ctx, i)`` Name of the i-th global +``das_context_get_variable_size(ctx, i)`` Size (in bytes) of the i-th global +========================================= ========================================= The daslang script diff --git a/doc/source/reference/tutorials/integration_c_09_aot.rst b/doc/source/reference/tutorials/integration_c_09_aot.rst index ec6c1fc1a4..d03bf3f9c6 100644 --- a/doc/source/reference/tutorials/integration_c_09_aot.rst +++ b/doc/source/reference/tutorials/integration_c_09_aot.rst @@ -88,15 +88,15 @@ Enum value CodeOfPolicies field Available integer policies ========================== -======================================= =============================================== -Enum value CodeOfPolicies field -======================================= =============================================== -``DAS_POLICY_STACK`` ``stack`` — context stack size (bytes) -``DAS_POLICY_MAX_HEAP_ALLOCATED`` ``max_heap_allocated`` — max heap (0 = unlimited) -``DAS_POLICY_MAX_STRING_HEAP_ALLOCATED`` ``max_string_heap_allocated`` -``DAS_POLICY_HEAP_SIZE_HINT`` ``heap_size_hint`` — initial heap size -``DAS_POLICY_STRING_HEAP_SIZE_HINT`` ``string_heap_size_hint`` -======================================= =============================================== +======================================== =============================================== +Enum value CodeOfPolicies field +======================================== =============================================== +``DAS_POLICY_STACK`` ``stack`` — context stack size (bytes) +``DAS_POLICY_MAX_HEAP_ALLOCATED`` ``max_heap_allocated`` — max heap (0 = unlimited) +``DAS_POLICY_MAX_STRING_HEAP_ALLOCATED`` ``max_string_heap_allocated`` +``DAS_POLICY_HEAP_SIZE_HINT`` ``heap_size_hint`` — initial heap size +``DAS_POLICY_STRING_HEAP_SIZE_HINT`` ``string_heap_size_hint`` +======================================== =============================================== Build & run diff --git a/doc/source/reference/tutorials/integration_cpp_02_calling_functions.rst b/doc/source/reference/tutorials/integration_cpp_02_calling_functions.rst index 4609b9dae0..ac2f283aa4 100644 --- a/doc/source/reference/tutorials/integration_cpp_02_calling_functions.rst +++ b/doc/source/reference/tutorials/integration_cpp_02_calling_functions.rst @@ -256,17 +256,17 @@ handle. For functions called repeatedly, cache the ``Func`` instead. Part A vs Part B comparison ============================ -============================== ============================ ============================== -Aspect Part A (cast + evalWithCatch) Part B (das_invoke_function) -============================== ============================ ============================== -Header ``daScript.h`` ``simulate/aot.h`` -Argument marshalling Manual ``vec4f[]`` Automatic (variadic templates) -Return value extraction Manual ``cast::to`` Automatic (template parameter) -Struct returns ``evalWithCatch(f, a, &buf)`` ``invoke_cmres(...)`` -AOT dispatch No Yes -Exception handling ``getException()`` after call Throws C++ exception -Best for Learning / edge cases Production code -============================== ============================ ============================== +============================== ============================== ============================== +Aspect Part A (cast + evalWithCatch) Part B (das_invoke_function) +============================== ============================== ============================== +Header ``daScript.h`` ``simulate/aot.h`` +Argument marshalling Manual ``vec4f[]`` Automatic (variadic templates) +Return value extraction Manual ``cast::to`` Automatic (template parameter) +Struct returns ``evalWithCatch(f, a, &buf)`` ``invoke_cmres(...)`` +AOT dispatch No Yes +Exception handling ``getException()`` after call Throws C++ exception +Best for Learning / edge cases Production code +============================== ============================== ============================== Building and running diff --git a/doc/source/reference/tutorials/integration_cpp_12_smart_pointers.rst b/doc/source/reference/tutorials/integration_cpp_12_smart_pointers.rst index 4f67b1de97..cdf50fd45a 100644 --- a/doc/source/reference/tutorials/integration_cpp_12_smart_pointers.rst +++ b/doc/source/reference/tutorials/integration_cpp_12_smart_pointers.rst @@ -85,9 +85,9 @@ that control what scripts can do: ``is_base_of`` at compile time. +---------------+--------------------------------------------------+ -| ``canNew`` | ``new Entity`` allocates + ``addRef()`` | +| ``canNew`` | ``new Entity`` allocates + ``addRef()`` | +---------------+--------------------------------------------------+ -| ``canDelete`` | ``delete ptr`` calls ``delRef()`` | +| ``canDelete`` | ``delete ptr`` calls ``delRef()`` | +---------------+--------------------------------------------------+ diff --git a/doc/source/reference/tutorials/integration_cpp_16_sandbox.rst b/doc/source/reference/tutorials/integration_cpp_16_sandbox.rst index 2a127ec8a7..6c19ac2ea2 100644 --- a/doc/source/reference/tutorials/integration_cpp_16_sandbox.rst +++ b/doc/source/reference/tutorials/integration_cpp_16_sandbox.rst @@ -83,7 +83,7 @@ Key policy flags: +-----------------------------------+------------------------------------------+ | ``max_string_heap_allocated`` | Caps string heap memory | +-----------------------------------+------------------------------------------+ -| ``stack`` | Context stack size in bytes | +| ``stack`` | Context stack size in bytes | +-----------------------------------+------------------------------------------+ | ``threadlock_context`` | Adds context mutex for thread safety | +-----------------------------------+------------------------------------------+ @@ -221,7 +221,7 @@ Available callbacks: +-------------------------------+-----------------------------------------------+ | ``module_allowed_unsafe`` | Control ``unsafe`` per module | +-------------------------------+-----------------------------------------------+ -| ``option_allowed`` | Whitelist ``options`` directives | +| ``option_allowed`` | Whitelist ``options`` directives | +-------------------------------+-----------------------------------------------+ | ``annotation_allowed`` | Whitelist annotations | +-------------------------------+-----------------------------------------------+ diff --git a/doc/source/stdlib/algorithm.rst b/doc/source/stdlib/algorithm.rst index 873ab4df4e..f63bff7d3a 100644 --- a/doc/source/stdlib/algorithm.rst +++ b/doc/source/stdlib/algorithm.rst @@ -247,8 +247,6 @@ Returns the index of the first element in the range [f, l) for which less(val, e .. das:function:: upper_bound(a: auto; f: int; l: int; val: auto(TT); less: block<(a:TT;b:TT):bool>) : auto ----- - ++++++++++++++++++ Array manipulation diff --git a/doc/source/stdlib/array_boost.rst b/doc/source/stdlib/array_boost.rst index a0e9270955..edf7346cf5 100644 --- a/doc/source/stdlib/array_boost.rst +++ b/doc/source/stdlib/array_boost.rst @@ -21,16 +21,16 @@ All functions and symbols are in "array_boost" module, use require to get access Temporary arrays ++++++++++++++++ - * :ref:`temp_array (arr: auto const implicit ==const) : auto ` + * :ref:`temp_array (arr: auto const implicit ==const) : auto ` * :ref:`temp_array (var arr: auto implicit ==const) : auto ` - * :ref:`temp_array (data: auto? ==const; lenA: int; a: auto(TT)) : array\ ` - * :ref:`temp_array (var data: auto? ==const; lenA: int; a: auto(TT)) : array\ ` + * :ref:`temp_array (data: auto? ==const; lenA: int; a: auto(TT)) : array\ ` + * :ref:`temp_array (var data: auto? ==const; lenA: int; a: auto(TT)) : array\ ` temp_array ^^^^^^^^^^ -.. _function-array_boost_temp_array_auto_const_implicit__eq__eq_const_0x3a: +.. _function-array_boost_temp_array_auto_const_implicit__eq__eq_const_0x3b: .. das:function:: temp_array(arr: auto const implicit ==const) : auto @@ -39,6 +39,7 @@ temp_array Creates temporary array from the given object. Important requirements are: + * object memory is linear * each element follows the next one directly, with the stride equal to size of the element * object memory does not change within the lifetime of the returned array @@ -50,24 +51,22 @@ Important requirements are: .. das:function:: temp_array(arr: auto implicit ==const) : auto -.. _function-array_boost_temp_array_auto_q___eq__eq_const_int_autoTT_0x5c: +.. _function-array_boost_temp_array_auto_q___eq__eq_const_int_autoTT_0x5f: .. das:function:: temp_array(data: auto? ==const; lenA: int; a: auto(TT)) : array -.. _function-array_boost_temp_array__auto_q___eq__eq_const_int_autoTT_0x4c: +.. _function-array_boost_temp_array__auto_q___eq__eq_const_int_autoTT_0x4e: .. das:function:: temp_array(data: auto? ==const; lenA: int; a: auto(TT)) : array ----- - +++++++++++ Empty check +++++++++++ - * :ref:`empty (v: auto(VecT)) : auto ` + * :ref:`empty (v: auto(VecT)) : auto ` -.. _function-array_boost_empty_autoVecT_0x46: +.. _function-array_boost_empty_autoVecT_0x48: .. das:function:: empty(v: auto(VecT)) : auto @@ -107,6 +106,4 @@ creates a view of the array, which is a temporary array that is valid only withi .. das:function:: array_view(bytes: array; offset: int; length: int; blk: block<(view:array#):void>) : auto ----- - diff --git a/doc/source/stdlib/ast.rst b/doc/source/stdlib/ast.rst index c645befe12..fe24dad55a 100644 --- a/doc/source/stdlib/ast.rst +++ b/doc/source/stdlib/ast.rst @@ -6146,8 +6146,6 @@ Creates an adapter for the AstVisitor interface. .. das:function:: make_visitor(class: void? implicit; info: StructInfo const? implicit) : smart_ptr ----- - +++++++++++++++++++ Adapter application diff --git a/doc/source/stdlib/ast_boost.rst b/doc/source/stdlib/ast_boost.rst index 9e42289e80..46972903ac 100644 --- a/doc/source/stdlib/ast_boost.rst +++ b/doc/source/stdlib/ast_boost.rst @@ -583,8 +583,6 @@ Moves a newly created ``smart_ptr`` (``Expression``, ``TypeDecl``, ``Variable``, .. das:function:: emplace_new(vec: dasvector`smart_ptr`Variable; ptr: smart_ptr) ----- - +++++++++++++++++++++++++++++++++++ Textual descriptions of the objects @@ -1022,8 +1020,6 @@ Creates an ``AnnotationDeclaration`` for the named annotation (with optional typ .. das:function:: append_annotation(st: smart_ptr; mod_name: string; ann_name: string) ----- - +++++++++++++++++++++ Expression generation diff --git a/doc/source/stdlib/base64.rst b/doc/source/stdlib/base64.rst index 8d35d6214d..2eb8eb56ab 100644 --- a/doc/source/stdlib/base64.rst +++ b/doc/source/stdlib/base64.rst @@ -66,8 +66,6 @@ Encodes a string to its Base64 text representation. .. das:function:: base64_encode(inp: array|array#) : auto ----- - ++++++++ Decoding @@ -103,6 +101,4 @@ Decodes a Base64-encoded string. Returns a tuple of the decoded text and its byt .. das:function:: base64_decode(_in: string; out: array) : int ----- - diff --git a/doc/source/stdlib/builtin.rst b/doc/source/stdlib/builtin.rst index fb92fae55e..3efe38976d 100644 --- a/doc/source/stdlib/builtin.rst +++ b/doc/source/stdlib/builtin.rst @@ -1872,8 +1872,6 @@ Returns a mutable iterator over all fixed-size array values in a mutable `table< .. das:function:: values(a: table ==const|table# ==const) : iterator ----- - ++++++++++++++++++++++++ das::string manipulation @@ -2873,8 +2871,6 @@ Formats a `uint8` value as a string using the given `format` specifier (followin .. das:function:: fmt(format: string implicit; value: float) : string ----- - ++++++++++++++++++++ Argument consumption @@ -2986,8 +2982,6 @@ Passes through and returns a mutable reference to `a`, verifying that `a` and al .. das:function:: _return_with_lockcheck(a: auto(valT) const& ==const) : auto& ----- - ++++++++++++++ Bit operations @@ -3102,8 +3096,6 @@ Counts and returns the number of set (1) bits in the 64-bit unsigned integer `bi .. das:function:: popcnt(bits: uint) : uint ----- - +++++++++ Intervals @@ -3141,8 +3133,6 @@ Constructs a `urange` value from the two `uint` endpoints `arg0` (inclusive) and .. das:function:: interval(arg0: int64; arg1: int64) : range64 ----- - ++++ RTTI diff --git a/doc/source/stdlib/dap.rst b/doc/source/stdlib/dap.rst index 11ed909259..2823b8f22d 100644 --- a/doc/source/stdlib/dap.rst +++ b/doc/source/stdlib/dap.rst @@ -642,8 +642,6 @@ Converts an EvaluateResponse struct to its DAP JSON representation. .. das:function:: JV(data: Variable) : JsonValue? ----- - ++++++++++++++++++++ JSON field accessors diff --git a/doc/source/stdlib/decs.rst b/doc/source/stdlib/decs.rst index e766bcf998..f3e5152200 100644 --- a/doc/source/stdlib/decs.rst +++ b/doc/source/stdlib/decs.rst @@ -550,8 +550,6 @@ If value already exists, it is overwritten. If already existing value type is no .. das:function:: set(cv: ComponentValue; val: auto) : auto ----- - +++++++++++++ Entity status @@ -865,8 +863,6 @@ Returns const temporary array of component given specific name and type of compo .. das:function:: get_ro(arch: Archetype; name: string; value: auto(TT)[]) : array ----- - +++++++ Request diff --git a/doc/source/stdlib/decs_boost.rst b/doc/source/stdlib/decs_boost.rst index 355c05fd79..8c879bffda 100644 --- a/doc/source/stdlib/decs_boost.rst +++ b/doc/source/stdlib/decs_boost.rst @@ -119,7 +119,7 @@ Additionally queries can automatically expand components of entities. For exampl In the example above structure q : Particle does not exist as a variable. Instead it is expanded into accessing individual components of the entity. REQURE section of the query is automatically filled with all components of the template. -If template prefix is not specified, prefix is taken from the name of the template (would be "Particle_"). +If template prefix is not specified, prefix is taken from the name of the template (would be ``Particle_``). Specifying empty prefix `[decs_template(prefix)]` will result in no prefix being added. Note: apart from tagging structure as a template, the macro also generates `apply_decs_template` and `remove_decs_template` functions. diff --git a/doc/source/stdlib/enum_trait.rst b/doc/source/stdlib/enum_trait.rst index 601cbdf493..090e58546f 100644 --- a/doc/source/stdlib/enum_trait.rst +++ b/doc/source/stdlib/enum_trait.rst @@ -137,6 +137,4 @@ converts string to enum value, panics if not found .. das:function:: to_enum(ent: auto(EnumT); name: string; defaultValue: EnumT) : EnumT ----- - diff --git a/doc/source/stdlib/faker.rst b/doc/source/stdlib/faker.rst index 60de857001..a9fe4e92cb 100644 --- a/doc/source/stdlib/faker.rst +++ b/doc/source/stdlib/faker.rst @@ -518,6 +518,4 @@ Returns week day for given date. .. das:function:: week_day(year: int; month: int; day: int) : int ----- - diff --git a/doc/source/stdlib/fio.rst b/doc/source/stdlib/fio.rst index 9afb28de4f..bc57ab2867 100644 --- a/doc/source/stdlib/fio.rst +++ b/doc/source/stdlib/fio.rst @@ -492,8 +492,6 @@ Retrieves file metadata such as size and timestamps for the file at the given pa .. das:function:: stat(file: string implicit; stat: FStat implicit) : bool ----- - +++++++++++++++++ Path manipulation diff --git a/doc/source/stdlib/functional.rst b/doc/source/stdlib/functional.rst index 60b8428546..e240ed097e 100644 --- a/doc/source/stdlib/functional.rst +++ b/doc/source/stdlib/functional.rst @@ -166,8 +166,6 @@ iterates over input and returns it sorted version .. das:function:: sorted(arr: array) : auto ----- - +++++++++++ Aggregation @@ -406,8 +404,6 @@ splits elements into `(matching, non_matching)` arrays .. das:function:: partition(src: iterator; blk: block<(what:TT):bool>) : tuple;array> ----- - +++++++++ Iteration @@ -486,8 +482,6 @@ yields every element unchanged, calling `blk` on each as a side-effect .. das:function:: tap(src: iterator; blk: lambda<(what:TT):void>) : auto ----- - ++++++++++ Generators diff --git a/doc/source/stdlib/handmade/module-match.rst b/doc/source/stdlib/handmade/module-match.rst index 62b6801baa..25d12e2155 100644 --- a/doc/source/stdlib/handmade/module-match.rst +++ b/doc/source/stdlib/handmade/module-match.rst @@ -19,7 +19,6 @@ Example: :: blue } - [sideeffects] def describe(c : Color) : string { match (c) { if (Color.red) { return "red"; } diff --git a/doc/source/stdlib/index.rst b/doc/source/stdlib/index.rst index e846856ccb..8ab53caaec 100644 --- a/doc/source/stdlib/index.rst +++ b/doc/source/stdlib/index.rst @@ -4,7 +4,7 @@ Daslang Standard Library 0.6 ################################# -Copyright (c) 2018-2024 Gaijin Entertainment +Copyright (c) 2018-2026 Gaijin Entertainment Authors: Anton Yudintsev, Boris Batkin The above copyright notice and this permission notice shall be included in diff --git a/doc/source/stdlib/jobque_boost.rst b/doc/source/stdlib/jobque_boost.rst index 4b5c11a727..8fc02d4610 100644 --- a/doc/source/stdlib/jobque_boost.rst +++ b/doc/source/stdlib/jobque_boost.rst @@ -414,8 +414,6 @@ The block returns only after all notifications have been received. .. das:function:: with_wait_group(count: int; blk: block<(var status:JobStatus?):void>) ----- - ++++++++++++++++++ Parallel execution diff --git a/doc/source/stdlib/json.rst b/doc/source/stdlib/json.rst index 3ae637e90b..eabbd27eeb 100644 --- a/doc/source/stdlib/json.rst +++ b/doc/source/stdlib/json.rst @@ -279,8 +279,6 @@ Overload accepting temporary type .. das:function:: write_json(val: JsonValue?) : string ----- - +++++++++++++++ JSON properties diff --git a/doc/source/stdlib/json_boost.rst b/doc/source/stdlib/json_boost.rst index 80634a776b..bbcacda570 100644 --- a/doc/source/stdlib/json_boost.rst +++ b/doc/source/stdlib/json_boost.rst @@ -298,8 +298,6 @@ Parse a JSON value and return the corresponding native value. .. das:function:: from_JV(v: JsonValue const?; ent: bitfield8:uint8<>; defV: bitfield8 = bitfield8()) : auto ----- - ++++++++++++++++++++++++ Element access operators @@ -374,8 +372,6 @@ Returns the value of the index in the JSON array, if it exists. .. das:function:: JsonValue? ==const?[](a: JsonValue? ==const; key: string) : JsonValue? ----- - +++++++++++++++++++++++++ Null coalescing operators @@ -453,8 +449,6 @@ Returns the value of the JSON object, if it exists, otherwise returns the defaul .. das:function:: JsonValue const???(a: JsonValue const?; val: string) : string ----- - ++++++++++++++++ Value extraction diff --git a/doc/source/stdlib/linked_list.rst b/doc/source/stdlib/linked_list.rst index a9caafac33..662d9e5a2c 100644 --- a/doc/source/stdlib/linked_list.rst +++ b/doc/source/stdlib/linked_list.rst @@ -20,8 +20,8 @@ Constants .. _global-linked_list-TLinkedList: -.. das:attribute:: TLinkedList = "(ListClass,Foo) //! Spoof template that generates a doubly-linked list class for a given element type.\nstruct LLNode_%ListClass \{\n //! Node of the doubly-linked list. Contains data pointer and prev/next links.\n data : %Foo? //! pointer to the stored element\n prev, next : LLNode_%ListClass? //! links to previous and next nodes\n\}\n\nclass %ListClass \{\n //! Doubly-linked list class. Maintains head and tail pointers.\n head, tail : LLNode_%ListClass? //! head and tail of the list\n def %ListClass \{\n head = null\n tail = null\n \}\n\n def add ( var data : %Foo? ) \{\n //! Appends an element to the end of the list.\n var node = new LLNode_%ListClass(data=data)\n if (head == null) \{\n head = node\n tail = node\n \} else \{\n tail.next = node\n node.prev = tail\n tail = node\n \}\n \}\n\n def remove ( data : %Foo? ) \{\n //! Removes the first node whose data matches the given pointer.\n var node = head\n while (node != null) \{\n if (node.data == data) \{\n if (node.prev != null) \{\n node.prev.next = node.next\n \} else \{\n head = node.next\n \}\n if (node.next != null) \{\n node.next.prev = node.prev\n \} else \{\n tail = node.prev\n \}\n return\n \}\n node = node.next\n \}\n \}\n def each : iterator<%Foo?> \{\n //! Returns an iterator over all elements in the list, from head to tail.\n return <- generator <%Foo?> () <| $() \{\n var node = head\n while (node != null) \{\n yield node.data\n node = node.next\n \}\n return false\n \}\n \}\n\}\n" - -|detail/Variable-linked_list-TLinkedList| +.. das:attribute:: TLinkedList = %spoof_template +Spoof template that generates a doubly-linked list class for a given element type. +Usage: ``apply_template(TLinkedList, "MyList", "MyElement")`` diff --git a/doc/source/stdlib/linq.rst b/doc/source/stdlib/linq.rst index 67859bdc28..7021b94936 100644 --- a/doc/source/stdlib/linq.rst +++ b/doc/source/stdlib/linq.rst @@ -1270,8 +1270,6 @@ Sums elements in an array .. das:function:: sum(src: iterator) : TT ----- - ++++++++++++++ Filtering data @@ -1870,8 +1868,6 @@ Returns true if the element is present in the iterator .. das:function:: contains(src: array; element: TT) : bool ----- - ++++++++++++++++++ Element operations @@ -2054,8 +2050,6 @@ Returns the only element of an iterator, or a default value if there is not exac .. das:function:: single_or_default(src: array; defaultValue: TT) : TT ----- - ++++++++++++++++++++ Transform operations @@ -2245,8 +2239,6 @@ Merges three iterators into an array of tuples .. das:function:: zip_to_array(a: iterator; b: iterator; result_selector: block<(l:TT;r:UU):auto>) : array,type))> ----- - +++++++++++++++++++++ Conversion operations @@ -2296,8 +2288,6 @@ Converts an array to a table .. das:function:: to_table(a: iterator; key: block<(v:TT):auto>; elementSelector: block<(v:TT):auto>) : table)), typedecl(elementSelector(type))> ----- - ++++++++++++++++++++ Comparators and keys @@ -2388,6 +2378,4 @@ Checks if two sequences are equal by key .. das:function:: sequence_equal_by(first: array; second: array; key: block<(arg:TT):auto>) : bool ----- - diff --git a/doc/source/stdlib/linq_boost.rst b/doc/source/stdlib/linq_boost.rst index 56727ba880..f03b95ecfc 100644 --- a/doc/source/stdlib/linq_boost.rst +++ b/doc/source/stdlib/linq_boost.rst @@ -48,6 +48,7 @@ Call macros implements _order_by(iterator, expression) shorthand notation that expands into order_by(iterator, $(_) => expression) for example:: + each(foo)._order_by(_.id) @@ -58,6 +59,7 @@ for example:: implements _union_by(iterator1, iterator2, expression) shorthand notation that expands into union_by(iterator1, iterator2, $(_) => expression) for example:: + each(foo1)._union_by(each(foo2), _.id) @@ -68,6 +70,7 @@ for example:: implements _take_while(iterator, expression) shorthand notation that expands into take_while(iterator, $(_) => expression) for example:: + each(foo)._take_while(_ < 5) @@ -78,6 +81,7 @@ for example:: implements _all(iterator, expression) shorthand notation that expands into all(iterator, $(_) => expression) for example:: + each(foo)._all(_ < 5) @@ -88,6 +92,7 @@ for example:: implements _distinct_by_to_array(iterator, expression) shorthand notation that expands into distinct_by_to_array(iterator, $(_) => expression) for example:: + each(foo)._distinct_by_to_array(_.id) @@ -98,6 +103,7 @@ for example:: implements _order_by_to_array(iterator, expression) shorthand notation that expands into order_by_to_array(iterator, $(_) => expression) for example:: + each(foo)._order_by_to_array(_.id) @@ -108,6 +114,7 @@ for example:: implements _except_by(iterator1, iterator2, expression) shorthand notation that expands into except_by(iterator1, iterator2, $(_) => expression) for example:: + each(foo1)._except_by(each(foo2), _.id) @@ -118,6 +125,7 @@ for example:: implements _min_max_average_by(iterator, expression) shorthand notation that expands into min_max_average_by(iterator, $(_) => expression) for example:: + each(foo)._min_max_average_by(_.value) @@ -128,6 +136,7 @@ for example:: implements _min_by(iterator, expression) shorthand notation that expands into min_by(iterator, $(_) => expression) for example:: + each(foo)._min_by(_.value) @@ -138,6 +147,7 @@ for example:: implements _select_to_array(iterator, expression) shorthand notation that expands into select_to_array(iterator, $(_) => expression) for example:: + each(foo)._select_to_array(_ * 2) @@ -148,6 +158,7 @@ for example:: implements _union_by_to_array(iterator1, iterator2, expression) shorthand notation that expands into union_by_to_array(iterator1, iterator2, $(_) => expression) for example:: + each(foo1)._union_by_to_array(each(foo2), _.id) @@ -158,6 +169,7 @@ for example:: implements _unique_by_to_array(iterator, expression) shorthand notation that expands into unique_by_to_array(iterator, $(_) => expression) for example:: + each(foo)._unique_by_to_array(_.id) @@ -168,6 +180,7 @@ for example:: implements _count(iterator, expression) shorthand notation that expands into count(iterator, $(_) => expression) for example:: + each(foo)._count(_ > 3) @@ -178,6 +191,7 @@ for example:: implements _max_by(iterator, expression) shorthand notation that expands into max_by(iterator, $(_) => expression) for example:: + each(foo)._max_by(_.value) @@ -188,6 +202,7 @@ for example:: implements _any(iterator, expression) shorthand notation that expands into any(iterator, $(_) => expression) for example:: + each(foo)._any(_ < 5) @@ -198,6 +213,7 @@ for example:: implements _except_by_to_array(iterator1, iterator2, expression) shorthand notation that expands into except_by_to_array(iterator1, iterator2, $(_) => expression) for example:: + each(foo1)._except_by_to_array(each(foo2), _.id) @@ -208,6 +224,7 @@ for example:: implements _order_by_descending(iterator, expression) shorthand notation that expands into order_by_descending(iterator, $(_) => expression) for example:: + each(foo)._order_by_descending(_.id) @@ -218,6 +235,7 @@ for example:: implements _order_by_descending_to_array(iterator, expression) shorthand notation that expands into order_by_descending_to_array(iterator, $(_) => expression) for example:: + each(foo)._order_by_descending_to_array(_.id) @@ -228,6 +246,7 @@ for example:: implements _distinct_by(iterator, expression) shorthand notation that expands into distinct_by(iterator, $(_) => expression) for example:: + each(foo)._distinct_by(_.id) @@ -238,6 +257,7 @@ for example:: implements _select(iterator, expression) shorthand notation that expands into select(iterator, $(_) => expression) for example:: + each(foo)._select(_ * 2) @@ -248,6 +268,7 @@ for example:: implements _intersect_by_to_array(iterator1, iterator2, expression) shorthand notation that expands into intersect_by_to_array(iterator1, iterator2, $(_) => expression) for example:: + each(foo1)._intersect_by_to_array(each(foo2), _.id) @@ -258,6 +279,7 @@ for example:: implements _min_max_by(iterator, expression) shorthand notation that expands into min_max_by(iterator, $(_) => expression) for example:: + each(foo)._min_max_by(_.value) @@ -268,6 +290,7 @@ for example:: implements _intersect_by(iterator1, iterator2, expression) shorthand notation that expands into intersect_by(iterator1, iterator2, $(_) => expression) for example:: + each(foo1)._intersect_by(each(foo2), _.id) @@ -278,6 +301,7 @@ for example:: implements _where_to_array(iterator, expression) shorthand notation that expands into where_to_array(iterator, $(_) => expression) for example:: + each(foo)._where_to_array(_ < 5) @@ -288,6 +312,7 @@ for example:: implements _skip_while(iterator, expression) shorthand notation that expands into skip_while(iterator, $(_) => expression) for example:: + each(foo)._skip_while(_ < 5) @@ -298,6 +323,7 @@ for example:: implements _where(iterator, expression) shorthand notation that expands into where_(iterator, $(_) => expression) for example:: + each(foo)._where(_ < 5) @@ -308,6 +334,7 @@ for example:: implements _unique_by(iterator, expression) shorthand notation that expands into unique_by(iterator, $(_) => expression) for example:: + each(foo)._unique_by(_.id) @@ -330,6 +357,7 @@ expands into a single comprehension that does all operations in one pass implements _sequence_equal_by(iterator1, iterator2, expression) shorthand notation that expands into sequence_equal_by(iterator1, iterator2, $(_) => expression) for example:: + each(foo1)._sequence_equal_by(each(foo2), _.id) diff --git a/doc/source/stdlib/math.rst b/doc/source/stdlib/math.rst index db9a3902be..1e735e85c9 100644 --- a/doc/source/stdlib/math.rst +++ b/doc/source/stdlib/math.rst @@ -304,8 +304,6 @@ Returns the component-wise minimum of two values, supporting scalar double, floa .. das:function:: min(x: int64; y: int64) : int64 ----- - +++++++++++++++++ float* and double @@ -1222,8 +1220,6 @@ Returns the tangent of the angle x given in radians for double or float; undefin .. das:function:: tan(x: float3) : float3 ----- - +++++++++++ float* only @@ -1621,8 +1617,6 @@ Truncates the float x toward zero to the nearest integer and returns the result .. das:function:: trunci(x: float3) : int3 ----- - +++++++++++ float3 only @@ -1799,8 +1793,6 @@ Computes the refraction direction of vector v through a surface with unit normal .. das:function:: refract(v: float3; n: float3; nint: float) : float3 ----- - ++++++++++++++++++++++ float2, float3, float4 @@ -1989,8 +1981,6 @@ Returns a unit-length vector with the same direction as the input float2, float3 .. das:function:: normalize(x: float4) : float4 ----- - +++++++++++++++ Noise functions @@ -2318,8 +2308,6 @@ Computes the fused multiply-add operation `a * b + c`. .. das:function:: mad(a: uint4; b: uint; c: uint4) : uint4 ----- - +++++++++++++++++++++ Matrix element access @@ -2468,8 +2456,6 @@ def float4x4 implicit ==const.[] (m: float4x4 implicit ==const; i: int) : float4 .. das:function:: float4x4 implicit ==const.[](m: float4x4 implicit ==const; i: uint) : float4& ----- - +++++++++++++++++ Matrix operations diff --git a/doc/source/stdlib/math_bits.rst b/doc/source/stdlib/math_bits.rst index 2b6895e586..757151694b 100644 --- a/doc/source/stdlib/math_bits.rst +++ b/doc/source/stdlib/math_bits.rst @@ -98,8 +98,6 @@ bit representation of x is interpreted as a float3 .. das:function:: uint_bits_to_float(x: uint4) : float4 ----- - +++++++++++++++++ int,uint in float @@ -166,8 +164,6 @@ bit representation of x is interpreted as a uint3 .. das:function:: float_bits_to_uint(x: float4) : uint4 ----- - ++++++++++++++++++++++ int64,uint64 in double @@ -299,6 +295,4 @@ return a float4 which stores bit-cast version of x .. das:function:: cast_to_vec4f(x: bool) : float4 ----- - diff --git a/doc/source/stdlib/math_boost.rst b/doc/source/stdlib/math_boost.rst index ff4775c896..dc85b08d06 100644 --- a/doc/source/stdlib/math_boost.rst +++ b/doc/source/stdlib/math_boost.rst @@ -132,8 +132,6 @@ returns true if inputs intersect .. das:function:: is_intersecting(ray: Ray; aabb: AABB; Tmin: float = 0f; Tmax: float = FLT_MAX) : bool ----- - ++++++++ Matrices @@ -318,8 +316,6 @@ convert value from linear space to sRGB curve space .. das:function:: linear_to_SRGB(c: float4) : float4 ----- - +++++++++++++++++++++++++++ Color packing and unpacking diff --git a/doc/source/stdlib/rst.rst b/doc/source/stdlib/rst.rst index 24131db24d..7b98de3c5a 100644 --- a/doc/source/stdlib/rst.rst +++ b/doc/source/stdlib/rst.rst @@ -55,7 +55,7 @@ Document writers ++++++++++++++++ * :ref:`document (name: string; var mod: Module?; fname: string; var groups: array\; hook: DocsHook = DocsHook()) ` - * :ref:`document_enumeration (doc_file: file; mod: Module?; value: auto) : auto ` + * :ref:`document_enumeration (doc_file: file; mod: Module?; value: auto) : auto ` * :ref:`document_enumerations (doc_file: file; mods: array\) : bool ` * :ref:`documents (name: string; mods: array\; fname: string; var groups: array\; var hook: DocsHook = DocsHook()) ` @@ -76,7 +76,7 @@ Generates RST documentation for a single module and writes it to a file. * **hook** : :ref:`DocsHook ` -.. _function-rst_document_enumeration_file_Module_q__auto_0x41f: +.. _function-rst_document_enumeration_file_Module_q__auto_0x422: .. das:function:: document_enumeration(doc_file: file; mod: Module?; value: auto) : auto @@ -162,8 +162,6 @@ Creates a unique, file-name-safe label string for a function. .. das:function:: function_label_file(value: smart_ptr|Function?; drop_args: int = 0) : auto ----- - ++++++++++++++++++ RST section makers diff --git a/doc/source/stdlib/rtti.rst b/doc/source/stdlib/rtti.rst index 6dd4c4cb5d..bed3f11898 100644 --- a/doc/source/stdlib/rtti.rst +++ b/doc/source/stdlib/rtti.rst @@ -1781,8 +1781,6 @@ Creates a temporary RTTI helper object (e.g., ``Program``, ``DebugInfoHelper``) .. das:function:: using(arg0: block<(recursive_mutex):void>) ----- - +++++++++++ Type access @@ -2132,8 +2130,6 @@ Returns the ``TypeInfo`` object for the specified local variable or expression, .. das:function:: type_info(vinfo: LocalVariableInfo) : TypeInfo const? ----- - ++++++++++++++ Program access @@ -2549,8 +2545,6 @@ Returns a ``string`` representation of a value given its data pointer and ``Type .. das:function:: sprint_data(data: void? implicit; type: TypeInfo const? implicit; flags: bitfield) : string ----- - ++++++++++++++++++++++++++++++ Function and mangled name hash @@ -2739,6 +2733,4 @@ Iterates through each element of an RTTI container (e.g., ``AnnotationArguments` .. das:function:: each(info: EnumInfo implicit ==const) : iterator ----- - diff --git a/doc/source/stdlib/safe_addr.rst b/doc/source/stdlib/safe_addr.rst index 965c90e0cf..8c18225a85 100644 --- a/doc/source/stdlib/safe_addr.rst +++ b/doc/source/stdlib/safe_addr.rst @@ -91,8 +91,6 @@ returns address of the given shared variable. it's safe because shared variables .. das:function:: shared_addr(tab: table; k: KEY) : auto ----- - ++++++++++++++++++ Temporary pointers @@ -118,8 +116,6 @@ returns temporary pointer from a given pointer .. das:function:: temp_ptr(x: auto(T)? const implicit ==const) : T?# ----- - ++++++++++++++++ Temporary values @@ -145,6 +141,4 @@ returns temporary reference to the given expression .. das:function:: temp_value(x: auto(T) const& ==const) : T const&# ----- - diff --git a/doc/source/stdlib/soa.rst b/doc/source/stdlib/soa.rst index 94e36c4a13..14839001c6 100644 --- a/doc/source/stdlib/soa.rst +++ b/doc/source/stdlib/soa.rst @@ -56,6 +56,7 @@ Structure macros Generates a Structure-of-Arrays layout from a regular struct. For a struct ``Foo`` with fields ``x : float`` and ``y : float``, generates: + * ``Foo`SOA`` — struct where every field is ``array`` * ``operator []`` returning ``SOA_INDEX`` proxy * ``length``, ``push``, ``emplace``, ``push_clone``, ``erase`` functions diff --git a/doc/source/stdlib/strings.rst b/doc/source/stdlib/strings.rst index b2619f658f..7adbbdc569 100644 --- a/doc/source/stdlib/strings.rst +++ b/doc/source/stdlib/strings.rst @@ -281,8 +281,6 @@ Returns true if the beginning of string `str` matches the string `cmp`, with opt .. das:function:: starts_with(str: string implicit; offset: int; cmp: string implicit; cmpLen: uint) : bool ----- - ++++++++++++++ String builder @@ -730,8 +728,6 @@ Returns the first index at which `substr` (string or character code) occurs in ` .. das:function:: find(str: string implicit; substr: int) : int ----- - +++++++++++++++++ String comparison @@ -1193,8 +1189,6 @@ Converts a string to a uint8, panicking on failure; an overload accepts `result` .. das:function:: uint8(str: string implicit) : uint8 ----- - +++++++++++++++ String as array diff --git a/doc/source/stdlib/strings_boost.rst b/doc/source/stdlib/strings_boost.rst index c5ac51a7b6..8f385e6916 100644 --- a/doc/source/stdlib/strings_boost.rst +++ b/doc/source/stdlib/strings_boost.rst @@ -121,8 +121,6 @@ Splits a string by the specified delimiter characters and returns an array of su .. das:function:: split_by_chars(text: string implicit; delim: string implicit; blk: block<(arg:array#):auto>) : auto ----- - ++++++++++ Formatting @@ -292,8 +290,6 @@ def last_index_of (str: string; sub: string; start: int) : int .. das:function:: last_index_of(str: string; sub: string) : int ----- - +++++++ Replace diff --git a/doc/source/stdlib/temp_strings.rst b/doc/source/stdlib/temp_strings.rst index 90639e1517..0c6442055e 100644 --- a/doc/source/stdlib/temp_strings.rst +++ b/doc/source/stdlib/temp_strings.rst @@ -76,6 +76,4 @@ Delete the string after the callback is called. Intern strings are not deleted. .. das:function:: temp_string(str: string; cb: block<(res:string#):void>) ----- - diff --git a/doc/source/stdlib/templates_boost.rst b/doc/source/stdlib/templates_boost.rst index e4f27a76d8..7f2bbfac26 100644 --- a/doc/source/stdlib/templates_boost.rst +++ b/doc/source/stdlib/templates_boost.rst @@ -367,8 +367,6 @@ Adds a rule to the template to replace a variable with an expression list. .. das:function:: replaceVariableWithList(self: Template; name: string; expr: array) ----- - ++++++++++++++++++++ Template application @@ -415,8 +413,6 @@ Applies the template to the given expression. If `forceAt` is set, the resulting .. das:function:: apply_template(expr: smart_ptr&; blk: block<(var rules:Template):void>) : ExpressionPtr ----- - ++++++++++++++++++ Expression helpers @@ -485,8 +481,6 @@ Create ExprBlock and move all expressions from expr to the list of the block. .. das:function:: make_expression_block(exprs: array) : smart_ptr ----- - +++++++++++++ Block helpers @@ -605,8 +599,6 @@ Add global variable to the module, given name and type. .. das:function:: add_global_var(mod: Module?; vname: string; typ: TypeDeclPtr; vat: LineInfo; priv: bool) : bool ----- - ++++++++++++++ Hygienic names @@ -823,8 +815,6 @@ Implementation details for the reification. Creates a type declaration from a st .. das:function:: add_type_ptr_ref(st: Enumeration?; flags: TypeDeclFlags) : TypeDeclPtr ----- - +++++++++++++++++ Structure helpers diff --git a/doc/source/stdlib/typemacro_boost.rst b/doc/source/stdlib/typemacro_boost.rst index 91f61046aa..7adad1b7c5 100644 --- a/doc/source/stdlib/typemacro_boost.rst +++ b/doc/source/stdlib/typemacro_boost.rst @@ -284,6 +284,4 @@ Extracts a string constant or function address argument at the given index from .. das:function:: typemacro_argument(dimExpr: auto; index: int; constType: auto(ExprConstType); defaultValue: auto(ValueT)) : ValueT ----- - diff --git a/doc/source/stdlib/uriparser.rst b/doc/source/stdlib/uriparser.rst index 6782ba8502..2e53fa43ec 100644 --- a/doc/source/stdlib/uriparser.rst +++ b/doc/source/stdlib/uriparser.rst @@ -210,8 +210,6 @@ Creates a scoped ``Uri`` variable that is automatically finalized at end of bloc .. das:function:: using(arg0: block<(Uri#):void>) ----- - +++++++++++++++++++ Escape and unescape diff --git a/doc/source/stdlib/utf8_utils.rst b/doc/source/stdlib/utf8_utils.rst index c2cd8dc714..f7205d17e3 100644 --- a/doc/source/stdlib/utf8_utils.rst +++ b/doc/source/stdlib/utf8_utils.rst @@ -125,8 +125,6 @@ Converts UTF-32 string to UTF-8 and appends it to the UTF-8 byte array .. das:function:: utf8_encode(source_utf32_string: array) : array ----- - ++++++++++++++++++++++ Length and measurement @@ -152,8 +150,6 @@ Returns the number of characters in the UTF-8 string .. das:function:: utf8_length(utf8_string: array) : int ----- - ++++++++++ Validation @@ -210,6 +206,4 @@ Returns true if the byte array contains a valid UTF-8 encoded string. .. das:function:: is_utf8_string_valid(utf8_string: string) : bool ----- - From 48b5b87ada4451f3bdc6ed50376bd9a02f67f4cf Mon Sep 17 00:00:00 2001 From: Boris Batkin Date: Tue, 17 Feb 2026 17:46:03 -0800 Subject: [PATCH 6/6] pointer tutorial --- .github/copilot-instructions.md | 4 +- CLAUDE.md | 4 +- doc/source/reference/language.rst | 5 +- doc/source/reference/language/datatypes.rst | 3 +- doc/source/reference/language/pointers.rst | 311 ++++++++++++++++++ doc/source/reference/tutorials.rst | 1 + doc/source/reference/tutorials/35_jobque.rst | 2 + .../reference/tutorials/36_pointers.rst | 232 +++++++++++++ tests/language/pointers.das | 261 +++++++++++++++ tutorials/language/36_pointers.das | 298 +++++++++++++++++ 10 files changed, 1114 insertions(+), 7 deletions(-) create mode 100644 doc/source/reference/language/pointers.rst create mode 100644 doc/source/reference/tutorials/36_pointers.rst create mode 100644 tests/language/pointers.das create mode 100644 tutorials/language/36_pointers.das diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ef092a603c..49446974ba 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -178,7 +178,7 @@ When editing RST files in `doc/source/reference/language/`: - All code blocks use `.. code-block:: das` with gen2 syntax - Include `// output:` comments showing expected output for runnable examples - Add `require` statements when examples need imports -- Use `:ref:` cross-references to link between pages (labels: `_structs`, `_classes`, `_functions`, `_statements`, `_expressions`, `_arrays`, `_tables`, `_iterators`, `_generators`, `_lambdas`, `_blocks`, `_tuples`, `_variants`, `_bitfields`, `_aliases`, `_modules`, `_options`, `_unsafe`, `_enumerations`, `_generic_programming`, `_pattern-matching`, `_comprehensions`, `_string_builder`, `_macros`, `_reification`, `_finalizers`, `_clone`, `_temporary`, `_move_copy_clone`, `_annotations`, `_program_structure`, `_type_conversions`, `_contexts`, `_locks`, `_datatypes_and_values`) +- Use `:ref:` cross-references to link between pages (labels: `_structs`, `_classes`, `_functions`, `_statements`, `_expressions`, `_arrays`, `_tables`, `_iterators`, `_generators`, `_lambdas`, `_blocks`, `_tuples`, `_variants`, `_bitfields`, `_aliases`, `_modules`, `_options`, `_unsafe`, `_enumerations`, `_generic_programming`, `_pattern-matching`, `_comprehensions`, `_string_builder`, `_macros`, `_reification`, `_finalizers`, `_clone`, `_temporary`, `_move_copy_clone`, `_annotations`, `_program_structure`, `_type_conversions`, `_contexts`, `_locks`, `_datatypes_and_values`, `_pointers`) - Verify examples compile: `bin/Release/daslang.exe example.das` ### RST table rules @@ -247,7 +247,7 @@ C++ integration tutorial RST files live in `doc/source/reference/tutorials/` wit - Each tutorial is one self-contained `.cpp` file with embedded `main()` — no separate build infrastructure needed beyond CMake target - Tutorial CMake targets: `integration_cpp_01` through `integration_cpp_NN` (defined in `tutorials/integration/cpp/CMakeLists.txt`) -- Tutorial labels for cross-references: `tutorial_hello_world`, `tutorial_variables`, `tutorial_operators`, `tutorial_control_flow`, `tutorial_functions`, `tutorial_arrays`, `tutorial_strings`, `tutorial_structs`, `tutorial_enumerations`, `tutorial_tables`, `tutorial_tuples_and_variants`, `tutorial_function_pointers`, `tutorial_blocks`, `tutorial_lambdas`, `tutorial_iterators_and_generators`, `tutorial_modules`, `tutorial_move_copy_clone`, `tutorial_classes`, `tutorial_generics`, `tutorial_lifetime`, `tutorial_error_handling`, `tutorial_unsafe`, `tutorial_string_format`, `tutorial_pattern_matching`, `tutorial_annotations`, `tutorial_contracts`, `tutorial_testing`, `tutorial_linq`, `tutorial_functional`, `tutorial_json`, `tutorial_regex`, `tutorial_operator_overloading` +- Tutorial labels for cross-references: `tutorial_hello_world`, `tutorial_variables`, `tutorial_operators`, `tutorial_control_flow`, `tutorial_functions`, `tutorial_arrays`, `tutorial_strings`, `tutorial_structs`, `tutorial_enumerations`, `tutorial_tables`, `tutorial_tuples_and_variants`, `tutorial_function_pointers`, `tutorial_blocks`, `tutorial_lambdas`, `tutorial_iterators_and_generators`, `tutorial_modules`, `tutorial_move_copy_clone`, `tutorial_classes`, `tutorial_generics`, `tutorial_lifetime`, `tutorial_error_handling`, `tutorial_unsafe`, `tutorial_string_format`, `tutorial_pattern_matching`, `tutorial_annotations`, `tutorial_contracts`, `tutorial_testing`, `tutorial_linq`, `tutorial_functional`, `tutorial_json`, `tutorial_regex`, `tutorial_operator_overloading`, `tutorial_pointers` - C++ integration tutorial labels: `tutorial_integration_cpp_hello_world`, `tutorial_integration_cpp_calling_functions`, `tutorial_integration_cpp_binding_functions`, `tutorial_integration_cpp_binding_types`, `tutorial_integration_cpp_binding_enums`, `tutorial_integration_cpp_interop`, `tutorial_integration_cpp_callbacks`, `tutorial_integration_cpp_methods`, `tutorial_integration_cpp_operators_and_properties` - C++ integration tutorial plan (remaining): 10 Custom Modules, 11 Context Variables, 12 Smart Pointers & GC, 13 AOT, 14 Serialization, 15 Custom Annotations, 16 Sandbox diff --git a/CLAUDE.md b/CLAUDE.md index 4a870005b6..2bc8f3c357 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -178,7 +178,7 @@ When editing RST files in `doc/source/reference/language/`: - All code blocks use `.. code-block:: das` with gen2 syntax - Include `// output:` comments showing expected output for runnable examples - Add `require` statements when examples need imports -- Use `:ref:` cross-references to link between pages (labels: `_structs`, `_classes`, `_functions`, `_statements`, `_expressions`, `_arrays`, `_tables`, `_iterators`, `_generators`, `_lambdas`, `_blocks`, `_tuples`, `_variants`, `_bitfields`, `_aliases`, `_modules`, `_options`, `_unsafe`, `_enumerations`, `_generic_programming`, `_pattern-matching`, `_comprehensions`, `_string_builder`, `_macros`, `_reification`, `_finalizers`, `_clone`, `_temporary`, `_move_copy_clone`, `_annotations`, `_program_structure`, `_type_conversions`, `_contexts`, `_locks`, `_datatypes_and_values`) +- Use `:ref:` cross-references to link between pages (labels: `_structs`, `_classes`, `_functions`, `_statements`, `_expressions`, `_arrays`, `_tables`, `_iterators`, `_generators`, `_lambdas`, `_blocks`, `_tuples`, `_variants`, `_bitfields`, `_aliases`, `_modules`, `_options`, `_unsafe`, `_enumerations`, `_generic_programming`, `_pattern-matching`, `_comprehensions`, `_string_builder`, `_macros`, `_reification`, `_finalizers`, `_clone`, `_temporary`, `_move_copy_clone`, `_annotations`, `_program_structure`, `_type_conversions`, `_contexts`, `_locks`, `_datatypes_and_values`, `_pointers`) - Verify examples compile: `bin/Release/daslang.exe example.das` ### RST table rules @@ -247,7 +247,7 @@ C++ integration tutorial RST files live in `doc/source/reference/tutorials/` wit - Each tutorial is one self-contained `.cpp` file with embedded `main()` — no separate build infrastructure needed beyond CMake target - Tutorial CMake targets: `integration_cpp_01` through `integration_cpp_NN` (defined in `tutorials/integration/cpp/CMakeLists.txt`) -- Tutorial labels for cross-references: `tutorial_hello_world`, `tutorial_variables`, `tutorial_operators`, `tutorial_control_flow`, `tutorial_functions`, `tutorial_arrays`, `tutorial_strings`, `tutorial_structs`, `tutorial_enumerations`, `tutorial_tables`, `tutorial_tuples_and_variants`, `tutorial_function_pointers`, `tutorial_blocks`, `tutorial_lambdas`, `tutorial_iterators_and_generators`, `tutorial_modules`, `tutorial_move_copy_clone`, `tutorial_classes`, `tutorial_generics`, `tutorial_lifetime`, `tutorial_error_handling`, `tutorial_unsafe`, `tutorial_string_format`, `tutorial_pattern_matching`, `tutorial_annotations`, `tutorial_contracts`, `tutorial_testing`, `tutorial_linq`, `tutorial_functional`, `tutorial_json`, `tutorial_regex`, `tutorial_operator_overloading` +- Tutorial labels for cross-references: `tutorial_hello_world`, `tutorial_variables`, `tutorial_operators`, `tutorial_control_flow`, `tutorial_functions`, `tutorial_arrays`, `tutorial_strings`, `tutorial_structs`, `tutorial_enumerations`, `tutorial_tables`, `tutorial_tuples_and_variants`, `tutorial_function_pointers`, `tutorial_blocks`, `tutorial_lambdas`, `tutorial_iterators_and_generators`, `tutorial_modules`, `tutorial_move_copy_clone`, `tutorial_classes`, `tutorial_generics`, `tutorial_lifetime`, `tutorial_error_handling`, `tutorial_unsafe`, `tutorial_string_format`, `tutorial_pattern_matching`, `tutorial_annotations`, `tutorial_contracts`, `tutorial_testing`, `tutorial_linq`, `tutorial_functional`, `tutorial_json`, `tutorial_regex`, `tutorial_operator_overloading`, `tutorial_pointers` - C++ integration tutorial labels: `tutorial_integration_cpp_hello_world`, `tutorial_integration_cpp_calling_functions`, `tutorial_integration_cpp_binding_functions`, `tutorial_integration_cpp_binding_types`, `tutorial_integration_cpp_binding_enums`, `tutorial_integration_cpp_interop`, `tutorial_integration_cpp_callbacks`, `tutorial_integration_cpp_methods`, `tutorial_integration_cpp_operators_and_properties` - C++ integration tutorial plan (remaining): 10 Custom Modules, 11 Context Variables, 12 Smart Pointers & GC, 13 AOT, 14 Serialization, 15 Custom Annotations, 16 Sandbox diff --git a/doc/source/reference/language.rst b/doc/source/reference/language.rst index f4a13f6493..6daf05598c 100644 --- a/doc/source/reference/language.rst +++ b/doc/source/reference/language.rst @@ -8,6 +8,7 @@ language/program_structure.rst language/lexical_structure.rst language/datatypes.rst + language/pointers.rst language/constants_and_enumerations.rst language/statements.rst language/expressions.rst @@ -41,8 +42,8 @@ language/builtin_functions.rst ***************************** - The Runtime - ***************************** +The Runtime +***************************** .. toctree:: language/contexts.rst diff --git a/doc/source/reference/language/datatypes.rst b/doc/source/reference/language/datatypes.rst index fea3797670..1962fddec5 100644 --- a/doc/source/reference/language/datatypes.rst +++ b/doc/source/reference/language/datatypes.rst @@ -293,7 +293,8 @@ All structs are always passed to functions arguments as references. Pointers -------------- -Pointers are types that 'reference' (point to) some other data, but can be null (point to nothing). +Pointers are types that 'reference' (point to) some other data, but can be null (point to nothing) +(see :ref:`Pointers `). In order to work with actual value, one need to dereference it using the dereference or safe navigation operators. Dereferencing will panic if a null pointer is passed to it. Pointers can be created using the new operator, or with the C++ environment. diff --git a/doc/source/reference/language/pointers.rst b/doc/source/reference/language/pointers.rst new file mode 100644 index 0000000000..855082585c --- /dev/null +++ b/doc/source/reference/language/pointers.rst @@ -0,0 +1,311 @@ +.. _pointers: + +======== +Pointers +======== + +.. index:: + single: Pointers + +Daslang provides nullable pointer types for heap-allocated data, optional +references, and low-level memory access. Pointer operations split into +two categories: **safe** operations that work without ``unsafe``, and +**unsafe** operations that require an ``unsafe`` block. + +.. _pointer_types: + +-------------- +Pointer types +-------------- + +============= ===================================================== +Type Description +============= ===================================================== +``T?`` Nullable pointer to type ``T`` +``T? const`` Const pointer — cannot modify the pointed-to value +``T?#`` Temporary pointer (from ``safe_addr``) — cannot escape scope +``void?`` Untyped pointer — must ``reinterpret`` to use +============= ===================================================== + +Pointer types are declared by appending ``?`` to any type:: + + var p : int? // pointer to int — null by default + var ps : Point? // pointer to struct + var vp : void? // void pointer + +All pointers default to ``null`` when uninitialized. + +.. _pointer_creation: + +----------------- +Creating pointers +----------------- + +new +^^^ + +``new`` allocates on the heap and returns ``T?``:: + + var p = new Point(x = 3.0, y = 4.0) // p is Point? + var q = new Point() // default field values + +Heap pointers must be released with ``delete`` (see :ref:`pointer_delete`) +or declared with ``var inscope`` for automatic cleanup:: + + var inscope pt = new Point(x = 1.0, y = 2.0) + // pt is automatically deleted at scope exit + +addr +^^^^ + +``addr(x)`` returns a pointer to an existing variable. **Requires unsafe.** + +:: + + var x = 42 + unsafe { + var p = addr(x) // p is int? + *p = 100 // modifies x + } + +The pointer is valid only while the variable is alive — using it after +the variable goes out of scope is undefined behavior. + +safe_addr +^^^^^^^^^ + +``safe_addr`` from ``daslib/safe_addr`` returns a temporary pointer (``T?#``) +without requiring ``unsafe``. The compiler validates that the argument is a +local or global variable (not a field of a temporary):: + + require daslib/safe_addr + var a = 13 + var p = safe_addr(a) // p is int?# (temporary pointer) + print("{*p}\n") + +Temporary pointers cannot be stored in containers or returned from functions. + +.. _pointer_deref: + +-------------- +Dereferencing +-------------- + +``*p`` or ``deref(p)`` follows the pointer to the value. Both panic if the +pointer is null:: + + *p // dereference + deref(p) // same thing + +For struct pointers, ``.`` auto-dereferences — no ``->`` operator is needed:: + + var inscope pt = new Point(x = 5.0, y = 6.0) + print("{pt.x}\n") // 5 — same as (*pt).x + pt.x = 10.0 // modify through auto-deref + +.. _pointer_null_safety: + +----------- +Null safety +----------- + +Null checks +^^^^^^^^^^^ + +Pointers can be compared to ``null``:: + + if (p != null) { + print("{*p}\n") // safe — we checked + } + +Null dereference panics at runtime and can be caught with ``try``/``recover``:: + + try { + var np : int? + print("{*np}\n") + } recover { + print("caught null dereference\n") + } + +Safe navigation ``?.`` +^^^^^^^^^^^^^^^^^^^^^^ + +``?.`` returns ``null`` instead of panicking when the pointer is null:: + + p?.x // returns x if p is non-null, null otherwise + a?.b?.c // chains — short-circuits on first null + +Safe navigation results are themselves nullable, so combine with ``??`` +for a concrete fallback:: + + let val = p?.x ?? -1 // -1 if p is null + +Null coalescing ``??`` +^^^^^^^^^^^^^^^^^^^^^^ + +``??`` provides a default value when the left side is null:: + + let x = p ?? default_value + +For pointer dereference:: + + let x = *p ?? 0 // 0 if p is null + +.. _pointer_delete: + +-------- +Deletion +-------- + +``delete`` frees heap memory and sets the pointer to null. **Requires unsafe.** + +:: + + var p = new Point() + unsafe { + delete p // frees memory, p becomes null + } + +Prefer ``var inscope`` for automatic cleanup — it adds a ``finally`` block +that deletes the pointer when the scope exits:: + + var inscope p = new Point() + // p is automatically deleted at end of scope + +.. _pointer_arithmetic: + +------------------- +Pointer arithmetic +------------------- + +All pointer arithmetic **requires unsafe**. No bounds checking is performed. + +Indexing +^^^^^^^^ + +``p[i]`` accesses the ``i``-th element at the pointer's address:: + + var arr <- [10, 20, 30, 40, 50] + unsafe { + var p = addr(arr[0]) + print("{p[0]}, {p[2]}\n") // 10, 30 + } + +Increment and addition +^^^^^^^^^^^^^^^^^^^^^^ + +:: + + unsafe { + ++ p // advance pointer by one element + p += 3 // advance by three elements + } + +.. warning:: + + Pointer arithmetic can easily cause out-of-bounds access or invalid + pointer states. Use array bounds-checked access whenever possible. + +.. _pointer_void: + +-------------- +Void pointers +-------------- + +``void?`` is an untyped pointer — equivalent to ``void*`` in C/C++. It is +used for opaque handles and C/C++ interop. You must ``reinterpret`` it back +to a typed pointer before dereferencing:: + + unsafe { + var x = 123 + var px = addr(x) + var vp : void? = reinterpret px // erase type + var px2 = reinterpret vp // restore type + print("{*px2}\n") // 123 + } + +.. _pointer_intptr: + +------ +intptr +------ + +``intptr(p)`` converts any pointer (raw or smart) to a ``uint64`` integer +representing its memory address:: + + let address = intptr(p) // uint64 + +Useful for debugging, logging, pointer identity comparisons, or hashing. + +.. _pointer_reinterpret: + +----------- +reinterpret +----------- + +``reinterpret`` performs a raw bit cast between types of the same size. +**Requires unsafe.** It does not convert values — it reinterprets the raw bits:: + + unsafe { + let f = 1.0 + let bits = reinterpret f // IEEE 754: 0x3f800000 + let back = reinterpret bits // 1.0 + } + +Can also cast between pointer types:: + + unsafe { + var p : int? = addr(x) + var vp = reinterpret p // to void? + var p2 = reinterpret vp // back to int? + } + +.. _pointer_typeinfo: + +--------- +Type info +--------- + +Several ``typeinfo`` queries test pointer properties at compile time:: + + typeinfo(is_pointer p) // true if p is a pointer type + typeinfo(is_smart_ptr p) // true if p is a smart_ptr + typeinfo(is_void_pointer p) // true if p is void? + typeinfo(can_delete_ptr p) // true if delete is valid for p + +.. _pointer_summary: + +------- +Summary +------- + +**Safe (no unsafe required):** + +* ``new T()`` — heap allocate, returns ``T?`` +* ``*p`` / ``deref(p)`` — dereference (panics if null) +* ``p.field`` — auto-deref field access +* ``p?.field`` — safe navigation (null-propagating) +* ``p ?? default`` — null coalescing +* ``safe_addr(x)`` — temporary pointer (``T?#``) +* ``var inscope p = new T()`` — automatic cleanup +* ``intptr(p)`` — pointer to integer + +**Unsafe (requires unsafe block):** + +* ``addr(x)`` — address of variable +* ``delete p`` — free heap memory +* ``p[i]`` — pointer indexing +* ``++ p`` / ``p += N`` — pointer arithmetic +* ``reinterpret`` — raw bit cast + +.. seealso:: + + :ref:`Unsafe ` for the full list of unsafe operations. + + :ref:`Values and Data Types ` for smart pointers + (``smart_ptr``). + + :ref:`Temporary types ` for temporary pointers (``T?#``) and + ``safe_addr``. + + :ref:`Tutorial: Pointers ` for a hands-on walkthrough. diff --git a/doc/source/reference/tutorials.rst b/doc/source/reference/tutorials.rst index b5b5ab255c..b302d65aff 100644 --- a/doc/source/reference/tutorials.rst +++ b/doc/source/reference/tutorials.rst @@ -50,6 +50,7 @@ introduced in earlier tutorials. tutorials/33_algorithm.rst tutorials/34_decs.rst tutorials/35_jobque.rst + tutorials/36_pointers.rst C Integration Tutorials ----------------------- diff --git a/doc/source/reference/tutorials/35_jobque.rst b/doc/source/reference/tutorials/35_jobque.rst index 914d6772ee..6481764bb5 100644 --- a/doc/source/reference/tutorials/35_jobque.rst +++ b/doc/source/reference/tutorials/35_jobque.rst @@ -305,6 +305,8 @@ for long-lived work that should not block the job queue: Previous tutorial: :ref:`tutorial_decs` + Next tutorial: :ref:`tutorial_pointers` + :ref:`Lambda ` — lambda language reference. :ref:`Blocks ` — block language reference. diff --git a/doc/source/reference/tutorials/36_pointers.rst b/doc/source/reference/tutorials/36_pointers.rst new file mode 100644 index 0000000000..3376a37a18 --- /dev/null +++ b/doc/source/reference/tutorials/36_pointers.rst @@ -0,0 +1,232 @@ +.. _tutorial_pointers: + +======================== +Pointers +======================== + +.. index:: + single: Tutorial; Pointers + single: Tutorial; Addr + single: Tutorial; Safe Navigation + single: Tutorial; Void Pointer + single: Tutorial; Pointer Arithmetic + +This tutorial covers pointer types, creation, dereferencing, null safety, pointer +arithmetic, and low-level operations like ``reinterpret`` and ``intptr``. + +Pointer types +============= + +In daslang, ``T?`` is a nullable pointer to ``T``:: + + var p : int? // pointer to int — null by default + var ps : Point? // pointer to struct + var vp : void? // untyped (void) pointer + +Pointers are used for heap-allocated data, optional references, and +low-level interop. Unlike C/C++, field access auto-dereferences:: + + p.x // same as (*p).x — no -> operator needed + +Creating pointers with new +========================== + +``new`` allocates on the heap and returns a pointer:: + + var p = new Point(x = 3.0, y = 4.0) // p is Point? + +Fields get default values when omitted:: + + var q = new Point() // x = 0.0, y = 0.0 + +Heap pointers must be freed explicitly with ``delete`` (requires ``unsafe``), +or use ``var inscope`` for automatic cleanup:: + + var inscope pt = new Point(x = 1.0, y = 2.0) + // pt is automatically deleted when it goes out of scope + +addr and safe_addr +================== + +``addr(x)`` returns a pointer to an existing variable. It requires +``unsafe`` because the pointer could outlive the variable:: + + var x = 42 + unsafe { + var p = addr(x) // p is int? + *p = 100 // modifies x through the pointer + } + +``safe_addr`` from ``daslib/safe_addr`` returns a temporary pointer +(``T?#``) without requiring ``unsafe``:: + + require daslib/safe_addr + var a = 13 + var p = safe_addr(a) // p is int?# — safe, no unsafe needed + print("{*p}\n") + +Dereferencing +============= + +``*p`` and ``deref(p)`` follow the pointer to the value. +Both panic if the pointer is null:: + + unsafe { + var y = 7 + var p = addr(y) + print("{*p}\n") // 7 + print("{deref(p)}\n") // 7 + } + +For struct pointers, ``.`` auto-dereferences — no ``->`` operator:: + + var inscope pt = new Point(x = 5.0, y = 6.0) + print("{pt.x}\n") // 5 — same as (*pt).x + +Null safety +=========== + +Uninitialized pointers are null. Dereferencing null panics:: + + var np : int? // null + try { + print("{*np}\n") + } recover { + print("null deref caught\n") + } + +Use null checks, safe navigation, or null coalescing to handle nullable pointers +safely: + +.. code-block:: das + + options gen2 + + struct Point { + x : float + y : float + } + + def get_x(p : Point?) : float { + return p?.x ?? -1.0 // -1.0 if p is null + } + +``?.`` returns null if the pointer is null (no panic). +``??`` provides a fallback value when the left side is null. + +Passing pointers to functions +============================= + +Pointers can be passed as function arguments. Functions can read from and +write through them:: + + def double_value(p : int?) { + *p = *p + *p + } + + var val = 21 + unsafe { + double_value(addr(val)) + } + print("{val}\n") // 42 + +Struct pointer arguments auto-deref for field access:: + + def move_point(p : Point?; dx : float; dy : float) { + p.x += dx // auto-deref + p.y += dy + } + +Deletion +======== + +``delete`` frees heap memory and sets the pointer to null. +Requires ``unsafe``:: + + var p = new Point(x = 1.0, y = 2.0) + unsafe { + delete p // memory freed, p is now null + } + +Prefer ``var inscope`` over manual ``delete`` — it adds a ``finally`` +block that automatically cleans up the pointer when the scope exits. + +Pointer arithmetic +================== + +Pointer indexing and arithmetic are unsafe. They operate on raw memory +with no bounds checking:: + + var arr <- [10, 20, 30, 40, 50] + unsafe { + var p = addr(arr[0]) + print("{p[0]}, {p[2]}\n") // 10, 30 + + ++ p // advance by one element + print("{*p}\n") // 20 + + p += 2 // advance by two more + print("{*p}\n") // 40 + } + +.. warning:: + + Pointer arithmetic can easily cause out-of-bounds access. + No runtime bounds checking is performed. + +void pointers +============= + +``void?`` is an untyped pointer — equivalent to ``void*`` in C. +Used for C/C++ interop where the actual type is opaque. +Must ``reinterpret`` back to a typed pointer before use:: + + unsafe { + var x = 123 + var px = addr(x) + var vp : void? = reinterpret px // erase type + var px2 = reinterpret vp // restore type + print("{*px2}\n") // 123 + } + +intptr +====== + +``intptr(p)`` converts a pointer to a ``uint64`` integer representing its +memory address. Useful for debugging, logging, or identity comparisons:: + + unsafe { + var x = 42 + var p = addr(x) + print("address: {intptr(p)}\n") + } + +reinterpret +=========== + +``reinterpret`` performs a raw bit cast between types of the same size. +Requires ``unsafe``:: + + unsafe { + let f = 1.0 + let bits = reinterpret f // IEEE 754: 0x3f800000 + let back = reinterpret bits + print("{back}\n") // 1 + } + +.. warning:: + + ``reinterpret`` does not convert values — it reinterprets raw bits. + The source and target types must have the same size. + +.. seealso:: + + :ref:`Pointers ` — pointer language reference. + + :ref:`Unsafe ` — unsafe operations reference. + + :ref:`Values and Data Types ` — all data types including smart pointers. + + Full source: :download:`tutorials/language/36_pointers.das <../../../../tutorials/language/36_pointers.das>` + + Previous tutorial: :ref:`tutorial_jobque` diff --git a/tests/language/pointers.das b/tests/language/pointers.das new file mode 100644 index 0000000000..dd26468562 --- /dev/null +++ b/tests/language/pointers.das @@ -0,0 +1,261 @@ +options gen2 +options no_unused_function_arguments = false +options no_unused_block_arguments = false + +require dastest/testing_boost public + +require daslib/safe_addr + +struct TestStruct { + x : int = 10 + y : int = 20 +} + +[test] +def test_new_and_fields(t : T?) { + t |> run("new with fields") <| @(t : T?) { + var p = new TestStruct(x = 5, y = 7) + t |> equal(p.x, 5) + t |> equal(p.y, 7) + unsafe { + delete p + } + } + t |> run("new default") <| @(t : T?) { + var p = new TestStruct() + t |> equal(p.x, 10) + t |> equal(p.y, 20) + unsafe { + delete p + } + } + t |> run("auto-deref field access") <| @(t : T?) { + unsafe { + var inscope p = new TestStruct(x = 42, y = 99) + // p.x auto-dereferences the pointer — no -> needed + t |> equal(p.x, 42) + t |> equal(p.y, 99) + } + } + t |> run("modify through pointer") <| @(t : T?) { + unsafe { + var inscope p = new TestStruct(x = 1, y = 2) + p.x = 100 + p.y = 200 + t |> equal(p.x, 100) + t |> equal(p.y, 200) + } + } +} + +[test] +def test_addr_and_deref(t : T?) { + t |> run("addr and deref") <| @(t : T?) { + var x = 42 + unsafe { + var p = addr(x) + t |> equal(*p, 42) + t |> equal(deref(p), 42) + } + } + t |> run("modify through addr") <| @(t : T?) { + var x = 10 + unsafe { + var p = addr(x) + *p = 99 + } + t |> equal(x, 99) + } + t |> run("addr of struct field") <| @(t : T?) { + var s = TestStruct(x = 7, y = 8) + unsafe { + var px = addr(s.x) + t |> equal(*px, 7) + *px = 77 + } + t |> equal(s.x, 77) + } +} + +[test] +def test_safe_addr(t : T?) { + t |> run("safe_addr local") <| @(t : T?) { + var a = 55 + var pa = safe_addr(a) // returns int?# (temporary pointer) + t |> equal(*pa, 55) + } + t |> run("safe_addr modify") <| @(t : T?) { + var b = 10 + var pb = safe_addr(b) + *pb = 20 + t |> equal(b, 20) + } +} + +[test] +def test_null_pointer(t : T?) { + t |> run("null default") <| @(t : T?) { + var p : int? + t |> equal(p == null, true) + t |> equal(p != null, false) + } + t |> run("non-null check") <| @(t : T?) { + var x = 42 + var p = unsafe(addr(x)) + t |> equal(p != null, true) + t |> equal(p == null, false) + } + t |> run("null deref requires unsafe") <| @(t : T?) { + // Dereferencing null requires unsafe — we just verify null state + var p : int? + t |> equal(p == null, true) + } +} + +[test] +def test_safe_navigation(t : T?) { + t |> run("?. on valid pointer") <| @(t : T?) { + unsafe { + var inscope p = new TestStruct(x = 42, y = 99) + t |> equal(p?.x ?? -1, 42) + t |> equal(p?.y ?? -1, 99) + } + } + t |> run("?. on null pointer") <| @(t : T?) { + var p : TestStruct? + t |> equal(p?.x ?? -1, -1) + t |> equal(p?.y ?? -1, -1) + } + t |> run("?? null coalescing on int?") <| @(t : T?) { + var x = 42 + var p = unsafe(addr(x)) + var q : int? + if (p != null) { + t |> equal(*p, 42) + } + t |> equal(q == null, true) + } +} + + +[test] +def test_pointer_indexing(t : T?) { + t |> run("index into array via pointer") <| @(t : T?) { + var arr <- [10, 20, 30, 40, 50] + unsafe { + var p = addr(arr[0]) + t |> equal(p[0], 10) + t |> equal(p[1], 20) + t |> equal(p[2], 30) + t |> equal(p[3], 40) + t |> equal(p[4], 50) + } + } + t |> run("write through pointer index") <| @(t : T?) { + var arr <- [1, 2, 3] + unsafe { + var p = addr(arr[0]) + p[1] = 99 + } + t |> equal(arr[1], 99) + } +} + +[test] +def test_pointer_arithmetic(t : T?) { + t |> run("pointer increment") <| @(t : T?) { + var arr <- [10, 20, 30, 40, 50] + unsafe { + var p = addr(arr[0]) + t |> equal(*p, 10) + ++ p + t |> equal(*p, 20) + ++ p + t |> equal(*p, 30) + } + } + t |> run("pointer += N") <| @(t : T?) { + var arr <- [10, 20, 30, 40, 50] + unsafe { + var p = addr(arr[0]) + p += 3 + t |> equal(*p, 40) + p += 1 + t |> equal(*p, 50) + } + } +} + +[test] +def test_intptr(t : T?) { + t |> run("intptr non-zero") <| @(t : T?) { + var x = 42 + unsafe { + var p = addr(x) + let address = intptr(p) + t |> equal(address != uint64(0), true) + } + } + t |> run("intptr same pointer same value") <| @(t : T?) { + var x = 42 + unsafe { + var p = addr(x) + t |> equal(intptr(p), intptr(p)) + } + } + t |> run("intptr different pointers differ") <| @(t : T?) { + var x = 1 + var y = 2 + unsafe { + var px = addr(x) + var py = addr(y) + t |> equal(intptr(px) != intptr(py), true) + } + } +} + +[test] +def test_reinterpret(t : T?) { + t |> run("float to int roundtrip") <| @(t : T?) { + unsafe { + let f = 1.0 + let bits = reinterpret f + t |> equal(bits, int(0x3F800000)) // IEEE 754 for 1.0 + let back = reinterpret bits + t |> equal(back, 1.0) + } + } +} + +[test] +def test_void_pointer(t : T?) { + t |> run("roundtrip through void?") <| @(t : T?) { + var x = 42 + unsafe { + var p = addr(x) + var vp : void? = reinterpret p + var p2 = reinterpret vp + t |> equal(*p2, 42) + } + } +} + +[test] +def test_delete(t : T?) { + t |> run("delete sets null") <| @(t : T?) { + var p = new TestStruct(x = 1, y = 2) + t |> equal(p != null, true) + unsafe { + delete p + } + t |> equal(p == null, true) + } + t |> run("var inscope auto-deletes") <| @(t : T?) { + // var inscope p = new ... — p is deleted at scope exit + // We just verify it works without crash + unsafe { + var inscope p = new TestStruct(x = 5, y = 6) + t |> equal(p.x, 5) + } + } +} diff --git a/tutorials/language/36_pointers.das b/tutorials/language/36_pointers.das new file mode 100644 index 0000000000..84f359bfc2 --- /dev/null +++ b/tutorials/language/36_pointers.das @@ -0,0 +1,298 @@ +// Tutorial 36: Pointers +// +// This tutorial covers: +// - Pointer types (T?, void?) +// - Creating pointers: new, addr(), safe_addr() +// - Dereferencing: *, deref(), auto-deref for fields +// - Null safety: null checks, ?., ??, ?[, try/recover +// - Passing pointers to functions +// - Heap allocation and deletion +// - Pointer arithmetic and indexing +// - intptr() — pointer to integer +// - reinterpret — raw bit reinterpretation +// +// Run: daslang.exe tutorials/language/36_pointers.das + +options gen2 + +require daslib/safe_addr + +struct Point { + x : float + y : float +} + +// A function that takes a pointer to a struct +def move_point(var p : Point?; dx, dy : float) : Point? { + if (p != null) { + p.x += dx // auto-deref: no -> needed, just use . + p.y += dy + } + return p +} + +// A function that takes a pointer to an int and modifies it +def double_value(var p : int?) { + *p = *p + *p +} + +[export] +def main() { + + // === Pointer types === + // + // In daslang, T? is a pointer to T. Pointers can be null. + // int? — pointer to int + // Point? — pointer to Point struct + // void? — untyped (void) pointer + // + // Pointers to structs are common — new always returns T?. + + // === Creating pointers with new === + // + // The new operator allocates on the heap and returns a pointer. + + print("=== new ===\n") + var p = new Point(x = 3.0, y = 4.0) + print(" p.x = {p.x}, p.y = {p.y}\n") // auto-deref on field access + + // new with no arguments — fields get default values (zero) + var q = new Point() + print(" q.x = {q.x}, q.y = {q.y}\n") + + // Don't forget to clean up heap allocations (or use var inscope) + unsafe { + delete p + delete q + } + + // === var inscope — automatic cleanup === + // + // var inscope adds a finally block that deletes the pointer + // when it goes out of scope. No manual delete needed. + + print("=== var inscope ===\n") + unsafe { + var inscope pt = new Point(x = 1.0, y = 2.0) + print(" pt.x = {pt.x}, pt.y = {pt.y}\n") + // pt is automatically deleted at end of scope + } + + // === addr() — pointer to existing variable === + // + // addr(x) returns a pointer to variable x. + // Requires unsafe because the pointer could outlive the variable. + + print("=== addr ===\n") + var a = 42 + unsafe { + var pa = addr(a) // pa is int? + print(" *pa = {*pa}\n") + *pa = 100 // modify through pointer + print(" a = {a}\n") // a is now 100 + } + + // === safe_addr() — without unsafe === + // + // safe_addr from daslib/safe_addr returns a temporary pointer (T?#) + // that is safe to use within the current scope, no unsafe needed. + + print("=== safe_addr ===\n") + var b = 77 + var pb = safe_addr(b) // pb is int?# (temporary pointer) + print(" *pb = {*pb}\n") + + // === Dereferencing === + // + // *p and deref(p) follow the pointer to the value. + // They panic if the pointer is null. + + print("=== deref ===\n") + unsafe { + var c = 5 + var pc = addr(c) + print(" *pc = {*pc}\n") + print(" deref(pc) = {deref(pc)}\n") + } + + // For struct pointers, field access auto-dereferences: + // p.x is the same as (*p).x + // No -> operator needed (unlike C/C++). + + // === Null pointers === + // + // Uninitialized pointers are null (zero). + // Dereferencing null panics. + + print("=== null ===\n") + var np : int? // null by default + print(" np is null: {np == null}\n") + + // Catch null dereference with try/recover: + try { + unsafe { + print(" {*np}\n") // panics — np is null + } + } recover { + print(" caught null deref\n") + } + + // === Safe navigation: ?. and ?? === + // + // ?. returns null if the pointer is null (no panic). + // ?? provides a default value when the left side is null. + + print("=== safe navigation ===\n") + var sp = new Point(x = 10.0, y = 20.0) + var nullp : Point? + + print(" sp?.x = {sp?.x ?? -1.0}\n") // 10.0 + print(" nullp?.x = {nullp?.x ?? -1.0}\n") // -1.0 (default) + + // ?. works on chains: + // a?.b?.c ?? default + + // === Passing pointers to functions === + + print("=== pointer args ===\n") + var pt2 = new Point(x = 1.0, y = 2.0) + move_point(pt2, 3.0, 4.0) + print(" after move: pt2.x = {pt2.x}, pt2.y = {pt2.y}\n") + + var val = 21 + unsafe { + double_value(addr(val)) + } + print(" after double: val = {val}\n") + + // === Pointer arithmetic (unsafe) === + // + // Pointers can index into contiguous memory and be incremented. + // All pointer arithmetic requires unsafe. + + print("=== pointer arithmetic ===\n") + var arr <- [10, 20, 30, 40, 50] + unsafe { + var parr = addr(arr[0]) + // Index into pointer + print(" parr[0] = {parr[0]}\n") + print(" parr[2] = {parr[2]}\n") + print(" parr[4] = {parr[4]}\n") + + // Pointer increment + ++ parr // advance by one element + print(" after ++: *parr = {*parr}\n") // 20 + + // Pointer addition + parr += 2 // advance by two more elements + print(" after +=2: *parr = {*parr}\n") // 40 + } + + // === void? — untyped pointer === + // + // void? is a raw pointer with no type information. + // Useful for interfacing with C/C++ APIs. + // Must reinterpret back to a typed pointer to use. + + print("=== void pointer ===\n") + var d = 123 + unsafe { + var pd = addr(d) + var vp : void? = reinterpret pd // erase type + var pd2 = reinterpret vp // restore type + print(" *pd2 = {*pd2}\n") + } + + // === intptr() — pointer to integer === + // + // intptr(p) converts a pointer to a uint64 representing its address. + // Useful for debugging, hashing, or identity comparisons. + + print("=== intptr ===\n") + var e = 42 + unsafe { + var pe = addr(e) + let address = intptr(pe) + print(" address != 0: {address != uint64(0)}\n") + print(" same pointer: {intptr(pe) == address}\n") + } + + // === reinterpret — raw bit cast === + // + // reinterpret re-reads the raw bits as a different type. + // Types must be the same size. Extremely dangerous. + + print("=== reinterpret ===\n") + unsafe { + let float_val = 1.0 + let int_bits = reinterpret float_val + print(" 1.0 as int bits: 0x{int_bits:08x}\n") // IEEE 754: 0x3f800000 + + let back = reinterpret int_bits + print(" back to float: {back}\n") + } + + // === Summary === + // + // Type | Meaning + // -----------|---------------------------- + // int? | Pointer to int (nullable) + // Point? | Pointer to struct (nullable) + // void? | Untyped pointer + // T?# | Temporary pointer (safe_addr) + // + // Operation | Requires unsafe? + // ----------------|------------------ + // new T() | No + // *p / deref(p) | No (panics if null) + // p.field | No (auto-deref) + // p?.field | No (safe navigation) + // p ?? default | No (null coalescing) + // addr(x) | Yes + // delete p | Yes + // p[i] | Yes + // ++p / p += N | Yes + // reinterpret | Yes + // safe_addr(x) | No (returns T?#) + + print("done\n") +} + +// output: +// === new === +// p.x = 3, p.y = 4 +// q.x = 0, q.y = 0 +// === var inscope === +// pt.x = 1, pt.y = 2 +// === addr === +// *pa = 42 +// a = 100 +// === safe_addr === +// *pb = 77 +// === deref === +// *pc = 5 +// deref(pc) = 5 +// === null === +// np is null: true +// caught null deref +// === safe navigation === +// sp?.x = 10 +// nullp?.x = -1 +// === pointer args === +// after move: pt2.x = 4, pt2.y = 6 +// after double: val = 42 +// === pointer arithmetic === +// parr[0] = 10 +// parr[2] = 30 +// parr[4] = 50 +// after ++: *parr = 20 +// after +=2: *parr = 40 +// === void pointer === +// *pd2 = 123 +// === intptr === +// address != 0: true +// same pointer: true +// === reinterpret === +// 1.0 as int bits: 0x3f800000 +// back to float: 1 +// done