[ci skip] Add compatibility functions documentation + Sphinx build fixes for Cart

4 files changed, 180 insertions, 22 deletions

diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index d4f882064..ca31669e8 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -506,7 +506,7 @@ Release Date: Not Released
       -  ``UTF8_ENABLED`` now requires only one of `Multibyte String <http://php.net/mbstring>`_ or `iconv <http://php.net/iconv>`_ to be available instead of both.
       -  Changed method ``clean_string()`` to utilize ``mb_convert_encoding()`` if it is available but ``iconv()`` is not.
 
-   -  Added compatibility layers for PHP's `mbstring <http://php.net/mbstring>`_ (limited support) and `password <http://php.net/password>`_ extensions.
+   -  Added `compatibility layers <general/compatibility_functions>` for PHP's `mbstring <http://php.net/mbstring>`_ (limited support) and `password <http://php.net/password>`_ extensions.
    -  Removed ``CI_CORE`` boolean constant from *CodeIgniter.php* (no longer Reactor and Core versions).
    -  Log Library will now try to create the **log_path** directory if it doesn't exist.
    -  Added support for HTTP-Only cookies with new config option *cookie_httponly* (default FALSE).
diff --git a/user_guide_src/source/general/compatibility_functions.rst b/user_guide_src/source/general/compatibility_functions.rst
new file mode 100644
index 000000000..e025d2aa3
--- /dev/null
+++ b/user_guide_src/source/general/compatibility_functions.rst
@@ -0,0 +1,157 @@
+#######################
+Compatibility Functions
+#######################
+
+CodeIgniter provides a set of compatibility functions that enable
+you to use functions what are otherwise natively available in PHP,
+but only in higher versions or depending on a certain extension.
+
+Being custom implementations, these functions will also have some
+set of dependancies on their own, but are still useful if your
+PHP setup doesn't offer them natively.
+
+.. note:: Much like the `common functions <common_functions>`, the
+	compatibility functions are always available, as long as
+	their dependancies are met.
+
+.. contents::
+  :local:
+
+.. raw:: html
+
+  <div class="custom-index container"></div>
+
+****************
+Password Hashing
+****************
+
+This set of compatibility functions offers a "backport" of PHP's
+standard `Password Hashing extension <http://php.net/password>`_
+that is otherwise available only since PHP 5.5.
+
+Dependancies
+============
+
+- PHP 5.3.7
+- ``CRYPT_BLOWFISH`` support for ``crypt()``
+
+Constants
+=========
+
+- ``PASSWORD_BCRYPT``
+- ``PASSWORD_DEFAULT``
+
+Function reference
+==================
+
+.. function:: password_get_info($hash)
+
+	:param	string	$hash: Password hash
+	:returns:	Information about the hashed password
+	:rtype:	array
+
+	For more information, please refer to the `PHP manual for
+	password_get_info() <http://php.net/password_get_info>`_.
+
+.. function:: password_hash($password, $algo[, $options = array()])
+
+	:param	string	$password: Plain-text password
+	:param	int	$algo: Hashing algorithm
+	:param	array	$options: Hashing options
+	:returns:	Hashed password or FALSE on failure
+	:rtype:	string
+
+	For more information, please refer to the `PHP manual for
+	password_hash() <http://php.net/password_hash>`_.
+
+	.. note:: Unless you provide your own (and valid) salt, this function
+		has a further dependancy on an available CSPRNG source. Each
+		of the following would satisfy that:
+		- ``mcrypt_create_iv()`` with ``MCRYPT_DEV_URANDOM``
+		- ``openssl_random_pseudo_bytes()``
+		- /dev/arandom
+		- /dev/urandom
+
+.. function:: password_needs_rehash()
+
+	:param	string	$hash: Password hash
+	:param	int	$algo: Hashing algorithm
+	:param	array	$options: Hashing options
+	:returns:	TRUE if the hash should be rehashed to match the given algorithm and options, FALSE otherwise
+	:rtype:	bool
+
+	For more information, please refer to the `PHP manual for
+	password_needs_rehash() <http://php.net/password_needs_rehash>`_.
+
+.. function:: password_verify($password, $hash)
+
+	:param	string	$password: Plain-text password
+	:param	string	$hash: Password hash
+	:returns:	TRUE if the password matches the hash, FALSE if not
+	:rtype:	bool
+
+	For more information, please refer to the `PHP manual for
+	password_verify() <http://php.net/password_verify>`_.
+
+****************
+Multibyte String
+****************
+
+This set of compatibility functions offers limited support for PHP's
+`Multibyte String extension <http://php.net/mbstring>`_. Because of
+the limited alternative solutions, only a few functions are available.
+
+.. note:: When a character set parameter is ommited,
+	``$config['charset']`` will be used.
+
+Dependancies
+============
+
+- `iconv <http://php.net/iconv>`_ extension
+
+.. important:: This dependancy is optional and these functions will
+	always be declared. If iconv is not available, they WILL
+	fall-back to their non-mbstring versions.
+
+.. important:: Where a character set is supplied, it must be
+	supported by iconv and in a format that it recognizes.
+
+.. note:: For you own dependancy check on the actual mbstring
+	extension, use the ``MB_ENABLED`` constant.
+
+Function reference
+==================
+
+.. function:: mb_strlen($str[, $encoding = NULL])
+
+	:param	string	$str: Input string
+	:param	string	$encoding: Character set
+	:returns:	Number of characters in the input string or FALSE on failure
+	:rtype:	string
+
+	For more information, please refer to the `PHP manual for
+	mb_strlen() <http://php.net/mb_strlen>`_.
+
+.. function:: mb_strpos($haystack, $needle[, $offset = 0[, $encoding = NULL]])
+
+	:param	string	$haystack: String to search in
+	:param	string	$needle: Part of string to search for
+	:param	int	$offset: Search offset
+	:param	string	$encoding: Character set
+	:returns:	Numeric character position of where $needle was found or FALSE if not found
+	:rtype:	mixed
+
+	For more information, please refer to the `PHP manual for
+	mb_strpos() <http://php.net/mb_strpos>`_.
+
+.. function:: mb_substr($str, $start[, $length = NULL[, $encoding = NULL]])
+
+	:param	string	$str: Input string
+	:param	int	$start: Position of first character
+	:param	int	$length: Maximum number of characters
+	:param	string	$encoding: Character set
+	:returns:	Portion of $str specified by $start and $length or FALSE on failure
+	:rtype:	string
+
+	For more information, please refer to the `PHP manual for
+	mb_substr() <http://php.net/mb_substr>`_.
\ No newline at end of file
diff --git a/user_guide_src/source/general/index.rst b/user_guide_src/source/general/index.rst
index 2bc684a1d..195c4a98a 100644
--- a/user_guide_src/source/general/index.rst
+++ b/user_guide_src/source/general/index.rst
@@ -20,6 +20,7 @@ General Topics
 	hooks
 	autoloader
 	common_functions
