FORMAT_MEDIUM gives "Thurs" instead of "Thu"

if you want to insure it's at most 3 characters, you just do this:
today.day_of_week.substring(0,3) It's always been this way. there are other cases, different languages, etc, where it might be greater than 3 characters.

True, but reading the api docs, one might think that this is always 3 characters in english:
day_of_week ? Toybox::Lang::Number, Toybox::Lang::String
The day of the week (e.g. Monday, Tuesday, Wednesday, etc,). Returns:

• (Toybox::Lang::Number, Toybox::Lang::String) — The day of the week in the specified format:
  
  • FORMAT_SHORT Number (0, 1, 2, etc.)
    
  • FORMAT_MEDIUM String (Sun, Mon, Tue, etc.)
    
  • FORMAT_LONG String (Sun, Mon, Tue, etc.)
    
    Medium and Long formatting are currently equivalent.
    
  
  Since:
  
• 1.0.0
  

Then maybe the docs need to be updated with correct values, or no examples at all.

Technically the docs are showing the correct values (for the ones that are shown), it just fails to document all seven constants for each of the formats the English language. :D

I dug up this post from a while back that indicates the documentation was more specific and was spread out over two different sections previously. Now that the documentation has been consolidated, and we fixed the bug where we explicitly said it was always three characters, we failed do add a note that the abbreviations aren't always 3 characters. I'll get something filed.

Honestly, if you want some control over this, you should look at using resource strings. There is a post somewhere around here that shows how to do it well.

Travis

The issue here is not that I cannot solve this in a way (though I appreciate the code examples), but it is that If someone reads through the api docs and sees that there are 3 modes in which you can format the date (SHORT, MEDIUM, LONG), if the half examples weren't there I'd think that:

• SHORT is someting like: M, T, W, T, F, S, S (or 0,1,2,3, 4, 5, 6),
  
• MEDIUM is Mon, Tue, Wed, Thu, Fri, Sat, Sun
  
• LONG is Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
  

With the half examples I'm assuming this:

• SHORT is: 0,1,2,3, 4, 5, 6
  
• MEDIUM is Mon, Tue, Wed, Thu, Fri, Sat, Sun
  
• LONG is Mon, Tue, Wed, Thu, Fri, Sat, Sun
  

Though the LONG in this case doesn't make any sense, why is it the same as medium?
Also I haven't checked the month but that should be the same as day of week. (in the sense of abbreviations).

So I appreciate you'll get something filed about the docs. Thank you.

if the half examples weren't there I'd think that..

As far as I can tell FORMAT_MEDIUM is supposed be used to get abbreviated weekday and month names in the current locale. This is no different than the %a and %b conversion specifiers for strftime() in C/C++/Python, or SimpleDateFormat in Java.

In English locales, Thursday is often abbreviated as Thur or Thurs and the documentation doesn't do a sufficient job of telling which one you should expect. Unfortunately it can't just to do that for the following reasons.

• I'm not certain that all locales have 3-character abbreviations for weekday and month names. For example, it is my understanding that Finnish doesn't use 3-character abbreviations.
  
• I'm not certain that all supported devices use the same abbreviations for a given language, and it isn't clear that they should be expected to.
  

I still agree that the documentation should be updated; I just don't think it should be made more explicit as you are suggesting. To do so would be misleading to those supporting non-English languages or to those on devices that didn't behave exactly as suggested. It should be made more general and should just indicate that the string is just a locale-specific abbreviated name and that it could vary by device.

If you want fine-grained control over the weekday names and abbreviations used, you'll have to use string resources as suggested previously. If you only support one language, you'll probably not run into any problems. As you add support for other languages, you'll probably start to run into the similar problems related to the length of the strings.

Though the LONG in this case doesn't make any sense, why is it the same as medium?

As Jim points out, the current documentation for Gregorian.Info indicates that this limitation exists. We've already got an issue filed to fix it.

So I appreciate you'll get something filed about the docs. Thank you.

Actually, several issues were filed previously for issues like this. I did go back and update those issues with comments about what the expected behavior is and why, so hopefully we'll arrive at some documentation that makes everyone happy.

Travis