Skip to content

Commit

Permalink
Add db_type description to docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@zann1x
zann1x committed Oct 18, 2023
1 parent 826fa77 commit 037a332
Show file tree
Hide file tree
Showing 10 changed files with 187 additions and 117 deletions.
39 changes: 22 additions & 17 deletions docs/api/backend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,22 +21,25 @@ All names are defined in either `soci` or `soci::details` namespace.
// data types, as seen by the user
enum data_type
{
dt_string,
dt_int8,
dt_uint8,
dt_int16,
dt_uint16,
dt_int32,
dt_integer = dt_int32,
dt_uint32,
dt_int64,
dt_long_long = dt_int64,
dt_uint64,
dt_unsigned_long_long = dt_uint64,
dt_double,
dt_date,
dt_blob,
dt_xml
dt_string, dt_date, dt_double, dt_integer, dt_long_long, dt_unsigned_long_long
};

// data types, as seen by the user
enum db_type
{
db_string,
db_int8,
db_uint8,
db_int16,
db_uint16,
db_int32,
db_uint32,
db_int64,
db_uint64,
db_double,
db_date,
db_blob,
db_xml
};

// the enum type for indicator variables
Expand Down Expand Up @@ -86,8 +89,9 @@ public:
};
```
The `data_type` enumeration type defines all types that form the core type support for SOCI.
The `data_type` and `db_type` enumeration type defines all types that form the core type support for SOCI.
The enum itself can be used by clients when dealing with dynamic rowset description.
`data_type` is deprecated in favor of `db_type`, so users are encouraged to use the latter.
The `indicator` enumeration type defines all recognized *states* of data.
The `i_truncated` state is provided for the case where the string is retrieved from the database
Expand Down Expand Up @@ -217,6 +221,7 @@ public:

virtual int prepare_for_describe() = 0;
virtual void describe_column(int colNum, data_type& dtype,
db_type& dbtype,
std::string& column_name) = 0;

virtual standard_into_type_backend* make_into_type_backend() = 0;
Expand Down
14 changes: 10 additions & 4 deletions docs/api/client.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,10 @@ The following types are commonly used in the rest of the interface:

```cpp
// data types, as seen by the user
enum data_type { dt_string, dt_date, dt_double, dt_int8, dt_uint8, dt_int16, dt_uint16, dt_int32, dt_uint32, dt_int64, dt_uint64 };
enum data_type { dt_string, dt_date, dt_double, dt_integer, dt_long_long, dt_unsigned_long_long };

// data types, as seen by the user
enum db_type { db_string, db_date, db_double, db_int8, db_uint8, db_int16, db_uint16, db_int32, db_uint32, db_int64, db_uint64 };

// the enum type for indicator variables
enum indicator { i_ok, i_null, i_truncated };
Expand All @@ -22,7 +25,8 @@ enum indicator { i_ok, i_null, i_truncated };
class soci_error : public std::runtime_error { /* ... */ };
```
The `data_type` type defines the basic SOCI data types. User provided data types need to be associated with one of these basic types.
The `data_type` and `db_type` types define the basic SOCI data types. User provided data types need to be associated with one of these basic types.
`data_type` is deprecated in favor of `db_type`, so users are encouraged to use the latter.
The `indicator` type defines the possible states of data.
Expand Down Expand Up @@ -443,14 +447,16 @@ class column_properties
{
public:
std::string get_name() const;
data_type get_data_type() const;
data_type_type get_data_type() const;
db_type get_db_type() const;
};
```

This class contains the following members:

* `get_name` function that returns the name of the column.
* `get_data_type` that returns the type of the column.
* `get_data_type` that returns the type of the column (deprecate in favor of `get_db_type`).
* `get_db_type` that returns the type of the column.

See [Dynamic resultset binding](../types.md#dynamic-binding) for examples.

Expand Down
19 changes: 14 additions & 5 deletions docs/backends/firebird.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,17 +73,26 @@ type is not known at compile time.
When calling `row::get<T>()`, the type you should pass as T depends upon the underlying database type.
For the Firebird backend, this type mapping is:

| Firebird Data Type | SOCI Data Type | `row::get<T>` specializations |
| Firebird Data Type | SOCI Data Type (`data_type`) | `row::get<T>` specializations |
| --------------------------------------- | --------------------------------------- | --------------------------------- |
| numeric, decimal (where scale > 0) | dt_double | double |
| numeric, decimal [^1] (where scale = 0) | dt_int16/dt_int32/dt_int64, dt_double | dt_int16/int32_t/dt_int64, double |
| numeric, decimal [^1] (where scale = 0) | dt_integer, dt_double | int, double |
| double precision, float | dt_double | double |
| smallint | dt_int16 | int16_t |
| integer | dt_int32 | int32_t |
| bigint | dt_int64 | int64_t |
| smallint, integer | dt_integer | int |
| char, varchar | dt_string | std::string |
| date, time, timestamp | dt_date | std::tm |

| Firebird Data Type | SOCI Data Type (`db_type`) | `row::get<T>` specializations |
| --------------------------------------- | --------------------------------------- | --------------------------------- |
| numeric, decimal (where scale > 0) | db_double | double |
| numeric, decimal [^1] (where scale = 0) | db_int16/db_int32/db_int64, db_double | int16_t/int32_t/int64_t, double |
| double precision, float | db_double | double |
| smallint | db_int16 | int16_t |
| integer | db_int32 | int32_t |
| bigint | db_int64 | int64_t |
| char, varchar | db_string | std::string |
| date, time, timestamp | db_date | std::tm |

[^1] There is also 64bit integer type for larger values which is
currently not supported.

Expand Down
40 changes: 25 additions & 15 deletions docs/backends/mysql.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,21 +72,31 @@ The MySQL backend supports the use of the SOCI `row` class, which facilitates re
When calling `row::get<T>()`, the type you should pass as `T` depends upon the underlying database type.
For the MySQL backend, this type mapping is:

| MySQL Data Type | SOCI Data Type | `row::get<T>` specializations |
| ----------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------- |
| FLOAT, DOUBLE, DECIMAL and synonyms | dt_double | double |
| TINYINT | dt_int8 | int8_t |
| TINYINT UNSIGNED | dt_uint8 | uint8_t |
| SMALLINT | dt_int16 | int16_t |
| SMALLINT UNSIGNED | dt_uint16 | uint16_t |
| MEDIUMINT | dt_int32 | int32_t |
| MEDIUMINT UNSIGNED | dt_uint32 | uint32_t |
| INT | dt_int32 | int32_t |
| INT UNSIGNED | dt_uint32 | uint32_t |
| BIGINT | dt_int64 | int64_t |
| BIGINT UNSIGNED | dt_uint64 | uint64_t |
| CHAR, VARCHAR, BINARY, VARBINARY, TINYBLOB, MEDIUMBLOB, BLOB,LONGBLOB, TINYTEXT, MEDIUMTEXT, TEXT, LONGTEXT, ENUM | dt_string | std::string |
| TIMESTAMP (works only with MySQL >= 5.0), DATE, TIME, DATETIME | dt_date | std::tm |
| MySQL Data Type | SOCI Data Type (`data_type`) | `row::get<T>` specializations |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------- |
| FLOAT, DOUBLE, DECIMAL and synonyms | dt_double | double |
| TINYINT, TINYINT UNSIGNED, SMALLINT, SMALLINT UNSIGNED, INT | dt_integer | int |
| INT UNSIGNED | dt_long_long | long long or unsigned |
| BIGINT | dt_long_long | long long |
| BIGINT UNSIGNED | dt_unsigned_long_long | unsigned long long |
| CHAR, VARCHAR, BINARY, VARBINARY, TINYBLOB, MEDIUMBLOB, BLOB,LONGBLOB, TINYTEXT, MEDIUMTEXT, TEXT, LONGTEXT, ENUM | dt_string | std::string |
| TIMESTAMP (works only with MySQL >= 5.0), DATE, TIME, DATETIME | dt_date | std::tm |

| MySQL Data Type | SOCI Data Type (`db_type`) | `row::get<T>` specializations |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------- |
| FLOAT, DOUBLE, DECIMAL and synonyms | db_double | double |
| TINYINT | db_int8 | int8_t |
| TINYINT UNSIGNED | db_uint8 | uint8_t |
| SMALLINT | db_int16 | int16_t |
| SMALLINT UNSIGNED | db_uint16 | uint16_t |
| MEDIUMINT | db_int32 | int32_t |
| MEDIUMINT UNSIGNED | db_uint32 | uint32_t |
| INT | db_int32 | int32_t |
| INT UNSIGNED | db_uint32 | uint32_t |
| BIGINT | db_int64 | int64_t |
| BIGINT UNSIGNED | db_uint64 | uint64_t |
| CHAR, VARCHAR, BINARY, VARBINARY, TINYBLOB, MEDIUMBLOB, BLOB,LONGBLOB, TINYTEXT, MEDIUMTEXT, TEXT, LONGTEXT, ENUM | db_string | std::string |
| TIMESTAMP (works only with MySQL >= 5.0), DATE, TIME, DATETIME | db_date | std::tm |

(See the [dynamic resultset binding](../types.md#dynamic-binding) documentation for general information
on using the `Row` class.)
Expand Down
27 changes: 17 additions & 10 deletions docs/backends/odbc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,18 +60,25 @@ The ODBC backend supports the use of the SOCI `row` class, which facilitates ret
When calling `row::get<T>()`, the type you should pass as T depends upon the underlying database type.
For the ODBC backend, this type mapping is:

| ODBC Data Type | SOCI Data Type | `row::get<T>` specializations |
| --------------------------------------------------------- | -------------- | ----------------------------- |
| SQL_DOUBLE, SQL_DECIMAL, SQL_REAL, SQL_FLOAT, SQL_NUMERIC | dt_double | double |
| SQL_TINYINT | dt_int8 | int8_t |
| SQL_SMALLINT | dt_int16 | int16_t |
| SQL_INTEGER | dt_int32 | int32_t |
| SQL_BIGINT | dt_int64 | int64_t |
| SQL_CHAR, SQL_VARCHAR | dt_string | std::string |
| SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP | dt_date | std::tm |
| ODBC Data Type | SOCI Data Type (`data_type`) | `row::get<T>` specializations |
| --------------------------------------------------------- | ---------------------------- | ----------------------------- |
| SQL_DOUBLE, SQL_DECIMAL, SQL_REAL, SQL_FLOAT, SQL_NUMERIC | dt_double | double |
| SQL_TINYINT, SQL_SMALLINT, SQL_INTEGER, SQL_BIGINT | dt_integer | int |
| SQL_CHAR, SQL_VARCHAR | dt_string | std::string |
| SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP | dt_date | std::tm |

| ODBC Data Type | SOCI Data Type (`db_type`) | `row::get<T>` specializations |
| --------------------------------------------------------- | -------------------------- | ----------------------------- |
| SQL_DOUBLE, SQL_DECIMAL, SQL_REAL, SQL_FLOAT, SQL_NUMERIC | db_double | double |
| SQL_TINYINT | db_int8 | int8_t |
| SQL_SMALLINT | db_int16 | int16_t |
| SQL_INTEGER | db_int32 | int32_t |
| SQL_BIGINT | db_int64 | int64_t |
| SQL_CHAR, SQL_VARCHAR | db_string | std::string |
| SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP | db_date | std::tm |

Not all ODBC drivers support all datatypes.
Columns having the attribute `unsigned` get mapped to their corresponding `dt_uint[n]` and `uint[n]_t` types.
Columns having the attribute `unsigned` get mapped to their corresponding `db_uint[n]` and `uint[n]_t` types.

(See the [dynamic resultset binding](../types.md#dynamic-binding) documentation for general information on using the `row` class.)

Expand Down
Loading

0 comments on commit 037a332

Please sign in to comment.