Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@tokox
tokox committed Mar 20, 2024
1 parent 9c26e84 commit 540e1e3
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 25 deletions.
47 changes: 23 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,49 +11,48 @@ Test program called `test.cpp` is just reading and writing same one JSON object.

### Classes, constants and variables

- Class `object` represents **JSON object**. It is made on top of `std::variant`
- `object::variant` is `std::variant` used by `object`
- `object::value_type` is *an enum* representing **JSON objects types**
- Class `object` represents **JSON object**. It is made on top of `std::any`
- `value_type` is *an enum* representing **JSON objects types**
- Types are represented as following:

| JSON type | C++ type | `object::value_type` name | `object::value_type` value (`object::variant` index) |
| :---------- | :------------------------------------ | :------------------------ | :--------------------------------------------------- |
| `Null` | `std::monostate` | `Null` | `0` |
| `Boolean` | `bool` | `Bool` | `1` |
| `Number` | `long long int` and `long double` | `Int` and `Float` | `2` and `3` |
| `String` | `std::string` | `String` | `4` |
| `Array` | `std::vector<object>` | `Vector` | `5` |
| `Object` | `std::map<std::string, object>` | `Map` | `6` |
| JSON type | C++ type | `value_type` |
| :---------- | :------------------------------------ | :----------------------- |
| `Null` | **\[None]** (std::any has no value) | `Null` |
| `Boolean` | `bool` | `Bool` |
| `Number` | `long long int` and `long double` | `Int` or `Float` |
| `String` | `std::string` | `String` |
| `Array` | `std::vector<object>` | `Vector` |
| `Object` | `std::map<std::string, object>` | `Map` |

- `import_error` is **an exception class** thrown by **import functions** (export functions don't throw (see below))
- `ERR_???` are **error messages**

- `float_prec` is `size_t` for **float precision**
- `float_prec` is **float precision**

### Functions for import:

| Function | Description |
| :--------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| `object from(iterator& input_iterator, iterator input_end)` | Main function for import. Detects what type of object it is and calls corresponding `TYPE_from` function. Takes iterator to current input character and input end (it may be iterator to `std::*stream`, `std::string`, `std::vector`, c-string - basically whatever you want). `iterator` is a template parameter. Returns `object` with imported JSON |
| `object TYPE_from(iterator& input_iterator, iterator input_end)` | Imports specific type TYPE (for every JSON type). They are called by `from` after type detection. They import specific type - if it isn't correct they throw `import_error` |
| `object from(std::string& input_string)` | Returns `from(input_string->iterator)` (first) |
| `object& from(object& obj, std::string& input_string)` | Calls `from(input_string)` (above), saves result to `obj` and returns it |
| `object from(std::istream& input_stream)` | Returns `from(input_stream->iterator)` (first) |
| `object& from(object& obj, std::istream& input_stream)` | Calls `from(input_stream)` (above), saves result to `obj` and returns it |
| `std::istream& operator>>(std::istream& input_stream, object& obj)` | Calls `from(obj, input_stream)` (above) and returns `input_stream` |
| `object from(std::string& input_string)` | Returns `from(input_string->iterator)` (first) |
| `object& from(object& obj, std::string& input_string)` | Calls `from(input_string)` (above), saves result to `obj` and returns it |
| `object from(std::istream& input_stream)` | Returns `from(input_stream->iterator)` (first) |
| `object& from(object& obj, std::istream& input_stream)` | Calls `from(input_stream)` (above), saves result to `obj` and returns it |
| `std::istream& operator>>(std::istream& input_stream, object& obj)` | Calls `from(obj, input_stream)` (above) and returns `input_stream` |

#### :bangbang: Important:

`number_from` is returning `object` containing `Int` (`long long int`) or `Float` (`long double`). It chooses **the better option**. Here is how it works:

| Condition for number | `Int` (`long long int`) or `Float` (`long double`) |
| :------------------------------------------------------------------------------------------------------- | :------------------------------------------------- |
| doesn't fit in `long long int` (less than one or more than `std::numeric_limits<long long int>::max()`) | `Float` (`long double`) |
| fits in `long long int` and is an integer | `Int` (`long long int`) |
| fits in `long long int` and `long double` loses precision (is less precise than rounded `long long int`) | `Int` (`long long int`) |
| Well, `long long int` isn't any better than `long double` there! (Other) | `Float` (`long double`) |
| Condition for number | `value_type` (C++ type) |
| :------------------------------------------------------------------------------------------------------- | :---------------------- |
| doesn't fit in `long long int` (less than one or more than `std::numeric_limits<long long int>::max()`) | `Float` (`long double`) |
| fits in `long long int` and is an integer | `Int` (`long long int`) |
| fits in `long long int` and `long double` loses precision (is less precise than rounded `long long int`) | `Int` (`long long int`) |
| Well, `long long int` isn't any better than `long double` there! (Other) | `Float` (`long double`) |

You can always **cast it** to the other one **after import**.
You can always **cast it** to another **after import**.

### Functions for export:

Expand Down
5 changes: 4 additions & 1 deletion cpp-json.spec
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Name: tokox-cpp-json
Version: 1.2
Release: 1%{?dist}
Release: 2%{?dist}
Summary: C++ JSON object import/export library

License: MIT
Expand Down Expand Up @@ -36,6 +36,9 @@ cp -a LICENSE.md README.md %{buildroot}/usr/share/doc/tokox/cpp-json
%doc /usr/share/doc/tokox/cpp-json/README.md

%changelog
* Wed Mar 20 2024 Tomasz Kośnikowski (tokox) - 1.2-2
- Updated README

* Tue Mar 19 2024 Tomasz Kośnikowski (tokox) - 1.2-1
- Replaced std::variant with std::any
- improved object class
Expand Down

0 comments on commit 540e1e3

Please sign in to comment.