filesystem.txt

                
   FILESYSTEM   
                
  

MACRO ==>               #Faire aussi un (avant les headers !) :
                        #  #define BOOST_FILESYSTEM_VERSION 3
LIBRARIES ==>           # libboost_filesystem[-mt] --> -lboost_filesystem[-mt]
                        #Avoir au moins la version 1.44

NAMESPACE ==>           #boost::filesystem:: pour tous

RESUME ==>              #Pas d'exception :
                        #  path(STRING)    #Chemin quelconque, pas d'exception
                        #  PATH / PATH2    #Concaténation
                        #  PATH.native()   #Renvoie forme native de l'OS
                        #  PATH.filename() #ou root_name(), etc.
                        #  PATH.begin()    #Itérateur de chemin
                        #  directory_entry #Chemin d'un fichier, pas d'exception
                        #  (STRING)
                        #  DIRECTORY_ENTRY #Type du fichier
                        #  .status().type()
                        #Exception filesystem_error si erreur :
                        #  [recursive_]    #Itérateur de fichier 
                        #  directory_iterator(PATH)
                        #  ACTION(PATH...) #Action comme cp, rm, ln, etc. 
                        #Aussi :
                        #  *stream(PATH)   #Possible

HEADER ==>              #<boost/filesystem.hpp>

PATH FORMATS ==>        #Composants :
                        #  - root-name (optionnel) :
                        #     - "//net" pour un réseau par exemple
                        #     - "c:", "d:", etc. pour un disque dur
                        #  - root-directory (optionnel)
                        #  - relative-path (filename final compris), fichiers
                        #    séparés par le directory-separator
                        #  - filename final (dont extension éventuellement).
                        #Le root-path est le root-name + root-directory
                        #Le parent-path est tout sauf le filename final.
                        #
                        #Exemple :
                        # //net/chemin///./le/fichier.txt
                        # et ./fichier
                        # +-------+------+---------------+---+---------+-------+
                        # |       |      |        .      | / | fichier |       |
                        # +-------+------+---------------+---+---------+-------+
                        # | //net |   /  | chemin///./le | / | fichier | .txt  |
                        # +-------+------+---------------+---+---------+-------+
                        # | ROOT- | ROOT |                   |  STEM   | EXTEN |
                        # | NAME  | -DIR |                   |         | -SION |
                        # +-------+------+-----------------------------+-------+
                        # |   ROOT-PATH  |           RELATIVE-PATH             |
                        # +--------------+----------------+--+-----------------+
                        # |        PARENT PATH            |  |    FILENAME     |
                        # +-------------------------------+  +-----------------+
                        #Si le fichier est un répertoire, filename est :
                        #  - le root_name si le chemin est seulment le root_name
                        #  - / s'il s'agit du répertoire root
                        #  - .. si le chemin se termine par ..
                        #  - . sinon
                        #
                        #Le generic format est le format Unix des chemins de
                        #fichier (utilisé aussi par les URL).
                        #Le native format est le format de l'OS utilisé.
                        #Pour W$ native != generic, sinon c'est ==. 
                        #Différences : 
                        # +----------------+----------------+-----------------+
                        # |                |    GENERIC     |     WINDOWS     |
                        # +----------------+----------------+-----------------+
                        # | root-name      |      non       |       c:        |
                        # | root-directory |       /        |     \ ou /      |
                        # | directory-     |       /        |     \ ou /      |
                        # | separator      |                |                 |
                        # +----------------+----------------+-----------------+

path                    #Classe désignant un chemin de fichier, portable entre
                        #les OS, supportant Unicode.

PATH(PATH_ARGS)         #PATH_ARGS désigne : un argument STR, STRING, WSTR, 
                        #WSTRING ou deux arguments INPT_ITVR1 et INPT_ITVR2,
                        #ou PATH2.
                        #Le tout suivi d'un CODECVT_TYPE optionnel.
                        #Je pense que PATH enregistre en UTF-8 et que CODECVT est utilisé pour convertir PATH_ARGS en
                        #UTF-8, avec par défaut le CODECVT de la locale, donc ça ne devrait pas poser de problème si locale est
                        #bien mise.
                        #Instantie un PATH, dont le chemin (native ou generic
                        #format) est STR ou STRING. Cela peut aussi être une
                        #suite de WCHAR ou CHAR_VAL entre deux itérateurs
                        #INPT_ITVR.
                        #Il y a aussi des operator overloadable.
                        #Le chemin n'est pas obligé de cibler un vrai fichier.
                        #Les "/" doublons, etc. ne sont pas supprimés.

