Dmitigr Pgfe  1.1beta
The modern C++ API to PostgreSQL
Public Member Functions | List of all members
Sql_string Class Referenceabstract

Represents preparsed SQL strings. More...

#include <dmitigr/pgfe/sql_string.hpp>

Inheritance diagram for Sql_string:
Parameterizable

Public Member Functions

virtual bool is_empty () const =0
 
virtual bool is_query_empty () const =0
 
virtual bool is_parameter_missing (std::size_t index) const =0
 
virtual bool has_missing_parameters () const =0
 
virtual void append (const Sql_string *appendix)=0
 Appends the specified SQL string to this instance. More...
 
virtual void append (const std::string &appendix)=0
 
virtual void replace_parameter (const std::string &name, const Sql_string *replacement)=0
 Replaces the parameter named by the name with the specified sql_string. More...
 
virtual void replace_parameter (const std::string &name, const std::string &replacement)=0
 
virtual std::string to_string () const =0
 
virtual std::string to_query_string () const =0
 
virtual Compositeextra ()=0
 
virtual const Compositeextra () const =0
 
- Public Member Functions inherited from Parameterizable
virtual ~Parameterizable ()=default
 The destructor. More...
 
virtual std::size_t positional_parameter_count () const =0
 
virtual std::size_t named_parameter_count () const =0
 
virtual std::size_t parameter_count () const =0
 
virtual const std::string & parameter_name (std::size_t index) const =0
 
virtual std::optional< std::size_t > parameter_index (const std::string &name) const =0
 
virtual std::size_t parameter_index_throw (const std::string &name) const =0
 
virtual bool has_parameter (const std::string &name) const =0
 
virtual bool has_positional_parameters () const =0
 
virtual bool has_named_parameters () const =0
 
virtual bool has_parameters () const =0
 

Constructors

static DMITIGR_PGFE_API std::unique_ptr< Sql_string > APIENTRY make (const std::string &input)
 Constructs the new sql string. More...
 
virtual std::unique_ptr< Sql_stringclone () const =0
 

Detailed Description

Represents preparsed SQL strings.

A dollar sign ("$") followed by digits is used to denote a parameter with explicitly specified position. A colon (":") followed by alphanumerics is used to denote a named parameter with automatically assignable position. Currently a valid parameter positions are in range [1, 65535] and the parameter_count() is always less or equal to 65536.

Examples of valid SQL strings:

Member Function Documentation

◆ append() [1/2]

virtual void append ( const Sql_string appendix)
pure virtual

Appends the specified SQL string to this instance.

Requires
appendix.
Effects
This instance contains the given appendix. If (is_query_empty() == true) before calling this method, then extra data of appendix is appended to the extra data of this instance.
Exception safety guarantee
Strong.

◆ append() [2/2]

virtual void append ( const std::string &  appendix)
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ clone()

virtual std::unique_ptr<Sql_string> clone ( ) const
pure virtual
Returns
The copy of this instance.

◆ extra() [1/2]

virtual Composite* extra ( )
pure virtual
Returns
The extra data associated with this instance.

An any data can be associated with the object of type Sql_string. The initial associations can be specified in the related comments. The related comments - are comments that have no more than one new line character in between themselves and the content following them. The content following the related comments should be neither named parameter nor positional parameter nor consisting only of spaces nor empty.

Consider the example of the SQL input:

-- This is an unrelated comment (because 2 new line feeds follows after it).
-- $id$unrelated$id$
-- This is a related one line comment 1
-- $id$select-all$id$
/* $where$
* num > 0
* AND num < :num
* $where$
*/
-- This is a related one line comment 2
SELECT * FROM table WHERE :where;

The SQL code above contains just one actual query:

SELECT * FROM table WHERE :where

This query has seven related comments and two unrelated comments (at the beginning) because there are two new line characters following them. Next, there are two data associations specified as a dollar-quoted string constants tagged as id and where. The valid characters of tags are alphanumerics, the underscore character and the dash. Please, note, that the content in between the named tags might consist to multiple lines. In such a cases there are rules of the content formatting:

  1. The leading and trailing newline characters are always ignored and other newline characters are always preserved;
  2. If the content begins with non newline character, then the content is associated exactly as provided, i.e. all indentations are preserved;
  3. If the content begins with a newline character then the following lines will be left-aligned relative the most left non space character. In case of the sequence of one-line comments, the most left non space character are always follows the one-line comment marker ("--"). In case of the multi-line comment, the most left non space character can be a character that follows the asterisk with a space ("* "), or just the most left character.

Examples:

Example 1. The misaligned content of the association specified in the multi-line comment

/*
* $text1$
* one
* two
* three
* $text1$
*/
SELECT 1, 2, 3

The content of the text1 association is "one\n * two\nthree"

Example 2. The aligned content of the association specified in the multi-line comment

/*
* $text2$
* one
* two
* three
* $text2$
*/
SELECT 1, 2, 3

The content of the text2 association is "one\ntwo\nthree"

Example 3. The content of the association specified in the sequence of one-line comments

-- $text3$
--one
-- two
-- three
-- $text3$
SELECT 1, 2, 3

The content of the text3 association is "one\n two\n three"

◆ extra() [2/2]

virtual const Composite* extra ( ) const
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ has_missing_parameters()

virtual bool has_missing_parameters ( ) const
pure virtual
Returns
true if this SQL string has a positional parameter with an index i such that (is_parameter_missing(i) == false), or false otherwise.
See also
is_parameter_missing()

◆ is_empty()

virtual bool is_empty ( ) const
pure virtual
Returns
true if this SQL string is empty, or false otherwise.

◆ is_parameter_missing()

virtual bool is_parameter_missing ( std::size_t  index) const
pure virtual
Returns
false if the parameter at specified index is missing, or true otherwise. For example, the SQL string
SELECT :p, $3
has two missing parameters at indexes 0 and 1.
Requires
(index < positional_parameter_count())
Remarks
Missing parameters can only be eliminated by using append() or replace_parameter(). Thus, by replacing the parameter "p" with $2, $1 in the example above, missing parameters will be eliminated because the statement will become the following:
SELECT $2, $1, $3

◆ is_query_empty()

virtual bool is_query_empty ( ) const
pure virtual
Returns
true if this SQL string is consists only from comments and blank line(s), or false otherwise.

◆ make()

static DMITIGR_PGFE_API std::unique_ptr<Sql_string> APIENTRY make ( const std::string &  input)
static

Constructs the new sql string.

Parameters
input- the normal SQL input, which may contain multiple commands and comments. Comments can contain an associated extra data.
Returns
The new instance of type Sql_string parsed from the input.
Remarks
While the SQL input may contain multiple commands, the parser stops on either semicolon or zero character.
See also
extra().

◆ replace_parameter() [1/2]

virtual void replace_parameter ( const std::string &  name,
const Sql_string replacement 
)
pure virtual

Replaces the parameter named by the name with the specified sql_string.

Requires
(has_parameter(name) && replacement)
Effects
This instance contains the given replacement instead of the parameter named by the name. The extra data will not be affected.
Exception safety guarantee
Strong.
See also
has_parameter()

◆ replace_parameter() [2/2]

virtual void replace_parameter ( const std::string &  name,
const std::string &  replacement 
)
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ to_query_string()

virtual std::string to_query_string ( ) const
pure virtual
Returns
The query string that's actually passed to the PostgreSQL server.

◆ to_string()

virtual std::string to_string ( ) const
pure virtual
Returns
The result of conversion of this instance to the instance of type std::string.

The documentation for this class was generated from the following file: