Skip to content

Commit

Permalink
Misc reformatting and typo fixes (#1260)
Browse files Browse the repository at this point in the history
  • Loading branch information
@workingjubilee
workingjubilee authored Aug 16, 2023
1 parent ec98c4f commit eb1c522
Show file tree
Hide file tree
Showing 9 changed files with 74 additions and 72 deletions.
90 changes: 46 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,61 +163,63 @@ cargo pgrx init

### Mapping of Postgres types to Rust

| Postgres Type | Rust Type (as `Option<T>`) |
|----------------------------|-------------------------------------------------------|
| `bytea` | `Vec<u8>` or `&[u8]` (zero-copy) |
| `text` | `String` or `&str` (zero-copy) |
| `varchar` | `String` or `&str` (zero-copy) or `char` |
| `"char"` | `i8` |
| `smallint` | `i16` |
| `integer` | `i32` |
| `bigint` | `i64` |
| `oid` | `u32` |
| `real` | `f32` |
| `double precision` | `f64` |
| `bool` | `bool` |
| `json` | `pgrx::Json(serde_json::Value)` |
| `jsonb` | `pgrx::JsonB(serde_json::Value)` |
| `date` | `pgrx::Date` |
| `time` | `pgrx::Time` |
| `timestamp` | `pgrx::Timestamp` |
| `time with time zone` | `pgrx::TimeWithTimeZone` |
| `timestamp with time zone` | `pgrx::TimestampWithTimeZone` |
| `anyarray` | `pgrx::AnyArray` |
| `anyelement` | `pgrx::AnyElement` |
| `box` | `pgrx::pg_sys::BOX` |
| `point` | `pgrx::pgrx_sys::Point` |
| `tid` | `pgrx::pg_sys::ItemPointerData` |
| `cstring` | `&core::ffi::CStr` |
| `inet` | `pgrx::Inet(String)` -- TODO: needs better support |
| Postgres Type | Rust Type (as `Option<T>`) |
|----------------------------|---------------------------------------------------------|
| `bytea` | `Vec<u8>` or `&[u8]` (zero-copy) |
| `text` | `String` or `&str` (zero-copy) |
| `varchar` | `String` or `&str` (zero-copy) or `char` |
| `"char"` | `i8` |
| `smallint` | `i16` |
| `integer` | `i32` |
| `bigint` | `i64` |
| `oid` | `u32` |
| `real` | `f32` |
| `double precision` | `f64` |
| `bool` | `bool` |
| `json` | `pgrx::Json(serde_json::Value)` |
| `jsonb` | `pgrx::JsonB(serde_json::Value)` |
| `date` | `pgrx::Date` |
| `time` | `pgrx::Time` |
| `timestamp` | `pgrx::Timestamp` |
| `time with time zone` | `pgrx::TimeWithTimeZone` |
| `timestamp with time zone` | `pgrx::TimestampWithTimeZone` |
| `anyarray` | `pgrx::AnyArray` |
| `anyelement` | `pgrx::AnyElement` |
| `box` | `pgrx::pg_sys::BOX` |
| `point` | `pgrx::pg_sys::Point` |
| `tid` | `pgrx::pg_sys::ItemPointerData` |
| `cstring` | `&core::ffi::CStr` |
| `inet` | `pgrx::Inet(String)` -- TODO: needs better support |
| `numeric` | `pgrx::Numeric<P, S> or pgrx::AnyNumeric` |
| `void` | `()` |
| `ARRAY[]::<type>` | `Vec<Option<T>>` or `pgrx::Array<T>` (zero-copy) |
| `int4range` | `pgrx::Range<i32>` |
| `int8range` | `pgrx::Range<i64>` |
| `void` | `()` |
| `ARRAY[]::<type>` | `Vec<Option<T>>` or `pgrx::Array<T>` (zero-copy) |
| `int4range` | `pgrx::Range<i32>` |
| `int8range` | `pgrx::Range<i64>` |
| `numrange` | `pgrx::Range<Numeric<P, S>>` or `pgrx::Range<AnyRange>` |
| `daterange` | `pgrx::Range<pgrx::Date>` |
| `tsrange` | `pgrx::Range<pgrx::Timestamp>` |
| `tstzrange` | `pgrx::Range<pgrx::TimestampWithTimeZone>` |
| `NULL` | `Option::None` |
| `internal` | `pgrx::PgBox<T>` where `T` is any Rust/Postgres struct |
| `uuid` | `pgrx::Uuid([u8; 16])` |
| `NULL` | `Option::None` |
| `internal` | `pgrx::PgBox<T>` where `T` is any Rust/Postgres struct |
| `uuid` | `pgrx::Uuid([u8; 16])` |

There are also `IntoDatum` and `FromDatum` traits for implementing additional type conversions,
along with `#[derive(PostgresType)]` and `#[derive(PostgresEnum)]` for automatic conversion of
custom types.

Note that `text` and `varchar` are converted to `&str` or `String`, so PGX
assumes that any Postgres database you use it with has a UTF-8-compatible
encoding. Currently, PGX will panic if it detects this is incorrect, to inform
you, the programmer, that you were wrong. However, it is best to not rely on
this behavior, as UTF-8 validation can be a performance hazard, this event was
previously assumed to simply not happen, and PGX may decide to change the
details of how it does UTF-8 validation in the future, as all functions for
doing so are, in any case, fundamentally `unsafe`. For best results, always use
PGX with UTF-8, and set database encodings explicitly upon database creation,
as the default Postgres server encoding, `SQL_ASCII`, will guarantee neither
Note that `text` and `varchar` are converted to `&str` or `String`, so PGRX
assumes any Postgres database you use it with has UTF-8-compatible encoding.
Currently, PGRX will panic if it detects this is incorrect, to inform you, the
programmer, that you were wrong. However, it is best to not rely on this
behavior, as UTF-8 validation can be a performance hazard. This problem was
previously assumed to simply not happen, and PGRX may decide to change the
details of how it does UTF-8 validation checks in the future in order to
mitigate performance hazards.

The default Postgres server encoding is `SQL_ASCII`, and it guarantees neither
ASCII nor UTF-8 (as Postgres will then accept but ignore non-ASCII bytes).
For best results, always use PGRX with UTF-8, and set database encodings
explicitly upon database creation.

## Digging Deeper

Expand Down
2 changes: 1 addition & 1 deletion cargo-pgrx/src/command/init.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -352,7 +352,7 @@ fn fixup_homebrew_for_icu(configure_cmd: &mut Command) {
you may disable ICU support by invoking `cargo pgrx init` with the \
`--configure-flags=--without-icu` argument, as follows:\n\
\n\
$ cargo pgx init --configure-flag=--without-icu\n\
$ cargo pgrx init --configure-flag=--without-icu\n\
\n\
However, this is not recommended.\
";
Expand Down
4 changes: 2 additions & 2 deletions pgrx-examples/custom_types/src/complex.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ pub struct Animals {
fn known_animals() -> Animals {
Animals {
names: vec!["Sally".into(), "Brandy".into(), "anchovy".into()],
age_lookup: hashmap! { 5 => "Sally".into(), 4 => "Brandy".into(), 3=> "anchovy".into()},
age_lookup: hashmap! { 5 => "Sally".into(), 4 => "Brandy".into(), 3 => "anchovy".into()},
}
}

Expand Down Expand Up @@ -70,7 +70,7 @@ mod tests {
animals,
Ok(Some(Animals {
names: vec!["Sally".into(), "Brandy".into(), "anchovy".into()],
age_lookup: hashmap! { 5 => "Sally".into(), 4 => "Brandy".into(), 3=> "anchovy".into()},
age_lookup: hashmap! { 5 => "Sally".into(), 4 => "Brandy".into(), 3 => "anchovy".into()},
}))
);
}
Expand Down
2 changes: 1 addition & 1 deletion pgrx/src/datum/date.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,7 @@ impl Date {
!matches!(self.0, pg_sys::DateADT::MIN | pg_sys::DateADT::MAX)
}

/// Return the backing [`pg_sy::DateADT`] value.
/// Return the backing [`pg_sys::DateADT`] value.
#[inline]
pub fn into_inner(self) -> pg_sys::DateADT {
self.0
Expand Down
14 changes: 7 additions & 7 deletions pgrx/src/datum/datetime_support/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ pub enum DateTimeParts {

/// For timestamp with time zone values, the number of seconds since 1970-01-01 00:00:00 UTC
/// (negative for timestamps before that); for date and timestamp values, the nominal number of
/// seconds since 1970-01-01 00:00:00, without regard to timezone or daylight-savings rules; for
/// seconds since 1970-01-01 00:00:00, without regard to time zone or daylight-savings rules; for
/// interval values, the total number of seconds in the interval
Epoch,

Expand Down Expand Up @@ -573,11 +573,11 @@ pub fn get_timezone_offset<Tz: AsRef<str>>(zone: Tz) -> Result<i32, DateTimeConv
))]
pub fn get_timezone_offset<Tz: AsRef<str>>(zone: Tz) -> Result<i32, DateTimeConversionError> {
/*
* Look up the requested timezone. First we look in the timezone
* Look up the requested time zone. First we look in the time zone
* abbreviation table (to handle cases like "EST"), and if that fails, we
* look in the timezone database (to handle cases like
* look in the time zone database (to handle cases like
* "America/New_York"). (This matches the order in which timestamp input
* checks the cases; it's important because the timezone database unwisely
* checks the cases; it's important because the time zone database unwisely
* uses a few zone names that are identical to offset abbreviations.)
*/
unsafe {
Expand Down Expand Up @@ -705,11 +705,11 @@ pub enum DateTimeConversionError {
FieldOverflow,
#[error("The date or time is not in the correct format")]
InvalidFormat,
#[error("`{0}` is not a known timezone")]
#[error("`{0}` is not a known time zone")]
UnknownTimezone(String),
#[error("`{0} is not a valid timezone offset")]
#[error("`{0} is not a valid time zone offset")]
InvalidTimezoneOffset(Interval),
#[error("Encoded timezone string is unknown")]
#[error("Encoded time zone string is unknown")]
CannotParseTimezone,
/// ERRCODE_DATETIME_VALUE_OUT_OF_RANGE
#[error("The value is out-of-range for valid instances of this datetime type")]
Expand Down
4 changes: 2 additions & 2 deletions pgrx/src/datum/from.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -336,7 +336,7 @@ impl FromDatum for f64 {
/// For Postgres text and varchar
///
/// Note that while these conversions are inherently unsafe, they still enforce
/// UTF-8 correctness, so they may panic if you use PGX with a database
/// UTF-8 correctness, so they may panic if you use PGRX with a database
/// that has non-UTF-8 data. The details of this are subject to change.
impl<'a> FromDatum for &'a str {
#[inline]
Expand Down Expand Up @@ -408,7 +408,7 @@ unsafe fn convert_varlena_to_str_memoized<'a>(varlena: *const pg_sys::varlena) -
/// This returns a **copy**, allocated and managed by Rust, of the underlying `varlena` Datum
///
/// Note that while these conversions are inherently unsafe, they still enforce
/// UTF-8 correctness, so they may panic if you use PGX with a database
/// UTF-8 correctness, so they may panic if you use PGRX with a database
/// that has non-UTF-8 data. The details of this are subject to change.
impl FromDatum for String {
#[inline]
Expand Down
12 changes: 6 additions & 6 deletions pgrx/src/datum/time_stamp_with_timezone.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ impl TryFrom<pg_sys::Datum> for TimestampWithTimeZone {
}

/// Create a [`TimestampWithTimeZone`] from an existing [`Timestamp`] (which is understood to be
/// in the "current time zone" and a timezone string.
/// in the "current time zone" and a time zone string.
impl<Tz: AsRef<str> + UnwindSafe + RefUnwindSafe> TryFrom<(Timestamp, Tz)>
for TimestampWithTimeZone
{
Expand Down Expand Up @@ -207,7 +207,7 @@ impl TimestampWithTimeZone {
}
}

/// Construct a new [`TimestampWithTimeZone`] from its constituent parts at a specific timezone
/// Construct a new [`TimestampWithTimeZone`] from its constituent parts at a specific time zone
///
/// # Errors
///
Expand Down Expand Up @@ -317,17 +317,17 @@ impl TimestampWithTimeZone {
(self.hour(), self.minute(), self.second() as u8, self.microseconds())
}

/// Shift the [`Timestamp`] to the `UTC` timezone
/// Shift the [`Timestamp`] to the `UTC` time zone
pub fn to_utc(&self) -> Timestamp {
self.at_timezone("UTC").unwrap()
}

/// Shift the [`TimestampWithTimeZone`] to the specified timezone
/// Shift the [`TimestampWithTimeZone`] to the specified time zone
///
/// # Errors
///
/// Returns a [`DateTimeConversionError`] if the specified timezone is invalid or if for some
/// other reason the underlying time cannot be represented in the specified timezone
/// Returns a [`DateTimeConversionError`] if the specified time zone is invalid or if for some
/// other reason the underlying time cannot be represented in the specified time zone
pub fn at_timezone<Tz: AsRef<str> + UnwindSafe + RefUnwindSafe>(
&self,
timezone: Tz,
Expand Down
12 changes: 6 additions & 6 deletions pgrx/src/datum/time_with_timezone.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ pub struct TimeWithTimeZone(pg_sys::TimeTzADT);
/// Create a [`TimeWithTimeZone`] from a [`pg_sys::TimeTzADT`]
///
/// This impl currently allows creating a `TimeWithTimeZone` that cannot be constructed by SQL,
/// such as at the time 37:42 in the timezone UTC+25:00, which may yield logic bugs if used.
/// such as at the time 37:42 in the time zone UTC+25:00, which may yield logic bugs if used.
impl From<pg_sys::TimeTzADT> for TimeWithTimeZone {
#[inline]
fn from(value: pg_sys::TimeTzADT) -> Self {
Expand Down Expand Up @@ -147,7 +147,7 @@ impl TimeWithTimeZone {
}
}

/// Construct a new [`TimeWithTimeZone`] from its constituent parts at a specific timezone
/// Construct a new [`TimeWithTimeZone`] from its constituent parts at a specific time zone
///
/// # Errors
///
Expand Down Expand Up @@ -177,7 +177,7 @@ impl TimeWithTimeZone {
.execute()
}

/// Construct a new [`TimeWithTimeZone`] from its constituent parts at a specific timezone [`Interval`]
/// Construct a new [`TimeWithTimeZone`] from its constituent parts at a specific time zone [`Interval`]
///
/// # Errors
///
Expand Down Expand Up @@ -255,12 +255,12 @@ impl TimeWithTimeZone {
self.at_timezone("UTC").unwrap().into()
}

/// Shift the [`TimeWithTimeZone`] to the specified timezone
/// Shift the [`TimeWithTimeZone`] to the specified time zone
///
/// # Errors
///
/// Returns a [`DateTimeConversionError`] if the specified timezone is invalid or if for some
/// other reason the underlying time cannot be represented in the specified timezone
/// Returns a [`DateTimeConversionError`] if the specified time zone is invalid or if for some
/// other reason the underlying time cannot be represented in the specified time zone
pub fn at_timezone<Tz: AsRef<str> + UnwindSafe + RefUnwindSafe>(
&self,
timezone: Tz,
Expand Down
6 changes: 3 additions & 3 deletions pgrx/src/spi.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,9 +196,9 @@ pub struct Spi;
impl Spi {
/// Determines if the current transaction can still be `read_only = true` for purposes of Spi
/// queries. This is detected in such a way that prior mutable commands within this transaction
/// (even those not executed via pgx' Spi) will influence whether or not we con consider the
/// (even those not executed via pgrx's Spi) will influence whether or not we can consider the
/// transaction `read_only = true`. This is what we want as the user will expect an otherwise
/// read only statement like SELECT to see the results of prior statements.
/// read-only statement like SELECT to see the results of prior statements.
///
/// Postgres docs say:
///
Expand All @@ -208,7 +208,7 @@ impl Spi {
/// would not see the results of any database updates done by the read-write queries.
///```
///
/// pgx interprets this to mean:
/// pgrx interprets this to mean:
/// ```text
/// Within a transaction, it's fine to execute Spi commands as `read_only = true` until the
/// first mutable statement (DDL or DML). From that point forward **all** statements
Expand Down

0 comments on commit eb1c522

Please sign in to comment.