PATH.assign(PATH_ARGS)  #Equivaut à PATH(PATH_ARGS)

path::value_type        #Type du caractère d'un chemin de fichier (char pour
                        #Unix, wchar_t pour W$)
path::string_type       #Type de string d'un chemin de fichier (std::string pour
                        #Unix, std::wstring pour W$)
path::codecvt_type      #Type de la facet CODECVT : std::codecvt<wchar_t, char,
                        #mbstate_t>

PATH /= PATH_ARGS       #Concatène PATH_ARGS à PATH, séparé par le native 
PATH.append(PATH_ARGS)  #directory separator. Renvoie *this.

PATH / PATH2            #Renvoie la concaténation de PATH et PATH2, séparé par 
                        #le native directory separator.

PATH.clear()            #PATH devient une null string.
PATH.make_preferred()   #PATH est convertit en native path (sous Windows, cela
                        #transforme les / en \ ; sous Unix, cela ne fait rien)
PATH.remove_filename()  #Revient à PATH = PATH.parent_path()
PATH.replace_extension  #Remplace l'extension de nom de fichier (dont le .) par 
([PATH])                #PATH (par défaut null string)
PATH.swap(PATH2)        
swap(PATH, PATH2)       #Swappe PATH et PATH2.

PATH.native()           #Renvoie PATH sous forme native, sous forme 
PATH.c_str()            #respectivement de :
PATH.string()           #  - STRING_TYPE
PATH.wstring()          #  - VALUE_TYPE_ADR
PATH.u16string()        #  - STRING
PATH.u32wstring()       #  - WSTRING
                        #  - U16STRING
                        #  - U32WSTRING
PATH.generic_string()   #Renvoie PATH sous forme generic, sous forme 
PATH.string()           #respectivement de :
PATH.wstring()          #  - STRING_TYPE
PATH.u16string()        #  - STRING
PATH.u32wstring()       #  - WSTRING
                        #  - U16STRING
                        #  - U32WSTRING

PATH.root_name()        #Renvoie sous forme de PATH :
                        #  - le root-name
PATH.root_directory()   #  - le root-directory
PATH.root_path()        #  - le root-path
PATH.relative_path()    #  - le relative_path
PATH.parent_path()      #  - le parent path
PATH.filename()         #  - le filename
PATH.extension(PATH)    #  - l'extension
PATH.stem(PATH)         #  - le filename, sans l'extension

PATH.empty()            #Renvoie true si PATH est une null string.
PATH.is_absolute()      #Renvoie true si PATH est un chemin absolu.
PATH.is_relative()      #Renvoie true si PATH est un chemin relatif.
PATH.has_root_name()    #Renvoie false si le root-name de PATH est une null
                        #string. De même pour :
PAT.has_root_directory()#  - le root-directory
PATH.has_root_path()    #  - le root-path
PATH.has_relative_path()#  - le relative_path
PATH.has_parent_path()  #  - le parent path
PATH.has_filename()     #  - le filename
PATH.has_extension(PATH)#  - l'extension
PATH.has_stem(PATH)     #  - le filename, sans l'extension

begin()                 #Renvoie un PATH::ITERATOR sur le début de PATH
end()                   #Renvoie un PATH::ITERATOR après la fin de PATH

lexicographical_compare #De chaque range résulte un PATH, et les deux PATH sont
(PATH::ITVR1,           #comparés sur la base juste alphabétique (pas sur le
PATH::ITVR2, PAT::ITVR3,#fait qu'il s'agisse de chemin), et renvoie true si le
PATH::ITVR4)            #premier range est < second range.
PATH == PATH2
PATH != PATH2
PATH < PATH2
PATH > PATH2
PATH >= PATH2           #Tests sur le même principal (seulement alphabétique :
PATH <= PATH2           #même un "/" doublon rend la comparaison !=.

OSTREAM << PATH         
ISTREAM >> PATH         #Imprime ou extrait PATH.native()

PATH.imbue(STD::LOCALE) #Modifie la LOCALE utilisée par PATH.

