From df565f98e69fb0a0732deb4e1508990da5b5fc14 Mon Sep 17 00:00:00 2001 From: lacatoire Date: Sun, 31 May 2026 19:38:11 +0200 Subject: [PATCH] [Sync EN] sscanf/fscanf: Clarify negative -1 return value (#5580) Refs: php/doc-en@9947012f745f0fb6e083bce5a8c920213ff468b7 Closes: #703 --- reference/filesystem/functions/fscanf.xml | 108 +++++++++---------- reference/spl/splfileobject/fscanf.xml | 88 +++++++-------- reference/strings/functions/sscanf.xml | 125 +++++++++++----------- 3 files changed, 157 insertions(+), 164 deletions(-) diff --git a/reference/filesystem/functions/fscanf.xml b/reference/filesystem/functions/fscanf.xml index 236b7e0b2..e0deb1857 100644 --- a/reference/filesystem/functions/fscanf.xml +++ b/reference/filesystem/functions/fscanf.xml @@ -1,6 +1,5 @@ - - + @@ -16,67 +15,69 @@ stringformat mixedvars - + La función fscanf es similar a la función sscanf, excepto que toma un archivo como entrada, representado por el recurso stream e interpreta la entrada según el formato format especificado. - - + + Todos los caracteres en blanco de la cadena de formato corresponden a tantos espacios en el flujo de entrada. Esto significa que una tabulación (\t) en la cadena de formato puede reemplazar un espacio simple en el flujo de entrada. - - + + Cada llamada a la función fscanf lee una línea del archivo. - + &reftitle.parameters; - - - - stream - - &fs.file.pointer; - - - &strings.scanf.parameter.format; - - vars - - - Los valores opcionales a asignar. - - - - - + + + stream + + &fs.file.pointer; + + + &strings.scanf.parameter.format; + + vars + + + Los valores opcionales a asignar. + + + + &reftitle.returnvalues; - + Si solo se pasan 2 argumentos a la función, el valor analizado - será devuelto en forma de un array. Si se pasan argumentos opcionales, + será devuelto como un array. Si se pasan argumentos opcionales, la función devolverá el número de valores asignados. Los argumentos opcionales deben ser pasados por referencia. - - + + Si se esperan más subcadenas en el format de las disponibles en string, &null; será devuelto. En otros casos de error, &false; será devuelto. - + + + Cuando se usan parámetros opcionales y se alcanza el final de la entrada + leída de stream antes de que se haya analizado + ningún valor, se devuelve -1. + &reftitle.examples; - - - Ejemplo con <function>fscanf</function> - + + Ejemplo con <function>fscanf</function> + ]]> - - - - - - Contenido del archivo users.txt - + + + + Contenido del archivo users.txt + - - - + + &reftitle.seealso; - - - fread - fgets - fgetss - sscanf - printf - sprintf - - + + fread + fgets + fgetss + sscanf + printf + sprintf + diff --git a/reference/spl/splfileobject/fscanf.xml b/reference/spl/splfileobject/fscanf.xml index 22a54ecff..017d60df1 100644 --- a/reference/spl/splfileobject/fscanf.xml +++ b/reference/spl/splfileobject/fscanf.xml @@ -1,5 +1,5 @@ - + @@ -14,82 +14,84 @@ stringformat mixedvars - + Lee una línea de el fichero e interpreta este de acuerdo a el format. - - + + Cualquier espacio en blanco en el format string coincide con cualquier espacio en blanco en la línea de el fichero. Esto significa que incluso un (\t) en el formato string puede coincidir con un sólo caracter de espacio en la secuencia de entrada. - + &reftitle.parameters; - - - &strings.scanf.parameter.format; - - vars - - - Los valores opcionales asignados. - - - - - + + &strings.scanf.parameter.format; + + vars + + + Los valores opcionales asignados. + + + + &reftitle.returnvalues; - + Si sólo se pasa un parámetro a este método, los valores analizados serán devueltos - como un array. De lo contrario, si se paran los parámetros opcionales, la función - devolverá el número de valores asignados. Los parámetros opcionales deben ser pasados - por referencia. - + como un array. De lo contrario, si se pasan los parámetros opcionales, + el método devolverá el número de valores asignados. Los parámetros opcionales deben + ser pasados por referencia. + + + Si se esperan más subcadenas en el format de las disponibles + en la línea leída del fichero, se devuelve &null;. + + + Cuando se usan parámetros opcionales y se alcanza el final de la línea leída del + fichero antes de que se haya analizado ningún valor, se devuelve -1. + &reftitle.examples; - - - Ejemplo de <methodname>SplFileObject::fscanf</methodname> - + + Ejemplo de <methodname>SplFileObject::fscanf</methodname> + fscanf("%s %s %s")) { - list ($nombre, $profesion, $codigopais) = $usuarioinfo; - // Operar con $name $profession $countrycode + list ($nombre, $profesion, $codigopais) = $usuarioinfo; + // Operar con $name $profession $countrycode } ?> ]]> - - Contenido de usuarios.txt - + + Contenido de usuarios.txt + - - - + + &reftitle.seealso; - - - fscanf - sscanf - printf - sprintf - - + + fscanf + sscanf + printf + sprintf + diff --git a/reference/strings/functions/sscanf.xml b/reference/strings/functions/sscanf.xml index 8f27b4f57..42bbeb976 100644 --- a/reference/strings/functions/sscanf.xml +++ b/reference/strings/functions/sscanf.xml @@ -1,6 +1,5 @@ - - + @@ -16,68 +15,69 @@ stringformat mixedvars - + sscanf es la función inversa de printf. sscanf lee datos de la cadena string e los interpreta según el formato format. - - + + Todos los caracteres en blanco en la cadena format corresponden a un carácter en blanco en la cadena string. Esto significa que incluso una tabulación (\t) en la cadena de formato puede corresponder a un simple espacio en la cadena str. - + &reftitle.parameters; - - - - string - - - La cadena a analizar. - - - - &strings.scanf.parameter.format; - - vars - - - Opcionalmente, se pueden pasar variables en este parámetro, - por referencia que contendrán los valores del análisis. - - - - - + + + string + + + La cadena a analizar. + + + + &strings.scanf.parameter.format; + + vars + + + Opcionalmente, se pueden pasar variables en este parámetro, + por referencia que contendrán los valores del análisis. + + + + &reftitle.returnvalues; - + Si solo se proporcionan dos parámetros, los valores encontrados - se devolverán como un array. De lo contrario, si se proporcionan los parámetros - opcionales, la función devolverá el número de - valores asignados. El parámetro opcional debe pasarse por - referencia. - - + se devolverán como un array. De lo contrario, si se proporcionan + los parámetros opcionales, la función devolverá el número de + valores asignados. El parámetro opcional debe pasarse por referencia. + + Si hay más subcadenas esperadas en el parámetro format que las disponibles en string, entonces &null; será devuelto. - + + + Cuando se usan parámetros opcionales y se alcanza el final de la cadena + de entrada string antes de que se haya analizado + ningún valor, se devuelve -1. + &reftitle.examples; - - - Ejemplo con <function>sscanf</function> - + + Ejemplo con <function>sscanf</function> + ]]> - - - - + + + Si se pasan parámetros opcionales, sscanf devolverá el número de valores asignados. - - - - <function>sscanf</function> - uso de parámetros opcionales - + + + <function>sscanf</function> - uso de parámetros opcionales + \n"; ?> ]]> - - - + + &reftitle.seealso; - - - printf - sprintf - fprintf - vprintf - vsprintf - vfprintf - fscanf - number_format - date - - + + printf + sprintf + fprintf + vprintf + vsprintf + vfprintf + fscanf + number_format + date +