Built-in-types Arrays: vec/dict/keyset sections don't describe how to get values

[yukonfb]

Please complete the information below:

Where is the problem?

• Built-in-types Arrays: 'vec', 'dict', 'keyset' (all three sections) and
• Built-in-types Arrays: 'Using dicts, keysets, and vecs' (table)

What is the problem?

Shows assignments, but not how to get values (!)

• How to get values from arrays ([], idx, maybe nested example as well)
• What will happen if key doesn't exist. Does it throw, does it return null, or something else?
• Ways to handle non-existent key (null-safe-like operations for [] and idx) $foo = mydict['badkey']['goodkey'] ?? null; // is it this?

---

Please don't change anything below this point.

---

• Build ID: HHVM=HHVM-4.52.1:HSL=v4.40.0:2020-04-09T15:46:58+0000:d96130cc77b2ef2fc08fd66697c635a9d1aa5519
• Page requested: /hack/built-in-types/arrays
• Page requested at: Fri, 10 Apr 2020 16:23:26 +0000
• Controller: GuidePageController

[jjergus]

Agreed, this definitely needs improvement.

How to get values from arrays ([], idx, maybe nested example as well)

This is currently documented in the subscript section but would probably make much more sense in the arrays guide like you suggested.

What will happen if key doesn't exist. Does it throw, does it return null, or something else?

I'm not sure if this is properly documented anywhere. Unfortunately this might also get pretty complicated (it's likely inconsistent between different array types, may depend on various INI options, and may keep changing as we migrate away from legacy PHP arrays), so it might be hard to keep up-to-date until things become more stable.

Ways to handle non-existent key (null-safe-like operations for [] and idx) $foo = mydict['badkey']['goodkey'] ?? null; // is it this?

This is documented in the coalesce section and also would probably make more sense in the arrays guide.

@Wilfred have you given any though to what we should do with the "Expressions and Operators" section? It looks to me like most of the pages should just be completely removed and their content moved to a more relevant place (e.g. the array stuff from above, "async blocks" somewhere in the async section, "yield" wherever we document generators, "new" wherever we document objects, etc.)

[jjergus]

There's also some documentation on the idx reference page: https://docs.hhvm.com/hack/reference/function/HH.idx/

That should probably just link to wherever we decide to document all this.

[Wilfred]

@jjergus agreed, I don't think the Expressions and Operators section is a very helpful way of structuring the content.

The structure I've been thinking of is:

Basic syntax
* Comments (3x syntaxes, doc comments)
* Strings (literals, interpolation)
* Numerics (literals, arithmetic)
* Booleans (literal, operations)
* Keywords (what they are, enforcement)

Statement syntax
* Conditionals
* Loops
* try/catch

Data structures (with recommendations)
* Hack arrays (vec, dict, keyset)
* Collections (Vector, Set, Map, ImmMap etc)
* PHP arrays (array, darray, varray, varray_or_darray)

Namespaces
* Declaring namespaces
* Aliasing namespaces

Async
* await and basic semantics
* concurrent blocks, async blocks

Generators
* Normal generators
* Async generators

Functions
* Named functions
* Anonymous functions

Object model
* Classes, methods, inheritance and visibility
* Constructors and parameter promotion
* Properties
* Interfaces
* Traits (semantics, constraints)
* User-defined attributes
* Class generics and associated type constants

Enums
* Inheritance
* Enforcement

Generics
* Erased generics (methods, classes, functions, inference)
* Reified generics

XHP
* Declare and using XHP
* Attributes and enums
* Namespace support

Indexes
* An operator index (e.g. ==>, =>, . etc)
* A built-in attribute index (__Override, __Newable etc)
* An HH_FIXME error code index

I think a thematic grouping is much easier to read and to find what you're looking for. Arrays are a big topic in Hack, so definitely deserve their own section.