EdgeDB call with Victor re durations and reword PR
6 min read
Durations
Demarcation points are natural because you can’t convert relative durations across them
Can’t jump between days and months
Can jump hours to days in relative delta
always 24 hours
Days cannot cast to 24 hours
daylight savings
Normalization functions can do this for you
duration_normalize_hours
duration_normailze_days- approximation, but it may not matter because you’re likely trying to present to a human
duration doesn’t have anything greater than hours
Explain the reasoning and introduce the normalization & truncation functions
truncation is helpful because you probably don’t care about granularities lower
don’t know how many hours are in a day (daylight savings, leap seconds) or how many days are in a month
Note that you need to explicitly convert because always converting is unsafe
Cast from relative duration to duration with units larger than hour will fail
Reword documentation PR
First line after the method should be a one-liner. Will get replicated in the table
Nuance goes in the big description, right after the one-liner.
Think of one-liner like a heading
Polymorphic functions almost always need to have the one-liner overwritten in the table to give more detail
Don’t use “set” except to refer to a proper set
To find a reference link: actual documentation to find where the link goes
search for what’s in brackets
search for what’s in brackets with underscore before
If searching for links to a reference, drop the underscore
Find all instances where one-liner and the following line (that contains the parameter references) are collapsed and un-collapse them since the one-liner can be re-used outside the context of the function signature that exposes those parameters
abstract.rst
58: Not just type information, also how many elements
without detailing its constituents
66: User cannot (easily) extend anyscalar
Generic functions are useful for standard library but painful for user-facing stuff
May eventually be a way for users to do this but not now
Gives us a type hierarchy that makes sense
Generic types allow generic functions to work on data of other types and preserve original type
Can compare an incoming value to anyint or anyfloat in order to cast it to the appropriate type (if that matters)
User benefit: Knowing something is an int or float during introspection can be useful
102: Should convey “These are the types to make ranges”
Arrays and tuples (collections) are scalars but are defined by types of their constituents
Range is like those in that they are types that behave like scalars but they are composites of other existing types
Unlike tuples and arrays, they are more restricted
Composite types? (need a name for it)
tuples have no restrictions on what goes inside
arrays are restricted (can’t put arrays inside)
postgres has multi-dimensional arrays (need to know dimensions before you start filling in)
arrays of arrays don’t care the size of inner arrays
couldn’t agree on the way to handle this
decided to kick it down the road and decide later
matrices may obviate the need
Victor: you’re insane if you’re storing lists or lists
if it’s an array of arrays, I can give one index to get back an array
can’t do this with a matrix
decided the type was obscure enough they could say no until and unless users make a case for it
Not trivial to decide what the result of foo[3]
Can have array of tuples if you need an array of arrays
Can’t have range of strings
range of 1-5 inclusive or 1-6 not inclusive of the last value are the same, for whole number ranges
need step for float ranges
need to be able to mark which types are valid for ranges
range_unpack has two versions: one with step and one without (for discrete ranges, assuming default step)
ranges in Postgres always include lower boundary and exclude upper
Can’t use custom integer because you don’t know the step
Ranges work only over built-in types
They are well-behaved
over custom types, would be error-prone to implement, so we don’t allow it
for users, good for introspection (“Can I create a range out of this?“)
:index: is a hint for the search function
107 and 123: Additions not useful
If they are searching for point, they are not looking for ranges
This is our terminology. If they are familiar with it, they probably know where to go.
If you are looking for discrete, hard to say what you are looking for
Might benefit users to reverse order of ranges to make it easier to explain
go from more concrete (discrete, contiguous) to more abstract (anypoint)
array.rst
60: Remove grammar.
Arrays are constructed by placing multiple comma-separated expressions within square brackets. Here are a few examples:
The rest of these edits can just go away.
81: You can also create an empty array, but it must be done by providing the type information using type casting. EdgeDB cannot infer the type of an empty array created otherwise. Here’s what that looks like:
show good example
Then introduce incorrect example and show
103: represents makes sense here
“Represents an ordered list of values of the same type”
drop “one-dimensional” to details
“In EdgeDB, arrays are always one-dimensional”
105: Split these to separate paragraphs again like before since they are not related
108: skip
116: Just provide an example directly to show what array typing looks like. Get rid of the link and rewrite the sentence.