Added missing @throws in Twig_LoaderInterface

Based on Twig_Loader_Chain implementation, this seems to be the possible exceptions that can be thrown by loaders.
Added @return doc on Twig_LoaderInterface->isFresh()
merged branch andrerom/patch-1 (PR #658)

Commits
-------

be07174 Added @return doc on Twig_LoaderInterface->isFresh()
8315992 Added missing @throws in Twig_LoaderInterface

Discussion
----------

Added missing @throws in Twig_LoaderInterface

Based on Twig_Loader_Chain implementation, this seems to be the possible exception that can be thrown by loaders.
Added a trim filter

Closes #634
Updated 'convert_encoding' filter documentation
merged branch raulfraile/patch-1 (PR #665)

Commits
-------

0519419 Updated 'convert_encoding' filter documentation

Discussion
----------

Updated 'convert_encoding' filter documentation

Updated 'convert_encoding' filter documentation to clarify which extension will be used in case both `iconv` and `mbstring` are installed.
merged branch stof/trim_filter (PR #662)

Commits
-------

d942d11 Added a trim filter

Discussion
----------

Added a trim filter

This adds a trim filter in Twig as most people thought it deserves being in the core rather than in the extensions.

Closes #634

---------------------------------------------------------------------------

by fabpot at 2012-03-13T16:47:15Z

I would have added a second option to control whether you trim on both side, only on the left, or only the right. What do you think?

---------------------------------------------------------------------------

by nikic at 2012-03-13T17:15:43Z

@fabpot In that case I'd rather add two additional functions `trim_left` (mapping to `ltrim`) and `trim_right` (mapping to `rtrim`). Should be more obvious than some flag at the end :)

---------------------------------------------------------------------------

by stof at 2012-03-13T18:47:38Z

I tend to think that separate filters would indeed be more obvious. What do you prefer @fabpot ?

And for the flag, how would you specify the option to use ? Using a string ? Using boolean flags is not appropriate here (as we have 3 meaningful cases) and I don't really like the string solution.

---------------------------------------------------------------------------

by fabpot at 2012-03-13T18:53:08Z

I don't like the idea of having 3 different filter just for trimming. That seems overkill to me.

---------------------------------------------------------------------------

by stof at 2012-03-13T19:14:12Z

which API do you suggest for the filter then ?

---------------------------------------------------------------------------

by fabpot at 2012-03-13T19:23:51Z

I've no definitive idea. So, perhaps we can just merge what you've done for now.

---------------------------------------------------------------------------

by Koc at 2012-03-13T20:17:17Z

+1 for merge this. There are different filters for different trimming.

I cannot remember but there are some situations when we got string with whitespaces in variable and `{{- my_variable -}}` couldn't help and we cann't use `spaceless` filter because `my_vaiable` contains not html for example.

upd: oh, sorry, I haven't noticed comment from @nikic .

---------------------------------------------------------------------------

by Tobion at 2012-03-13T21:05:09Z

I suggest `function trim($left = true, $right = true)` but `left` and `right` could also be strings.
That would cover all cases.

---------------------------------------------------------------------------

by raulfraile at 2012-03-13T23:43:28Z

I think 3 different filters would be much clearer than using string/boolean parameters. IMO is the same case than strtolower/strtoupper.
fixed the date filter when a DateTime instance is passed with a specific timezone (closes #660)