1# Boost.Nowide 2 3Branch | Travis | Appveyor | Github | codecov.io | Documentation 4------------|--------|----------|--------|------------|-------------- 5[master](https://github.com/boostorg/nowide/tree/master) | [](https://travis-ci.com/boostorg/nowide) | [](https://ci.appveyor.com/project/Flamefire/nowide-fr98b/branch/master) |  | [](https://codecov.io/gh/boostorg/nowide/branch/master) | [](https://www.boost.org/doc/libs/master/libs/nowide/index.html) 6[develop](https://github.com/boostorg/nowide/tree/develop) | [](https://travis-ci.com/boostorg/nowide) | [](https://ci.appveyor.com/project/Flamefire/nowide-fr98b/branch/develop) |  | [](https://codecov.io/gh/boostorg/nowide/branch/develop) | [](https://www.boost.org/doc/libs/develop/libs/nowide/index.html) 7 8Coverity Scan: [](https://scan.coverity.com/projects/boostorg-nowide) 9 10Library for cross-platform, unicode aware programming. 11 12The library provides an implementation of standard C and C++ library functions, such that their inputs are UTF-8 aware on Windows without requiring to use the Wide API. 13 14### License 15 16Distributed under the [Boost Software License, Version 1.0](http://www.boost.org/LICENSE_1_0.txt). 17 18### Properties 19 20* optional C++17 (filesystem) support 21* Usable outside of Boost via CMake 22* Compiled library on every OS 23 24Note on the last point: 25Having a compiled library allows cross-platform access to e.g. `setenv` which would not be available when using a `-std=c++nn` flag. 26This is different to the version available prior to the inclusion in Boost. 27 28### Requirements (All versions) 29 30* C++11 (or higher) compatible compiler 31 * MSVC 2015 and up work 32 * libstdc++ < 5 is unsupported as it is silently lacking C++11 features 33 34### Requirements (Boost version) 35 36* Boost (>= 1.56) 37* CMake (when not using as part of Boost) or B2 (otherwise) 38 39### Requirements (Standalone version) 40 41The [standalone branch](https://github.com/boostorg/nowide/tree/standalone) keeps track of the [develop branch](https://github.com/boostorg/nowide/tree/develop) and can be used without any other part of Boost. 42It is automatically updated so referring to a specific commit is recommended. 43You can also use the standalone source archive which is part of every release. 44 45* CMake 46 47# Quickstart 48 49Instead of using the standard library functions use the corresponding member of Boost.Nowide with the same name. 50On Linux those are (mostly) aliases for the `std` ones, but on Windows they accept UTF-8 as input and use the wide API for the underlying functionality. 51 52Examples: 53- `std::ifstream -> boost::nowide::ifstream` 54- `std::fopen -> boost::nowide::fopen` 55- `std::fclose -> boost::nowide::fclose` 56- `std::getenv -> boost::nowide::getenv` 57- `std::putenv -> boost::nowide::putenv` 58- `std::cout -> boost::nowide::cout` 59 60To also convert your input arguments to UTF-8 on Windows use: 61 62``` 63int main(int argc, char **argv) 64{ 65 boost::nowide::args _(argc, argv); // Must use an instance! 66 ... 67} 68``` 69 70See the [Documentation](https://www.boost.org/doc/libs/master/libs/nowide/index.html) for details. 71 72# Compile 73 74## With Boost 75 76Compile and install the Boost super project the usual way via `./b2`. 77The headers and library will then be available together with all other Boost libraries. 78From within CMake you can then use `find_package(boost_nowide)` and link against `Boost::nowide`. 79 80## With CMake 81 82Boost.Nowide fully supports CMake. 83So you can use `add_subdirectory("path-to-boost-nowide-repo")` and link your project against the target `Boost::nowide`. 84 85You can also pre-compile and install Boost.Nowide via the usual workflow: 86``` 87mkdir build && cd build 88cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local 89make install 90``` 91 92A CMake-Config file will be installed alongside Boost.Nowide so `find_package(boost_nowide)` does work out-of the box 93(provided it was installed into a "standard" location or its `INSTALL_PREFIX` was added to `CMAKE_PREFIX_PATH`). 94 95# Boost.Filesystem integration 96 97Boost.Nowide integrates with Boost.Filesystem: 98- Call `boost::nowide::nowide_filesystem()` to imbue UTF-8 into Boost.Filesystem (for use by `boost::filesystem::path`) such that narrow strings passed into Boost.Filesystem are treated as UTF-8 on Windows 99 100### More information 101 102* [Ask questions](http://stackoverflow.com/questions/ask?tags=c%2B%2B,boost,boost-nowide) 103* [Report bugs](https://github.com/boostorg/nowide/issues): Be sure to mention Boost version, platform and compiler you're using. A small compilable code sample to reproduce the problem is always good as well. 104* Submit your patches as pull requests against **develop** branch. Note that by submitting patches you agree to license your modifications under the [Boost Software License, Version 1.0](http://www.boost.org/LICENSE_1_0.txt). 105* Discussions about the library are held on the [Boost developers mailing list](http://www.boost.org/community/groups.html#main). Be sure to read the [discussion policy](http://www.boost.org/community/policy.html) before posting and add the `[nowide]` tag at the beginning of the subject line. 106
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}