path::iterator          #Itérator BidirectionnalIt. sur un PATH. *PATH::ITERATOR
                        #renvoient des PATH (morceaux du PATH principal) :
                        #  - d'abord le root-name, si présent
                        #  - puis le root-directory, si présent
                        #  - puis chaque filename
                        #  - un dernier "." si le dernier fichier est répertoire
                        #    (dont le nom entier le précède tout de même comme 
                        #    filename)

CHEMIN PORTABLE ==>     #Un chemin portable doit :
                        #  - contenir seulement [[:alnum:].-_]
                        #  - pour le . :
                        #    - pas au début (POSIX)
                        #    - pas à la fin (Windows)
                        #    - pas dans un nom de répertoire (ISO-9660, OpenVMS)
                        #    - un seul, et suivi de 3 lettres max (ISO-9660,
                        #      OpenVMS)
                        #  - pas de - au début
                        #  - pas supposé que case sensitive (Windows), ni
                        #    insensitive (POSIX).
                        #  - maximum 255 caractères du chemin

native(STRING)          #Renvoie true si le nom de fichier STRING est compatible
                        #avec l'OS actuel.
portable_posix_name     #Renvoie true si le nom de fichier STRING est compatible
(STRING)                #POSIX.
windows_name(STRING)    #Renvoie true si le nom de fichier STRING est compatible
                        #Windows
portable_name(STRING)   #Renvoie true si le nom de fichier STRING est compatible
                        #Windows et POSIX, et que le premier caractère n'est ni 
                        #un . ni un -
portable_directory_name #Renvoie true si le nom de fichier STRING est compatible
(STRING)                #Windows et POSIX, qu'il s'agit d'un répertoire et que 
                        #le nom de répertoire ne contient pas de "."
portable_file_name      #Renvoie true si le nom de fichier STRING est compatible
(STRING)                #Windows et POSIX et que tout "." est suivi de minimum 1
                        #et maximum 3 caractères.

directory_entry         #Classe désignant un fichier, caractérisé par un PATH.
                        #Tandis que PATH est juste un chemin, il s'agit ici du
                        #fichier désigné par le chemin.

DIRECTORY_ENTRY         #Instantie un DIRECTORY_ENTRY dont le PATH est 
([PATH_ARGS])           #PATH_ARGS (par défaut null string).

DIRECTORY_ENTRY.        
assign(PATH_ARGS)       #Equivaut à DIRECTORY_ENTRY(PATH_ARGS)

DIRECTORY_ENTRY.        #Remplace le filename du PATH de DIRECTORY_ENTRY par
replace_filename(PATH2) #PATH2.

DIRECTORY_ENTRY.path()  #Renvoie le PATH de DIRECTORY_ENTRY
DIRECTORY_ENTRY ==
DIRECTORY_ENTRY2
DIRECTORY_ENTRY !=
DIRECTORY_ENTRY2
DIRECTORY_ENTRY <=
DIRECTORY_ENTRY2
DIRECTORY_ENTRY >=
DIRECTORY_ENTRY2
DIRECTORY_ENTRY >
DIRECTORY_ENTRY2        #Test d'égalités des DIRECTORY_ENTRY.path() (seulement
DIRECTORY_ENTRY <       #alphabétique, prend même en compte les "/" doublons, 
DIRECTORY_ENTRY2        #etc.

DIRECTORY_ENTRY.status()#Renvoie le FILE_STATUS de DIRECTORY_ENTRY, déférencé.
DIRECTORY_ENTRY         #Renvoie le FILE_STATUS de DIRECTORY_ENTRY, non 
.symlink_status()       #déférencé.

file_status             #Classe désignant le type ou le status d'erreur d'un
                        #fichier.

FILE_STATUS([FILE_TYPE])#Construit un FILE_STATUS associé à FILE_TYPE (par
                        #défaut status_error).

FILE_STATUS.type()      #Renvoie le FILE_TYPE associé.
FIL_STATU.type(FIL_TYPE)#FILE_TYPE devient le nouveau FILE_TYPE associé.

file_type               #Enum désignant le type ou le status d'erreur d'un
                        #fichier. Valeurs possibles :
regular_file            #
directory_file          #
symlink_file            #
block_file              #
character_file          #
fifo_file               #
socket_file             #
type_unknown            #
file_not_found          #
status_error            #

directory_iterator      #Itérateur de fichiers désignés par des PATH, dans un
                        #répertoire donné. Il s'agit d'un InputIteratorIt.