+	compatibility_functions
 	routing
 	errors
 	Caching <caching>
diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst
index 8a473b49d..d7d495967 100644
--- a/user_guide_src/source/libraries/cart.rst
+++ b/user_guide_src/source/libraries/cart.rst
@@ -114,26 +114,26 @@ same page.
 ::
 
 	$data = array(
-	               array(
-	                       'id'      => 'sku_123ABC',
-	                       'qty'     => 1,
-	                       'price'   => 39.95,
-	                       'name'    => 'T-Shirt',
-	                       'options' => array('Size' => 'L', 'Color' => 'Red')
-	                    ),
-	               array(
-	                       'id'      => 'sku_567ZYX',
-	                       'qty'     => 1,
-	                       'price'   => 9.95,
-	                       'name'    => 'Coffee Mug'
-	                    ),
-	               array(
-	                       'id'      => 'sku_965QRS',
-	                       'qty'     => 1,
-	                       'price'   => 29.95,
-	                       'name'    => 'Shot Glass'
-	                    )
-	            );
+		array(
+			'id'      => 'sku_123ABC',
+			'qty'     => 1,
+			'price'   => 39.95,
+			'name'    => 'T-Shirt',
+			'options' => array('Size' => 'L', 'Color' => 'Red')
+		),
+		array(
+			'id'      => 'sku_567ZYX',
+			'qty'     => 1,
+			'price'   => 9.95,
+			'name'    => 'Coffee Mug'
+		),
+		array(
+			'id'      => 'sku_965QRS',
+			'qty'     => 1,
+			'price'   => 29.95,
+			'name'    => 'Shot Glass'
+		)
+	);
 
 	$this->cart->insert($data);
 
@@ -206,7 +206,7 @@ Updating The Cart
 
 To update the information in your cart, you must pass an array
 containing the Row ID and quantity to the ``$this->cart->update()``
-method::
+method.
 
 .. note:: If the quantity is set to zero, the item will be removed from
 	the cart.