<commit_before>﻿/* -*- coding: utf-8; mode: c++; tab-width: 3; indent-tabs-mode: nil -*-

Copyright 2010, 2011, 2012, 2013
<NAME>

This file is part of Application-Building Components (henceforth referred to as ABC).

ABC is free software: you can redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

ABC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
License for more details.

You should have received a copy of the GNU General Public License along with ABC. If not, see
<http://www.gnu.org/licenses/>.
--------------------------------------------------------------------------------------------------*/

#ifndef ABC_FILE_PATH_HXX
#define ABC_FILE_PATH_HXX

#include <abc/core.hxx>
#ifdef ABC_CXX_PRAGMA_ONCE
   #pragma once
#endif

#include <abc/str.hxx>



////////////////////////////////////////////////////////////////////////////////////////////////////
// abc::file_path


namespace abc {

/** DOC:7101 abc::file_path

An abc::file_path instance is always either an empty path string ("") or a path that is not
necessarily normalized or absolute, but has no incorrect or redundant path separators; e.g. an
abc::file_path instance will never contain “/a//b///c”, and under Win32 it will never be “C:/a” or
“a\\\b/c”.

Under Win32, all absolute DOS-style paths (e.g. “C:\My\File”) are normalized to the Win32 File
Namespace, which means they all start with “\\?\”, forming e.g. “\\?\C:\My\File”. This prefix is
also considered the root, although trying to do anything with it other than concatenating more path
components will most likely result in exceptions being thrown. Nonetheless, this convention allows
to have a single root under Win32 just like under POSIX.

Reference for Python’s approach: “os.path — Common pathname manipulations” <http://docs.python.org/
3/library/os.path.html>
Reference for Win32: “Naming Files, Paths, and Namespaces” <http://msdn.microsoft.com/en-us/library/
windows/desktop/aa365247.aspx>
*/

// Enumerates directory entries.
#if 0
class _file_path_iterator;<commit_msg>Improve documentation<commit_after>﻿/* -*- coding: utf-8; mode: c++; tab-width: 3; indent-tabs-mode: nil -*-

Copyright 2010, 2011, 2012, 2013
<NAME>

This file is part of Application-Building Components (henceforth referred to as ABC).

ABC is free software: you can redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

ABC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
License for more details.

You should have received a copy of the GNU General Public License along with ABC. If not, see
<http://www.gnu.org/licenses/>.
--------------------------------------------------------------------------------------------------*/

#ifndef ABC_FILE_PATH_HXX
#define ABC_FILE_PATH_HXX

#include <abc/core.hxx>
#ifdef ABC_CXX_PRAGMA_ONCE
   #pragma once
#endif

#include <abc/str.hxx>



////////////////////////////////////////////////////////////////////////////////////////////////////
// abc::file_path


namespace abc {

/** DOC:7101 abc::file_path

An abc::file_path instance is always either an empty path string ("") or a path that is not
necessarily normalized or absolute, but has no incorrect or redundant path separators; e.g. an
abc::file_path instance will never contain “/a//b///c”, and under Win32 it will never be “C:/a” or
“a\\\b/c”.

Under Win32, all absolute DOS-style paths (e.g. “C:\My\File”) are normalized to the Win32 File
Namespace, which means they all start with “\\?\”, forming e.g. “\\?\C:\My\File”. This prefix is
also considered the root, although trying to do anything with it other than concatenating more path
components will most likely result in exceptions being thrown. Nonetheless, this convention allows
to have a single root under Win32 just like under POSIX.

abc::file_path instances can be used with the OS’s file API by using abc::file_path::os_str(), which
will return a string suitable for such use. Under Win32, this will make the path absolute in order
to be able to use the Win32 File Namespace, which has advantages and drawbacks; os_str() mitigates
the drawbacks, allowing to overcome limitations in the Win32 file API. See abc::file_path::os_str()
for more information.

Reference for Python’s approach: “os.path — Common pathname manipulations” <http://docs.python.org/
3/library/os.path.html>
Reference for Win32: “Naming Files, Paths, and Namespaces” <http://msdn.microsoft.com/en-us/library/
windows/desktop/aa365247.aspx>
*/

// Enumerates directory entries.
#if 0
class _file_path_iterator;
{'fraction_non_alphanumeric': 0.1611177170035672, 'fraction_numerical': 0.01743955608402695, 'mean_word_length': 2.980283911671924, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5752221', 'n_tokens_mistral': 1437, 'n_tokens_neox': 1331, 'n_words': 628}