Wrote a short introduction about the string API.

Doc/Generator/Input/Manual.txt

@@ -6,6 +6,9 @@ Title2: Using the library
 
 *
 <- Starting.html | Getting started
+
+*
+<- Strings.html | Basic text operations
 ---
 Title2: Modifying the library
 

Doc/Generator/Input/Strings.txt

@@ -0,0 +1,57 @@
+<- Manual.html | Back to main page
+
+Title: Basic text operations
+The string API can be found in Source/DFPSR/api/stringAPI.h, where you can read the specific documentation for each method.
+The methods allow easily loading and parsing files using a single page of code without the risk of corrupting memory.
+Element access it read-only even for writable strings, so you're supposed to create strings by clearing and appending.
+This could probably be done with a single string type, but it's easier to reason about using one that heap allocates (String) and one that's lighter (ReadableString).
+---
+Title2: Encoding
+Both dsr::String and dsr::ReadableString are encoded in the UTF-32 format
+ using only line-feed for line-breaks.
+This takes more memory but guarantees that each character is one element
+ which makes algorithms a lot easier to implement when you cannot get corrupted
+ characters or line-breaks by mistake.
+---
+Title2: string_load
+Loading text from a file using string_load supports UTF-8 and UTF-16.
+If no byte order mark is detected, the content is loaded as raw Latin-1
+ by treating each byte in the file as U+00 to U+FF.
+Loading a string from a file using string_load removes carriage-return (U'\r' or 13)
+ and null terminators (U'\0' or 0).
+---
+Title2: string_save
+Saving text to a file using string_save lets you select the encodings for
+ characters and line-breaks.
+By default, text is stored as UTF-8 (only takes more space when needed)
+ with a byte order mark (so that other programs know that it's UTF-8)
+ and CR-LF line-breaks (so that it can be read on all major desktop systems).
+
+---
+Title2: dsr::String
+String is the dynamic text container based on reference counting and immutability.
+It guarantees that a head allocated buffer exists when length > 0.
+Assigning a String to another will make a shallow copy and increase the buffer's reference count.
+Appending more text to or clearing a String sharing its buffers with others will clone the buffer to prevent it from overwriting other strings.
+Splitting a String will use reference counting to refer to the same allocation.
+Splitting a literal will first create a new heap allocation and then refer to it from all new elements.
+---
+Title2: dsr::ReadableString
+ReadableString is used instead of String as an input argument so that U"" literals can be given without creating a new allocation.
+Accidentally giving a regular "" literal (not UTF-32) will be stopped instead of automatically converted.
+If you want to accept giving "" and automatically allocate a buffer for the UTF-32 conversion, then just use String.
+See the String as a value and ReadableString as a constant reference.
+---
+Title2: dsr::Printable
+Inheriting from Printable and defining toStreamIndented allow printing your type using printText (prints to standard output), debugText (only prints in debug mode) and throwError (calls std::runtime_error).
+
+For non-virtual types, you can define string_toStreamIndented with an overload to keep the type simple.
+
+Each of these printing methods allow passing multiple arguments separated by commas.
+To print to a new String, give a number of arguments to string_combine.
+If you want to keep the existing content and add more text at the end, use string_append.
+If appending a character, you probably don't want to print its numerical value, so call string_appendChar for each character being added.
+
+Unlike the << operation, toStreamIndented can take an indentation argument which makes it faster and easier to serialize types into files.
+Just let each line begin with the given indentation and then add your own, which can be given to the child components' indentation arguments recursively.
+---

Doc/Generator/main.cpp

@@ -15,18 +15,17 @@ bool string_beginsWith(const ReadableString &a, const ReadableString &b) {
 void processContent(String &target, String content) {
 	string_split_callback([&target](ReadableString section) {
 		//printText(U"Processing: ", section, U"\n");
-		ReadableString dense = string_removeOuterWhiteSpace(section);
-		if (string_length(dense) == 0) {
+		if (string_length(section) == 0) {
 			//printText(U"    Break\n");
 			string_append(target, U"\n</P><P>\n");
-		} else if (string_match(dense, U"*")) {
+		} else if (string_match(section, U"*")) {
 			//printText(U"    Dot\n");
 			string_append(target, U"<IMG SRC=\"Images/SmallDot.png\">\n");
-		} else if (string_match(dense, U"---")) {
+		} else if (string_match(section, U"---")) {
 			//printText(U"    Border\n");
 			string_append(target, U"</P><IMG SRC=\"Images/Border.png\"><P>\n");
-		} else if (string_beginsWith(dense, U"<-")) {
-			ReadableString arguments = string_from(dense, 2);
+		} else if (string_beginsWith(section, U"<-")) {
+			ReadableString arguments = string_from(section, 2);
 			int splitIndex = string_findFirst(arguments, U'|');
 			if (splitIndex > -1) {
 				ReadableString link = string_removeOuterWhiteSpace(string_before(arguments, splitIndex));
@@ -37,8 +36,8 @@ void processContent(String &target, String content) {
 				//printText(U"    Link to ", arguments, U"\n");
 				string_append(target, U"<A href=\"", arguments, "\">", arguments, "</A>");
 			}
-		} else if (string_beginsWith(dense, U"Image:")) {
-			ReadableString arguments = string_from(dense, 6);
+		} else if (string_beginsWith(section, U"Image:")) {
+			ReadableString arguments = string_from(section, 6);
 			int splitIndex = string_findFirst(arguments, U'|');
 			if (splitIndex > -1) {
 				ReadableString image = string_removeOuterWhiteSpace(string_before(arguments, splitIndex));
@@ -49,25 +48,24 @@ void processContent(String &target, String content) {
 				//printText(U"    Image at ", arguments, U"\n");
 				string_append(target, U"<IMG SRC=\"", arguments, "\" ALT=\"\">\n");
 			}
-		} else if (string_beginsWith(dense, U"Title:")) {
-			ReadableString title = string_from(dense, 6);
+		} else if (string_beginsWith(section, U"Title:")) {
+			ReadableString title = string_from(section, 6);
 			//printText(U"    Title: ", title, U"\n");
 			string_append(target, U"</P><H1>", title, U"</H1><P>");
-		} else if (string_beginsWith(dense, U"Title2:")) {
-			ReadableString title = string_from(dense, 7);
+		} else if (string_beginsWith(section, U"Title2:")) {
+			ReadableString title = string_from(section, 7);
 			//printText(U"    Title2: ", title, U"\n");
 			string_append(target, U"</P><H2>", title, U"</H2><P>");
-		} else if (string_beginsWith(dense, U"Title3:")) {
-			ReadableString title = string_from(dense, 7);
+		} else if (string_beginsWith(section, U"Title3:")) {
+			ReadableString title = string_from(section, 7);
 			//printText(U"    Title3: ", title, U"\n");
 			string_append(target, U"</P><H3>", title, U"</H3><P>");
-		} else if (string_beginsWith(dense, U"Code:")) {
-			ReadableString code = string_from(dense, 5);
+		} else if (string_beginsWith(section, U"Code:")) {
+			ReadableString code = string_from(section, 5);
 			//printText(U"    Code: ", code, U"\n");
 			string_append(target, U"<blockquote>", code, U"</blockquote>");
 		} else {
-			//printText(U"    Text: ", dense, U"\n");
-			string_append(target, dense);
+			string_append(target, section, U"\n");
 		}
 	}, content, U'\n');
 }

Doc/License.html

@@ -28,41 +28,59 @@ A:active { color: #00A0A0; }
 </P><H1> License terms for David Forsgren Piuva's Software Renderer</H1><P>
 </P><P>
 The software renderer is using a combination of the ZLIB open source license (for David Piuva's code) and public domain (for other people's code).
+
 </P><P>
 The ZLIB license essentially requires the copyright notice to remain in source code redistributions and that the origin is not missrepresented. This is just common sense made explicit for the sake of consumer protection, because lying about having written the library would be a scam against the buyers.
+
 </P><P>
-Public domain essentially means owned by the people, to prevent code from being withdrawn. When a project has many contributors, the risk of having one of them withdrawing copy rights increases significantly. Public domain code don't have any copyright holder, so pulling back contributions is only possible if the code turns out to be illegal.</P><IMG SRC="Images/Border.png"><P>
+Public domain essentially means owned by the people, to prevent code from being withdrawn. When a project has many contributors, the risk of having one of them withdrawing copy rights increases significantly. Public domain code don't have any copyright holder, so pulling back contributions is only possible if the code turns out to be illegal.
+</P><IMG SRC="Images/Border.png"><P>
 </P><H2> ZLIB Open source license (David Piuva's code)</H2><P>
 </P><P>
 zlib open source license
+
 </P><P>
 Copyright (c) David Forsgren Piuva
+
 </P><P>
 This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
+
 </P><P>
 Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:
+
 </P><P>
 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
+
 </P><P>
 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
+
 </P><P>
-3. This notice may not be removed or altered from any source distribution.</P><IMG SRC="Images/Border.png"><P>
+3. This notice may not be removed or altered from any source distribution.
+</P><IMG SRC="Images/Border.png"><P>
 </P><H2> Public domain (other people's code)</H2><P>
 </P><P>
 The renderer has embedded the stb_image library using public domain terms (unlicense.org). While you could use stb_image under the more restrictive MIT license terms out of respect for its creators, it's essentially nullified by the more permissive public domain option.
+
 </P><P>
-This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means. In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</P><IMG SRC="Images/Border.png"><P>
+This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means. In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+</P><IMG SRC="Images/Border.png"><P>
 <b>SDK media</b>
+
 </P><P>
-You may use the media files in SDK examples for your own project. Just don't falsely claim to have made it, because that would be fraud.</P><IMG SRC="Images/Border.png"><P>
+You may use the media files in SDK examples for your own project. Just don't falsely claim to have made it, because that would be fraud.
+</P><IMG SRC="Images/Border.png"><P>
 </P><H2> License summary (for those who worry about getting sued)</H2><P>
 </P><P>
 The stb_image library lets you choose between MIT and public domain, so the least restrictive option becomes public domain. When combined with the non-optional ZLIB license from the majority of the DFPSR library, the ZLIB terms are more restrictive than public domain. In conclusion, all you need to follow is the ZLIB terms for the library as a whole because public domain is compatible with all open source license terms.
+
 </P><P>
 For releasing source code, you can only violate the terms as a whole if you alter a copyright notice or lie about who made what.
+
 </P><P>
 For releasing binaries, you can only violate the terms as a whole if you lie about who made what. There are no requirements to credit anyone in released binaries, because stb_image lets you choose the public domain license.
+
 </P><P>
-You are not forced to share modifications, because the library does not contain any GPL license. It is however in a company's best interest to share bug-fixes so that they don't have to be re-applied when pulling a new version.</P><IMG SRC="Images/Border.png"><P>
+You are not forced to share modifications, because the library does not contain any GPL license. It is however in a company's best interest to share bug-fixes so that they don't have to be re-applied when pulling a new version.
+</P><IMG SRC="Images/Border.png"><P>
 </P>
 </BODY> </HTML>

Doc/Manual.html

@@ -26,11 +26,15 @@ A:active { color: #00A0A0; }
 <P>
 </P><H1> David Piuva's software renderer</H1><P>
 </P><P>
-When you just want to code in your own pace without worrying about API deprecation.</P><IMG SRC="Images/Border.png"><P>
+When you just want to code in your own pace without worrying about API deprecation.
+</P><IMG SRC="Images/Border.png"><P>
 </P><H2> Using the library</H2><P>
 </P><P>
 <IMG SRC="Images/SmallDot.png">
-<A href="Starting.html">Getting started</A></P><IMG SRC="Images/Border.png"><P>
+<A href="Starting.html">Getting started</A>
+</P><P>
+<IMG SRC="Images/SmallDot.png">
+<A href="Strings.html">Basic text operations</A></P><IMG SRC="Images/Border.png"><P>
 </P><H2> Modifying the library</H2><P>
 </P><P>
 <IMG SRC="Images/SmallDot.png">

Doc/Security.html

@@ -29,12 +29,20 @@ A:active { color: #00A0A0; }
 </P><H1> Security information for David Forsgren Piuva's Software Renderer</H1><P></P><IMG SRC="Images/Border.png"><P>
 </P><H2> Purpose</H2><P>
 </P><P>
-The library is designed to stand the test of time when making software to be ported by future generations.Any attempts at security against hackers from a distant future with hundreds of years to study the source code and superior quantum processors to break your encryptions would be futile.</P><IMG SRC="Images/Border.png"><P>
+The library is designed to stand the test of time when making software to be ported by future generations.
+Any attempts at security against hackers from a distant future with hundreds of years to study the source code and superior quantum processors to break your encryptions would be futile.
+</P><IMG SRC="Images/Border.png"><P>
 </P><H2> Design</H2><P>
 </P><P>
-Due to the flat design of the library (shallow call depth), applying browser grade security in every internal function would not be practical nor fast.Memory bound checks are removed in release builds for maximum performance.Your application should terminate if incorrect input caused an error to be thrown from the library, because resuming execution from a state which breaks the invariant means that correctness can no longer be guaranteed.</P><IMG SRC="Images/Border.png"><P>
+Due to the flat design of the library (shallow call depth), applying browser grade security in every internal function would not be practical nor fast.
+Memory bound checks are removed in release builds for maximum performance.
+Your application should terminate if incorrect input caused an error to be thrown from the library, because resuming execution from a state which breaks the invariant means that correctness can no longer be guaranteed.
+</P><IMG SRC="Images/Border.png"><P>
 </P><H2> How to be "safe" (if such a thing can ever be acheived)</H2><P>
 </P><P>
-In order to be safe, you must either read all input from a reliable source (like a protected folder) or validate all input yourself before giving it to the library (no memory aliasing, extreme image dimensions, invalid file syntax...).Just preventing others from writing over binaries would not help, because the library does not have security against file corruption when loading media.Treat it like you would treat a fast low-level graphics API, don't give direct access to potential attackers.</P><IMG SRC="Images/Border.png"><P>
+In order to be safe, you must either read all input from a reliable source (like a protected folder) or validate all input yourself before giving it to the library (no memory aliasing, extreme image dimensions, invalid file syntax...).
+Just preventing others from writing over binaries would not help, because the library does not have security against file corruption when loading media.
+Treat it like you would treat a fast low-level graphics API, don't give direct access to potential attackers.
+</P><IMG SRC="Images/Border.png"><P>
 </P>
 </BODY> </HTML>

Doc/Starting.html

@@ -30,79 +30,107 @@ A:active { color: #00A0A0; }
 </P><H2> Working in Linux</H2><P>
 </P><P>
 Place the library's root folder inside of a new folder. This gives room for the temporary object's folder, which will be created outside of the dfpsr folder when compiling.
+
 </P><P>
 <IMG SRC="Images/Warning.png" ALT="Warning">
 A light-weight Linux distribution for laptops (such as Linux Mint) might require you to install GNU's compiler toolchain <B>"gcc"</B> and X11 headers <B>"libx11-dev"</B>.
+
 </P><P>
 <IMG SRC="Images/Warning.png" ALT="Warning">
 Big-endian support is only theoretical and has never actually been tested, because big-endian desktops were practically extinct when the library was created. If you happen to own such a rare museum item in working condition, sending the <B>DSR_BIG_ENDIAN</B> macro to compilation should activate the big-endian mode and shift the direction of bit shift meant to be equivalent with the address space.
+
 </P><P>
 </P><H2> Build and run an example program:</H2><P>
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Select an SDK example and open its folder in a terminal.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Give permission to execute the build script.
+
 </P><P>
 <blockquote> chmod +x build.sh</blockquote>
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Run the build script.
+
 </P><P>
 <blockquote> ./build.sh</blockquote></P><H2> If no example runs, try regression tests to diagnose:</H2><P><IMG SRC="Images/SmallDot.png">
 Open the source folder in a terminal and run the test script:
+
 </P><P>
 <blockquote>chmod +x test.sh</blockquote>
+
 </P><P>
 <blockquote>./test.sh</blockquote>
+
 </P><P>
 This will stop with a clearly visible error message if any of the tests fail.
+
 </P><P>
 </P><H2> Create your own project</H2><P>
 </P><P>
 <IMG SRC="Images/SmallDot.png">
-Copy the folder of a template program.If you want a 3D application with animations, start from basic3D.If you want graphical user interface that only redrawn when something happens, start from basicGUI.If you want a command line interface application, start from basicCLI. Command line applications are more portable by using "WINDOW_MANAGER=NONE". This compiles the dummy wrapper NoWindow.cpp so that it can run on the pure operating system without any display server.
+Copy the folder of a template program.
+If you want a 3D application with animations, start from basic3D.
+If you want graphical user interface that only redrawn when something happens, start from basicGUI.
+If you want a command line interface application, start from basicCLI. Command line applications are more portable by using "WINDOW_MANAGER=NONE". This compiles the dummy wrapper NoWindow.cpp so that it can run on the pure operating system without any display server.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Change ROOT_PATH and TEMP_DIR in your build script to refer to the same locations from a new source path. If you don't use the build script, you can just delete it.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Update header include paths to the library from the new folder location.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
-Add your own external dependencies to LINKER_FLAGS within a quote with -l in front of each library name.</P><IMG SRC="Images/Border.png"><P>
+Add your own external dependencies to LINKER_FLAGS within a quote with -l in front of each library name.
+</P><IMG SRC="Images/Border.png"><P>
 </P><H2> Compiling a project on Microsoft Windows</H2><P>
 </P><P>
 Create a project from existing code:
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Download a mingw edition of CodeBlocks from their website. <A href="http://www.codeblocks.org/downloads/26#windows">www.codeblocks.org/downloads</A>
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Start CodeBlocks with administrator rights and create a new Win32 project, just to get the correct libraries. You can then throw away the template main file.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 If not starting as an administrator, certain parts of the file system may lack necessary permissions needed for creating executable binaries.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Select C++ 14 with G++ from the GCC toolchain, so that it will be compatible with the software renderer. Link with "-lm -pthread" to get standard C++ math and threading. This should be done for both debug and release.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Import all source files from <B>dfpsr/Source/DFPSR</B>.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Import all source files from <B>the project you want to build</B>.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Import <B>dfpsr/Source/windowManagers/Win32Window.cpp</B>.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Save your project, so that you can continue working on the project.
+
 </P><P>
 <IMG SRC="Images/SmallDot.png">
 Build and run the project.
+
 </P><P>
-This is not an ideal solution for development if you plan to have multiple projects depending on the same library. A better solution would be to compile the whole dfpsr folder into a static library, link to it in each of your projects and refer to includeFramework.h.</P><IMG SRC="Images/Border.png"><P>
+This is not an ideal solution for development if you plan to have multiple projects depending on the same library. A better solution would be to compile the whole dfpsr folder into a static library, link to it in each of your projects and refer to includeFramework.h.
+</P><IMG SRC="Images/Border.png"><P>
 </P>
 </BODY> </HTML>

Doc/Strings.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html> <HTML lang=en> <HEAD> <STYLE>
+body { background-color: #EEFFEE; font-size: 16px; font-family: Arial;
+       color: #000000; margin: 0px;
+       padding-left: 0px; padding-right: 0px;
+       padding-top: 0px; padding-bottom: 0px; }
+H1 { padding-left: 10px; padding-top: 10px; padding-bottom: 10px; font-size: 26px; }
+H2 { padding-left: 10px; padding-top: 10px;  font-size: 20px; }
+blockquote {
+  color: #FFFFFF; background: #000000;
+  font-size: 20px; font-family: monospace;
+  padding-left: 5px; padding-right: 5px;
+  padding-top: 5px; padding-bottom: 5px;
+}
+P { padding-left: 10px; }
+IMG { padding-left: 0px; padding-right: 0px;
+       padding-top: 0px; padding-bottom: 0px; }
+
+A { font-size: 18px; font-family: Arial; color: #0000A0; text-decoration: none; }
+A:hover { color: #000070; background: #AAffAA; }
+A:active { color: #00A0A0; }
+.normal { font-size: 18px; color: #00A0A0; }
+.sub { font-size: 18px; color: #ffffdf; }
+
+</STYLE> </HEAD> <BODY>
+<IMG SRC="Images/Title.png" ALT="Images/Title.png">
+<P>
+<A href="Manual.html">Back to main page</A>
+</P><P>
+</P><H1> Basic text operations</H1><P>The string API can be found in Source/DFPSR/api/stringAPI.h, where you can read the specific documentation for each method.
+The methods allow easily loading and parsing files using a single page of code without the risk of corrupting memory.
+Element access it read-only even for writable strings, so you're supposed to create strings by clearing and appending.
+This could probably be done with a single string type, but it's easier to reason about using one that heap allocates (String) and one that's lighter (ReadableString).
+</P><IMG SRC="Images/Border.png"><P>
+</P><H2> Encoding</H2><P>Both dsr::String and dsr::ReadableString are encoded in the UTF-32 format
+ using only line-feed for line-breaks.
+This takes more memory but guarantees that each character is one element
+ which makes algorithms a lot easier to implement when you cannot get corrupted
+ characters or line-breaks by mistake.
+</P><IMG SRC="Images/Border.png"><P>
+</P><H2> string_load</H2><P>Loading text from a file using string_load supports UTF-8 and UTF-16.
+If no byte order mark is detected, the content is loaded as raw Latin-1
+ by treating each byte in the file as U+00 to U+FF.
+Loading a string from a file using string_load removes carriage-return (U'\r' or 13)
+ and null terminators (U'\0' or 0).
+</P><IMG SRC="Images/Border.png"><P>
+</P><H2> string_save</H2><P>Saving text to a file using string_save lets you select the encodings for
+ characters and line-breaks.
+By default, text is stored as UTF-8 (only takes more space when needed)
+ with a byte order mark (so that other programs know that it's UTF-8)
+ and CR-LF line-breaks (so that it can be read on all major desktop systems).
+
+</P><P>
+</P><IMG SRC="Images/Border.png"><P>
+</P><H2> dsr::String</H2><P>String is the dynamic text container based on reference counting and immutability.
+It guarantees that a head allocated buffer exists when length > 0.
+Assigning a String to another will make a shallow copy and increase the buffer's reference count.
+Appending more text to or clearing a String sharing its buffers with others will clone the buffer to prevent it from overwriting other strings.
+Splitting a String will use reference counting to refer to the same allocation.
+Splitting a literal will first create a new heap allocation and then refer to it from all new elements.
+</P><IMG SRC="Images/Border.png"><P>
+</P><H2> dsr::ReadableString</H2><P>ReadableString is used instead of String as an input argument so that U"" literals can be given without creating a new allocation.
+Accidentally giving a regular "" literal (not UTF-32) will be stopped instead of automatically converted.
+If you want to accept giving "" and automatically allocate a buffer for the UTF-32 conversion, then just use String.
+See the String as a value and ReadableString as a constant reference.
+</P><IMG SRC="Images/Border.png"><P>
+</P><H2> dsr::Printable</H2><P>Inheriting from Printable and defining toStreamIndented allow printing your type using printText (prints to standard output), debugText (only prints in debug mode) and throwError (calls std::runtime_error).
+
+</P><P>
+For non-virtual types, you can define string_toStreamIndented with an overload to keep the type simple.
+
+</P><P>
+Each of these printing methods allow passing multiple arguments separated by commas.
+To print to a new String, give a number of arguments to string_combine.
+If you want to keep the existing content and add more text at the end, use string_append.
+If appending a character, you probably don't want to print its numerical value, so call string_appendChar for each character being added.
+
+</P><P>
+Unlike the << operation, toStreamIndented can take an indentation argument which makes it faster and easier to serialize types into files.
+Just let each line begin with the given indentation and then add your own, which can be given to the child components' indentation arguments recursively.
+</P><IMG SRC="Images/Border.png"><P>
+</P>
+</BODY> </HTML>

Doc/StyleGuide.html

@@ -28,18 +28,46 @@ A:active { color: #00A0A0; }
 </P><P>
 </P><H1> Code convention for David Forsgren Piuva's Software Renderer</H1><P>
 </P><P>
-To keep the style consistent, the style being used in the library is explained in this document.</P><IMG SRC="Images/Border.png"><P>
-1. Use common sense! If it looks wrong to human readers then it's wrong. Don't defeat the purpose of any rule by taking it too far.</P><IMG SRC="Images/Border.png"><P>
-2. Don't use iterators when there is any other way to accomplish the task. You can't write efficient algorithms without knowing the data structures.</P><IMG SRC="Images/Border.png"><P>
-3. Tabs for indentation then spaces for alignment. It's the best of both worlds by both having variable length tabs	and correct alignment that works between lines of the same indentation.</P><IMG SRC="Images/Border.png"><P>
-4. No dangling else, use explicit {} for safety. Otherwise someone might add an extra statement and get random crashes.</P><IMG SRC="Images/Border.png"><P>
-5. No hpp extensions, use h for all headers. Could be either way, but this library uses *.h for compact naming, so keep it consistent.</P><IMG SRC="Images/Border.png"><P>
-6. C-style casting for raw data manipulation and C++-style for high-level classes.When using assembly intrinsics and raw pointer manipulation to alter the state of bits,verbose high-level abstractions only make it harder to count CPU cycles in your head.Always use the tool that makes sense for the problem you're trying to solve.C++ style is for things that are abstracted on a higher level.C style is for when a byte is just a byte and you just want to manipulate it in a specific way.</P><IMG SRC="Images/Border.png"><P>
-7. Don't call member methods with "this" set to nullptr.This would be undefined behaviour and may randomly crash.Use global functions instead. They allow checking pointers for nullbecause they are explicit arguments declared by the programmer.</P><IMG SRC="Images/Border.png"><P>
-8. Avoid using STD/STL directly in SDK examples.Exposing types from the standard library should be done using an alias or wrapper in the dsr namespace.This allow replacing the standard library without breaking backward compatibility.The C++ standard libraries have broken backward compatibility before and it can happen again.</P><IMG SRC="Images/Border.png"><P>
-9. Don't abuse the auto keyword everywhere just to make it look more "modern".Explicit type safety is what makes compiled languages safer than scripting.</P><IMG SRC="Images/Border.png"><P>
-10. No new line for opening brackets.Makes the code more compact and decreases the risk of copy-paste errors.</P><IMG SRC="Images/Border.png"><P>
-11. Don't fix the style of someone else's code if you can easily read it.Especially if there's no style rule explicitly supporting the change.Otherwise style changes will defeat the purpose by introducing more version conflicts.</P><IMG SRC="Images/Border.png"><P>
-12. Don't change things that you don't know how to test.</P><IMG SRC="Images/Border.png"><P>
+To keep the style consistent, the style being used in the library is explained in this document.
+</P><IMG SRC="Images/Border.png"><P>
+1. Use common sense! If it looks wrong to human readers then it's wrong. Don't defeat the purpose of any rule by taking it too far.
+</P><IMG SRC="Images/Border.png"><P>
+2. Don't use iterators when there is any other way to accomplish the task. You can't write efficient algorithms without knowing the data structures.
+</P><IMG SRC="Images/Border.png"><P>
+3. Tabs for indentation then spaces for alignment. It's the best of both worlds by both having variable length tabs	and correct alignment that works between lines of the same indentation.
+</P><IMG SRC="Images/Border.png"><P>
+4. No dangling else, use explicit {} for safety. Otherwise someone might add an extra statement and get random crashes.
+</P><IMG SRC="Images/Border.png"><P>
+5. No hpp extensions, use h for all headers. Could be either way, but this library uses *.h for compact naming, so keep it consistent.
+</P><IMG SRC="Images/Border.png"><P>
+6. C-style casting for raw data manipulation and C++-style for high-level classes.
+When using assembly intrinsics and raw pointer manipulation to alter the state of bits,
+verbose high-level abstractions only make it harder to count CPU cycles in your head.
+Always use the tool that makes sense for the problem you're trying to solve.
+C++ style is for things that are abstracted on a higher level.
+C style is for when a byte is just a byte and you just want to manipulate it in a specific way.
+</P><IMG SRC="Images/Border.png"><P>
+7. Don't call member methods with "this" set to nullptr.
+This would be undefined behaviour and may randomly crash.
+Use global functions instead. They allow checking pointers for null
+because they are explicit arguments declared by the programmer.
+</P><IMG SRC="Images/Border.png"><P>
+8. Avoid using STD/STL directly in SDK examples.
+Exposing types from the standard library should be done using an alias or wrapper in the dsr namespace.
+This allow replacing the standard library without breaking backward compatibility.
+The C++ standard libraries have broken backward compatibility before and it can happen again.
+</P><IMG SRC="Images/Border.png"><P>
+9. Don't abuse the auto keyword everywhere just to make it look more "modern".
+Explicit type safety is what makes compiled languages safer than scripting.
+</P><IMG SRC="Images/Border.png"><P>
+10. No new line for opening brackets.
+Makes the code more compact and decreases the risk of copy-paste errors.
+</P><IMG SRC="Images/Border.png"><P>
+11. Don't fix the style of someone else's code if you can easily read it.
+Especially if there's no style rule explicitly supporting the change.
+Otherwise style changes will defeat the purpose by introducing more version conflicts.
+</P><IMG SRC="Images/Border.png"><P>
+12. Don't change things that you don't know how to test.
+</P><IMG SRC="Images/Border.png"><P>
 </P>
 </BODY> </HTML>

Source/DFPSR/api/stringAPI.cpp

@@ -773,6 +773,7 @@ static int64_t getCapacity(const ReadableString &source) {
 }
 
 static void expand(String &target, int64_t newLength, bool affectUsedLength) {
+	cloneIfShared(target);
 	if (newLength > target.length) {
 		if (newLength > getCapacity(target)) {
 			reallocateBuffer(target, newLength, true);