DIRECTORY_ITERATOR()    #Construit un itérateur sur l'élément suivant le dernier
                        #(end)
DIRECTORY_ITERATOR      #Construit un itérateur sur l'un des éléments contenus
(PATH)                  #dans le répertoire PATH. 

*DIRECTORY_ITERATOR     #Renvoie le fichier ciblé actuellement sous forme de 
                        #DIRECTORY_ENTRY. Ne pas utiliser ->, qui n'est pas
                        #toujours implémenté.
                        #En cas d'erreur, lance une exception filesystem_error.

DIRECTORY_ITERATOR++    #Va vers le fichier suivant. L'ordre n'est pas forcément
DIRECTORY_ITERATOR      #alphabétique.
.increment()            #En cas d'erreur, lance une exception filesystem_error.

recursive_directory_    #Itérateur de fichiers désignés par des PATH, mais
iterator                #récursive. Permet de rentrer récursivement dans les
                        #dossiers. Possède les mêmes membres que 
                        #directory_iterator, plus :

RECURSIVE_DIRECTORY_    #Va vers le fichier suivant. Cependant, si le fichier
ITERATOR++              #actuel est un répertoire, cible alors un fichier de
                        #ce répertoire. S'il n'y a plus de fichier dans un
                        #répertoire et qu'il ne s'agit pas du level 0, le
                        #prochain fichier est celui qui suit le répertoire
                        #actuel.

RECURSIVE_DIRECTORY_    #Renvoie le niveau actuel (0 pour la base, 1 pour une
ITERATOR.level()        #récursion, 2 pour deux, etc.)

RECURSIVE_DIRECTORY_    
ITERATOR.pop()          #Retourne dans le répertoire du dessus sans terminer
                        #l'itération dans le répertoire actuel.
RECURSIVE_DIRECTORY     
_ITERATOR.no_push()     #Désactive l'effet récursif.

RECURSIVE_DIRECTORY     
.no_push_pending()      #Renvoie true si l'effet récursif est désactivé.

EXCEPTIONS ==>          #Toutes les fonctions suivantes (jusqu'à la partie sur
                        #<boost/filesystem/fstream.hpp>) jettent des exceptions
                        #filesystem_error en cas d'erreur (notamment si l'un des
                        #fichiers n'existe pas), et remplit les membres de
                        #filesystem_error.
                        #Lancent aussi des exceptions :
                        #  - FILE_STATUS.[symlink_]status()
                        #  - [recursive_]directory_iterator : increment() et
                        #    constructors
                        #Ces fonctions ne lancent pas d'exceptions :
                        #  - exists, is_* avec FILE_STATUS en arg
                        #  - status_known
                        #  - absolute
ERROR_CODE ==>          #Toutes les fonctions pouvant lancer des exceptions, 
                        #peuvent prendre un dernier argument SYSTEM::ERROR_CODE
                        #(cf boost::system), auquel cas aucune exception n'est
                        #lancée, mais SYSTEM::ERROR_CODE est initialisé en 
                        #conséquence (ou clear() si pas d'erreur).

filesystem_error        #Enfant de boost::system_error

FILESYSTEM_ERROR(STRING
[[PATH1, ]PATH2, ]
SYSTEM::ERROR_CODE)

FILESYSTEM_ERROR.path1()#Renvoie PATH1
FILESYSTEM_ERROR.path2()#Renvoie PATH2
FILESYSTEM_ERROR.what() #Renvoie STRING + SYSTEM::ERROR_CODE

copy_file(PATH, PATH2   #Comme cp PATH PATH2. Si BOOST_SCOPED_ENUM == 
[, BOOST_SCOPED_ENUM])  #fail_if_exists, il n'y a pas d'overwrite. Avec 
                        #overwrite_if_exists, c'est le contraire. Non déférencé.
copy_symlink(PATH,      #Copie PATH, déférencé, qui doit être un symlink (sinon
PATH2)                  #exception), vers PATH2

copy_option::enum_type  #Enum désignant le fait d'écraser ou non un fichier.
                        #Valeurs possibles :
copy_option::
fail_if_exists          #N'écrase pas.
copy_option::
overwrite_if_exists     #Ecrase.

rename(PATH, PATH2)     #Comme mv PATH PATH2
remove(PATH)            #Comme rm PATH. Renvoie false si PATH existait déjà.
remove_all(PATH)        #Comme rm -r PATH. Renvoie false si PATH existait déjà

