{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "reference:c-api:datetimes", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy represents dates internally using an int64 counter and a unit metadata struct. Time differences are represented similarly using an int64 and a unit metadata struct. The functions described below are available to to facilitate converting between ISO 8601 date strings, NumPy datetimes, and Python datetime objects in C." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Datetime API" } ], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In addition to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_datetime" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_timedelta" }, { "__type": "Text", "__tag": 4046, "value": " typedefs for " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_int64" }, { "__type": "Text", "__tag": 4046, "value": ", NumPy defines two additional structs that represent time unit metadata and an \"exploded\" view of a datetime." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Data types" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Converts a datetime from a datetimestruct to a datetime in the units specified by the unit metadata. The date is assumed to be valid." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the " }, { "__type": "InlineCode", "__tag": 4051, "value": "num" }, { "__type": "Text", "__tag": 4046, "value": " member of the metadata struct is large, there may be integer overflow in this function." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns 0 on success and -1 on failure." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Converts a datetime with units specified by the unit metadata to an exploded datetime struct." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns 0 on success and -1 on failure." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tests for and converts a Python " }, { "__type": "InlineCode", "__tag": 4051, "value": "datetime.datetime" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "datetime.date" }, { "__type": "Text", "__tag": 4046, "value": " object into a NumPy " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_datetimestruct" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "out_bestunit" }, { "__type": "Text", "__tag": 4046, "value": " gives a suggested unit based on whether the object was a " }, { "__type": "InlineCode", "__tag": 4051, "value": "datetime.date" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "datetime.datetime" }, { "__type": "Text", "__tag": 4046, "value": " object." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "apply_tzinfo" }, { "__type": "Text", "__tag": 4046, "value": " is 1, this function uses the tzinfo to convert to UTC time, otherwise it returns the struct with the local time." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns -1 on error, 0 on success, and 1 (with no error set) if obj doesn't have the needed date or datetime attributes." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Parses (almost) standard ISO 8601 date strings. The differences are:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The date \"20100312\" is parsed as the year 20100312, not as equivalent to \"2010-03-12\". The '-' in the dates are not optional." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Only seconds may have a decimal point, with up to 18 digits after it (maximum attoseconds precision)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Either a 'T' as in ISO 8601 or a ' ' may be used to separate the date and the time. Both are treated equivalently." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Doesn't (yet) handle the \"YYYY-DDD\" or \"YYYY-Www\" formats." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Doesn't handle leap seconds (seconds value has 60 in these cases)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Doesn't handle 24:00:00 as synonym for midnight (00:00:00) tomorrow" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Accepts special values \"NaT\" (not a time), \"Today\", (current day according to local time) and \"Now\" (current time in UTC)." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "str" }, { "__type": "Text", "__tag": 4046, "value": " must be a NULL-terminated string, and " }, { "__type": "InlineCode", "__tag": 4051, "value": "len" }, { "__type": "Text", "__tag": 4046, "value": " must be its length." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "unit" }, { "__type": "Text", "__tag": 4046, "value": " should contain -1 if the unit is unknown, or the unit which will be used if it is." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "casting" }, { "__type": "Text", "__tag": 4046, "value": " controls how the detected unit from the string is allowed to be cast to the 'unit' parameter." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "out" }, { "__type": "Text", "__tag": 4046, "value": " gets filled with the parsed date-time." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "out_bestunit" }, { "__type": "Text", "__tag": 4046, "value": " gives a suggested unit based on the amount of resolution provided in the string, or -1 for NaT." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "out_special" }, { "__type": "Text", "__tag": 4046, "value": " gets set to 1 if the parsed time was 'today', 'now', empty string, or 'NaT'. For 'today', the unit recommended is 'D', for 'now', the unit recommended is 's', and for 'NaT' the unit recommended is 'Y'." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns 0 on success, -1 on failure." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns the string length to use for converting datetime objects with the given local time and unit settings to strings. Use this when constructing strings to supply to " }, { "__type": "InlineCode", "__tag": 4051, "value": "NpyDatetime_MakeISO8601Datetime" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Converts an " }, { "__type": "InlineCode", "__tag": 4051, "value": "npy_datetimestruct" }, { "__type": "Text", "__tag": 4046, "value": " to an (almost) ISO 8601 NULL-terminated string. If the string fits in the space exactly, it leaves out the NULL terminator and returns success." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The differences from ISO 8601 are the 'NaT' string, and the number of year digits is >= 4 instead of strictly 4." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "local" }, { "__type": "Text", "__tag": 4046, "value": " is non-zero, it produces a string in local time with a +-#### timezone offset. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "local" }, { "__type": "Text", "__tag": 4046, "value": " is zero and " }, { "__type": "InlineCode", "__tag": 4051, "value": "utc" }, { "__type": "Text", "__tag": 4046, "value": " is non-zero, produce a string ending with 'Z' to denote UTC. By default, no time zone information is attached." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "base" }, { "__type": "Text", "__tag": 4046, "value": " restricts the output to that unit. Set " }, { "__type": "InlineCode", "__tag": 4051, "value": "base" }, { "__type": "Text", "__tag": 4046, "value": " to -1 to auto-detect a base after which all the values are zero." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "tzoffset" }, { "__type": "Text", "__tag": 4046, "value": " is used if " }, { "__type": "InlineCode", "__tag": 4051, "value": "local" }, { "__type": "Text", "__tag": 4046, "value": " is enabled, and " }, { "__type": "InlineCode", "__tag": 4051, "value": "tzoffset" }, { "__type": "Text", "__tag": 4046, "value": " is set to a value other than -1. This is a manual override for the local time zone to use, as an offset in minutes." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "casting" }, { "__type": "Text", "__tag": 4046, "value": " controls whether data loss is allowed by truncating the data to a coarser unit. This interacts with " }, { "__type": "InlineCode", "__tag": 4051, "value": "local" }, { "__type": "Text", "__tag": 4046, "value": ", slightly, in order to form a date unit string as a local time, the casting must be unsafe." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns 0 on success, -1 on failure (for example if the output string was too short)." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Conversion functions" } ], "level": 1, "target": null } ], "local_refs": [] }