Differences

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

Link to this comparison view

Next revision 		Previous revision
create_string [2011/07/31 17:42]
hermann created 		create_string [2026/08/28 03:17] (current)
hermann Sync from local documentation review
Line 1: Line 1:
-====== Create String ====== ​+====== Create String ======
  
 ===== Description ===== ===== Description =====
  
-This functor generates ​a string ​based on contained parameters ​and a pre-defined ​format string.+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  ​]]  | The format ​string, used to generate the final string. ​ |+| 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 ===== ===== Optional Inputs =====
 +
 +None.
  
 ===== Outputs ===== ===== Outputs =====
  
-^ Name ^ Type ^ Description ^ +^ Name  ^ Type  ^ Description ​ ^ 
-| Result ​ | [[ String Type|String  ​]]  | The string ​generated by this functor.  |+| Result ​ | [[String Type]] ​ | String ​generated by substituting the identified values and strings into the format string.  |
  
 ===== Group ===== ===== Group =====
Line 21: Line 23:
 [[Functor List#Map Algebra | Map Algebra]] [[Functor List#Map Algebra | Map Algebra]]
  
-===== Notes ===== +===== Notes =====
  
-The output ​string ​is built from "​blocks ​of strings" ​inside the format string.+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.
  
-For example, if you want  an output ​ string "​cities_87",​ where 87 is a number that comes from the [[Step]] functor, ​ you need to write the format string as: \\ +Two instances of [[Number Value]] or [[Number ​String]] placed ​inside ​this container ​cannot share the same Value Number; doing so raises an error.
-cities_<​v1>​ where v1 represents a [[Number ​Value]] functor ​inside ​the "​Create String" ​container.+
  
-Likewise, if you want to output ​a string ​"capitals_1.200", the format ​will be: \\ +To include ​a literal ​"<" ​in the format ​string without starting a placeholder,​ escape it as "\<".
-capitals_<v1,0,3>, where 1.2 comes the number value with a precision of 3 digits.+
  
-For a valid format, such as string ​"cities_0001", ​the format will be cities<​v1,​4> ​where 4 is the padding number.+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.
  
-Also you can replace parts of the input string with other strings, such as "​big_city"​. In this case, the format string will be:<​br>​ +===== Internal Name =====
-big_<​s1>​ where  s1 represents a Number String functor within the "​Create String"​ container. +
- +
-You can prefix "<"​ with a backslash ("​\"​) to turn it into an ordinary character. For exemple, if you want  an output ​ string "​cities_<​87>",​ where 87 comes from another functor, you need to write the format string as: \\ +
-cities_\<<​v1>>​ +
-  +
-===== Internal Name ===== +
  
 CreateString CreateString
 +
 +===== 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.
 +  * [[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.