feature #3895 [Validator] Support "maxSize" given in KiB (jeremy-deru…

…sse)

This PR was merged into the master branch.

Discussion
----------

[Validator] Support "maxSize" given in KiB

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | symfony/symfony#11027
| Applies to    | 2.6
| Fixed tickets | symfony/symfony#10962

To display the constraint validation message with an expected suffix, this PR add a new option in  File constraint.

Commits
-------

1e8fa48 Replace bullet list by a table
77a0687 Add versionAdded on binary suffix
b414f5c Use comma as thousands separator
7dcd7c3 Move secion "binaryFormat" to the right place
71fdd60 Fix line wrap
3f3f4e0 Provide information about SI and Binary prefixes
deac0c3 Add option binaryFormat in constraint file
e3acdc5 Support MaxSize in KiB and MiB

reference/constraints/File.rst

@@ -20,6 +20,7 @@ form type.
 | Applies to     | :ref:`property or method <validation-property-target>`              |
 +----------------+---------------------------------------------------------------------+
 | Options        | - `maxSize`_                                                        |
+|                | - `binaryFormat`_                                                   |
 |                | - `mimeTypes`_                                                      |
 |                | - `maxSizeMessage`_                                                 |
 |                | - `mimeTypesMessage`_                                               |
@@ -79,7 +80,6 @@ below a certain file size and a valid PDF, add the following:
                         maxSize: 1024k
                         mimeTypes: [application/pdf, application/x-pdf]
                         mimeTypesMessage: Please upload a valid PDF
-                        
 
     .. code-block:: php-annotations
 
@@ -155,19 +155,46 @@ Options
 maxSize
 ~~~~~~~
 
+.. versionadded:: 2.6
+    The suffixes ``Ki`` and ``Mi`` were introduced in Symfony 2.6.
+
 **type**: ``mixed``
 
 If set, the size of the underlying file must be below this file size in order
 to be valid. The size of the file can be given in one of the following formats:
 
-* **bytes**: To specify the ``maxSize`` in bytes, pass a value that is entirely
-  numeric (e.g. ``4096``);
++--------+-----------+-----------------+------+
+| Suffix | Unit Name |      value      | e.g. |
++========+===========+=================+======+
+|        | byte      |          1 byte | 4096 |
++--------+-----------+-----------------+------+
+| k      | kilobyte  |     1,000 bytes | 200k |
++--------+-----------+-----------------+------+
+| M      | megabyte  | 1,000,000 bytes |   2M |
++--------+-----------+-----------------+------+
+| Ki     | kibibyte  |     1,024 bytes | 32Ki |
++--------+-----------+-----------------+------+
+| Mi     | mebibyte  | 1,048,576 bytes |  8Mi |
++--------+-----------+-----------------+------+
+
+For more information about the difference between binary and SI suffixes,
+see `Wikipedia: Binary prefix`_.
+
+binaryFormat
+~~~~~~~~~~~~
+
+.. versionadded:: 2.6
+    The ``binaryFormat`` option was introduced in Symfony 2.6.
+
+**type**: ``boolean`` **default**: ``null``
 
-* **kilobytes**: To specify the ``maxSize`` in kilobytes, pass a number and
-  suffix it with a lowercase "k" (e.g. ``200k``);
+When ``true``, the sizes will be displayed in messages with binary suffixes
+(KiB, MiB). When ``false``, the sizes will be displayed with SI suffixes (kB,
+MB). When ``null``, then the binaryFormat will be guessed from the suffix
+defined in the ``maxSize`` option.
 
-* **megabytes**: To specify the ``maxSize`` in megabytes, pass a number and
-  suffix it with a capital "M" (e.g. ``4M``).
+For more information about the difference between binary and SI suffixes,
+see `Wikipedia: Binary prefix`_.
 
 mimeTypes
 ~~~~~~~~~
@@ -251,3 +278,4 @@ to disk.
 
 
 .. _`IANA website`: http://www.iana.org/assignments/media-types/index.html
+.. _`Wikipedia: Binary prefix`: http://en.wikipedia.org/wiki/Binary_prefix