You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2017/03/15 12:31:47 UTC
[05/10] incubator-freemarker git commit: Manual: Clarified that
container in FTL are immutable.
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 <dd...@apache.org>
Authored: Wed Mar 15 11:38:13 2017 +0100
Committer: ddekany <dd...@apache.org>
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>