Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
create_string [2026/08/20 02:01]
hermann 		create_string [2026/08/28 03:17] (current)
hermann Sync from local documentation review
Line 3: Line 3:
 ===== Description ===== ===== Description =====
  
-''​Create String''​ is a **container** functor that builds an output string from a format string and a set of connected ​values or strings, substituting each connected item into the format string at the position of its tag. It is part of the calculator family in the sense that it accepts hook functors ​([[number_value|Number Value]], [[number_string|Number String]]) placed inside it, but unlike [[calculate_value|Calculate Value]] and the other calculator functors, it does not take a bracketed algebraic expression ​— ''​format'' ​is a plain string containing literal text plus numbered, type-prefixed tags.+This container builds an output string from a format string and a set of values or strings ​identified by [[Number Value]] and [[Number String]] functors placed inside it, substituting each one into the format string at the position of its tag. It accepts hook functors ​the same way the calculator functors do, but unlike [[Calculate Value]] and the other calculator functors, it does not take a bracketed algebraic expression: Format ​is a plain string containing literal text plus numbered, type-prefixed tags.
  
 ===== Inputs ===== ===== Inputs =====
  
-^ Name ^ Type ^ Description ^ +^ Name  ^ Type  ^ Description ​ ^ 
-| Format | [[string_type|String Type]] | The format ​string used to generate the output string, built from literal text plus tags that reference ​connected ​hook functors: ''​<vN>''​ for the Nth connected ​[[number_value|Number Value]], ''<​sN>''​ for the Nth connected ​[[number_string|Number String]]. A numeric tag can add padding, or padding and precision together, as ''​<vN,padding>''​ or ''​<vN,​padding,​precision>''​. See Notes for worked examples. |+| Format ​ | [[String Type]] ​ | Format ​string used to generate the output string, built from literal text plus tags that reference ​the hook functors ​placed inside this container: <v''​N''​> for the [[Number Value]] ​whose Value Number is ''​N'', ​<s''​N''> ​for the [[Number String]] ​whose Value Number is ''​N''​. A numeric tag can also add padding, or padding and precision together, as <​v''​N'',​''​padding''​> or <​v''​N'',​''​padding''​,''​precision''​>. See Notes for worked examples. ​ | 
 + 
 +===== Optional Inputs ===== 
 + 
 +None.
  
 ===== Outputs ===== ===== Outputs =====
  
-^ Name ^ Type ^ Description ^ +^ Name  ^ Type  ^ Description ​ ^ 
-| Result | [[string_type|String Type]] | The string ​generated by substituting the connected ​values/strings into the format string. |+| Result ​ | [[String Type]] ​ | String ​generated by substituting the identified ​values ​and strings into the format string. ​ |
  
 ===== Group ===== ===== Group =====
  
-[[functor_list#map_algebra|Map Algebra]]+[[Functor List#Map Algebra ​| Map Algebra]]
  
 ===== Notes ===== ===== Notes =====
  
-==== Hooks and tag syntax ====+Every placeholder used in the format string must have a matching [[Number Value]] or [[Number String]] instance inside this container with the same number; otherwise the model raises an error. Conversely, an instance of [[Number Value]] or [[Number String]] placed inside this container but not referenced by any placeholder in the format string reports a warning.
  
-Like the calculator functors, ''​Create String''​ takes its data through hook functors placed inside it — [[number_value|Number Value]] ​for numbers, ​[[number_string|Number String]] ​for strings — each assigned a number that the format string references by its tag (''<​v1>'',​ ''<​s1>'',​ and so on). This is the same verbose-form hook mechanism used by expression-based calculators (see [[ego_script#​verbose_form|Verbose form]]), except the reference sits inside a literal format string rather than an algebraic expression, and there is no separate abbreviated-syntax form for ''​Create String''​.+Two instances of [[Number Value]] ​or [[Number String]] ​placed inside this container cannot share the same Value Number; doing so raises ​an error.
  
-==== Format examples ====+To include a literal "<"​ in the format string without starting a placeholder,​ escape it as "​\<"​.
  
-  * ''​cities_<​v1>''​ with a Number Value of ''​87'' ​produces ​''​"​cities_87"​''​. +Examples: ​''​cities_<​v1>''​ with a Number Value of 87 produces "​cities_87"​. ''​capitals_<​v1,​0,​3>''​ with a value of 1.2 (padding 0, precision 3) produces "​capitals_1.200"​. ''​cities_<​v1,​4>''​ with a value of 1 (padding 4, no precision) produces "​cities_0001"​. ''​big_<​s1>''​ with a Number String of "​city"​ produces "​big_city"​. ''​cities_\<<​v1>>''​ with a value of 87 produces "​cities_<​87>" ​-- the backslash before "<" ​turns it into a literal character instead of starting a tag.
-  * ''​capitals_<​v1,​0,​3>''​ with a value of ''​1.2'' ​(padding ​''​0''​, precision ​''​3''​) produces ​''​"​capitals_1.200"​''​. +
-  * ''​cities_<​v1,​4>''​ with a value of ''​1'' ​(padding ​''​4''​, no precision) produces ​''​"​cities_0001"​''​. +
-  * ''​big_<​s1>''​ with a Number String of ''​"​city"​'' ​produces ​''​"​big_city"​''​. +
-  * ''​cities_\<<​v1>>''​ with a value of ''​87'' ​produces ​''​"​cities_<​87>"​''​ — prefixing ''​<''​ with a backslash ​turns it into a literal character instead of starting a tag.+
  
 ===== Internal Name ===== ===== Internal Name =====
  
-''​CreateString''​+CreateString
  
 ===== Usage examples ===== ===== Usage examples =====
  
-  * [[manipulating_tables_and_lookup_tables#​iterating_over_lookup_table_values|Iterating over Lookup Table values]] ​— builds a per-row message from a table'​s key and value using ''​<v1>''​/''​<v2>'' ​tags. +  * [[Manipulating Tables and Lookup Tables#​iterating_over_lookup_table_values|Iterating over Lookup Table values]] ​-- builds a per-row message from a table'​s key and value using <​v1>/<​v2>​ tags. 
-  * [[ego_script#​container_functors|Container functors]] in the EGO Script documentation ​— uses ''​Create String'' ​with ''​Number Value'' ​to embed a computed result inside a message printed after a block completes.+  * [[EGO Script#​container_functors|Container functors]] in the EGO Script documentation ​-- uses Create String with Number Value to embed a computed result inside a message printed after a block completes.