Manual: Clarified that container in FTL are immutable.
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/5f418218 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/5f418218 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/5f418218 Branch: refs/heads/2.3 Commit: 5f418218b7669573baeca8e53cb08f1b5fd6d57a Parents: 649d85d Author: ddekany <[email protected]> Authored: Wed Mar 15 11:38:13 2017 +0100 Committer: ddekany <[email protected]> Committed: Wed Mar 15 11:38:13 2017 +0100 ---------------------------------------------------------------------- src/manual/en_US/book.xml | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/5f418218/src/manual/en_US/book.xml ---------------------------------------------------------------------- diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml index 5673870..beab00d 100644 --- a/src/manual/en_US/book.xml +++ b/src/manual/en_US/book.xml @@ -1406,6 +1406,15 @@ brown</programlisting> <para>The data-model itself (or better said the root of it) is a hash.</para> + + <para>FreeMarker templates don't support modifying the contents of + containers (such as adding, removing or replacing sub variables), + and it assumes that their content won't change during template + processing. (But you can make new container values by adding + together two existing container values with <literal>+</literal>; + see that in the <link linkend="exp_cheatsheet">chapter about + expressions</link>, and please note the performance + consequences.)</para> </section> <section> @@ -3079,11 +3088,12 @@ CDEF</programlisting> repeated concatenations, like for appending items to a sequence inside a loop. It's just for things like <literal><#list users + admins as person></literal>. Although concatenating sequences - is fast and its speed is independently of the size of the - concatenated sequences, the resulting sequence will be always a - little bit slower to read than the original two sequences were. - This way the result of many repeated concatenations is a sequence - that is slow to read.</para> + is fast and is constant time (it's speed is independently of the + size of the concatenated sequences), the resulting sequence will + be always a little bit slower to read than the original two + sequences were. Thus, after tens or hundreds of repeated + concatenations the result can be impractically slow to + reader.</para> </section> <section xml:id="dgui_template_exp_seqenceop_slice"> @@ -3232,9 +3242,11 @@ Slicing with right-unlimited ranges: <para>Note that hash concatenation is not to be used for many repeated concatenations, like for adding items to a hash inside a - loop. It's the same as with the <link - linkend="dgui_template_exp_sequenceop_cat">sequence - concatenation</link>.</para> + loop. While adding together hashes is fast and is constant time + (independent of the size of the hashes added), the resulting hash + is a bit slower to read than the hashes added together. Thus after + tens or hundreds of additions the result can be impractically slow + to read.</para> </section> </section> @@ -18622,8 +18634,17 @@ or string literal does not expand interpolations (as <literal>"${foo}"</literal>); if you need to assign to a dynamically constructed name, the you have to use <link - linkend="faq_assign_to_dynamic_variable_name">this - trick</link>.</para> + linkend="faq_assign_to_dynamic_variable_name">a different + trick</link>. Note that because the FreeMarker template language + assumes that sequences (lists, arrays, etc.) and hashes (maps, + beans, etc.) are immutable, you can <emphasis>not</emphasis> + write something like <literal><#assign myObj.someProperty = + 'will NOT work'></literal> or <literal><#assign myList[0] + = 'will NOT work'></literal>. However, adding sequences or + hashes with the <literal>+</literal> operator to form another + value is supported; see in the <link + linkend="exp_cheatsheet">chapter about expressions</link>, and + please note the performance consequences.</para> </listitem> <listitem>
