ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
environment.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_system of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8ALIB_EXPORT namespace alib { namespace system {
9
10//==================================================================================================
11/// Simple struct providing one static method that reads an environment variable into an
12/// \alib string-type.
13///
14/// While under posix compatible operating systems, environment variable names are
15/// case-sensitive, under Microsoft windows they are not.
16//==================================================================================================
18{
19 //==============================================================================================
20 /// Reads an environment variable into an \alib string.
21 ///
22 /// \attention
23 /// 1. While under posix compatible operating systems, environment variable names are
24 /// case-sensitive, under Microsoft windows they are not.
25 /// <br><br>
26 /// 2. As documented with
27 /// \https{std::getenv,en.cppreference.com/w/cpp/utility/program/getenv}, the operation is
28 /// not thread-safe against changes of the environment in parallel threads.
29 ///
30 /// \note
31 /// When path-variables are requested, usually instead of passing an \b AString for parameter
32 /// \p{target}, a reference of type \alib{system;Path} may be given, which is derived
33 /// from class \b AString.
34 /// However, compatibility of both types depend on the platform and compilation flags
35 /// of the \alibbuild: The character-type of class \b Path equals C++ standard type
36 /// <c>std::filesystem::path::value_type</c>, while the one of \b AString depends on
37 /// compilation symbol \ref ALIB_CHARACTERS_WIDE. On GNU/Linux and MacOS, both default to
38 /// \alib{characters;nchar}, on WindowsOS both default to \alib{characters;wchar} and as such
39 /// compatibility is given with the defaults. If compilation of \alib is explicitly switched
40 /// to use a different character type, then conversion has to be performed.<br><p>
41 /// \note
42 /// Class \alib{system;Path} provides built-in mechanics that uses the environment
43 /// to retrieve certain default paths, and that performs conversion when necessary
44 /// internally.
45 ///
46 /// @param varName The name of the variable to be retrieved.
47 /// @param target An AString to write the result to.
48 /// @param targetData If \c CurrentData::Keep, the parameter \p{target} is not cleared
49 /// before the result is written. Defaults to \c CurrentData::Clear.
50 /// @return \c true if variable was found.
51 //==============================================================================================
52 ALIB_DLL static
53 bool Get( const CString& varName,
54 AString& target,
56};
57
58} // namespace alib[::system]
59
60/// Type alias in namespace \b alib.
62
63} // namespace [alib]
64
65
#define ALIB_DLL
Definition alib.inl:496
#define ALIB_EXPORT
Definition alib.inl:488
@ Clear
Chooses to clear existing data.
strings::TAString< character, lang::HeapAllocator > AString
Type alias in namespace alib.
strings::TCString< character > CString
Type alias in namespace alib.
Definition cstring.inl:503
system::EnvironmentVariables EnvironmentVariables
Type alias in namespace alib.
static ALIB_DLL bool Get(const CString &varName, AString &target, lang::CurrentData targetData=lang::CurrentData::Clear)