4

This function for example...

int preg_match_all ( string $pattern , string $subject [, array &$matches [, int $flags = PREG_PATTERN_ORDER [, int $offset = 0 ]]] )

It takes the strings $pattern and $subject. However, what is [?

Mogsdad
  • 44,709
  • 21
  • 151
  • 275
Koray Tugay
  • 22,894
  • 45
  • 188
  • 319
  • This is a documentation syntax - you don't actually put the square brackets into code. – halfer Jan 19 '13 at 23:09
  • 1
    see http://stackoverflow.com/questions/10053286/intx-base-square-brackets-in-functions-in-python-documentation – Janus Troelsen Jan 19 '13 at 23:09
  • Possible duplicate of [How to read API documentation for newbs?](https://stackoverflow.com/questions/10925478/how-to-read-api-documentation-for-newbs) – Bergi Nov 04 '18 at 19:13

2 Answers2

8

That is how the documentation for a function indicates arguments that are optional

Quentin
  • 914,110
  • 126
  • 1,211
  • 1,335
  • can I for example skip the first optional argument (&$matches) but have the last two in this example? – Koray Tugay Jan 19 '13 at 23:08
  • 2
    @korayTugay unfortunatlely nope. You can check what the default value was and pass it though. Because the function figures out the parameter based on the index. If you're writing your own functions and want to have orderless optional parameters, you can pass an array – Raekye Jan 19 '13 at 23:09
  • 2
    @KorayTugay — No. They are optional *within* the group of preceding arguments (hence the nested square brackets) – Quentin Jan 19 '13 at 23:10
  • 1
    No as all three optional parameters are wrapped in the same square bracket. – Ian Brindley Jan 19 '13 at 23:10
  • 1
    @KorayTugay If this answer was helpful, please consider accepting it. – Kermit Mar 13 '13 at 14:18
3

This is an old convention from Unix systems' Usage messages:

On Unix-like platforms, usage messages tend to follow the same commonly-used pattern users are familiar with. They often begin with "Usage:" (hence possibly the name), the command, followed by a list of arguments. To indicate optional arguments, Square brackets are commonly used, and can also be used to group parameters that must be specified together. Exclusive parameters can be indicated by separating them with vertical bars within groups.

Here is a thorough example based on the NetBSD source code style guide:

Usage: program [-aDde] [-f | -g] [-n number] [-b b_arg | -c c_arg] req1 req2 [opt1 [opt2]]

This would indicate that "program" should be called with:

  • options without operands: a, D, d, e (any of which may be omitted). Note that in this case some parameters are case-sensitive
  • exclusive options: f, g (denoted by the vertical bar)
  • options with operands: n
  • exclusive options with operands: b, c
  • required arguments: req1, req2
  • optional argument opt1, which may be used with or without opt2 (marked optional within the group by using another set of square brackets)
  • optional argument opt2, which requires opt1
Community
  • 1
  • 1
Janus Troelsen
  • 20,267
  • 14
  • 135
  • 196