uLib -- Library of commonly useful C functions and C++ classes.

Copyright (C) Love Nystrom.
Released to the public domain under the NNOSL license.

Contributors:
Love Nystrom <neo.love@hotmail.com> - Original release.

===============================================================================

Acknowledgements:

uLib (optionally) uses slightly modified headers from the Native Development Kit,
to provide declarations for Windows Native data types (used by e.g. NTDLL).
However, uLib is not derived from NDK, and can be built without it.

The NDK is Copyright (c) 2005-2012 Alex Ionescu.
A well deserved Thank You go out to all contributing NDK authors.
The NDK is distributed under it's own licence, not the NNOSL governing %uLib.
(See ndk.txt and readme.txt in the uLib/ndk include directory for details.)

Acknowledgements for other, smaller, contributions can be found
in the respective source modules where they occur.

===============================================================================

Release notes

"uLib" stands for "utilityLib" or "userLib", and is intended for Windows user mode, though some parts, e.g. DLinkList, is platform independent, and can also be used in kernel mode, or even on other platforms, provided that C++ is permitted.

The library contains powerful and fast functions and classes for Windows applications. It is primarily intended for C++, but the non-class parts can be used with C as well.

Some notable classes

DLinkList - Double-linked list class, optimal, with QuickSort of links, et c.
DynArray - Dynamically resizable arrays, unsorted/sorted, lean and flexible.
Thread - Kill-safe threads with stack unwind & local d'tors (requires SEH).
IniFile - Adds convenience and functionality to Windows INI implementation.
SharedMem - Super easy sharing of memory between processes.
TTResFont - Easy embedding of TrueType fonts as resources.
RingBuffer - Light-weight heterogenous circular FIFO data buffer.
FileDialog - File open/save dialog with support for multiple file selection.

Some notable functions

Supplementary I/O, f.ex. ReadLine(), IsEndOfFile(), LoadAndMapFile().
Lightning fast FileExist() / DirExist().
Case insensitive stristr() / wcsistr().
Flexible and powerful debugging output with DPrint().
Easy processing of multi-strings, f.ex. EnumerateMultiSz().
Easy enumeration of version resource strings with EnumVersionStrings().
Easy creation of memory dialog templates.
Easy emulation of keyboard and mouse input.

Useful and powerful tricks

Run processes with std handle redirection, with CreateCapturedProcess().
Display non-blocking message boxes, with AsyncMsgBoxEx().

.. And lots more, to make Your coding easier, cleaner, and faster.

Prepare

First, fetch the source if you haven't. Put the headers in <basedir>/inc/uLib, and the implementation in <basedir>/uLib.

Then add the 'inc' directory to your include path, and the implementation directory to your source path. This organisation invites usage to be e.g. #include <uLib/Debug.h>, which makes your include statements crystal clear. All uLib sources use this style internally.

Then add the 'uLib/<compiler>/<x86|x64>' directory to your lib path. Preferentially, when using MSVC, add the 'uLib/<compiler>/uLib.vcproj to your "solution", so you can set the dependency and get automatic link resolution and automatic rebuild on uLib source updates.

Of course you can modify this scheme if you want to.

Build

In order to build all versions of uLib, You need an x86/x64 capable C/C++ compiler, and both x86 and x64 MASM compatible assemblers. Your mileage may vary if you don't need all variants.

Currently I build uLib with VisualStudio 2oo8 and CodeBlocks 20, but it is intended to be buildable with any C/C++ compiler for Windows. You could contribute if You have something else, e.g. Borland or Intel !

uLib builds for x86 and x64, with ANSI, MultiByte, or Unicode char sets. Some parts of uLib, f.ex. DLinkList, does not use any Windows APIs, and those can of course be separately compiled for any platform.

When building the GCC libs (with C::B/MinGW), due to difficulties in setting up dual bitness assemblers, the project uses pre-assembled .obj files from the MSVC project, and link them to the library (.a) files instead of assembling them with AS.

Documentation

uLib's documentation is sometimes a bit terse, due to the fact that it was, until now, a proprietary library, and I only needed some brief comments in the headers and source to remind me of the non-obvious...

The documenation commentary is located in the headers. If in doubt, consult the headers and source, or ask me by email if it's non-trivial. Fleshing out the documentation with doxyGen comments is ongoing.

The library is extensive, so expect to spend some initial time browsing the doc and the headers, to get a sense of what's available...

Bug Reports

Please direct bug reports to the SourceForge ticket tracker, or directly to me by email if it's confidential.

Compatibility

uLib has a good track record on Windows and shows no obvious quirks on ReactOS, due to judicious self constraint in it's API usage. However, it's possible that some parts of uLib might uncover unimplemented ReactOS features. Surely that's for the better.

Remember to set WINVER to 0x502 (in Common.h) when building uLib for use on ReactOS.

Contributions

Please respect my code formatting style, at least the three minimum requirements:

A space is mandatory after the opening parenthesis, and before the closing parenthesis, of function argument lists.
Line-broken argument lists should never ever be indented to the opening parenthesis, just one indent from the previous line.
Prototypes with anonymous argument lists are, in general, forbidden.

Good luck on the path... // Love