From 801c63a34e4859d509c1533899d6b181b0117d2c Mon Sep 17 00:00:00 2001
From: Hartmut Holzgraefe <hholzgra@php.net>
Date: Wed, 18 Sep 2002 07:56:17 +0000
Subject: [PATCH] documentation for new optional calling convention

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@96031 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/strings/functions/setlocale.xml | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/reference/strings/functions/setlocale.xml b/reference/strings/functions/setlocale.xml
index b7bb9bb148..83e55e6bc0 100644
--- a/reference/strings/functions/setlocale.xml
+++ b/reference/strings/functions/setlocale.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
   <refentry id="function.setlocale">
    <refnamediv>
@@ -12,6 +12,12 @@
       <type>string</type><methodname>setlocale</methodname>
       <methodparam><type>mixed</type><parameter>category</parameter></methodparam>
       <methodparam><type>string</type><parameter>locale</parameter></methodparam>
+      <methodparam choice='opt'><type>string</type><parameter>...</parameter></methodparam>
+     </methodsynopsis>
+     <methodsynopsis>
+      <type>string</type><methodname>setlocale</methodname>
+      <methodparam><type>mixed</type><parameter>category</parameter></methodparam>
+      <methodparam><type>array</type><parameter>locale</parameter></methodparam>
      </methodsynopsis>
     <para>
      <parameter>Category</parameter> is a named constant (or string)
@@ -60,9 +66,17 @@
      categories, or from "LANG".
     </para>
     <para>
-     If locale is zero or <literal>"0"</literal>, the locale setting
+     If <parameter>locale</parameter> is zero or <literal>"0"</literal>, the locale setting
      is not affected, only the current setting is returned.
     </para>
+    <para>
+     If <parameter>locale</parameter> is an array or followed by additional
+     parameters then each array element or parameter is tried to be set as
+     new locale until success. This is usefull if a locale is known under
+     different names on different systems or for providing a fallback 
+     for a possibly not available locale.
+    <note><simpara>Passing multiple locales is not available before PHP 4.3</simpara></note>
+    </para>
     <para>
      Setlocale returns the new current locale, or &false; if the locale
      functionality is not implemented in the platform, the specified
@@ -80,6 +94,10 @@
 
     /* Output: vrijdag 22 december 1978 */
     echo strftime ("%A %e %B %Y", mktime (0, 0, 0, 12, 22, 1978));
+
+    /* try different possible locale names for german */
+    $loc_de = setlocale (LC_ALL, 'de_DE@euro', 'de_DE', 'de', 'ge');
+    echo "Preferred locale for german on this system is '$loc_de';
 ?>
 ]]>
       </programlisting>