std::filesystem::path
Definido en el archivo de encabezado <filesystem> | ||
class path; | (desde C++17) | |
Los objetos de tipo path representan rutas de acceso en un sistema de archivo. Solo se manejan los aspectos sintácticos de las rutas de acceso: el nombre de la ruta puede representar una ruta que no existe o incluso una que no puede existir en el sistema de archivos o sistema operativo actual.
El nombre de la ruta de acceso tiene la siguiente sintaxis:
- nombre-raíz(opcional): Identifica la raíz en un sistema de archivos con múltiples raíces (como "C:" o "//myserver"). En caso de ambigüedad, la secuencia más larga de caracteres que forma un nombre-raíz se trata como el nombre-raíz. La biblioteca estándar puede definir nombres-raíz adicionales a los comprendidos por la API del sistema operativo.
- directorio-raíz(opcional): Un separador de directorio que, si está presente, marca esta ruta como absoluta. Si falta (y el primer elemento que no sea el nombre raíz es un nombre de archivo), entonces la ruta es relativa y requiere otra ruta como ubicación de inicio para resolver a un nombre de archivo.
- Cero o más de los siguientes:
- nombre-de-archivo: Una secuencia de caracteres que no son separadores de directorio o separadores de directorio preferidos (el sistema operativo o el sistema de archivos pueden imponer limitaciones adicionales). Este nombre puede identificar un archivo, un vínculo físico, un vínculo simbólico o un directorio. Se reconocen dos nombre-de-archivo especiales:
- punto: El nombre del archivo que consta de un solo carácter de punto . es un nombre de directorio que se refiere al directorio actual.
- punto-punto: El nombre del archivo que consta de dos caracteres de punto .. es un nombre de directorio que se refiere al directorio padre.
- separador-de-directorios: El carácter de barra inclinada / o el carácter alternativo proporcionado como
path::preferred_separator. Si este carácter se repite, se trata como un único separador de directorio: /usr///////lib es lo mismo que /usr/lib
Una ruta de acceso puede ser normalizada siguiendo este algoritmo:
- Si la ruta está vacía, detenerse (la forma normal de una ruta vacía es una ruta vacía).
- Reemplazar cada separador-de-directorio (que puede constar de varias barras inclinadas) con un solo
path::preferred_separator. - Reemplazar cada carácter de barra inclinada en el nombre-raíz con
path::preferred_separator. - Eliminar cada punto y cualquier separador-de-directorio inmediatamente siguiente.
- Eliminar cada carácter que no es el nombre de archivo punto-punto inmediatamente seguido por un separador-de-directorio y un punto-punto, junto con cualquier separador-de-directorio inmediatamente siguiente.
- Si hay un directorio-raíz, eliminar todos los punto-punto y cualquier separador-de-directorio que los siguen inmediatamente.
- Si el último nombre de archivo es punto-punto, eliminar los separador-de-directorio finales.
- Si la ruta de acceso está vacía, agregar un punto (la forma normal de ./ es .)
La ruta de acceso se puede recorrer elemento por elemento mediante iteradores devueltos por las funciones begin() y end(), que visualizan la ruta en formato genérico e iteran sobre el nombre raíz, directorio raíz, y los elementos de nombre de archivo subsiguientes (se omiten los separadores de directorio excepto el que identifica el directorio raíz). Si el último elemento de la ruta es un separador de directorio, el último iterador eliminará la referencia a un elemento vacío.
Llamar a cualquier función miembro no constante de un objeto path invalida todos los iteradores que se refieren a elementos de ese objeto.
Si el sistema operativo usa una sintaxis nativa que es diferente de la sintaxis portátil genérica descrita anteriormente, las funciones de biblioteca que están definidas para aceptar el "formato detectado" aceptan nombres de ruta de acceso en ambos formatos: se toma un argumento de formato detectado estar en el formato genérico si y solo si coincide con el formato genérico pero no es aceptable para el sistema operativo como ruta de acceso nativa. En aquellos sistemas operativos donde el formato nativo difiere entre los nombres de ruta de los directorios y los nombres de ruta de los archivos, un nombre de ruta de acceso genérico se trata como una ruta de directorio si termina en un separador de directorio y un archivo normal en caso contrario.
En cualquier caso, la clase std::path se comporta como si almacenara un nombre de ruta de acceso en el formato nativo y se convierte automáticamente al formato genérico según sea necesario (cada función miembro especifica en qué formato interpreta la ruta).
En los sistemas POSIX, el formato genérico es el formato nativo y no es necesario distinguirlos ni convertirlos.
Las rutas de acceso se pueden convertir implícitamente hacia y desde std::basic_strings, lo que hace posible su uso con otras API de archivos.
Los operadores de flujo usan std::quoted para que los espacios no causen truncamiento cuando luego los lea el operador de entrada de flujo.
Descomposición de funciones miembro (por ejemplo, extension) devuelve objetos filesystem::path en lugar de objetos cadena como lo hacen otras API.
Contenido |
[editar]Tipos miembro y constantes
| Tipo | Definición | ||||||||
value_type | Tipo de carácter utilizado por la codificación nativa del sistema de archivos: char en POSIX, wchar_t en Windows | ||||||||
string_type | std::basic_string<value_type> | ||||||||
const_iterator | Una constante BidirectionalIterator con un value_type de path, excepto que para iteradores desreferenciables a y b de tipo path::iterator con a == b, no hay un requerimiento que *a y *b estén vinculados al mismo objeto. | ||||||||
iterator | Un alias a const_iterator. | ||||||||
| Determina cómo interpretar las representaciones de cadenas de nombres de ruta de acceso. También se definen los siguientes enumeradores:
(enum) |
[editar]Constantes miembro
constexpr value_type preferred_separator [estático] | El separador de directorio alternativo que se puede utilizar además del portátil /. En Windows, este es el carácter de barra invertida \. En POSIX, esta es la misma barra inclinada / que el separador portátil. (constante miembro pública estática) |
[editar]Funciones miembro
| Construye una ruta de acceso. (función miembro pública) | |
| Destruye un objeto ruta de acceso. (función miembro pública) | |
| Asigna otra ruta de acceso. (función miembro pública) | |
| Asigna el contenido. (función miembro pública) | |
Concatenación | |
| Agrega elementos a la ruta de acceso con un separador de directorio. (función miembro pública) | |
| Concatena dos rutas de acceso sin introducir un separador de directorio. (función miembro pública) | |
Modificadores | |
| Borra el contenido. (función miembro pública) | |
| Convierte los separadores de directorio al separador de directorio preferido. (función miembro pública) | |
| Remueve el componente de nombre de archivo de la ruta de acceso. (función miembro pública) | |
| Reemplaza el último componente de la ruta de acceso con otra ruta de acceso. (función miembro pública) | |
| Reemplaza la extensión. (función miembro pública) | |
| Intercambia dos rutas de acceso. (función miembro pública) | |
Observadores de formato | |
| Devuelve la versión nativa de la ruta de acceso. (función miembro pública) | |
| Devuelve la ruta de acceso en un nombre de ruta de acceso convertido a una cadena. (función miembro pública) | |
| Devuelve la ruta de acceso en formato de nombre de ruta de acceso genérico convertido en una cadena. (función miembro pública) | |
Comparación | |
| Compara las representaciones lexicográficas de dos rutas de acceso lexicográficamente. (función miembro pública) | |
Generación | |
| Convierte la ruta de acceso a la forma normal. Convierte la ruta de acceso a la forma relativa. Convierte la ruta de acceso a la forma aproximada. (función miembro pública) | |
Descomposición | |
| Devuelve el nombre-raíz de la ruta de acceso si está presente. (función miembro pública) | |
| Devuelve el directorio-raíz de la ruta de acceso si está presente. (función miembro pública) | |
| Devuelve la ruta de acceso de la raíz si está presente en la ruta de acceso. (función miembro pública) | |
| Devuelve la ruta de acceso relativa a la ruta de acceso raíz. (función miembro pública) | |
| Devuelve la ruta de acceso de la ruta de acceso padre. (función miembro pública) | |
| Devuelve el componente de nombre de archivo de la ruta de acceso. (función miembro pública) | |
| Devuelve el componente del pie de la ruta de acceso (el nombre de archivo sin la extensión final). (función miembro pública) | |
| Devuelve el componente de extensión de archivo de la ruta de acceso. (función miembro pública) | |
Consultas | |
| Comprueba si la ruta de acceso está vacía (función miembro pública) | |
| Comprueba si el elemento correspondiente de la ruta de acceso no está vacío. (función miembro pública) | |
| Comprueba si root_path() identifica de forma exclusiva la ubicación del sistema de archivos. (función miembro pública) | |
Iteradores | |
| Acceso de iterador a la ruta de acceso como una secuencia de elementos. (función miembro pública) | |
[editar]Funciones no miembro
| Intercambia dos rutas de acceso (función) | |
| Calcula el valor de dispersión para un objeto ruta de acceso. (función) | |
(hasta C++20)(hasta C++20)(hasta C++20)(hasta C++20)(hasta C++20)(C++20) | Compara lexicográficamente dos rutas de acceso. (función) |
| Concatena dos rutas de acceso con un separador de directorio. (función) | |
| Realiza entrada y salida de flujo en una ruta de acceso con comillas. (función) | |
(C++17)(en desuso en C++20) | Crea una ruta de acceso a partir de una fuente codificada en UTF-8. (función) |