create_directory(PATH)  #Comme mkdir PATH. Si le répertoire parent n'existe pas,
                        #lance une exception. Renvoie false si PATH existait
                        #déjà.
create_directories(PATH)#Comme mkdir -p PATH. Renvoie false si PATH existait
                        #déjà.

unique_path([PATH])     #Renvoie un nom de fichier temporaire : renvoie PATH,
                        #en remplaçant chaque '%' par un caractère hexadécimal
                        #aléatoire. Par défaut PATH est "%%%%-%%%%-%%%%-%%%%"

create_symlink(PATH,    #
PATH2)                  
create_directory_symlink#Comme ln -s PATH PATH2.  Certains OS (W$ avant Vista) 
(PATH, PATH2)           #et systèmes de fichier (FAT), ne le supportent pas, 
                        #donc pas portable.

read_symlink(PATH)      #Comme readlink PATH (sans options).

create_hard_link(PATH,  #Equivaut à ln PATH PATH2. Certains OS et systèmes de
PATH2)                  #fichier (FAT), ne le supportent pas, donc pas portable.

hard_link_count(PATH)   #Renvoie le nombre d'hards links de PATH (cf ci-dessus
                        #pour les considérations de portabilité)

exists(PATH)            #Comme [[ -e PATH ]]
is_regular_file(PATH)   #Renvoie true si PATH est un fichier régulier.
is_directory(PATH)      #Renvoie true si PATH est un répertoire
is_symlink(PATH)        #Renvoie true si PATH est un symlink.
is_other(PATH)          #Renvoie true si PATH n'est ni un fichier régulier, ni
                        #un répertoire, ni un symlink.
exists(FILE_STATUS)     
is_directory        
(FILE_STATUS)           
is_other(FILE_STATUS)   
is_regular_file         #Comme leurs homologues, sauf qu'il s'agit de rechercher
(FILE_STATUS)           #le type ou l'existence dans le FILE_STATUS directement
is_symlink(FILE_STATUS) #plutôt que dans le PATH.

status(PATH)            #Renvoie le FILE_STATUS associé à PATH (déréfencé)
status_known            #Renvoie false si FILE_STATUS.type() == type_unknown
(FILE_STATUS)           
symlink_status(PATH)    #Renvoie le FILE_STATUS associé à PATH (non-déréfencé)

last_write_time(PATH)   #Renvoie la mtime de PATH, sous forme de STD::TIME_T_VAL

last_write_time(PATH    
, STD::TIME_T_VAL)      #Modifie la mtime de PATH, avec STD::TIME_T_VAL

resize_file(PATH,       #Comme truncate PATH UINTMAX_VAL
UINTMAX_VAL)            

file_size(PATH)         #Renvoie le nombre d'octets du fichier régulier dont le 
                        #chemin est PATH (peut différer en raison des newlines
                        #différentes entre OS)
is_empty(PATH)          #Renvoie true si PATH existe et a une taille de 0 
                        #octets.
space(PATH)             #Renvoie le nombre d'octets disponibles de la partition
                        #sur laquelle se trouve PATH, sous forme de SPACE_INFO.

space_info              #Désigne un nombre d'octets en mémoire disponible.

SPACE_INFO.capacity     #Nombre d'octets total
SPACE_INFO.free         #Nombre d'octets disponible (root)
SPACE_INFO.available    #Nombre d'octets disponible (non-root)

current_path([PATH])    #Comme pwd.
equivalent(PATH, PATH2) #Renvoie true si PATH et PATH2 (déréférencés) font
                        #référence au même fichier (même inode)
absolute(PATH[, PATH2]) #Renvoie PATH, sous forme de chemin absolu. Si PATH2 est
                        #précisé et que PATH est relatif, plutôt que le 
                        #comportement par défaut, concatène PATH2 et PATH
system_complete(PATH)   #Même chose (sans le deuxième argument), mais peut 
                        #apporter des erreurs.

HEADER ==>              #<boost/filesystem/fstream.hpp>

ifstream                #
ofstream                #
fstream                 #
filebuf                 #
wifstream               #
wofstream               #Exactement identique aux même classes dans <fstream>,
wfstream                #sauf qu'elles prennent des PATH en argument et non des
wfilebuf                #STR.