Classe path

A classe path armazena um objeto do tipo string_type, chamado myname aqui para fins de explicação, adequada para uso como um nome de caminho. string_type é um sinônimo para basic_string<value_type>, em que value_type é um sinônimo para wchar_t no Windows ou char em POSIX.

A path classe descrita aqui é a classe C++17 std::filesystem::path no <filesystem> cabeçalho.

Para obter mais informações e exemplos de código, consulte Navegação do Sistema de Arquivos (C++).

Sintaxe

class path;

Construtores

Typedefs

Enumerations

Funções de membro

Operadores

Requisitos

Cabeçalho: <filesystem>

Namespace: std::filesystem

path::append

Acrescenta a sequência especificada a myname, convertida e inserindo um preferred_separator conforme necessário.

template <class Source>
path& append(const Source& source);

template <class InIt>
path& append(InIt first, InIt last);

Parâmetros

source
A sequência especificada.

first
O início da sequência especificada.

last
O fim da sequência especificada.

path::assign

Substitui myname com a sequência especificada, convertida conforme necessário.

path& assign(string_type&& source);

template <class Source>
path& assign(const Source& source);

template <class InIt>
path& assign(InIt first, InIt last);

Parâmetros

source
A sequência especificada.

first
O início da sequência especificada.

last
O fim da sequência especificada.

path::begin

Retorna um path::iterator designando o primeiro elemento de caminho no nome do caminho, se existir.

iterator begin() const;

path::c_str

Retorna um ponteiro para o primeiro caractere em myname.

const value_type* c_str() const noexcept;

path::clear

Executa myname.clear().

void clear() noexcept;

path::compare

A primeira função compara os elementos desse caminho com pval. As outras funções constrói um caminho a partir de seu argumento e retornam o resultado da comparação com esse caminho.

int compare(const path& pval) const noexcept;
int compare(const string_type& str) const;
int compare(basic_string_view<value_type> str) const;
int compare(const value_type *ptr) const;

Parâmetros

pval
O caminho a ser comparado.

str
A cadeia de caracteres a ser comparada.

ptr
O ponteiro a ser comparado.

path::concat

Acrescenta a sequência especificada a myname, convertida (mas não inserindo um separador) conforme necessário.

template <class Source>
path& concat(const Source& source);

template <class InIt>
path& concat(InIt first, InIt last);

Parâmetros

source
A sequência especificada.

first
O início da sequência especificada.

last
O fim da sequência especificada.

path::const_iterator

Um sinônimo de iterator.

typedef iterator const_iterator;

path::empty

Retorna myname.empty().

bool empty() const noexcept;

path::end

Retorna um iterador de fim de sequência do tipo iterator.

iterator end() const;

path::extension

Retorna o sufixo de filename().

path extension() const;

Comentários

Retorna o sufixo de filename() X, de modo que:

Se X == path(".") || X == path("..") ou se X não contiver nenhum ponto, o sufixo será vazio.

Caso contrário, o sufixo começa com (e inclui) o ponto mais à direita.

path::filename

Retorna o componente filename de myname, especificamente empty() ? path() : *--end(). O componente pode estar vazio.

path filename() const;

path::format

Especifica o formato de nome de caminho usado para interpretar a sequência de caracteres passada para um path construtor.

enum format {
    auto_format,
    native_format,
    generic_format
};

Membros

Comentários

Como o formato nativo e o formato genérico são intercambiáveis em Windows, a implementação do Microsoft trata os três enumeradores da mesma forma. O format parâmetro é fornecido para conformidade e portabilidade padrão. Para obter mais informações, consulte a especificação WG21 N4659 [fs.class.path].

path::generic_string

Retorna this->string<Elem, Traits, Alloc>(al) com (em Windows) qualquer barra invertida convertida em barra "/".

template <class Elem,
    class Traits = char_traits<Elem>,
    class Alloc = allocator<Elem>>
  basic_string<Elem, Traits, Alloc>
    generic_string(const Alloc& al = Alloc()) const;

string generic_string() const;

path::generic_u16string

Retorna u16string() com (em Windows) qualquer barra invertida convertida em barra "/".

u16string generic_u16string() const;

path::generic_u32string

Retorna u32string() com (em Windows) qualquer barra invertida convertida em barra "/".

u32string generic_u32string() const;

path::generic_u8string

Retorna u8string() com (em Windows) qualquer barra invertida convertida em barra "/".

string generic_u8string() const;

path::generic_wstring

Retorna wstring() com (em Windows) qualquer barra invertida convertida em barra "/".

wstring generic_wstring() const;

path::has_extension

Retorna !extension().empty().

bool has_extension() const;

path::has_filename

Retorna !filename().empty().

bool has_filename() const;

path::has_parent_path

Retorna !parent_path().empty().

bool has_parent_path() const;

path::has_relative_path

Retorna !relative_path().empty().

bool has_relative_path() const;

path::has_root_directory

Retorna !root_directory().empty().

bool has_root_directory() const;

path::has_root_name

Retorna !root_name().empty().

bool has_root_name() const;

path::has_root_path

Retorna !root_path().empty().

bool has_root_path() const;

path::has_stem

Retorna !stem().empty().

bool has_stem() const;

path::is_absolute

Para o Windows, a função retorna has_root_name() && has_root_directory(). Para o POSIX, a função retorna has_root_directory().

bool is_absolute() const;

path::is_relative

Retorna !is_absolute().

bool is_relative() const;

path::iterator

Um iterador de constante bidirecional que designa os componentes path de myname.

class iterator
   {
   // bidirectional iterator for path
   typedef bidirectional_iterator_tag iterator_category;
   typedef path_type value_type;
   typedef ptrdiff_t difference_type;
   typedef const value_type *pointer;
   typedef const value_type& reference;
   // ...
   };

Comentários

A classe descreve um iterador bidirecional constante que designa os componentes path de myname na sequência:

1. o nome raiz, se existir

2. o diretório raiz, se existir

3. os elementos de diretório restantes do path pai, se existirem, terminando com o nome do arquivo, se existir

Para pval, um objeto do tipo path:

1. path::iterator X = pval.begin() designa o primeiro elemento path no nome do caminho, se existir.

2. X == pval.end() é true quando X aponta para logo após o final da sequência de componentes.

3. *X retorna uma cadeia de caracteres que corresponde ao componente atual

4. ++X designa o próximo componente na sequência, se existir.

5. --X designa o componente anterior na sequência, se existir.

6. Alterar myname invalida todos os iteradores que designam elementos em myname.

path::lexically_normal

Retorna myname convertido em formulário normal. A conversão é puramente lexical: o sistema de arquivos não é acessado.

path lexically_normal() const;

Comentários

A normalização recolhe elementos redundantes, como . separadores de diretório e de diretório .. . Por exemplo, path("a/./b/../c").lexically_normal() produz a\c em Windows. Um caminho vazio normaliza para um caminho vazio; um caminho que reduz a nada normaliza para .. Para obter o algoritmo de normalização completa, consulte a especificação WG21 N4659 [fs.path.generic].

path::lexically_proximate

Retorna o resultado de lexically_relative(base). Se esse resultado for um caminho vazio, retornará uma cópia.*this

path lexically_proximate(const path& base) const;

Parâmetros

base
O caminho base para o qual *this se aproxima.

path::lexically_relative

Retorna myname feito em relação à baseanálise lexical (cadeia de caracteres). O sistema de arquivos não é acessado.

path lexically_relative(const path& base) const;

Parâmetros

base
O caminho base a ser relativo *this a.

Comentários

Se root_name() != base.root_name(), ou se um caminho for absoluto e o outro for relativo ou se o caminho tiver um nome de arquivo, mas nenhum diretório raiz enquanto a base não o fizer, retornará um caminho vazio. Caso contrário, determina o caminho relativo de base até *this encontrando o primeiro elemento incompatível e emitindo .. para cada elemento restante de base, seguido pelos elementos restantes de *this. Por exemplo, path("/a/d").lexically_relative("/a/b/c") gera ..\..\d. Para obter o algoritmo completo, consulte a especificação WG21 N4659 [fs.path.gen].

path::make_preferred

Converte cada separador em um preferred_separator, conforme necessário.

path& make_preferred();

path::native

Obtenha a representação de cadeia de caracteres nativa do caminho.

const string_type& native() const noexcept;

Comentários

O caminho está disponível em um formato genérico portátil (consulte generic_string()) ou no formato nativo do caminho. Essa função retorna a cadeia de caracteres nativa. Em um sistema POSIX, o formato genérico e o formato nativo são os mesmos.

No exemplo a seguir em execução no Windows, a cadeia de caracteres de caminho genérico é c:/t/temp.txt e a cadeia de caracteres nativa é c:\t\temp.txt.

// Compile with /std:c++17 or higher
#include <filesystem>

int main()
{
    std::filesystem::path p(R"(c:\t\temp.txt)");
    auto native = p.native();          // Windows: L"c:\\t\\temp.txt"
    auto generic = p.generic_string(); // Windows: "c:/t/temp.txt"
}

path::operator=

Substitui os elementos do caminho por uma cópia de outro caminho.

path& operator=(const path& right);
path& operator=(path&& right) noexcept;
path& operator=(string_type&& source);

template <class Source>
path& operator=(const Source& source);

Parâmetros

right
O path que está sendo copiado no path.

source
A fonte de path.

Comentários

O primeiro operador membro copia right.myname para myname. O segundo operador membro move right.myname para myname. O terceiro operador membro passa source para myname. O quarto operador membro se comporta da mesma forma que *this = path(source).

path::operator+=

Diversas expressões concat.

path& operator+=(const path& right);
path& operator+=(const string_type& str);
path& operator+=(basic_string_view<value_type> str);
path& operator+=(const value_type *ptr);
path& operator+=(value_type elem);

template <class Source>
path& operator+=(const Source& source);

template <class Elem>
path& operator+=(Elem elem);

Parâmetros

right
O caminho adicionado.

str
A cadeia de caracteres adicionada.

ptr
O ponteiro adicionado.

elem
O value_type ou Elem adicionado.

source
A fonte adicionada.

Comentários

As funções de membro se comportam da mesma forma que chamar concat com o argumento. As pathsobrecargas terminadas value_type* em nulo e , basic_string_viewe , string_typeem caso nulo, concatenam a sequência de caracteres do argumento. O value_type e Elem as sobrecargas concatenam um único caractere. A sobrecarga com modelo Source concatena a sequência de origem convertida.

path::operator/=

Diversas expressões append.

path& operator/=(const path& right);

template <class Source>
path& operator/=(const Source& source);

Parâmetros

right
O caminho adicionado.

source
A fonte adicionada.

Comentários

As funções de membro se comportam da mesma maneira que as seguintes expressões correspondentes:

1. append(right);

2. append(source);

path::operator string_type

Retorna myname.

operator string_type() const;

path::parent_path

Retorna o componente de caminho pai de myname.

path parent_path() const;

Comentários

Retorna o componente de caminho pai de myname, especificamente o prefixo de myname após a remoção de filename().native() e qualquer separador de diretório imediatamente anterior. (Da mesma forma, se begin() != end(), é a combinação de todos os elementos no intervalo [begin(), --end()) aplicando operator/= sucessivamente.) O componente pode estar vazio.

path::path

Constrói um de path várias maneiras.

path() noexcept;

path(const path& right);
path(path&& right) noexcept;

path(string_type&& source, format fmt = auto_format);

template <class Source>
path(const Source& source, format fmt = auto_format);

template <class InIt>
path(InIt first, InIt last, format fmt = auto_format);

template <class Source>
path(const Source& source, const locale& loc, format fmt = auto_format);

template <class InIt>
path(InIt first, InIt last, const locale& loc, format fmt = auto_format);

Parâmetros

right
O caminho do qual o caminho construído deve ser uma cópia.

source
A origem da qual o caminho construído deve ser uma cópia.

fmt
O nome de format caminho usado para interpretar source ou o first/last intervalo. Usa auto_format como padrão.

loc
A localidade especificada.

first
A posição do primeiro elemento a ser copiado.

last
A posição do último elemento a ser copiado.

Comentários

Todos os construtores criam myname de várias maneiras:

Para path(), é myname().

Para path(const path& right), é myname(right.myname).

Para path(path&& right), é myname(right.myname).

Para path(string_type&& source, format fmt), é myname(move(source)).

Para template<class Source> path(const Source& source, format fmt), é myname(source).

Para template<class Source> path(const Source& source, const locale& loc, format fmt) ele é myname(source), obtendo todas as facetas codecvt necessárias de loc.

Para template<class InIt> path(InIt first, InIt last, format fmt), é myname(first, last).

Para template<class InIt> path(InIt first, InIt last, const locale& loc, format fmt) ele é myname(first, last), obtendo todas as facetas codecvt necessárias de loc.

O fmt parâmetro seleciona o formato pathname. Em Windows, os formatos nativos e genéricos são intercambiáveis, portanto, a implementação do Microsoft ignorafmt.

path::preferred_separator

O objeto constante fornece o caractere preferencial para separar os componentes do caminho, dependendo do sistema operacional do host.

#if _WIN32_C_LIB
static constexpr value_type preferred_separator = L'\\';
#else // assume POSIX
static constexpr value_type preferred_separator = '/';
#endif // filesystem model now defined

Comentários

Usar L'/' em lugar dele é igualmente permitido na maioria dos contextos no Windows.

path::relative_path

Retorna o componente de caminho relativo de myname.

path relative_path() const;

Comentários

Retorna o componente de caminho relativo de myname, especificamente o sufixo de myname após remover root_path().native() e os separadores de diretório imediatamente subsequentes, se houver. O componente pode estar vazio.

path::remove_filename

Remove o nome do arquivo.

path& remove_filename();

path::replace_extension

Substitui a extensão de myname.

path& replace_extension(const path& newext = path());

Parâmetros

newext
A nova extensão.

Comentários

Primeiro, remove o sufixo extension().native() de myname. Depois, se !newext.empty() && newext[0] != dot (em que dot é *path(".").c_str()), então dot é acrescentado a myname. Em seguida, newext é acrescentado a myname.

path::replace_filename

Substitui o nome do arquivo.

path& replace_filename(const path& pval);

Parâmetros

pval
O caminho do nome do arquivo.

Comentários

A função membro executa:

remove_filename();

*this /= pval;
return (*this);

path::root_directory

Retorna o componente do diretório raiz de myname.

path root_directory() const;

Comentários

O componente pode estar vazio.

path::root_name

Retorna o componente de nome raiz de myname.

path root_name() const;

Comentários

O componente pode estar vazio.

path::root_path

Retorna o componente de caminho raiz de myname.

path root_path() const;

Comentários

Retorna o componente de caminho raiz de myname, especificamente root_name() / root_directory. O componente pode estar vazio.

path::stem

Retorna o componente stem de myname.

path stem() const;

Comentários

Retorna o componente stem de myname, especificamente filename().native(), removendo eventuais ocorrências de extension().native() à direita. O componente pode estar vazio.

path::string

Converte a sequência armazenada em myname.

template <class Elem, class Traits = char_traits<Elem>, class Alloc = allocator<Elem>>
basic_string<Elem, Traits, Alloc> string(const Alloc& al = Alloc()) const;
string string() const;

Comentários

A primeira função membro (modelo) converte a sequência armazenada em myname da mesma maneira que:

1. string() para string<char, Traits, Alloc>()

2. wstring() para string<wchar_t, Traits, Alloc>()

3. u16string() para string<char16_t, Traits, Alloc>()

4. u32string() para string<char32_t, Traits, Alloc>()

A segunda função membro converte a sequência armazenada em myname na codificação preferida pelo sistema de host para uma sequência char armazenada em um objeto do tipo string.

path::string_type

O tipo é um sinônimo de basic_string<value_type>.

typedef basic_string<value_type> string_type;

path::swap

Executa swap(myname, right.myname).

void swap(path& right) noexcept;

path::u16string

Converte a sequência armazenada em myname em UTF-16 e a retorna armazenada em um objeto do tipo u16string.

u16string u16string() const;

path::u32string

Converte a sequência armazenada em myname em UTF-32 e a retorna armazenada em um objeto do tipo u32string.

u32string u32string() const;

path::u8string

Converte a sequência armazenada em myname em UTF-8 e a retorna armazenada em um objeto do tipo u8string.

string u8string() const;

path::value_type

O tipo descreve os elementos path preferidos pelo sistema operacional do host.

#if _WIN32_C_LIB
typedef wchar_t value_type;
#else // assume POSIX
typedef char value_type;
#endif // filesystem model now defined

path::wstring

Converte a sequência armazenada em myname na codificação preferida pelo sistema de host para uma sequência wchar_t e a retorna armazenada em um objeto do tipo wstring.

wstring wstring() const;

Confira também

<filesystem>
Referência de Arquivos de Cabeçalho