163 | {% block body %}{% endblock %}
164 |
165 |
166 | {% block comments %}{% endblock %}
167 |
168 |
4 |
5 | Read the Docs
6 | v: {{ current_version }}
7 |
8 |
9 |
36 | {% endif %}
37 |
38 |
--------------------------------------------------------------------------------
/docs/source/general/console.rst:
--------------------------------------------------------------------------------
1 | .. _console:
2 |
3 | PawLIB Tester Console
4 | ################################
5 |
6 | PawLIB also provides a tester application, which will allow you to run
7 | any of Goldilocks tests and benchmarks using GoldilocksShell.
8 |
9 | In addition to the various tests, we've provided comparative tests in our
10 | suites, to facilitate performance comparisons of PawLIB against the standard
11 | alternatives. See :ref:`goldilocks_benchmarker` for details on reading the
12 | benchmarker statistics and results.
13 |
14 | See :ref:`setup-build-tester` for instructions on how to build the PawLIB
15 | Tester.
16 |
17 | Once it's built, you can run the tester from within the PawLIB repository
18 | via ``./tester``.
19 |
20 | For PawLIB test and suite ID naming conventions, see :ref:`tests`.
21 |
22 | Interactive Mode
23 | ================================
24 |
25 | We can start Interactive Mode by running the tester application without
26 | arguments, via ``./tester``. Type commands at the ``>>`` prompt.
27 |
28 | All commands are detailed under :ref:`goldilocksshell_interactive`.
29 |
30 | Command-Line Mode
31 | ==============================
32 |
33 | We can run tests and suites by passing arguments to our ``./tester``
34 | application. This is especially useful if you want to run tests in a
35 | automated manner, such as with a continuous integration system.
36 |
37 | You can get help via ``./tester --help``.
38 |
39 | Multiple commands may be run in a single line. They will be executed in order.
40 |
41 | All commands are detailed under :ref:`goldilocksshell_cli`.
--------------------------------------------------------------------------------
/.vscode/tasks.json:
--------------------------------------------------------------------------------
1 | {
2 | // See https://go.microsoft.com/fwlink/?LinkId=733558
3 | // for the documentation about the tasks.json format
4 | "version": "2.0.0",
5 | "tasks": [
6 | {
7 | "label": "Build Debug",
8 | "type": "shell",
9 | "command": "make tester_debug",
10 | "group": {
11 | "kind": "build",
12 | "isDefault": true
13 | },
14 | },
15 | {
16 | "label": "Rebuild Debug",
17 | "type": "shell",
18 | "command": "make cleandebug; make tester_debug",
19 | "group": "build",
20 | },
21 | {
22 | "label": "Build Release",
23 | "type": "shell",
24 | "command": "make tester",
25 | "group": "build",
26 | },
27 | {
28 | "label": "Rebuild Release",
29 | "type": "shell",
30 | "command": "make cleanrelease, make tester",
31 | "group": "build",
32 | },
33 | {
34 | "label": "Run Debug",
35 | "type": "shell",
36 | "command": "./tester_debug",
37 | "group": {
38 | "kind": "test",
39 | "isDefault": true
40 | },
41 | "dependsOn": "Build Debug",
42 | },
43 | {
44 | "label": "Run Release",
45 | "type": "shell",
46 | "command": "./tester",
47 | "group": "test",
48 | "dependsOn": "Build Release"
49 | },
50 | ]
51 | }
--------------------------------------------------------------------------------
/pawlib-source/src/pool_tests.cpp:
--------------------------------------------------------------------------------
1 | #include "pawlib/pool_tests.hpp"
2 |
3 | void TestSuite_Pool::load_tests()
4 | {
5 | register_test("P-tB1601",
6 | new TestPool_ThriceFill(), true, new TestPool_ThriceFillAlloc());
7 |
8 | register_test("P-tB1602",
9 | new TestPool_Create(TestPool_Create::TestPoolCreateMode::DFLT));
10 | register_test("P-tB1603",
11 | new TestPool_Create(TestPool_Create::TestPoolCreateMode::COPY));
12 | register_test("P-tB1604",
13 | new TestPool_Create(TestPool_Create::TestPoolCreateMode::DFLT_FAILSAFE));
14 | register_test("P-tB1605",
15 | new TestPool_Create(TestPool_Create::TestPoolCreateMode::COPY_FAILSAFE));
16 |
17 | register_test("P-tB1606",
18 | new TestPool_Access());
19 |
20 | register_test("P-tB1607",
21 | new TestPool_Access());
22 |
23 | register_test("P-tB1608",
24 | new TestPool_Exception(TestPool_Exception::FailTestType::POOL_FULL_ASGN));
25 | register_test("P-tB1609",
26 | new TestPool_Exception(TestPool_Exception::FailTestType::POOL_FULL_ASGN_CPY));
27 | register_test("P-tB160A",
28 | new TestPool_Exception(TestPool_Exception::FailTestType::POOL_ACC_DELETED_REF));
29 | register_test("P-tB160B",
30 | new TestPool_Exception(TestPool_Exception::FailTestType::POOL_DES_FOREIGN_REF));
31 | register_test("P-tB160C",
32 | new TestPool_Exception(TestPool_Exception::FailTestType::POOL_DES_DELETED_REF));
33 | register_test("P-tB160D",
34 | new TestPool_Exception(TestPool_Exception::FailTestType::POOL_DES_FOREIGN_REF));
35 | }
36 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | # LICENSE (BSD-3-Clause)
2 |
3 | Copyright (C) 2019 MousePaw Media.
4 | All rights reserved.
5 |
6 | Redistribution and use in source and binary forms, with or without modification,
7 | are permitted provided that the following conditions are met:
8 |
9 | 1. Redistributions of source code must retain the above copyright notice, this
10 | list of conditions and the following disclaimer.
11 |
12 | 2. Redistributions in binary form must reproduce the above copyright notice,
13 | this list of conditions and the following disclaimer in the documentation and/or
14 | other materials provided with the distribution.
15 |
16 | 3. Neither the name of the copyright holder nor the names of its contributors
17 | may be used to endorse or promote products derived from this software without
18 | specific prior written permission.
19 |
20 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
21 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
22 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
24 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
25 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
27 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 |
--------------------------------------------------------------------------------
/docs/source/_themes/sphinx_rtd_theme/search.html:
--------------------------------------------------------------------------------
1 | {#
2 | basic/search.html
3 | ~~~~~~~~~~~~~~~~~
4 |
5 | Template for the search page.
6 |
7 | :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
8 | :license: BSD, see LICENSE for details.
9 | #}
10 | {%- extends "layout.html" %}
11 | {% set title = _('Search') %}
12 | {% set script_files = script_files + ['_static/searchtools.js'] %}
13 | {% block footer %}
14 |
17 | {# this is used when loading the search index using $.ajax fails,
18 | such as on Chrome for documents on localhost #}
19 |
20 | {{ super() }}
21 | {% endblock %}
22 | {% block body %}
23 |
31 |
32 | {% if search_performed %}
33 |
10 |
32 | {% trans %}Free document hosting provided by Read the Docs.{% endtrans %} 33 | 34 |
35 | -
11 |
- {{ _('Versions') }} 12 | {% for slug, url in versions %} 13 |
- {{ slug }} 14 | {% endfor %} 15 |
-
17 |
- {{ _('Downloads') }} 18 | {% for type, url in downloads %} 19 |
- {{ type }} 20 | {% endfor %} 21 |
-
23 |
- {{ _('On Read the Docs') }} 24 |
- 25 | {{ _('Project Home') }} 26 | 27 |
- 28 | {{ _('Builds') }} 29 | 30 |
32 | {% trans %}Free document hosting provided by Read the Docs.{% endtrans %} 33 | 34 |
{{ _('Search Results') }}
34 | {% if not search_results %} 35 |{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.') }}
36 | {% endif %} 37 | {% endif %} 38 |
39 | {% if search_results %}
40 |
50 | {% endblock %}
51 |
--------------------------------------------------------------------------------
/pawlib-source/src/flex_array_tests.cpp:
--------------------------------------------------------------------------------
1 | #include "pawlib/flex_array_tests.hpp"
2 |
3 | const int ONETHOU = 1000;
4 | const int HUNTHOU = 100000;
5 | //const int tenmill = 10,000,000; // for stress testing
6 | void TestSuite_FlexArray::load_tests()
7 | {
8 | //Benchmark test section for "Push" function (flexarray vs. vector)
9 | //push at end
10 | register_test("P-tB1001", new TestFArray_Push(ONETHOU), true, new TestVector_Push(ONETHOU));
11 | register_test("P-tS1001", new TestFArray_Push(HUNTHOU), false);
12 |
13 | //Benchmark test section for "Shift" function (flexarray vs. vector)
14 | //push at front
15 | register_test("P-tB1002", new TestFArray_Shift(ONETHOU), true, new TestVector_Shift(ONETHOU));
16 | register_test("P-tS1002", new TestFArray_Shift(HUNTHOU), false);
17 |
18 | //Benchmark test section for "Insert" function (flexarray vs. vector)
19 | //insert at middle
20 | register_test("P-tB1003", new TestFArray_Insert(ONETHOU), true, new TestVector_Insert(ONETHOU));
21 | register_test("P-tS1003", new TestFArray_Insert(HUNTHOU), false);
22 |
23 | register_test("P-tB1004", new TestFArray_Yank(ONETHOU), true, new TestVector_Yank(ONETHOU));
24 | register_test("P-tS1004", new TestFArray_Yank(HUNTHOU), false);
25 |
26 | register_test("P-tB1005", new TestFArray_Unshift(ONETHOU), true, new TestVector_Unshift(ONETHOU));
27 | register_test("P-tS1005", new TestFArray_Unshift(HUNTHOU), false);
28 |
29 | register_test("P-tB1006", new TestFArray_Pop(ONETHOU), true, new TestVector_Pop(ONETHOU));
30 | register_test("P-tS1006", new TestFArray_Pop(HUNTHOU), false);
31 |
32 | register_test("P-tB1007", new TestFArray_Erase(ONETHOU), true, new TestVector_Erase(ONETHOU));
33 | register_test("P-tS1007", new TestFArray_Erase(HUNTHOU), false);
34 |
35 | register_test("P-tB1008", new TestFArray_Peek(), true, new TestVector_Peek());
36 |
37 | register_test("P-tB1009", new TestFArray_Contained(), true);
38 | register_test("P-tB1010", new TestFArray_SharedPtr(), true);
39 | register_test("P-tB1011", new TestFArray_UniquePtr(), true);
40 | }
41 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # CHANGELOG
2 |
3 | ## Unreleased
4 |
5 | ## PawLIB 1.0 [2017-06-17]
6 |
7 | ### Stable Features
8 |
9 | * CoreTypes 1.0
10 | * NEW trilean atomic data type.
11 | * FlexArray 1.0
12 | * NEW high-performance vector-like data structure.
13 | * FlexQueue 1.0
14 | * NEW high-performance queue (FIFO) data structure.
15 | * FlexStack 1.0
16 | * NEW high-performance stack (LIFO) data structure.
17 | * Goldilocks 1.0
18 | * Added on-demand test loading and execution.
19 | * Added on-demand benchmarker.
20 | * Added comparative benchmarking w/ advanced statistics.
21 | * End-user can define new tests and test suites.
22 | * IOChannel 1.0
23 | * Multiple outputs.
24 | * Intelligent type-based formatting.
25 | * Text formatting flags.
26 | * Message prioritization and categorization.
27 | * Print memory addresses and output raw binary dumps with pointers.
28 | * Pool 1.0
29 | * NEW general-purpose implementation of the object pool design pattern.
30 | * Standard Utilities 1.0
31 | * Integer-to-string converter.
32 | * Float-to-string converter.
33 |
34 | ### Experimental Features
35 |
36 | * BinConf 0.1 [Experimental]
37 | * Utilities for converting between various data types and their binary equivalents.
38 | * FlexBit 0.1 [Experimental]
39 | * NEW adaptive, optimized byte-based stack data structure.
40 | * FlexMap 0.1 [Experimental]
41 | * NEW high-performance map data structure, based on the same
42 | algorithm as the other Flex data structures.
43 | * RigidStack 0.1 [Experimental]
44 | * An efficient, fixed-size stack.
45 | * Onestring 0.3 [Experimental]
46 | * Template-sized, Unicode-friendly string.
47 | * Pawsort 0.1 [Experimental]
48 | * NEW dual-pivot introsort (unstable sorting algorithm).
49 | * Added implementation of Knuth shell sort.
50 | * Added implementation of heap sort.
51 | * Added implementation of insertion sort.
52 | * QuickString 0.3 [Experimental]
53 | * Template-sized, high-performance string.
54 | * SinglyLinkedList 0.1 [Experimental]
55 | * A general-purpose implementation of the singly linked list data structure.
56 |
--------------------------------------------------------------------------------
/docs/source/_themes/sphinx_rtd_theme/footer.html:
--------------------------------------------------------------------------------
1 |
52 |
53 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # PawLIB
2 |
3 | The **PawLIB** static library provides various common utility functions,
4 | many of which are designed as high-performance, near-drop-in-replacements
5 | for common C++ Standard Library (`std`) classes. See the [official project page][1].
6 |
7 | PawLIB focuses on minimizing CPU usage first, and memory second, and as
8 | such it is designed to run on older systems and those with more limited
9 | resources.
10 |
11 | It is used by virtually all of MousePaw Media' core projects.
12 |
13 | - Flex Data Structures: High performance alternatives to C++ data structures, and then some.
14 | - Goldilocks: Testing and benchmarking framework.
15 | - IOChannel: Feature-rich multi-output text output system. (Alternative to ``std::cout``)
16 | - Trilean: A new atomic data type with three unique states: true, false, and maybe.
17 | - Pool: A general-purpose implementation of the object pool design pattern.
18 | - Onestring: Performance string class with full Unicode support. (Alternative to ``std::string``) [Experimental]
19 |
20 | ## Authors
21 |
22 | - Nate Groggett
23 | - Jason C. McDonald
24 | - Michael Parkman
25 | - Sergio Ramirez
26 | - Scott Taylor
27 | - Jonathan Theodore
28 | - Jarek Thomas
29 | - Bowen Volwiler
30 |
31 | ## Dependencies
32 |
33 | PawLIB depends on CPGF.
34 |
35 | ## Building
36 |
37 | If you have the full source repository, see BUILDING.md for information
38 | on how to build PawLIB, PawLIB Tester, and the documentation.
39 |
40 | The Ready-To-Use version of PawLIB only contains the folders `include`
41 | and `lib`. You can find the full source repository on [GitHub][5].
42 |
43 | ## Contributions
44 |
45 | We do NOT accept pull requests through GitHub.
46 | If you would like to contribute code, please read our
47 | [Contribution Guide][3].
48 |
49 | All contributions are licensed to us under the
50 | [MousePaw Media Terms of Development][4].
51 |
52 | ## License
53 |
54 | PawLIB is licensed under the BSD-3 License. (See LICENSE.md)
55 |
56 | The project is owned and maintained by [MousePaw Media][2].
57 |
58 | [1]: https://www.mousepawmedia.com/pawlib
59 | [2]: https://www.mousepawmedia.com/developers
60 | [3]: https://www.mousepawmedia.com/developers/contribution
61 | [4]: https://www.mousepawmedia.com/termsofdevelopment
62 | [5]: https://github.com/mousepawmedia/pawlib
63 |
--------------------------------------------------------------------------------
/pawlib-source/include/pawlib/constants.hpp:
--------------------------------------------------------------------------------
1 | /** Constants [PawLIB]
2 | * Version: 1.0
3 | *
4 | * All globally-used constants.
5 | *
6 | * Author(s): Jason C. McDonald
7 | */
8 |
9 | /* LICENSE (BSD-3-Clause)
10 | * Copyright (c) 2016-2019 MousePaw Media.
11 | * All rights reserved.
12 | *
13 | * Redistribution and use in source and binary forms, with or without
14 | * modification, are permitted provided that the following conditions are met:
15 | *
16 | * 1. Redistributions of source code must retain the above copyright notice,
17 | * this list of conditions and the following disclaimer.
18 | *
19 | * 2. Redistributions in binary form must reproduce the above copyright notice,
20 | * this list of conditions and the following disclaimer in the documentation
21 | * and/or other materials provided with the distribution.
22 | *
23 | * 3. Neither the name of the copyright holder nor the names of its contributors
24 | * may be used to endorse or promote products derived from this software without
25 | * specific prior written permission.
26 | *
27 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
28 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
29 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
30 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
31 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
32 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
33 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
34 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
35 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
36 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
37 | * THE POSSIBILITY OF SUCH DAMAGE.
38 | *
39 | * CONTRIBUTING
40 | * See https://www.mousepawmedia.com/developers for information
41 | * on how to contribute to our projects.
42 | */
43 |
44 | #ifndef PAWLIB_CONSTANTS_HPP
45 | #define PAWLIB_CONSTANTS_HPP
46 |
47 | #include -
41 | {% for href, caption, context in search_results %}
42 |
-
43 | {{ caption }}
44 |
{{ context|e }}
45 |
46 | {% endfor %}
47 |
90 |
91 | {# SIDE NAV, TOGGLES ON MOBILE #}
92 |
145 |
146 |
147 |
148 | {# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
149 |
155 |
156 |
157 | {# PAGE CONTENT #}
158 |
174 |
175 |
176 | {% include "versions.html" %}
177 |
178 | {% if not embedded %}
179 |
180 |
191 | {%- for scriptfile in script_files %}
192 |
193 | {%- endfor %}
194 |
195 | {% endif %}
196 |
197 | {# RTD hosts this file, so just load on non RTD builds #}
198 | {% if not READTHEDOCS %}
199 |
200 | {% endif %}
201 |
202 | {# STICKY NAVIGATION #}
203 | {% if theme_sticky_navigation %}
204 |
209 | {% endif %}
210 |
211 | {%- block footer %} {% endblock %}
212 |
213 |
214 |
215 |
--------------------------------------------------------------------------------
/docs/source/core/trilean.rst:
--------------------------------------------------------------------------------
1 | Trilean
2 | ###################################
3 |
4 | What Is It?
5 | ===================================
6 |
7 | A trilean is an atomic data type with three distinct states: "true", "maybe",
8 | and "false". It is designed to behave like a boolean, but with the
9 | additional feature of "uncertainty."
10 |
11 | In order to understand trilean, one must remember that "true" and "false"
12 | are *certain* states, entirely distinct from and unequivalent to "maybe".
13 | All of trilean's behavior is based around this rule.
14 |
15 | Why Use Trilean?
16 | ----------------------------------
17 |
18 | The logic of trilean has historically been achieved in C++ using either
19 | an enumeration or a pair of booleans. However, trilean offers a couple of
20 | distinct advantages:
21 |
22 | * A trilean variable is exactly one byte in size.
23 | * All three states can be represented in a single variable.
24 | * Trilean is fully compatible with boolean and its constants.
25 | * Conditional logic with trilean is simpler and cleaner.
26 |
27 | Using Trilean
28 | ==================================
29 |
30 | Including Trilean
31 | ---------------------------------------
32 |
33 | To include Trilean, use the following:
34 |
35 | .. code-block:: c++
36 |
37 | #include "pawlib/core_types.hpp"
38 |
39 | "Maybe" Contant
40 | ----------------------------------
41 |
42 | Along with the normal ``true`` and ``false`` constants provided by C++,
43 | trilean offers a ``maybe`` constant. This new constant is designed to
44 | be distinct from ``true`` and ``false``, yet usable in the same manner
45 | for trileans.
46 |
47 | Defining and Assigning
48 | ----------------------------------
49 |
50 | Defining a new trilean variable is simple.
51 |
52 | .. code-block:: c++
53 |
54 | tril foo = true;
55 | tril bar = maybe
56 | tril baz = false;
57 |
58 | In addition to the three constants, you can assign other booleans and trileans.
59 |
60 | .. code-block:: c++
61 |
62 | bool foo = true;
63 | tril bar = foo;
64 | tril baz = bar;
65 |
66 | // foo, bar, and baz are all 'true'
67 |
68 | Conditionals
69 | ----------------------------------
70 |
71 | Obviously, one can compare a trilean against of its state constants
72 | directly.
73 |
74 | .. code-block:: c++
75 |
76 | tril foo = maybe;
77 |
78 | if(foo == true)
79 | // code if TRUE...
80 | else if(foo == maybe)
81 | // code if MAYBE...
82 | else if(foo == false)
83 | // code if FALSE...
84 |
85 | However, one can also test a trilean in the same manner as a boolean.
86 |
87 | .. code-block:: c++
88 |
89 | tril foo = maybe;
90 |
91 | if(foo)
92 | // code if TRUE...
93 | else if(~foo)
94 | // code if MAYBE...
95 | else if(!foo)
96 | // code if FALSE...
97 |
98 | You will notice that, in addition to the familiar tests for "true"
99 | (``if(foo)``) and "false" (``if(!foo)``), trilean has a third unary
100 | operator, ``~``, for "maybe" (``if(~foo)``).
101 |
102 | .. IMPORTANT:: Remember, neither the "true" or "false" conditions will ever
103 | match "maybe".
104 |
105 | This basic behavior is what makes trilean so useful. For example, you may want
106 | to repeat a block of code until you encounter specific scenarios to cause it
107 | to either pass or fail, using something like ``while(~foo)``.
108 |
109 | Comparisons
110 | ----------------------------------
111 |
112 | Trilean can be compared to booleans and other trileans using the ``==`` and
113 | ``!=`` operators.
114 |
115 | .. code-block:: c++
116 |
117 | tril foo = true;
118 | tril bar = maybe;
119 | bool baz = true;
120 |
121 | if(foo == bar)
122 | // This fails.
123 |
124 | if(foo != bar)
125 | // This passes.
126 |
127 | if(foo == baz)
128 | // This passes.
129 |
130 | if(baz == foo)
131 | // This passes.
132 |
133 | if(baz == bar)
134 | // This fails.
135 |
136 | What About Switch?
137 | ----------------------------------
138 |
139 | The idea of allowing a trilean to cast to an integer was discussed and
140 | debated in great deal. Finally, the decision was made to prevent casting
141 | a trilean to anything but a boolean (discussed later).
142 |
143 | This means that trileans **are not compatible with switch statements**.
144 | While this may be initially disappointing to anyone used to using an
145 | enumeration for three-state logic, one will notice that an if-statement covering
146 | all three states of a trilean has at least 4 less lines of boilerplate.
147 |
148 | .. code-block:: c++
149 |
150 | tril foo;
151 |
152 | /* This code demonstrates an if statement covering all three states
153 | * of a trilean. */
154 |
155 | if(foo)
156 | {
157 | // Some code.
158 | }
159 | else if(~foo)
160 | {
161 | // Some code.
162 | }
163 | else if(!foo)
164 | {
165 | // Some code.
166 | }
167 |
168 | Certainty
169 | ==================================
170 |
171 | Because trilean stores its data in two bits, it is possible for a variable
172 | to track its last certain state. In other words, if a trilean is "true" or
173 | "false," and then is set to "maybe", that true/false value is still being
174 | stored behind the scenes.
175 |
176 | To make this useful, trilean offers a ``certain()`` function, which returns
177 | the last certain state of the variable without actually modifying itself.
178 |
179 | .. code-block:: c++
180 |
181 | tril foo = true;
182 | foo = maybe;
183 |
184 | bool bar = foo.certain();
185 |
186 | // bar is now 'true', while foo is still 'maybe'
187 |
188 | This behavior can also be used to revert a trilean to its last certain state.
189 |
190 | .. code-block:: c++
191 |
192 | tril foo = true;
193 | foo = maybe;
194 | foo = foo.certain();
195 |
196 | // foo is now 'true'
197 |
198 | Implications
199 | ----------------------------------
200 |
201 | The concept of "certainty" technically allows one to recognize and use four
202 | trilean states:
203 |
204 | * Certain true (``if( foo )``)
205 | * Uncertain true (``if( ~foo && foo.certain() )``)
206 | * Uncertain false (``if (~foo && !foo.certain() )``)
207 | * Certain false (``if (!foo)``)
208 |
209 | Uncertainty Variables
210 | ----------------------------------
211 |
212 | The "magical" behavior of assigning the constant "maybe" not affecting the
213 | previous certain state is achieved through "uncertainty" variables. Any time an
214 | uncertainty is assigned to a trilean, only the uncertainty of the trilean
215 | is affected.
216 |
217 | The constant "maybe" is usually the only uncertainty object you will interact
218 | with. However, it is possible to create your own ``certainty``. Be aware that
219 | this data type does not provide any mechanism for modifying it after creation.
220 |
221 | .. code-block:: c++
222 |
223 | uncertainty my_maybe(true);
224 | uncertainty my_certain(false);
225 |
226 | As is expected, an uncertainty can never match "true" or "false", or be
227 | directly cast to a boolean. However, the ``~`` operator works as with trileans.
228 |
229 | .. code-block:: c++
230 |
231 | if(~my_maybe)
232 | // This passes.
233 |
234 | if(~my_certain)
235 | // This fails.
236 |
237 | if(~my_certain == false)
238 | // This passes.
239 |
240 | The usefulness of an uncertainty variable is, quite probably, limited to
241 | allowing manipulation of a trilean's certainty.
242 |
243 | Gotchas
244 | ==================================
245 |
246 | Casting to Bool
247 | ----------------------------------
248 |
249 | In order to preserve the core logic that "maybe != true" in statements like
250 | ``if(foo)``, casting a trilean to a boolean causes "maybe" to be converted to
251 | "false".
252 |
253 | .. code-block:: c++
254 |
255 | tril foo = maybe;
256 | bool bar = foo;
257 |
258 | // bar is now 'false'
259 |
260 | In most cases, it is recommended to use the ``certain()`` function.
261 |
262 | .. NOTE:: In case you were wondering, we ensured that "maybe != false" in comparisons
263 | and conditionals by separately overloading the ``!``, ``!=``, and ``==``
264 | operators.
265 |
--------------------------------------------------------------------------------
/pawlib-source/include/pawlib/core_types.hpp:
--------------------------------------------------------------------------------
1 | /** Core and Atomic Data Types [PawLIB]
2 | * Version: 1.0
3 | *
4 | * New basic data types, including Trilean.
5 | *
6 | * Author(s): Jason C. McDonald
7 | */
8 |
9 | /* LICENSE (BSD-3-Clause)
10 | * Copyright (c) 2016-2019 MousePaw Media.
11 | * All rights reserved.
12 | *
13 | * Redistribution and use in source and binary forms, with or without
14 | * modification, are permitted provided that the following conditions are met:
15 | *
16 | * 1. Redistributions of source code must retain the above copyright notice,
17 | * this list of conditions and the following disclaimer.
18 | *
19 | * 2. Redistributions in binary form must reproduce the above copyright notice,
20 | * this list of conditions and the following disclaimer in the documentation
21 | * and/or other materials provided with the distribution.
22 | *
23 | * 3. Neither the name of the copyright holder nor the names of its contributors
24 | * may be used to endorse or promote products derived from this software without
25 | * specific prior written permission.
26 | *
27 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
28 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
29 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
30 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
31 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
32 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
33 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
34 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
35 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
36 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
37 | * THE POSSIBILITY OF SUCH DAMAGE.
38 | *
39 | * CONTRIBUTING
40 | * See https://www.mousepawmedia.com/developers for information
41 | * on how to contribute to our projects.
42 | */
43 |
44 | #ifndef PAWLIB_CORETYPES_HPP
45 | #define PAWLIB_CORETYPES_HPP
46 |
47 | #include
159 |
172 |
173 |
160 | {% include "breadcrumbs.html" %}
161 |
171 |
162 |
169 | {% include "footer.html" %}
170 |
51 |
84 | {%- endif %}
85 | {%- endmacro %}
86 |
87 | {%- macro script() %}
88 |
97 | {%- for scriptfile in script_files %}
98 |
99 | {%- endfor %}
100 | {%- endmacro %}
101 |
102 | {%- macro css() %}
103 |
104 |
105 | {%- for cssfile in css_files %}
106 |
107 | {%- endfor %}
108 | {%- endmacro %}
109 |
110 |
111 |
112 |
113 | {{ metatags }}
114 | {%- block htmltitle %}
115 |
52 | {%- block sidebarlogo %}
53 | {%- if logo %}
54 |
57 | {%- endif %}
58 | {%- endblock %}
59 | {%- if sidebars != None %}
60 | {#- new style sidebar: explicitly include/exclude templates #}
61 | {%- for sidebartemplate in sidebars %}
62 | {%- include sidebartemplate %}
63 | {%- endfor %}
64 | {%- else %}
65 | {#- old style sidebars: using blocks -- should be deprecated #}
66 | {%- block sidebartoc %}
67 | {%- include "localtoc.html" %}
68 | {%- endblock %}
69 | {%- block sidebarrel %}
70 | {%- include "relations.html" %}
71 | {%- endblock %}
72 | {%- block sidebarsourcelink %}
73 | {%- include "sourcelink.html" %}
74 | {%- endblock %}
75 | {%- if customsidebar %}
76 | {%- include customsidebar %}
77 | {%- endif %}
78 | {%- block sidebarsearch %}
79 | {%- include "searchbox.html" %}
80 | {%- endblock %}
81 | {%- endif %}
82 |
83 |
164 | {%- block document %}
165 |
181 | {%- endblock %}
182 |
183 | {%- block relbar2 %}{{ relbar() }}{% endblock %}
184 |
185 | {%- block footer %}
186 |
201 |
166 | {%- if render_sidebar %}
167 |
176 | {%- endblock %}
177 |
178 | {%- block sidebar2 %}{{ sidebar() }}{% endblock %}
179 |
180 |
168 | {%- endif %}
169 |
174 | {%- endif %}
175 |
170 | {% block body %} {% endblock %}
171 |
172 | {%- if render_sidebar %}
173 | asdf asdf asdf asdf 22
202 | {%- endblock %} 203 | 204 | 205 | 206 | -------------------------------------------------------------------------------- /docs/source/core/stdutils.rst: -------------------------------------------------------------------------------- 1 | Standard Utilities 2 | ################################### 3 | 4 | These are common utility functions which are used by many other classes 5 | in PawLIB. 6 | 7 | Not all of the functions are documented below, only those we believe will 8 | be useful to PawLIB users. 9 | 10 | Including Standard Utilities 11 | ================================= 12 | 13 | To include Standard Utilities, use the following: 14 | 15 | .. code-block:: c++ 16 | 17 | #include "pawlib/stdutils.hpp" 18 | 19 | Integer to std::string [``itos()``] 20 | ================================================== 21 | 22 | We can convert any integer data type, signed or unsigned, to a std::string 23 | using ``itos()``. 24 | 25 | ``itos()`` converts the integer to a std::string. It accepts three arguments, 26 | two of which are required: 27 | 28 | * the integer to convert, 29 | 30 | * the base you're working in, represented as an integer (default=10), 31 | 32 | * whether to represent digits greater than 9 as uppercase (default=false) 33 | 34 | .. code-block:: c++ 35 | 36 | // The integer to convert. 37 | int foo = -16753; 38 | 39 | /* Convert the float to a std::string. We're passing all the arguments, 40 | * even though only the first two are required, for the sake of example. 41 | */ 42 | std::string foo_s = stdutils::itos(foo, 10, false); 43 | 44 | // Print out the std::string. 45 | ioc << foo_s << IOCtrl::endl; 46 | 47 | // OUTPUT: -16753 48 | 49 | .. IMPORTANT:: Enumerations are not implicitly cast to ints with this function. 50 | Therefore, you must ``static_cast